recapi 0.4.1__tar.gz

recapi-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recapi-0.4.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: recapi
+Version: 0.4.1
+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.1-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; 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 |
+| `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.

recapi-0.4.1/README.md

@@ -0,0 +1,202 @@
+# 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.1-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; 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 |
+| `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.

recapi-0.4.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recapi"
+version = "0.4.1"
+description = "Python client for the recapi recommendation API: per-user history, event batching, retries, popular fallback."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+license = { text = "MIT" }
+
+[tool.setuptools]
+packages = ["recapi"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "N", "SIM", "RUF", "PL", "D"]
+# Magic methods and __init__ are documented on the class; recommend() mirrors
+# the API's request fields as keywords; small thresholds read better inline.
+ignore = ["D105", "D107", "PLR0913", "PLR2004"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D", "PLR2004", "N806", "PLC0415"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["recapi", "fakeapi"]

recapi-0.4.1/recapi/__init__.py

@@ -0,0 +1,38 @@
+"""recapi: recommendations for any site or app with a catalog.
+
+Quick start::
+
+    import recapi
+
+    client = recapi.Client("rk_sec_...", "https://api.example.com")
+    client.track("item-42", "view", user_id="user-1")
+    recs = client.recommend(user_id="user-1", count=4)
+
+In asyncio apps (FastAPI), ``recapi.AsyncClient`` has the same methods as
+coroutines. See ``sdk/python/README.md``.
+"""
+
+from typing import Any
+
+from .client import Client, Item, MemoryStore, RecapiError, Recommendations, Store, __version__
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "Item",
+    "MemoryStore",
+    "RecapiError",
+    "Recommendations",
+    "Store",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # asyncio takes longer to import than the rest of the library: only the
+    # apps that use AsyncClient pay for it.
+    if name == "AsyncClient":
+        from .async_client import AsyncClient  # noqa: PLC0415
+
+        return AsyncClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

recapi-0.4.1/recapi/async_client.py

@@ -0,0 +1,95 @@
+"""The recapi client for asyncio apps (FastAPI, async Django), standard library only.
+
+Every method of :class:`Client` runs on a small thread pool of the client's
+own, so a slow recapi never blocks the event loop, and the client's
+connections to recapi stay open between calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import os
+import time
+import weakref
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from .client import Client, Item, Recommendations, _call
+
+# Calls in flight per process. A call takes a few milliseconds of a thread,
+# so 8 serve hundreds of recommendations a second; past that they queue, and
+# recommend() falls back by its deadline.
+THREADS = 8
+
+
+class AsyncClient:
+    """A :class:`Client` whose methods are coroutines; same arguments, same behaviour.
+
+    Create one per process. recommend()'s 1.5 s count from the ``await``: a
+    call still waiting for a free thread then goes straight to popular items.
+    """
+
+    def __init__(self, api_key: str, base_url: str, **options: Any) -> None:
+        self._client = Client(api_key, base_url, **options)
+        self._init_pool()
+        if hasattr(os, "register_at_fork"):
+            ref = weakref.ref(self)
+            os.register_at_fork(after_in_child=lambda: _call(ref, "_init_pool"))
+
+    def _init_pool(self) -> None:
+        # Also in a forked child, which has none of the parent's threads.
+        self._pool = ThreadPoolExecutor(THREADS, thread_name_prefix="recapi-async")
+
+    async def _run(self, fn: Any, *args: Any, **kwargs: Any) -> Any:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._pool, functools.partial(fn, *args, **kwargs))
+
+    async def recommend(self, **params: Any) -> Recommendations:
+        """Personalised recommendations: :meth:`Client.recommend`, same keywords."""
+        client = self._client
+        deadline = time.monotonic() + client._recommend_timeout
+        job = self._pool.submit(client._recommend, deadline, **params)
+        result = asyncio.wrap_future(job)
+        try:
+            return await asyncio.wait_for(asyncio.shield(result), client._recommend_timeout)
+        except TimeoutError:
+            if not job.cancel():
+                return await result  # running: its own deadline has passed too
+        except asyncio.CancelledError:
+            job.cancel()
+            raise
+        # Every thread was still busy at the deadline: don't wait for one to
+        # serve the fallback. Past its deadline, the call asks only for popular items.
+        return await asyncio.to_thread(client._recommend, deadline, **params)
+
+    async def track(self, item_id: str, level: int | str, **ids: str | None) -> None:
+        """Record an interaction: :meth:`Client.track`."""
+        await self._run(self._client.track, item_id, level, **ids)
+
+    async def identify(self, anon_id: str, user_id: str) -> None:
+        """At login, the visitor's history becomes the user's: :meth:`Client.identify`."""
+        await self._run(self._client.identify, anon_id, user_id)
+
+    async def popular(self, **params: Any) -> list[Item]:
+        """Popular items: :meth:`Client.popular`."""
+        return await self._run(self._client.popular, **params)
+
+    async def upsert_items(self, items: Any) -> int:
+        """Create or replace items: :meth:`Client.upsert_items`."""
+        return await self._run(self._client.upsert_items, items)
+
+    async def delete_user(self, user_id: str) -> None:
+        """Erase a user (GDPR): :meth:`Client.delete_user`."""
+        await self._run(self._client.delete_user, user_id)
+
+    async def flush(self) -> None:
+        """Send every queued event now: :meth:`Client.flush`."""
+        await self._run(self._client.flush)
+
+    async def close(self) -> None:
+        """Send what is queued and stop the sender: :meth:`Client.close` (also runs at exit).
+
+        As with Client, later calls still work (their events are sent at once).
+        """
+        await self._run(self._client.close)