catalog_ids: rank several catalogs together

.env.example

@@ -1,2 +1,3 @@
 UNBOXAI_API_KEY= # the key you receive in your email
+UNBOXAI_CATALOG_ID= # optional: your catalog, used when a call names none (default retail_catalog)
 HF_TOKEN= # optional: Hugging Face write token, only needed to host catalog images (see docs/catalog-format.md)

README.md

@@ -93,6 +93,8 @@ job = client.embed(path, wait=True, timeout=1800.0)
 client.complete([Search("...")], catalog_id=job.catalog_id)
 ```
 
+To make your catalog the default, so calls need no `catalog_id`, set `UNBOXAI_CATALOG_ID=cat_...` or pass `default_catalog_id=` to the client.
+
 A catalog holds up to 100,000 items, and each API key holds 2 catalogs. The file name is the catalog's name, so uploading the same name again refreshes that catalog.
 
 Once it is embedded, you can add or replace items, list and delete catalogs, and generate the keywords that `sections` uses to group results under titles such as "black coats":
@@ -107,7 +109,15 @@ for section in client.sections([Search("coat")], catalog_id=job.catalog_id).sect
     print(section.title, [item.data["name"] for item in section.items])
 ```
 
-[`docs/catalogs.md`](https://github.com/Unbox-AI/behaviorgpt/blob/main/docs/catalogs.md) has the details: catalog slots, what replacing an item keeps, how long keywords take and what happens when a job fails.
+To rank several catalogs together, say your own next to `retail_catalog`, pass `catalog_ids` instead of `catalog_id`. One ranking comes back, and each item says which catalog it is in:
+
+```python
+res = client.complete([View(shoe)], catalog_ids=[job.catalog_id, "retail_catalog"])
+for item in res.items:
+    print(item.catalog_id, item.data["name"])
+```
+
+[`docs/catalogs.md`](https://github.com/Unbox-AI/behaviorgpt/blob/main/docs/catalogs.md) has the details: catalog slots, what replacing an item keeps, how long keywords take, what happens when a job fails, and how a history names items of several catalogs.
 
 If mapping your data to the format is hard, open a coding agent in this directory and ask it to embed your catalog. The repo ships a skill at [`.claude/skills/embed-catalog/SKILL.md`](https://github.com/Unbox-AI/behaviorgpt/blob/main/.claude/skills/embed-catalog/SKILL.md) that walks the agent through mapping your columns, building and validating the parquet, checking image URLs, and uploading. Claude Code picks it up automatically; for other agents, point them at that file.
 

docs/catalogs.md

@@ -1,6 +1,6 @@
 # Managing catalogs
 
-How catalogs are named and limited, how to update, list and delete them, and how to add the keywords that `sections` needs. For what the uploaded file must contain, see [catalog-format.md](catalog-format.md).
+How catalogs are named and limited, how to update, list and delete them, how to rank several together, and how to add the keywords that `sections` needs. For what the uploaded file must contain, see [catalog-format.md](catalog-format.md).
 
 ## Names and limits
 
@@ -36,6 +36,25 @@ client.delete_catalog("cat_...")
 - `delete_catalog()` removes one of your catalogs with its items and frees its slot. It cannot be undone.
 - Deleting another key's catalog fails with status 404, the same as an unknown id. While a job runs for the catalog, deleting fails with status 409; try again once the job is ready or failed.
 
+## Several catalogs at once
+
+`complete`, `sections` and `similar_items` take `catalog_ids` instead of `catalog_id` to rank up to 5 catalogs together, for instance your own catalog and `retail_catalog`. The model reads the history once and scores the items of every catalog on the same scale, so the result is one ranking, not one per catalog.
+
+```python
+both = [job.catalog_id, "retail_catalog"]
+res = client.complete([View(shoe)], catalog_ids=both)
+for item in res.items:
+    print(item.catalog_id, item.id, item.data["name"])
+```
+
+- An item id is unique only within its catalog, so every item of a response says which catalog it is in, `item.catalog_id`. Single-catalog responses fill it in too.
+- An item in a history is in the first catalog of `catalog_ids` unless it names another: `View("sku-1", catalog_id="retail_catalog")`. An `Item` from a response knows its catalog, so `View(item)` and `Order([item])` need nothing more. An order can mix items of several catalogs.
+- In `filters`, `catalog_id` is the item's catalog: `{"catalog_id": "retail_catalog"}` keeps only its items, and `{"$not": {"catalog_id": job.catalog_id}}` leaves yours out.
+- `similar_items(item, catalog_ids=both)` finds the items most like `item` in all of them. The item is in its own catalog if it is an `Item`, else in `catalog_id`, else in the first.
+- `sections` weighs each catalog by its number of items when it groups them, so a small catalog does not crowd out a large one.
+- An item that names a catalog the request does not read is refused before anything is sent.
+- The catalogs must have been embedded by the same model, as their scores are compared. A catalog embedded by an older model is refused with status 409; upload it again to embed it with the current one.
+
 ## Keywords and sections
 
 Sections group the items the model ranks under titles such as "black coats", best section first. They are built from item keywords, which `embed` does not generate by default because they take time. Generate them for an embedded catalog with `add_keywords`:

src/behaviorgpt/__init__.py

@@ -12,6 +12,7 @@
 )
 from behaviorgpt.types.events import (
     AddToCart,
+    CartItem,
     Order,
     RemoveFromCart,
     Search,
@@ -24,6 +25,7 @@
     "View",
     "RemoveFromCart",
     "Order",
+    "CartItem",
     "UnboxAIClient",
     "AsyncUnboxAIClient",
     "ProgressBar",