behaviorgpt 0.2.2__tar.gz → 0.4.0__tar.gz

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: behaviorgpt
-Version: 0.2.2
+Version: 0.4.0
 Summary: Python client for BehaviorGPT, UnboxAI's Large Behavioral Model for search, recommendations and personalization
 Keywords: recommendations,personalization,search,behavioral model,unboxai
 Author: Unbox AI
@@ -123,11 +123,14 @@ The model can only return items it knows about. Out of the box the client uses `
 
 - [`docs/catalog-format.md`](https://github.com/Unbox-AI/behaviorgpt/blob/main/docs/catalog-format.md) lists the required columns and types.
 - A catalog can hold at most 100,000 items.
-- Each API key can hold 2 catalogs. The file name is the catalog's name: uploading a file with the same name again refreshes that catalog and keeps its `catalog_id`, and a new name takes one of the 2 slots. A failed upload does not use up a slot. Once both slots are in use, an upload under a new name is refused; to remove a catalog or raise the limit, contact alexander@unboxai.com.
-- [`examples/sample_catalog.csv`](https://github.com/Unbox-AI/behaviorgpt/blob/main/examples/sample_catalog.csv) is an example only, showing what each column should contain. Your own file will look different depending on your catalog, and it has to be converted to the parquet structure described in the format doc before upload.
+- Each API key can hold 2 catalogs. The file name is the catalog's name: uploading a file with the same name again refreshes that catalog and keeps its `catalog_id`, and a new name takes one of the 2 slots. A failed upload does not use up a slot. Once both slots are in use, an upload under a new name is refused until you delete one of them (see below); to raise the limit, contact alexander@unboxai.com.
+- [`examples/sample_catalog.csv`](https://github.com/Unbox-AI/behaviorgpt/blob/main/examples/sample_catalog.csv) is an example only, showing what each column should contain. Your own file will look different depending on your catalog. A CSV with the documented column names converts to the parquet structure with `catalog_from_csv`.
 
 ```python
-job = client.embed("my_catalog.parquet", wait=True, timeout=1800.0)
+from behaviorgpt import catalog_from_csv
+
+path = catalog_from_csv("my_catalog.csv")  # writes my_catalog.parquet
+job = client.embed(path, wait=True, timeout=1800.0)
 client.complete([Search("...")], catalog_id=job.catalog_id)
 ```
 
@@ -146,6 +149,19 @@ client.add_items("new_items.parquet", catalog_id=job.catalog_id, wait=True)
 - Uploading the catalog's file again with `embed` replaces the whole catalog, added items included. Put them in that file too to keep them.
 - A catalog embedded before `add_items` existed needs one more full upload before items can be added to it.
 
+### Listing and deleting catalogs
+
+```python
+for c in client.list_catalogs():
+    print(c.catalog_id, c.catalog_name, c.status, c.owned)
+
+client.delete_catalog("cat_...")
+```
+
+- `list_catalogs()` returns your own catalogs, in any status, and the shared ones that are ready. `owned` marks your own.
+- `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 an `embed` or `add_items` job runs for the catalog, deleting fails with status 409; try again once the job is ready or failed.
+
 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.
 
 ### Events

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/README.md

