Metadata-Version: 2.4
Name: recapi
Version: 0.4.2
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

Your recapi API serves the library: install it with pip, or put the same URL
in your `requirements.txt`. No package index, no build step, no dependencies:

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

The dashboard's quick start shows this line with your API's address. 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, this returns
# popular items instead (result.fallback is True), and an empty list if
# recapi is down altogether (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 cache.

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

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 id or level |
| `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` |
| `popular(*, count=10, tags_any=None, tags_all=None)` | Popular items (`Item`, metadata and `why` included), for pages without a user |
| `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` raises only on a 3xx, 4xx or 429, or a reply that isn't the API's
(`invalid_response`, such as a `base_url` pointing at a web page): a fallback
would hide them. On a
network error, a timeout or a 5xx it returns popular items, or an empty list
when `/v1/popular` fails too, and logs the errors.
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.
