Metadata-Version: 2.4
Name: recapi
Version: 0.4.6
Summary: Python client for the recapi recommendation API: per-user history, event batching, retries, popular fallback.
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# recapi for Python

Python client for the recapi recommendation API, for servers: Django,
Flask, FastAPI, workers and scripts. Python ≥ 3.11, standard library only:
installing it never adds a dependency to your application.

It does what the JS SDK does in a browser, for every user of your server: it
keeps each user's **history** and sends it with every recommendation request
(recommendations follow the latest click, and recapi doesn't look the user
up), **batches events** in the background (up to 1,000 per request, an
idempotency key each, retries with backoff), **falls back to popular items**
when recapi is slow or failing, and **attributes** events on recommended items
to the recommendation that showed them (the dashboard's clicks and conversions).

## Install

The library is on PyPI, with no dependencies: install it with pip, or add
`recapi` to your `requirements.txt`.

```sh
pip install recapi
```

Production releases publish each version there
([docs/deployment.md](../../docs/deployment.md#publishing-the-libraries)).
Your recapi API serves the same library, for servers that can't reach PyPI
(the dashboard's quick start shows the line with your API's address):

```sh
pip install https://api.<your-domain>/sdk/python/recapi-0.4.6-py3-none-any.whl
```

To work on the library itself, install it from a checkout of this repository
(`pip install ./sdk/python`).

## Quick start

```python
import recapi

# One client per process, created at start-up. Use a secret key: it stays on
# your server.
client = recapi.Client("rk_sec_…", "https://api.example.com")

# Describe your items (a product, an article, a video…), 1,000 per request.
# metadata is yours (up to 2 KB) and comes back with the item in every list.
item = {"item_id": "item-42", "tags": ["sports"], "title": "Cup final highlights"}
item["metadata"] = {"name": "Cup final highlights", "url": "/videos/42"}
client.upsert_items([item])

# The user opened an item (level 3). Queued and sent in the background.
client.track("item-42", "view", user_id="user-881")

# Recommendations for that user. If recapi is slow or failing or a limit is
# reached, this returns popular items instead (result.fallback is True), and an
# empty list if those fail too or the key is refused (hide the slot): no
# try/except.
# item.why says why it is listed, safe to show anyone (docs/api.md, "Reason
# codes"): pick your own words, no label for codes you don't map.
LABELS = {
    "for_you": "Picked for you",
    "similar": "Similar items",
    "next": "Up next",
    "bought_together": "Often bought together",
    "trending": "Trending now",
    "popular": "Popular",
    "new": "New",
}
result = client.recommend(user_id="user-881", placement="homepage", count=4)
for item in result.items:
    print(item.item_id, item.slot, item.metadata)  # metadata: a dict, or None
    label = LABELS.get(item.why)  # "Trending now"..., None: show no label

# The user clicks a recommended item: track it as usual. The event carries
# the recommendation's id by itself (within 30 minutes of the display, then
# for 24 hours after the click).
client.track("item-77", "view", user_id="user-881")
```

Levels follow the [recommended scale](../../docs/api.md#interaction-levels):
`"view"` (3), `"cart"` (5), `"purchase"` (10), or any integer from -10 to 10
(`track("article-9", 5, …)` for an article read to the end); 0 is an
impression. `"reject"` (-10) is an explicit "not interested": the item is never
recommended to that user again until a positive event on it. Visitors who are
not logged in: pass a stable `anon_id` instead of `user_id`, a random id kept
in their session or a cookie (`secrets.token_hex(16)`), never the session id
itself: recapi stores the `anon_id` and the dashboard shows it. Call
`client.identify(anon_id, user_id)` when they log in: their history and the
items they were shown become the user's, so what they did before logging in
keeps counting.

## Where the history lives

By default each process keeps its users' state in memory (the 10,000 most
recently seen users). That is enough for one process. When several
processes or servers serve the same users, give them a shared store: any
object with `get(key)`, `set(key, value)` (strings) and `delete(key)` works,
such as a Redis client or Django's Redis or Memcached cache.

```python
client = recapi.Client("rk_sec_…", "https://api.example.com", store=redis.Redis())
# or, in Django with one of those caches (from django.core.cache import cache):
client = recapi.Client("rk_sec_…", "https://api.example.com", store=cache)
```

Written to a redis-py client or Django's cache, a user's state lasts 30 days
from its last write, with no setting to choose: well past the 24 hours a click
earns credit, and recapi gives a known `user_id` its history back afterwards.
Without it, Django would drop the state after its default 5 minutes, taking the
click's credit with it, and Redis would keep it for ever. Any other store gets a
plain `set(key, value)`: make it expire entries itself after about 30 days.

Not every Django cache can hold this. The library recognises Django's own
classes (a subclass of one is left alone) and logs one line at start:

| Django cache | What happens | Shared between |
|---|---|---|
| `RedisCache`, `PyMemcacheCache`, `PyLibMCCache` | used, no line | servers |
| `FileBasedCache` | used, with a warning: it holds 300 entries by default | one server's processes |
| `LocMemCache` (Django's default) | the library's own store instead, with a warning | nothing |
| `DummyCache` | the library's own store instead, with a warning | nothing |

A user the store doesn't know yet (a new process, an evicted user, another
server) still gets personalised results: the request then has no history,
recapi uses the history it keeps from that user's events, and returns it with
the recommendations; the client stores it for the next calls. If the store's
first call for that user was a `track()` or an `identify()`, the first
`recommend()` fetches that history (`GET /v1/users/{id}/history`, unbilled)
with half of its 1.5 s and merges it with what was tracked here (after an
`identify()`, without the visitor's browsing, which is already merged here); a
failed fetch is tried again on the next call. This works for `user_id` only, and
only with a secret key. A store that fails
(Redis down) is logged and skipped: tracking and recommendations go on.
Updates to one user are serialised within a process only: two processes
updating the same user in the same instant can lose one of the two changes to
the stored history (never the event itself, which recapi still receives).

Each user's state is a small JSON value (at most 50 weighted items, 20
recent, 200 rejections and 100 shown items) under
`recapi:<hash of the API key>:u:<user_id>` (`:a:<anon_id>` for visitors), so a
test and a production key never share entries.

## Processes and shutdown

Create the client once per process; it is thread-safe, and a forked child
(gunicorn, uWSGI) starts with an empty queue of its own. Queued events are
sent at interpreter exit (one try, so a deploy never waits on an outage).
Short-lived jobs and serverless handlers call `client.flush()` before they
return: it sends everything now, with retries.

The client keeps its connections to recapi open between calls (one per call
in flight at the busiest moment, up to 16), so a call pays the TLS handshake
once, not every time (at 10 ms from the API, a `recommend` takes 13 ms instead
of 43). A connection the API closed while idle is replaced on the next call.
`HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are honoured. Redirects are not
followed: a 3xx fails like a 4xx, so `base_url` must be the API's own address
(`https://` in production).

## asyncio (FastAPI, async Django)

In an `async def` handler, a blocking call would stop every other request of
the worker while it waits. `recapi.AsyncClient` takes the same arguments as
`Client` and has the same methods, as coroutines. Its calls run on a few
threads of its own, and `recommend`'s 1.5 s count from the `await`: a call
that finds no free thread by then returns popular items.

```python
import recapi
from fastapi import FastAPI

client = recapi.AsyncClient("rk_sec_…", "https://api.example.com")
app = FastAPI()


@app.get("/home")
async def home(user_id: str):
    result = await client.recommend(user_id=user_id, placement="homepage", count=4)
    return [item.item_id for item in result.items]
```

In plain `def` handlers and sync Django views, keep `Client`.

## Page caches

A page cache (Django's `cache_page` or per-site cache middleware, Varnish, a
CDN) stores a page's HTML and serves it to every visitor. A list
`recommend()` rendered into that HTML is then one visitor's list, under one
recommendation id, shown to everyone: no personalisation, no new items
tried, and clicks and experiments counted against that one list. Render the
recommendations in the browser with the JS library (the script tag in the
dashboard's quick start), or from a fragment the page cache leaves out: an
uncached view called by AJAX that runs `recommend()`. Never cache a
`recommend()` result across visitors. The dashboard's Overview warns when
one recommendation id collects the events of many users ("Page caches").

## Reference

| Method | What it does |
|---|---|
| `track(item_id, level, *, user_id=None, anon_id=None, recommendation_id=None)` | Updates the user's history at once and queues the event. `recommendation_id` overrides the automatic attribution. Raises `ValueError` for an invalid level or user, visitor or recommendation id. An `item_id` the API would refuse (1-256 bytes of UTF-8, no control character; `None` or no string at all too) drops the event with a log line: no exception, and the other events are sent as usual |
| `recommend(*, user_id=None, anon_id=None, count=0, placement=None, tags_any=None, tags_all=None, exclude=None, context_item_id=None, discovery=None)` | Returns `Recommendations(recommendation_id, fallback, items)`, each item `Item(item_id, score, slot, metadata, why)`. `metadata` is the dict stored with the item ([Item metadata](../../docs/api.md#item-metadata)), None when it has none; `why` its [reason code](../../docs/api.md#reason-codes). The user's rejected items are added to `exclude`. At most 1.5 s; on a network error, timeout, 5xx or 429 it returns popular items (`fallback` True, no id), or no item when those fail too; on a 401 or 403 no item at once. A `context_item_id` the API would refuse (no string at all too) isn't sent: you get the same popular list and a log line, with no recommendation request. Any other failure (a bad request, a reply that isn't the API's) raises |
| `popular(*, count=10, tags_any=None, tags_all=None)` | Popular items (`Item`, metadata and `why` included), for pages without a user. On a network error, timeout, 5xx, 429, 401 or 403: an empty list and a log line. Other failures as in `recommend` |
| `upsert_items(items)` | Creates or replaces items (dicts with the [item fields](../../docs/api.md#put-v1itemsitem_id--secret-key)), 1,000 per request, with retries. Returns how many were stored |
| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry. The user's first restore from recapi then leaves that visitor's browsing out, so it doesn't count twice |
| `delete_user(user_id)` | Erases the user's events in recapi (GDPR) and their state in the store |
| `flush()` / `close()` | Send queued events now; `close()` also stops the background sender |

`Client(api_key, base_url, *, store=None, timeout=5.0, flush_interval=2.0,
max_batch=1000)`: `timeout` per request in seconds (`recommend` waits at most
1.5 s). `AsyncClient` takes the same arguments. Errors are `recapi.RecapiError` (`code`, `status`, `retryable`);
`recommend` and `popular` raise only on a bad request (another 400, 404, 413, other
3xx/4xx) or a reply that isn't the API's (`invalid_response`, such as a
`base_url` pointing at a web page): neither can start on a live site without a
deploy. On a network error, a timeout, a 5xx or a 429 `recommend` returns popular
items, or an empty list when `/v1/popular` fails too; on a 401 or 403 (a revoked
key, a suspended shop) an empty list at once, as `/v1/popular` would refuse the
same key; `popular` returns an empty list for all of these. Each failed call logs
one warning with the API's message to the `recapi` logger: a wrong key shows
there, not as an exception.
A page often takes a product id from a visitor's URL, so a crafted link can carry
an id the API would refuse. It raises nowhere: `recommend` never sends such a
`context_item_id` and answers with popular items, and `track` drops that event
alone. Each logs one warning, which never quotes the id. An empty or `None`
`context_item_id` just means none.
Background failures go to the `recapi` logger: refused events are dropped, a
batch that can succeed later is retried with backoff (up to 10,000 queued).

The API builds the wheel from `recapi/*.py` and `pyproject.toml`, and pip
caches its URL for a year: a change there needs a new `version` in
`pyproject.toml` and `__version__` in `recapi/client.py`, and a new entry in
`published.json` (the Go test `TestWheelChangesNeedANewVersion` prints it).
An older version's URL then installs the new one, so the library's public
methods and their arguments only grow.

Tests: `cd sdk/python && python3 -m unittest discover -s tests`. They run the
shared vectors of the [history spec](../../docs/history-spec.md) and of the
behaviour every library shares (`spec/client_vectors.json`) against a local
HTTP server.
