# BehaviorGPT

> BehaviorGPT is Unbox AI's model of behavior. Given what a person did (viewed, searched, chose, ordered), it predicts what they will do next, so search, recommendations, insights and risk scores all come from one call with different histories. It ranks catalogs it has never seen, with no training. You build with it through the Python SDK, the portal's API from any language, website and app widgets, an MCP server, or the model's raw API.

Getting started:

- Get a free API key at https://portal.unboxai.com by signing in with email. No card.
- Keep the key on a server, in the `UNBOXAI_API_KEY` environment variable. Never put it in code, in a prompt, in a page or in an app.
- Websites and phone apps use a publishable key (`ubx_pub_...`) instead, made on the portal's Events page. It is safe to ship: it only ranks and records events, and only from the sites and apps it lists.
- A catalog is the list of items to rank: products, artworks, articles, listings. Public sample catalogs are shared with every key, so you can start before uploading your own.
- Ranking reads a user's history. Either send it with each call (`history`, oldest first), or record events as they happen (the tracking script, or `POST /events`) and pass the `user_id`.

Pick the first path that fits. Each one handles the details the raw API asks for.

## Python

- [Python SDK](https://raw.githubusercontent.com/Unbox-AI/behaviorgpt/main/README.md): the recommended way. `pip install behaviorgpt`; `complete` ranks from a history, `client.shop` gives finished search results and shelves, `client.events` records what users do, `client.embed` uploads a catalog

## Any other language, from a server

- [Portal API (OpenAPI)](https://portal.unboxai.com/api/v1/openapi.json): at `https://portal.unboxai.com`, with the key as `Authorization: Bearer`. The ranking calls under `/api/v1/shop/` (suggest, search, browse, recommend, sections, item, visual) take a catalog, a `user_id` or a short `history`, and return finished items. Also links that open the apps on your catalogs, and embeds

## Websites and phone apps

- [Widgets](https://portal.unboxai.com/widgets/README.md): search, results, shelves, sections, search by picture and an assistant from one script tag; React and React Native hooks; Swift and Kotlin over plain JSON. With a publishable key
- [Tracking](https://portal.unboxai.com/track/README.md): record what users do on a website or in an app, so rankings read their history by `user_id`

## AI agents

- MCP server: `https://portal.unboxai.com/mcp`, with the header `Authorization: Bearer <key>`. Its tools search your catalogs, rank for a user's history, find what goes together and look items up. In Claude Code: `claude mcp add --transport http behaviorgpt https://portal.unboxai.com/mcp --header "Authorization: Bearer $UNBOXAI_API_KEY"`

## Your own catalog

- [Uploading a catalog, step by step](https://raw.githubusercontent.com/Unbox-AI/behaviorgpt/main/.claude/skills/embed-catalog/SKILL.md): turn any file (CSV, JSON, Excel, a feed) into a catalog and embed it
- [Catalog format](https://raw.githubusercontent.com/Unbox-AI/behaviorgpt/main/docs/catalog-format.md): the 15 columns a catalog file needs, and how to build it from a CSV
- [Catalogs](https://raw.githubusercontent.com/Unbox-AI/behaviorgpt/main/docs/catalogs.md): names and limits, updating items, several catalogs at once, keywords and sections

## Raw API (advanced)

- [Unbox AI API (OpenAPI)](https://behaviorgpt-northeurope.api.unboxai.com/v1/openapi.json): the model's own API at `https://behaviorgpt-northeurope.api.unboxai.com/v1`, with the key in `x-api-key`. Full control, and more to get right: every ranking call needs `store_id`, `domains` and `timezone` and exactly one of `history` or `user_id`. Ranking (`/vector/search`, `/vector/recommendations`, `/vector/similar_products`, `/vector/sections`), catalogs (`/embed-catalog`, `/catalogs`), events (`/events`) and maps. Use it when the paths above don't offer what you need

## Optional

- [Research](https://research.unboxai.com): how the model is trained and evaluated
- [SDK repository](https://github.com/Unbox-AI/behaviorgpt): source, examples and a notebook
- [Guides](https://portal.unboxai.com/build/): the same ways to build, for people (the page needs JavaScript; the docs above hold the same)