behaviorgpt 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: behaviorgpt
-Version: 0.2.2
+Version: 0.3.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,7 +123,7 @@ 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.
+- 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, and it has to be converted to the parquet structure described in the format doc before upload.
 
 ```python
@@ -146,6 +146,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.3.0}/README.md

@@ -106,7 +106,7 @@ 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.
+- 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, and it has to be converted to the parquet structure described in the format doc before upload.
 
 ```python
@@ -129,6 +129,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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "behaviorgpt"
-version = "0.2.2"
+version = "0.3.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.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "behaviorgpt"
-version = "0.2.2"
+version = "0.3.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.3.0}/src/behaviorgpt/_client.py

@@ -18,6 +18,7 @@ from behaviorgpt.types import (
     AddItemsJobDetails,
     AddToCart,
     CartItem,
+    CatalogSummary,
     Domains,
     EmbedJobDetails,
     Item,
@@ -290,6 +291,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,
@@ -454,6 +471,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.3.0}/src/behaviorgpt/resources/catalogs.py

@@ -4,6 +4,7 @@ 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
@@ -13,6 +14,7 @@ from behaviorgpt._exceptions import UnboxAIError
 from behaviorgpt.resources._shared import handle_response
 from behaviorgpt.types import (
     AddItemsJobDetails,
+    CatalogSummary,
     EmbedJobDetails,
     JobStatus,
     SimilarItemsRequest,
@@ -133,6 +135,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 +417,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 +538,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.3.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.3.0}/src/behaviorgpt/types/http.py

@@ -148,6 +148,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)