@@ -106,11 +106,14 @@ The model can only return items it knows about. Out of the box the client uses `
 
 - [`docs/catalog-format.md`](https://github.com/Unbox-AI/behaviorgpt/blob/main/docs/catalog-format.md) lists the required columns and types.
 - A catalog can hold at most 100,000 items.
-- Each API key can hold 2 catalogs. The file name is the catalog's name: uploading a file with the same name again refreshes that catalog and keeps its `catalog_id`, and a new name takes one of the 2 slots. A failed upload does not use up a slot. Once both slots are in use, an upload under a new name is refused; to remove a catalog or raise the limit, contact alexander@unboxai.com.
-- [`examples/sample_catalog.csv`](https://github.com/Unbox-AI/behaviorgpt/blob/main/examples/sample_catalog.csv) is an example only, showing what each column should contain. Your own file will look different depending on your catalog, and it has to be converted to the parquet structure described in the format doc before upload.
+- Each API key can hold 2 catalogs. The file name is the catalog's name: uploading a file with the same name again refreshes that catalog and keeps its `catalog_id`, and a new name takes one of the 2 slots. A failed upload does not use up a slot. Once both slots are in use, an upload under a new name is refused until you delete one of them (see below); to raise the limit, contact alexander@unboxai.com.
+- [`examples/sample_catalog.csv`](https://github.com/Unbox-AI/behaviorgpt/blob/main/examples/sample_catalog.csv) is an example only, showing what each column should contain. Your own file will look different depending on your catalog. A CSV with the documented column names converts to the parquet structure with `catalog_from_csv`.
 
 ```python
-job = client.embed("my_catalog.parquet", wait=True, timeout=1800.0)
+from behaviorgpt import catalog_from_csv
+
+path = catalog_from_csv("my_catalog.csv")  # writes my_catalog.parquet
+job = client.embed(path, wait=True, timeout=1800.0)
 client.complete([Search("...")], catalog_id=job.catalog_id)
 ```
 
@@ -129,6 +132,19 @@ client.add_items("new_items.parquet", catalog_id=job.catalog_id, wait=True)
 - Uploading the catalog's file again with `embed` replaces the whole catalog, added items included. Put them in that file too to keep them.
 - A catalog embedded before `add_items` existed needs one more full upload before items can be added to it.
 
+### Listing and deleting catalogs
+
+```python
+for c in client.list_catalogs():
+    print(c.catalog_id, c.catalog_name, c.status, c.owned)
+
+client.delete_catalog("cat_...")
+```
+
+- `list_catalogs()` returns your own catalogs, in any status, and the shared ones that are ready. `owned` marks your own.
+- `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 an `embed` or `add_items` job runs for the catalog, deleting fails with status 409; try again once the job is ready or failed.
+
 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.
 
 ### Events

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "behaviorgpt"
-version = "0.2.2"
+version = "0.4.0"
 description = "Python client for BehaviorGPT, UnboxAI's Large Behavioral Model for search, recommendations and personalization"
 readme = "README.md"
 license = "MIT"

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "behaviorgpt"
-version = "0.2.2"
+version = "0.4.0"
 description = "Python client for BehaviorGPT, UnboxAI's Large Behavioral Model for search, recommendations and personalization"
 readme = "README.md"
 license = "MIT"

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/__init__.py

@@ -5,7 +5,7 @@ from behaviorgpt._exceptions import (
     RateLimitError,
     UnboxAIError,
 )
