recapi 0.4.1__py3-none-any.whl

recapi/history.py

@@ -0,0 +1,269 @@
+"""Decayed user history, exactly as docs/history-spec.md (times in unix ms).
+
+A port of ``sdk/js/src/history.js``, snapshot merging included (which the
+trainer's copy doesn't need); ``spec/history_vectors.json`` keeps them equal.
+"""
+
+from __future__ import annotations
+
+import copy
+import math
+import re
+from typing import Any
+
+HALF_LIFE_SECONDS = 604800
+TOP_K = 50
+RECENT_SIZE = 20
+REJECTED_SIZE = 200
+MAX_ID_BYTES = 256
+
+_RATE = math.log(2) / HALF_LIFE_SECONDS
+# Go's unicode.IsControl, which the API applies to every id: C0, DEL and C1.
+_CONTROL = re.compile("[\x00-\x1f\x7f-\x9f]")
+
+
+def is_id(value: object) -> bool:
+    """Return whether the API accepts ``value`` as an id: 1-256 bytes of UTF-8, no controls."""
+    if not isinstance(value, str) or not value or _CONTROL.search(value):
+        return False
+    try:
+        return len(value.encode("utf-8")) <= MAX_ID_BYTES
+    except UnicodeEncodeError:  # a lone surrogate
+        return False
+
+
+def _decay(dt_ms: float) -> float:
+    return math.exp(-_RATE * (dt_ms / 1000))
+
+
+def _is_weight(value: object) -> bool:
+    return _is_time(value) and value >= 0
+
+
+def _is_time(value: object) -> bool:
+    return isinstance(value, int | float) and not isinstance(value, bool) and math.isfinite(value)
+
+
+class History:
+    """One user's history: weighted top, recent list and rejection marks.
+
+    ``top`` maps item -> (score, t), ``recent`` is (item, t) oldest first,
+    ``rejected`` maps item -> time of the newest rejection, ``last_t`` is the
+    newest event applied to the recent list (None when unknown).
+    """
+
+    __slots__ = ("last_t", "recent", "rejected", "top")
+
+    def __init__(self) -> None:
+        self.top: dict[str, tuple[float, float]] = {}
+        self.recent: list[tuple[str, float]] = []
+        self.rejected: dict[str, float] = {}
+        self.last_t: float | None = None
+
+    def is_empty(self) -> bool:
+        """Return whether there is nothing to send, so the server uses its stored history.
+
+        Rejections alone don't count: the server still has the user's positive
+        events, and it excludes both sets.
+        """
+        return not self.top and not self.recent
+
+    def apply(self, item: str, level: int, t: float) -> None:
+        """Apply one event: level 0 changes nothing, a negative level is a rejection."""
+        if level == 0:
+            return
+        if level < 0:
+            self._reject(item, t)
+            return
+        mark = self.rejected.get(item)
+        if mark is not None:
+            if t < mark:
+                return
+            del self.rejected[item]
+        current = self.top.get(item)
+        if current is None:
+            self.top[item] = (float(level), t)
+        elif t >= current[1]:
+            self.top[item] = (current[0] * _decay(t - current[1]) + level, t)
+        else:
+            self.top[item] = (current[0] + level * _decay(current[1] - t), current[1])
+        if self.last_t is None or t >= self.last_t:
+            self.recent = [entry for entry in self.recent if entry[0] != item]
+            self.recent.append((item, t))
+            self.recent = self.recent[-RECENT_SIZE:]
+            self.last_t = t
+        self._prune(t)
+
+    def _reject(self, item: str, t: float) -> None:
+        # Dropped, not lowered: a lowered score would decay back towards 0.
+        current = self.top.get(item)
+        if current is not None and current[1] > t:
+            return
+        self.top.pop(item, None)
+        self.recent = [entry for entry in self.recent if entry[0] != item]
+        self.rejected[item] = max(t, self.rejected.get(item, t))
+        self._prune_rejected()
+
+    def ranked(self, now: float) -> list[tuple[str, float, float]]:
+        """Return (item, weight at ``now``, t) by weight desc, ties by item id asc."""
+        entries = [(item, s * _decay(now - t), t) for item, (s, t) in self.top.items()]
+        entries.sort(key=lambda e: (-e[1], e[0]))
+        return entries
+
+    def rejected_order(self) -> list[str]:
+        """Return the rejected items, oldest mark first, ties by item id."""
+        return sorted(self.rejected, key=lambda item: (self.rejected[item], item))
+
+    def _prune(self, now: float) -> None:
+        if len(self.top) > TOP_K:
+            self.top = {item: self.top[item] for item, _, _ in self.ranked(now)[:TOP_K]}
+
+    def _prune_rejected(self) -> None:
+        if len(self.rejected) > REJECTED_SIZE:
+            kept = self.rejected_order()[-REJECTED_SIZE:]
+            self.rejected = {item: self.rejected[item] for item in kept}
+
+    def wire(self, now: float) -> tuple[list[list[Any]], list[str], list[str]]:
+        """Return the request's ``history`` and ``recent``, and the rejected items.
+
+        Weights are decayed to ``now`` and rounded half up to 4 decimals like
+        JS ``Math.round`` (Python's ``round`` rounds half to even); ages are
+        whole seconds, never negative.
+        """
+        history = [
+            [item, math.floor(weight * 1e4 + 0.5) / 1e4, max(0, math.floor((now - t) / 1000))]
+            for item, weight, t in self.ranked(now)[:TOP_K]
+        ]
+        recent = [item for item, _ in self.recent[-RECENT_SIZE:]]
+        return history, recent, self.rejected_order()
+
+    @classmethod
+    def from_snapshot(cls, snapshot: object) -> History:
+        """Build a history from the server's snapshot, skipping invalid entries.
+
+        Each top entry is a score at ``as_of``, each rejected item a mark at
+        ``as_of``. ``last_t`` stays unknown: ``as_of`` is the server clock, and a
+        local clock behind it would see every new event as out of order.
+        """
+        state = cls()
+        if not isinstance(snapshot, dict) or not _is_time(snapshot.get("as_of")):
+            return state
+        as_of = snapshot["as_of"]
+        for e in _list(snapshot.get("top")):
+            if isinstance(e, list) and len(e) >= 2 and is_id(e[0]) and _is_weight(e[1]):
+                state.top[e[0]] = (float(e[1]), as_of)
+        seen: set[str] = set()
+        for item in _list(snapshot.get("recent")):
+            if is_id(item) and item not in seen:
+                seen.add(item)
+                state.recent.append((item, as_of))
+        state.recent = state.recent[-RECENT_SIZE:]
+        for item in _list(snapshot.get("rejected")):
+            if is_id(item):
+                state.rejected[item] = as_of
+        state._prune(as_of)
+        state._prune_rejected()
+        return state
+
+    def merge(self, other: History, now: float) -> History:
+        """Return the union of two histories built from disjoint events.
+
+        Top scores add up, expressed at the later of the two times; the recent
+        lists are interleaved by time (``self`` first on ties); rejection marks
+        are united, and a mark older than the item's merged entry is dropped,
+        otherwise the item leaves the top and the recent list.
+        """
+        out = History()
+        out.top = dict(self.top)
+        for item, (s, t) in other.top.items():
+            mine = out.top.get(item)
+            if mine is None:
+                out.top[item] = (s, t)
+                continue
+            later = max(t, mine[1])
+            out.top[item] = (s * _decay(later - t) + mine[0] * _decay(later - mine[1]), later)
+
+        out.rejected = dict(self.rejected)
+        for item, t in other.rejected.items():
+            out.rejected[item] = max(t, out.rejected.get(item, t))
+        for item, t in list(out.rejected.items()):
+            entry = out.top.get(item)
+            if entry is not None and entry[1] > t:
+                del out.rejected[item]
+            else:
+                out.top.pop(item, None)
+
+        by_item: dict[str, tuple[float, int]] = {}
+        for order, (item, t) in enumerate([*self.recent, *other.recent]):
+            existing = by_item.get(item)
+            if existing is None or t > existing[0]:
+                by_item[item] = (t, order)
+        # Rejected items go before the trim, so they don't cost the list its places.
+        kept = sorted(
+            ((t, order, item) for item, (t, order) in by_item.items() if item not in out.rejected)
+        )
+        out.recent = [(item, t) for t, _, item in kept[-RECENT_SIZE:]]
+
+        times = [t for t in (self.last_t, other.last_t) if t is not None]
+        out.last_t = max(times) if times else None
+        out._prune(now)
+        out._prune_rejected()
+        return out
+
+    def merge_snapshot(self, snapshot: History, now: float) -> History:
+        """Merge a server snapshot, keeping the items rejected here rejected.
+
+        The snapshot dates its scores ``as_of``, which only bounds when its
+        events happened; a local rejection is usually one the server hasn't
+        stored yet, so it wins over the snapshot's score.
+        """
+        trimmed = copy.copy(snapshot)
+        trimmed.top = {k: v for k, v in snapshot.top.items() if k not in self.rejected}
+        return self.merge(trimmed, now)
+
+    def encode(self) -> dict[str, Any]:
+        """Return the JSON-safe stored form (raw scores), shaped like JS ``encodeState``."""
+        return {
+            "top": [[item, s, t] for item, (s, t) in self.top.items()],
+            "recent": [[item, t] for item, t in self.recent],
+            "rejected": [[item, t] for item, t in self.rejected.items()],
+            "lastT": self.last_t,
+        }
+
+    @classmethod
+    def decode(cls, raw: object) -> History | None:
+        """Inverse of :meth:`encode`; None for any malformed field.
+
+        A state stored before rejections existed has no ``rejected``.
+        """
+        if not _valid_encoding(raw):
+            return None
+        assert isinstance(raw, dict)
+        state = cls()
+        state.top = {item: (float(s), t) for item, s, t in raw["top"]}
+        state.recent = [(item, t) for item, t in raw["recent"]]
+        state.rejected = {item: t for item, t in raw.get("rejected", [])}
+        state.last_t = raw["lastT"]
+        state._prune_rejected()
+        return state
+
+
+def _valid_encoding(raw: object) -> bool:
+    if not isinstance(raw, dict) or "lastT" not in raw:
+        return False
+    top, recent, rejected = raw.get("top"), raw.get("recent"), raw.get("rejected", [])
+    if not all(isinstance(v, list) for v in (top, recent, rejected)):
+        return False
+    return (
+        (raw["lastT"] is None or _is_time(raw["lastT"]))
+        and all(_pair(e, 3) and _is_weight(e[1]) and _is_time(e[2]) for e in top)
+        and all(_pair(e, 2) and _is_time(e[1]) for e in [*recent, *rejected])
+    )
+
+
+def _list(value: object) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _pair(entry: object, size: int) -> bool:
+    return isinstance(entry, list) and len(entry) == size and is_id(entry[0])

recapi-0.4.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+recapi/__init__.py,sha256=dBZomX78DpCBWvfyqQ1AZu1qeLWuDIdeHyNCowqMjG4,1023
+recapi/async_client.py,sha256=4Ih_busG8XNFlfePsZNnksTGkihLGGX_nzF-zUTr3lY,4040
+recapi/client.py,sha256=N-Yr06fcMgr7rGVn4tzzXIuQXCsYZDB0_jmR_LuRxWA,41339
+recapi/history.py,sha256=G_IDP8hTZYatx1n_wTLUG9Xvxum8xcfP44RTDCb81O4,10717
+recapi-0.4.1.dist-info/licenses/LICENSE,sha256=XykRbxi-optoQKGLtp2z4VTCzFHPzAqWSrnnwo2wIgA,1063
+recapi-0.4.1.dist-info/METADATA,sha256=1TUCLErII3a_OxSGprQJXDTTEI8V8QVsxhBgVeToFY0,11025
+recapi-0.4.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+recapi-0.4.1.dist-info/top_level.txt,sha256=kG0cd06DOh-xlw4tYZWttzEO4zjkDIlMvrw7XnuWsg8,7
+recapi-0.4.1.dist-info/RECORD,,

recapi-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

recapi-0.4.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+recapi