[bruel-gabrielsson]

umap() now takes catalog_ids=: one map of several catalogs, one colour each, drawn by the API on request (Unbox-AI/unbox-api#595, deployed).

page = client.umap(catalog_ids=[job.catalog_id, "retail_catalog"], wait=300)

• It posts to /maps, then polls GET /maps/{map_id} every 5 s until the map is ready or wait runs out, then returns the page.
  • A failed map raises UnboxAIError with the API's reason.
  • A map still being drawn at the deadline raises with status 202, carrying the map_id.
• It works at any size: above 100,000 items every catalog is sampled evenly. So umap(catalog_ids=["retail_catalog"]) maps the shared catalog too, which never had a map before.
• For apps that draw their own map, client.catalogs gains create_map, get_map, get_map_page and get_map_points, sync and async. CatalogMap is in behaviorgpt.types.
• Docs: a README example next to catalog_ids, and a paragraph in docs/catalog-format.md.

Tests: tests/test_maps.py covers ready, waiting, the deadline, failure, catalog errors, the argument checks, the resource and the async client. 197 pass. Checked against production: a map of sygrid, photowall and art, 61,252 items.