-from behaviorgpt.resources.catalogs import ProgressPrinter
+from behaviorgpt.resources.catalogs import ProgressPrinter, catalog_from_csv
 from behaviorgpt.types.events import (
     AddToCart,
     Order,
@@ -23,6 +23,7 @@ __all__ = [
     "UnboxAIClient",
     "AsyncUnboxAIClient",
     "ProgressPrinter",
+    "catalog_from_csv",
     "UnboxAIError",
     "AuthenticationError",
     "BadRequestError",

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/_client.py

@@ -18,6 +18,7 @@ from behaviorgpt.types import (
     AddItemsJobDetails,
     AddToCart,
     CartItem,
+    CatalogSummary,
     Domains,
     EmbedJobDetails,
     Item,
@@ -35,6 +36,7 @@ from behaviorgpt.types import (
 # file is stored and queued: httpx's 5 s default is too short for both.
 DEFAULT_HTTP_TIMEOUT = httpx.Timeout(120.0, connect=10.0, write=300.0)
 DEFAULT_BASE_URL = "https://behaviorgpt-northeurope.api.unboxai.com/v1"
+DEFAULT_TRAILING_SEARCHES = 3
 
 
 class _BaseClient:
@@ -74,6 +76,7 @@ class _BaseClient:
         catalog_id: Optional[str],
         filters: Optional[dict[str, Any]],
         register_event: bool,
+        max_trailing_searches: int = DEFAULT_TRAILING_SEARCHES,
     ) -> tuple[bool, UnboxAIRequest, dict]:
         """The request `complete` sends, whether it goes to search, and its headers."""
         active_catalog, request_headers = self._catalog_headers(catalog_id)
@@ -90,6 +93,7 @@ class _BaseClient:
                 offset=offset,
                 filters=filters,
                 register_event=register_event,
+                max_trailing_searches=max_trailing_searches,
             )
             return True, req, request_headers
 
@@ -216,9 +220,22 @@ class UnboxAIClient(_BaseClient):
         catalog_id: Optional[str] = None,
         filters: Optional[dict[str, Any]] = None,
         register_event: bool = False,
+        max_trailing_searches: int = DEFAULT_TRAILING_SEARCHES,
     ) -> UnboxAIResponse:
+        """Rank the items most likely to come after `history`.
+
+        When the history ends in searches, up to `max_trailing_searches` of
+        them in a row, the query included, reach the model, so `nike` then
+        `shoes` reads as one intent.
+        """
         is_search, req, headers = self._complete_request(
-            history, limit, offset, catalog_id, filters, register_event
+            history,
+            limit,
+            offset,
+            catalog_id,
+            filters,
+            register_event,
+            max_trailing_searches,
         )
         endpoint = self.search if is_search else self.recommendations
         return endpoint.create(payload=req, headers=headers)
@@ -290,6 +307,22 @@ class UnboxAIClient(_BaseClient):
     def job_status(self, job_id: str) -> JobStatus:
         return self.catalogs.get_job_status(job_id)
 
+    def list_catalogs(self) -> list[CatalogSummary]:
+        """The catalogs this key can query: its own, in any status, and the
+        shared ones that are ready. `owned` marks the key's own."""
+        return self.catalogs.list_catalogs()
+
+    def delete_catalog(self, catalog_id: str) -> None:
+        """Delete one of this key's catalogs, its items and its index, and
+        free its slot. This cannot be undone.
+
+        A catalog that is not this key's raises `UnboxAIError` with status
+        404, the same as an unknown one. While an embed or `add_items` job runs
+        for the catalog, it raises with status 409; delete once the job is
+        ready or failed.
+        """
+        self.catalogs.delete_catalog(catalog_id)
+
     def similar_items(
         self,
         item_id: str,
@@ -397,9 +430,18 @@ class AsyncUnboxAIClient(_BaseClient):
         catalog_id: Optional[str] = None,
         filters: Optional[dict[str, Any]] = None,
         register_event: bool = False,
+        max_trailing_searches: int = DEFAULT_TRAILING_SEARCHES,
     ) -> UnboxAIResponse:
+        """Rank the items most likely to come after `history`; see
+        `UnboxAIClient.complete`."""
         is_search, req, headers = self._complete_request(
-            history, limit, offset, catalog_id, filters, register_event
+            history,
+            limit,
+            offset,
+            catalog_id,
+            filters,
+            register_event,
+            max_trailing_searches,
         )
         endpoint = self.search if is_search else self.recommendations
         return await endpoint.create(payload=req, headers=headers)
@@ -454,6 +496,14 @@ class AsyncUnboxAIClient(_BaseClient):
     async def job_status(self, job_id: str) -> JobStatus:
         return await self.catalogs.get_job_status(job_id)
 
+    async def list_catalogs(self) -> list[CatalogSummary]:
+        """See `UnboxAIClient.list_catalogs`."""
+        return await self.catalogs.list_catalogs()
+
+    async def delete_catalog(self, catalog_id: str) -> None:
+        """See `UnboxAIClient.delete_catalog`."""
+        await self.catalogs.delete_catalog(catalog_id)
+
     async def similar_items(
         self,
         item_id: str,

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/resources/catalogs.py

@@ -1,18 +1,23 @@
+import ast
 import asyncio
 import time
 import warnings
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any, Callable, Optional
+from urllib.parse import quote
 
 import httpx
 import pyarrow as pa
+import pyarrow.compute as pc
+import pyarrow.csv as pa_csv
 import pyarrow.parquet as pq
 
 from behaviorgpt._exceptions import UnboxAIError
 from behaviorgpt.resources._shared import handle_response
 from behaviorgpt.types import (
     AddItemsJobDetails,
+    CatalogSummary,
     EmbedJobDetails,
     JobStatus,
     SimilarItemsRequest,
@@ -93,6 +98,79 @@ def check_catalog_schema(path: Path) -> None:
         )
 
 
+LIST_COLUMNS: dict[str, type] = {
+    "sales_since": int,
+    "search_keywords": str,
+    "keywords": str,
+}
+
+
+def _parse_list(column: str, cell: Optional[str]) -> Optional[list]:
+    """`[1, 2]` or `a, b` as a list of the column's item type; empty is null."""
+    if cell is None or not cell.strip():
+        return None
+    cast = LIST_COLUMNS[column]
+    try:
+        items = (
+            ast.literal_eval(cell) if cell.strip().startswith("[") else cell.split(",")
+        )
+        return [cast(str(item).strip()) for item in items if str(item).strip()]
+    except (ValueError, SyntaxError) as exc:
+        raise UnboxAIError(f"{column}: cannot read {cell!r} as a list") from exc
+
+
+def catalog_from_csv(
+    csv_path: Path | str, parquet_path: Optional[Path | str] = None
+) -> Path:
+    """Convert a CSV with the columns of docs/catalog-format.md to a catalog
+    parquet, check it and return its path.
+
+    Every cell is read as text, so prices keep their formatting. List columns
+    take `[1, 2]` or `a, b`. Empty cells, and columns the CSV lacks, become
+    null; other columns are left out. Duplicate ids keep their first row. The
+    parquet goes next to the CSV unless `parquet_path` is given; its file name
+    becomes the catalog's name.
+    """
+    csv_path = Path(csv_path)
+    out = Path(parquet_path) if parquet_path else csv_path.with_suffix(".parquet")
+    try:
+        table = pa_csv.read_csv(
+            csv_path,
+            convert_options=pa_csv.ConvertOptions(
+                column_types={column: pa.string() for column in CATALOG_SCHEMA},
+                include_columns=list(CATALOG_SCHEMA),
+                include_missing_columns=True,
+                strings_can_be_null=True,
+            ),
+        )
+    except pa.ArrowInvalid as exc:
+        raise UnboxAIError(f"{csv_path} is not a readable CSV file: {exc}") from exc
+
+    first_rows = {}
+    for row, item_id in enumerate(table.column("id").to_pylist()):
+        first_rows.setdefault(item_id, row)
+    table = table.take(sorted(first_rows.values()))
+
+    columns = {}
+    for column, expected in CATALOG_SCHEMA.items():
+        values = table.column(column)
+        if column in LIST_COLUMNS:
+            values = pa.array(
+                [_parse_list(column, cell) for cell in values.to_pylist()],
+                type=expected,
+            )
+        elif expected != pa.string():
+            try:
+                values = pc.cast(values, expected)
+            except pa.ArrowInvalid as exc:
+                raise UnboxAIError(f"{column}: expected {expected}: {exc}") from exc
+        columns[column] = values
+
+    pq.write_table(pa.table(columns, schema=pa.schema(CATALOG_SCHEMA)), out)
+    check_catalog_schema(out)
+    return out
+
+
 def format_reference_time(reference_time: datetime | str) -> str:
     """Format `reference_time` for the upload; a `datetime` must be timezone-aware."""
     if isinstance(reference_time, str):
@@ -133,6 +211,16 @@ def items_path(catalog_id: str) -> str:
     return f"/catalogs/{catalog_id}/items"
 
 
+def catalog_path(catalog_id: str) -> str:
+    if not catalog_id:
+        raise ValueError("catalog_id is required to delete a catalog")
+    return f"/catalogs/{quote(catalog_id, safe='')}"
+
+
+def catalog_summaries(response: httpx.Response) -> list[CatalogSummary]:
+    return [CatalogSummary(**c) for c in handle_response(response)["catalogs"]]
+
+
 def similar_items_body(
     item_id: str, catalog_id: str, limit: int, offset: int, filters: Optional[dict]
 ) -> dict:
@@ -405,6 +493,12 @@ class Catalogs:
     def get_umap(self, *, catalog_id: str):
         return umap_page(self._client.get(f"/{catalog_id}/umap"))
 
+    def list_catalogs(self) -> list[CatalogSummary]:
+        return catalog_summaries(self._client.get("/catalogs"))
+
+    def delete_catalog(self, catalog_id: str) -> None:
+        handle_response(self._client.delete(catalog_path(catalog_id)))
+
 
 class AsyncCatalogs:
     """The async counterpart of `Catalogs`; see it for what each method does."""
@@ -520,3 +614,9 @@ class AsyncCatalogs:
 
     async def get_umap(self, *, catalog_id: str) -> str:
         return umap_page(await self._client.get(f"/{catalog_id}/umap"))
+
+    async def list_catalogs(self) -> list[CatalogSummary]:
+        return catalog_summaries(await self._client.get("/catalogs"))
+
+    async def delete_catalog(self, catalog_id: str) -> None:
+        handle_response(await self._client.delete(catalog_path(catalog_id)))

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/resources/requests.py

@@ -25,6 +25,7 @@ class UnboxAIRequester:
         register_event: bool = False,
         timestamp: Optional[datetime] = None,
         num_candidates: Optional[int] = None,
+        max_trailing_searches: Optional[int] = None,
     ) -> UnboxAIRequest:
         return UnboxAIRequest(
             query=query,
@@ -38,4 +39,5 @@ class UnboxAIRequester:
             register_event=register_event,
             timestamp=timestamp,
             num_candidates=num_candidates,
+            max_trailing_searches=max_trailing_searches,
         )

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/types/__init__.py

@@ -16,6 +16,7 @@ from behaviorgpt.types.events import (
 )
 from behaviorgpt.types.http import (
     AddItemsJobDetails,
+    CatalogSummary,
     EmbedJobDetails,
     Item,
     ItemsPage,
@@ -42,6 +43,7 @@ __all__ = [
     "SimilarItemsRequest",
     "EmbedJobDetails",
     "AddItemsJobDetails",
+    "CatalogSummary",
     "JobStatus",
     "ItemsRejected",
     "RejectedItem",

{behaviorgpt-0.2.2 → behaviorgpt-0.4.0}/src/behaviorgpt/types/http.py

@@ -56,6 +56,10 @@ class UnboxAIRequest(BaseModel):
     timestamp: Optional[datetime] = None
     # How many nearest-neighbour candidates the server explores.
     num_candidates: Optional[int] = Field(default=None, gt=0, le=5_000)
+    # Search only: how many searches in a row at the end of the history, the
+    # query included, reach the model. Unset, the deployment's history settings
+    # apply.
+    max_trailing_searches: Optional[int] = Field(default=None, ge=1, le=10)
 
     @field_validator("timestamp")
     @classmethod
@@ -148,6 +152,17 @@ class AddItemsJobDetails(EmbedJobDetails):
     products: int
 
 
+class CatalogSummary(BaseModel):
+    catalog_id: str
+    # display label derived from the uploaded file name, server-side
+    catalog_name: str
+    # 'pending', 'ready' or 'failed'; shared catalogs are listed only when ready
+    status: str
+    # uploaded with this API key, so it counts against the key's catalog slots
+    # and this key can delete it
+    owned: bool
+
+
 class SimilarItemsRequest(BaseModel):
     model_config = ConfigDict(serialize_by_alias=True)