controlvar 0.1.1__tar.gz → 0.2.0__tar.gz

{controlvar-0.1.1 → controlvar-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlvar
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python client for the Controlvar public API (experiments, feature flags, event tracking)
 License: MIT
 Project-URL: Homepage, https://github.com/Controlvar/controlvar/tree/main/sdk/python#readme
@@ -42,11 +42,11 @@ else to install.
 
 If you installed `experimently`, the name this package had before the project was renamed, uninstall it and install `controlvar`.
 
-The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.1.1 is a
+The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.2.0 is a
 beta release. It installs and imports as `controlvar`.
 
 ```bash
-pip install controlvar==0.1.1
+pip install controlvar==0.2.0
 ```
 
 To work on the SDK itself, install it from the root of a clone of this repository instead:
@@ -55,6 +55,22 @@ To work on the SDK itself, install it from the root of a clone of this repositor
 pip install -e sdk/python
 ```
 
+## Changes in this version
+
+- `report_error()` is new: it sends one error report to the server and returns `True` when the
+  server stored it.
+- `track()` returns `True` when the event was sent and the server answered 2xx, and `False`
+  otherwise. Before this version, a `track()` without a key returned `True` only when the server
+  accepted every entry it was fanned out to. Now a batch answered 2xx returns `True` even when the
+  server refused one of its entries; `track_batch()` returns the per-entry results.
+- A `track()` without a key still reaches the experiments and flags this client answered for the
+  user in the last 24 hours (with the exceptions under Tracking fan-out rule) after their cached
+  answers expire; before this version it reached only the answers still in the cache. Those keys
+  are this client instance's only: an event tracked by another instance, in this process or
+  another, reaches none of them.
+- With nothing to reach, a `track()` without a key is now sent once with no key and stored as
+  history, and returns `True` on a 2xx; before this version it sent nothing and returned `False`.
+
 ## Quick start
 
 Set `CONTROLVAR_API_KEY` to an API key, then run the block as it is; the two `print` calls
@@ -95,16 +111,17 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 
 | Method | Returns | Failure behaviour |
 |---|---|---|
-| `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when the experiment is not ACTIVE) |
+| `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when no experiment has the key, or for a draft with no control variant); an experiment that is not ACTIVE returns its control variant with `assigned` False and `reason` its status |
 | `get_variant(experiment_key, user_id, user_attributes=None)` | `str` variant name | returns `default_variant` |
 | `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
 | `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
 | `get_all_flags(user_id, user_attributes=None)` | `dict[str, bool]` (not cached) | raises `ExperimentationError` |
-| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when accepted | never raises; `False` on failure or when nothing was sent |
+| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
 | `track_batch(events)` | `BatchResult(success_count, failure_count, errors)`; `.ok` | never raises; a failed chunk counts all its events as failures |
+| `report_error(error_type, message, *, feature_flag_key=None, experiment_key=None, user_id=None, stack_trace=None, metadata=None, timestamp=None)` | `bool` — `True` when the server stored the report (201) | never raises; `False` and a logged warning otherwise |
 | `get_assignments(user_id, active_only=True)` | `list[dict]` from the server | raises `ExperimentationError` |
 | `cached_assignments(user_id)` / `cached_flags(user_id)` | cached, unexpired entries | — |
-| `clear_cache()` | — | — |
+| `clear_cache()` | — (keeps the keys a key-less `track` is sent to) | — |
 | `ready(timeout_seconds=None)`, `status()`, `close()` / `with` | local mode: readiness, ruleset state, shutdown (sends evaluation counts) | never raise |
 | `consistent_hash(user_id, flag_key)` / `md5_hex(user_id, flag_key)` | cross-SDK MD5 bucket in `[0, 1)` / hex digest | pure functions; **not** the flag bucketing function |
 
@@ -119,6 +136,11 @@ retried once after `Retry-After` seconds (capped at 5 s).
 the server decided. Caches are keyed by user + key only — call `clear_cache()` after changing a
 user's attributes.
 
+`report_error` returns `True` when the server stored the report. A stored report counts toward the
+flag's error rate and automatic rollback only when the client's key has the `sdk:ruleset` scope and
+was created by a user who can change feature flags; the flag's safety check shows the others as
+`uncounted_error_count`.
+
 ### Enrolment: `assigned` and `reason`
 
 An `Assignment` also carries `assigned` and `reason`. `assigned is False` means the server did not
@@ -129,13 +151,22 @@ and `reason` says why. A server that predates the fields sends neither, so `assi
 (never `False`). Decide deliberately how to treat those rows rather than dropping them with an
 `assigned is True` filter.
 
+An experiment that is not ACTIVE answers every user with its control variant, `assigned` False and
+`reason` set to its status (`"draft"`, `"paused"`, `"completed"` or `"archived"`).
+
 ## Tracking fan-out rule
 
 - **with** `experiment_key` and/or `feature_flag_key` → one `POST /api/v1/tracking/track`;
 - **without** a key → one `POST /api/v1/tracking/batch` (chunks of 100) containing one entry per
-  experiment the user has been assigned to in this client (`experiment_key`) plus one per flag
-  evaluated for the user (`feature_flag_key`), taken from the cache (successful, unexpired only);
-- nothing cached for the user → nothing is sent and `track` returns `False`.
+  experiment (`experiment_key`) and one per flag (`feature_flag_key`) this client answered for the
+  user in the last 24 hours, cached or not, except an experiment whose latest answer has `reason`
+  `"draft"`, `"paused"`, `"completed"` or `"archived"`;
+- nothing to attribute it to → one `POST /api/v1/tracking/track` with no key, stored as history (it
+  counts in holdout results and as CUPED history, never in an experiment's results);
+- `track` returns `True` when the event was sent and the server answered 2xx, `False` otherwise.
+
+The keys live in this client's memory, for up to 10,000 users; `clear_cache()` keeps them, and
+another process does not have them. In a server, pass `experiment_key` on conversions.
 
 `event_type` defaults to `event_name`; `properties` is sent as `metadata`; `timestamp` may be a
 `datetime` (naive values are treated as UTC) or an ISO-8601 string.
@@ -146,11 +177,12 @@ Every request carries `X-API-Key: <key>`, `Content-Type: application/json` and `
 
 | SDK call | Method and path | Body / query | Response used |
 |---|---|---|---|
-| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when not ACTIVE |
+| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
 | `get_feature_flag`, `is_feature_enabled` | `GET /api/v1/feature-flags/evaluate/{flag_key}?user_id=…&context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{key, enabled, config, reason}`; off with `reason: "inactive"` when the flag exists but is not ACTIVE; 404 only for an unknown key |
 | `get_all_flags` | `GET /api/v1/feature-flags/user/{user_id}?context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{"<flag_key>": bool, …}` |
 | `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?}` | ignored |
-| `track` without keys, `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
+| `track` without keys | `POST /api/v1/tracking/batch`, one entry per experiment and flag it reaches; with none, `POST /api/v1/tracking/track` | `{events: [<track body>, …]}` (≤ 100 per request); with none, the track body with no key | ignored |
+| `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
 | `get_assignments` | `GET /api/v1/tracking/assignments/{user_id}?active_only=true` | — | list of dicts |
 
 ## Contract smoke

{controlvar-0.1.1 → controlvar-0.2.0}/README.md

@@ -16,11 +16,11 @@ else to install.
 
 If you installed `experimently`, the name this package had before the project was renamed, uninstall it and install `controlvar`.
 
-The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.1.1 is a
+The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.2.0 is a
 beta release. It installs and imports as `controlvar`.
 
 ```bash
-pip install controlvar==0.1.1
+pip install controlvar==0.2.0
 ```
 
 To work on the SDK itself, install it from the root of a clone of this repository instead:
@@ -29,6 +29,22 @@ To work on the SDK itself, install it from the root of a clone of this repositor
 pip install -e sdk/python
 ```
 
+## Changes in this version
+
+- `report_error()` is new: it sends one error report to the server and returns `True` when the
+  server stored it.
+- `track()` returns `True` when the event was sent and the server answered 2xx, and `False`
+  otherwise. Before this version, a `track()` without a key returned `True` only when the server
+  accepted every entry it was fanned out to. Now a batch answered 2xx returns `True` even when the
+  server refused one of its entries; `track_batch()` returns the per-entry results.
+- A `track()` without a key still reaches the experiments and flags this client answered for the
+  user in the last 24 hours (with the exceptions under Tracking fan-out rule) after their cached
+  answers expire; before this version it reached only the answers still in the cache. Those keys
+  are this client instance's only: an event tracked by another instance, in this process or
+  another, reaches none of them.
+- With nothing to reach, a `track()` without a key is now sent once with no key and stored as
+  history, and returns `True` on a 2xx; before this version it sent nothing and returned `False`.
+
 ## Quick start
 
 Set `CONTROLVAR_API_KEY` to an API key, then run the block as it is; the two `print` calls
@@ -69,16 +85,17 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 
 | Method | Returns | Failure behaviour |
 |---|---|---|
-| `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when the experiment is not ACTIVE) |
+| `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when no experiment has the key, or for a draft with no control variant); an experiment that is not ACTIVE returns its control variant with `assigned` False and `reason` its status |
 | `get_variant(experiment_key, user_id, user_attributes=None)` | `str` variant name | returns `default_variant` |
 | `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
 | `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
 | `get_all_flags(user_id, user_attributes=None)` | `dict[str, bool]` (not cached) | raises `ExperimentationError` |
-| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when accepted | never raises; `False` on failure or when nothing was sent |
+| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
 | `track_batch(events)` | `BatchResult(success_count, failure_count, errors)`; `.ok` | never raises; a failed chunk counts all its events as failures |
+| `report_error(error_type, message, *, feature_flag_key=None, experiment_key=None, user_id=None, stack_trace=None, metadata=None, timestamp=None)` | `bool` — `True` when the server stored the report (201) | never raises; `False` and a logged warning otherwise |
 | `get_assignments(user_id, active_only=True)` | `list[dict]` from the server | raises `ExperimentationError` |
 | `cached_assignments(user_id)` / `cached_flags(user_id)` | cached, unexpired entries | — |
-| `clear_cache()` | — | — |
+| `clear_cache()` | — (keeps the keys a key-less `track` is sent to) | — |
 | `ready(timeout_seconds=None)`, `status()`, `close()` / `with` | local mode: readiness, ruleset state, shutdown (sends evaluation counts) | never raise |
 | `consistent_hash(user_id, flag_key)` / `md5_hex(user_id, flag_key)` | cross-SDK MD5 bucket in `[0, 1)` / hex digest | pure functions; **not** the flag bucketing function |
 
@@ -93,6 +110,11 @@ retried once after `Retry-After` seconds (capped at 5 s).
 the server decided. Caches are keyed by user + key only — call `clear_cache()` after changing a
 user's attributes.
 
+`report_error` returns `True` when the server stored the report. A stored report counts toward the
+flag's error rate and automatic rollback only when the client's key has the `sdk:ruleset` scope and
+was created by a user who can change feature flags; the flag's safety check shows the others as
+`uncounted_error_count`.
+
 ### Enrolment: `assigned` and `reason`
 
 An `Assignment` also carries `assigned` and `reason`. `assigned is False` means the server did not
@@ -103,13 +125,22 @@ and `reason` says why. A server that predates the fields sends neither, so `assi
 (never `False`). Decide deliberately how to treat those rows rather than dropping them with an
 `assigned is True` filter.
 
+An experiment that is not ACTIVE answers every user with its control variant, `assigned` False and
+`reason` set to its status (`"draft"`, `"paused"`, `"completed"` or `"archived"`).
+
 ## Tracking fan-out rule
 
 - **with** `experiment_key` and/or `feature_flag_key` → one `POST /api/v1/tracking/track`;
 - **without** a key → one `POST /api/v1/tracking/batch` (chunks of 100) containing one entry per
-  experiment the user has been assigned to in this client (`experiment_key`) plus one per flag
-  evaluated for the user (`feature_flag_key`), taken from the cache (successful, unexpired only);
-- nothing cached for the user → nothing is sent and `track` returns `False`.
+  experiment (`experiment_key`) and one per flag (`feature_flag_key`) this client answered for the
+  user in the last 24 hours, cached or not, except an experiment whose latest answer has `reason`
+  `"draft"`, `"paused"`, `"completed"` or `"archived"`;
+- nothing to attribute it to → one `POST /api/v1/tracking/track` with no key, stored as history (it
+  counts in holdout results and as CUPED history, never in an experiment's results);
+- `track` returns `True` when the event was sent and the server answered 2xx, `False` otherwise.
+
+The keys live in this client's memory, for up to 10,000 users; `clear_cache()` keeps them, and
+another process does not have them. In a server, pass `experiment_key` on conversions.
 
 `event_type` defaults to `event_name`; `properties` is sent as `metadata`; `timestamp` may be a
 `datetime` (naive values are treated as UTC) or an ISO-8601 string.
@@ -120,11 +151,12 @@ Every request carries `X-API-Key: <key>`, `Content-Type: application/json` and `
 
 | SDK call | Method and path | Body / query | Response used |
 |---|---|---|---|
-| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when not ACTIVE |
+| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
 | `get_feature_flag`, `is_feature_enabled` | `GET /api/v1/feature-flags/evaluate/{flag_key}?user_id=…&context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{key, enabled, config, reason}`; off with `reason: "inactive"` when the flag exists but is not ACTIVE; 404 only for an unknown key |
 | `get_all_flags` | `GET /api/v1/feature-flags/user/{user_id}?context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{"<flag_key>": bool, …}` |
 | `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?}` | ignored |
-| `track` without keys, `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
+| `track` without keys | `POST /api/v1/tracking/batch`, one entry per experiment and flag it reaches; with none, `POST /api/v1/tracking/track` | `{events: [<track body>, …]}` (≤ 100 per request); with none, the track body with no key | ignored |
+| `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
 | `get_assignments` | `GET /api/v1/tracking/assignments/{user_id}?active_only=true` | — | list of dicts |
 
 ## Contract smoke

controlvar-0.2.0/controlvar/attribution.py

@@ -0,0 +1,105 @@
+"""The keys a key-less ``track()`` is sent to, kept apart from the TTL value cache.
+
+Every successful answer (an assignment, ``assigned=False`` included, or a flag
+evaluation, local or from the server) records its key for the user. A key-less
+event goes to each key recorded for its user, so a purchase made after the cache
+entry expired still reaches the experiment the user was answered for.
+``clear_cache()`` does not touch this record: a user's sticky assignments do not
+change when their attributes do.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import Dict, FrozenSet, List, Optional, Tuple
+
+from . import cache
+
+__all__ = ["ATTRIBUTION_HORIZON_SECONDS", "LIFECYCLE_REASONS", "MAX_ATTRIBUTED_USERS", "AttributedKeys"]
+
+#: Users kept per client instance; the user answered least recently is dropped first.
+MAX_ATTRIBUTED_USERS = 10_000
+
+#: A key is used for this long after its latest successful answer, then dropped.
+ATTRIBUTION_HORIZON_SECONDS = 24 * 60 * 60
+
+#: An experiment whose latest answer gave one of these reasons is not running, so a
+#: key-less event is not sent to it. Other reasons (``holdout``,
+#: ``mutual_exclusion``, ``targeting``) are kept: holdout results count those
+#: users' events.
+LIFECYCLE_REASONS: FrozenSet[str] = frozenset({"draft", "paused", "completed", "archived"})
+
+# key -> (answered_at, reason); dict order is first-answer order.
+_Answers = Dict[str, Tuple[float, Optional[str]]]
+
+
+class AttributedKeys:
+    """``user_id -> (experiment answers, flag answers)``, least recently answered user first.
+
+    Time is ``controlvar.cache._now`` (monotonic), read at call time, so a test that
+    patches it moves this record and the cache together.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._users: "OrderedDict[str, Tuple[_Answers, _Answers]]" = OrderedDict()
+
+    def record_experiment(self, user_id: str, experiment_key: str, reason: Optional[str] = None) -> None:
+        self._record(user_id, experiment_key, reason, 0)
+
+    def record_flag(self, user_id: str, flag_key: str) -> None:
+        self._record(user_id, flag_key, None, 1)
+
+    def forget_experiment(self, user_id: str, experiment_key: str) -> None:
+        """Drop one experiment's key for the user: the server answered its assignment 404, so
+        a key-less event must not reach it (a server that answers 404 for an experiment that is
+        not running would otherwise credit the user's stored arm while the user is shown
+        control)."""
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                return
+            answers[0].pop(experiment_key, None)
+            if not answers[0] and not answers[1]:
+                del self._users[user_id]
+
+    def keys(self, user_id: str) -> Tuple[List[str], List[str]]:
+        """The user's experiment keys and flag keys within the horizon, each in the
+        order they were first answered. Keys past the horizon are dropped here."""
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                return [], []
+            now = cache._now()
+            experiments, flags = _live(answers[0], now), _live(answers[1], now)
+            if not answers[0] and not answers[1]:
+                del self._users[user_id]
+            return experiments, flags
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._users)
+
+    def _record(self, user_id: str, key: str, reason: Optional[str], kind: int) -> None:
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                answers = ({}, {})
+                self._users[user_id] = answers
+            else:
+                self._users.move_to_end(user_id)  # now the most recently answered user
+            # Assigning an existing key keeps its place: the order stays first-answer order.
+            answers[kind][key] = (cache._now(), reason)
+            while len(self._users) > MAX_ATTRIBUTED_USERS:
+                self._users.popitem(last=False)
+
+
+def _live(answers: _Answers, now: float) -> List[str]:
+    out: List[str] = []
+    for key, (answered_at, reason) in list(answers.items()):
+        if now - answered_at > ATTRIBUTION_HORIZON_SECONDS:
+            del answers[key]
+        elif reason not in LIFECYCLE_REASONS:
+            out.append(key)
+    return out

{controlvar-0.1.1 → controlvar-0.2.0}/controlvar/client.py

@@ -9,11 +9,13 @@
   ruleset whenever the answer is provably the server's, and by the server
   otherwise; experiments always stay on the server.
 * Successful assignments/evaluations are cached per user + key for
-  ``cache_ttl_seconds``; failures are never cached.
+  ``cache_ttl_seconds``; failures are never cached. Every successful answer also
+  records its key for the key-less ``track()`` fan-out, for 24 hours
+  (:mod:`controlvar.attribution`); ``clear_cache()`` keeps that record.
 * ``get_assignment``/``get_feature_flag``/``get_all_flags``/``get_assignments``
   raise :class:`~controlvar.ExperimentationError`; the convenience
   wrappers ``get_variant``/``is_feature_enabled`` swallow it and return a
-  default; ``track``/``track_batch`` never raise.
+  default; ``track``/``track_batch``/``report_error`` never raise.
 * Safe to share between threads.
 """
 
@@ -26,6 +28,7 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Union
 from urllib.parse import quote, urlencode
 
+from .attribution import AttributedKeys
 from .cache import UserKeyCache
 from .evaluator import DEFER
 from .local import (
@@ -146,6 +149,8 @@ class ExperimentationClient:
         self._transport: Transport = transport if transport is not None else UrllibTransport()
         self._assignments: UserKeyCache[Assignment] = UserKeyCache(cache_ttl_seconds)
         self._flags: UserKeyCache[FlagEvaluation] = UserKeyCache(cache_ttl_seconds)
+        # The keys a key-less track() is sent to; outlives the cache entries.
+        self._attributed = AttributedKeys()
         self._sleep = time.sleep
         self._headers: Dict[str, str] = {
             "X-API-Key": api_key,
@@ -235,19 +240,19 @@ class ExperimentationClient:
         except Exception as exc:  # noqa: BLE001 - normalise any transport failure
             raise ExperimentationError(f"{method} {url} failed: {exc}") from exc
 
-    def _request(
+    def _exchange(
         self,
         method: str,
         path: str,
         *,
         body: Optional[Mapping[str, Any]] = None,
         query: Optional[Mapping[str, str]] = None,
-    ) -> Any:
-        """Perform one API call and return the decoded JSON body (``None`` if empty).
+    ) -> Response:
+        """Send one API call and return its response, whatever the status.
 
         Retries exactly once on 429, sleeping for ``Retry-After`` (capped at
         :data:`MAX_RETRY_AFTER_SECONDS`). Raises :class:`ExperimentationError`
-        for any non-2xx response, network failure or undecodable body.
+        for a network failure, and ``TypeError`` for a body JSON cannot encode.
         """
         url = self.api_url + path
         if query:
@@ -260,7 +265,23 @@ class ExperimentationClient:
             logger.debug("429 from %s %s; retrying once after %.1fs", method, path, wait)
             self._sleep(wait)
             response = self._send(method, url, data)
+        return response
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Perform one API call and return the decoded JSON body (``None`` if empty).
 
+        Retries exactly once on 429, sleeping for ``Retry-After`` (capped at
+        :data:`MAX_RETRY_AFTER_SECONDS`). Raises :class:`ExperimentationError`
+        for any non-2xx response, network failure or undecodable body.
+        """
+        response = self._exchange(method, path, body=body, query=query)
         if response.status < 200 or response.status >= 300:
             raise ExperimentationError(
                 f"{method} {path} failed with HTTP {response.status}",
@@ -290,8 +311,10 @@ class ExperimentationClient:
 
         Sticky on the server and cached here per user + key. ``user_attributes``
         is sent as ``context`` (used by targeting rules). Raises
-        :class:`ExperimentationError` (``status == 404`` when the experiment is
-        not ACTIVE or unknown).
+        :class:`ExperimentationError` (``status == 404`` when no experiment has
+        the key, or for a draft with no control variant). An experiment that is
+        not ACTIVE returns its control variant with ``assigned`` False and
+        ``reason`` its status.
         """
         cached = self._assignments.get(user_id, experiment_key)
         if cached is not None:
@@ -300,7 +323,13 @@ class ExperimentationClient:
         body: Dict[str, Any] = {"experiment_key": experiment_key, "user_id": user_id}
         if user_attributes is not None:
             body["context"] = dict(user_attributes)
-        data = self._request("POST", "/api/v1/tracking/assign", body=body)
+        try:
+            data = self._request("POST", "/api/v1/tracking/assign", body=body)
+        except ExperimentationError as exc:
+            # A 404: a key-less track() must no longer reach this experiment.
+            if exc.status == 404:
+                self._attributed.forget_experiment(user_id, experiment_key)
+            raise
 
         if not isinstance(data, dict) or not isinstance(data.get("variant_name"), str):
             raise ExperimentationError(
@@ -322,6 +351,7 @@ class ExperimentationClient:
             reason=data["reason"] if isinstance(data.get("reason"), str) else None,
         )
         self._assignments.set(user_id, experiment_key, assignment)
+        self._attributed.record_experiment(user_id, assignment.experiment_key, assignment.reason)
         return assignment
 
     def get_variant(
@@ -381,6 +411,7 @@ class ExperimentationClient:
                 )
                 # Recorded for the key-less track() fan-out, as a server answer is.
                 self._flags.set(user_id, flag_key, local)
+                self._attributed.record_flag(user_id, flag_key)
                 return local
         cached = self._flags.get(user_id, flag_key)
         if cached is not None:
@@ -410,6 +441,7 @@ class ExperimentationClient:
             source="server" if self._local is not None else None,
         )
         self._flags.set(user_id, flag_key, evaluation)
+        self._attributed.record_flag(user_id, flag_key)
         return evaluation
 
     def is_feature_enabled(
@@ -494,13 +526,19 @@ class ExperimentationClient:
         * With ``experiment_key`` and/or ``feature_flag_key``: one
           ``POST /api/v1/tracking/track``.
         * Without a key: one ``POST /api/v1/tracking/batch`` (chunked at 100)
-          containing one entry per cached assignment (``experiment_key``) plus
-          one per cached evaluated flag (``feature_flag_key``) for this user.
-          If nothing is cached for the user, nothing is sent and ``False`` is
-          returned.
-
-        ``event_type`` defaults to ``event_name``. Returns ``True`` only when
-        the server accepted the event(s).
+          containing one entry per experiment (``experiment_key``) plus one per
+          flag (``feature_flag_key``) this client answered for the user in the
+          last 24 hours, cached or not. An experiment whose latest answer said it
+          is a draft, paused, completed or archived gets no entry.
+        * Without a key and with nothing to attribute it to: one
+          ``POST /api/v1/tracking/track`` with no key, which the server stores as
+          history.
+
+        ``event_type`` defaults to ``event_name``. Returns ``True`` when the
+        event was sent and the server answered 2xx (every request, when a
+        fan-out takes more than one); ``False`` otherwise. A 2xx batch can still
+        report a failed entry, for example a key the server no longer has; use
+        :meth:`track_batch` to read the per-entry results.
         """
         try:
             base = self._event_body(user_id, event_name, event_value, properties, event_type, timestamp)
@@ -513,19 +551,30 @@ class ExperimentationClient:
                 self._request("POST", "/api/v1/tracking/track", body=body)
                 return True
 
-            events: List[Dict[str, Any]] = [
-                dict(base, experiment_key=assignment.experiment_key)
-                for assignment in self.cached_assignments(user_id)
-            ]
-            events.extend(dict(base, feature_flag_key=flag.key) for flag in self.cached_flags(user_id))
+            experiments, flags = self._attributed.keys(user_id)
+            events: List[Dict[str, Any]] = [dict(base, experiment_key=key) for key in experiments]
+            events.extend(dict(base, feature_flag_key=key) for key in flags)
             if not events:
-                logger.debug("track(%s, %s): nothing cached for user; nothing sent", user_id, event_name)
-                return False
-            return self.track_batch(events).ok
+                # Nothing to attribute it to: sent once with no key, stored as history.
+                self._request("POST", "/api/v1/tracking/track", body=base)
+                return True
+            return self._post_batches(events)
         except Exception as exc:  # noqa: BLE001 - fire-and-forget
             logger.warning("track(%s, %s) failed: %s", user_id, event_name, exc)
             return False
 
+    def _post_batches(self, events: List[Dict[str, Any]]) -> bool:
+        """``POST /api/v1/tracking/batch`` in chunks of 100; ``True`` when every
+        chunk was answered 2xx. A failed chunk is logged and the rest are still sent."""
+        ok = True
+        for start in range(0, len(events), BATCH_LIMIT):
+            try:
+                self._request("POST", "/api/v1/tracking/batch", body={"events": events[start : start + BATCH_LIMIT]})
+            except Exception as exc:  # noqa: BLE001 - never raise
+                logger.warning("track fan-out chunk starting at %d failed: %s", start, exc)
+                ok = False
+        return ok
+
     def track_batch(self, events: Iterable[Mapping[str, Any]]) -> BatchResult:
         """Send raw track bodies via ``POST /api/v1/tracking/batch`` in chunks of 100. Never raises.
 
@@ -577,10 +626,68 @@ class ExperimentationClient:
             body["timestamp"] = _iso_timestamp(body["timestamp"])
         return body
 
+    # ---------------------------------------------------------- error reports
+
+    def report_error(
+        self,
+        error_type: str,
+        message: str,
+        *,
+        feature_flag_key: Optional[str] = None,
+        experiment_key: Optional[str] = None,
+        user_id: Optional[str] = None,
+        stack_trace: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+        timestamp: Union[datetime, str, None] = None,
+    ) -> bool:
+        """Report an error that happened while a flag or experiment was active, with one
+        ``POST /api/v1/tracking/errors``. Works in both evaluation modes. Never raises.
+
+        Returns ``True`` exactly when the server answered 201: the report is stored. It
+        counts toward the flag's error rate and automatic rollback only when this client's
+        key is a server-side key (the ``sdk:ruleset`` scope, created by a user who can change
+        flags); the flag's safety check shows the others as ``uncounted_error_count``.
+        Returns ``False``, and logs a warning, on any other answer (401, 404, 422, a 429
+        after its one retry, 5xx) or a network failure. The server checks the report (it
+        needs ``feature_flag_key`` or ``experiment_key``); the SDK does not. ``timestamp``
+        (a ``datetime``, naive meaning UTC, or an ISO-8601 string) is kept with the report
+        as ``client_timestamp``; the stored row is timed when the server receives it.
+        """
+        path = "/api/v1/tracking/errors"
+        try:
+            body: Dict[str, Any] = {"error_type": error_type, "message": message}
+            if feature_flag_key is not None:
+                body["feature_flag_key"] = feature_flag_key
+            if experiment_key is not None:
+                body["experiment_key"] = experiment_key
+            if user_id is not None:
+                body["user_id"] = user_id
+            if stack_trace is not None:
+                body["stack_trace"] = stack_trace
+            if metadata is not None:
+                body["metadata"] = dict(metadata)
+            stamp = _iso_timestamp(timestamp)
+            if stamp is not None:
+                body["timestamp"] = stamp
+            response = self._exchange("POST", path, body=body)
+        except Exception as exc:  # noqa: BLE001 - never raise
+            logger.warning("report_error(%s) failed: %s", error_type, exc)
+            return False
+        if response.status == 201:
+            return True
+        logger.warning(
+            "report_error(%s) was not stored: POST %s answered HTTP %d: %s",
+            error_type,
+            path,
+            response.status,
+            response.text()[:200],
+        )
+        return False
+
     # ------------------------------------------------------------------ cache
 
     def cached_assignments(self, user_id: str) -> List[Assignment]:
-        """Successful, unexpired assignments cached for the user (what ``track`` fans out to)."""
+        """Successful, unexpired assignments cached for the user."""
         return [assignment for _, assignment in self._assignments.entries(user_id)]
 
     def cached_flags(self, user_id: str) -> List[FlagEvaluation]:
@@ -588,6 +695,7 @@ class ExperimentationClient:
         return [evaluation for _, evaluation in self._flags.entries(user_id)]
 
     def clear_cache(self) -> None:
-        """Drop every cached assignment and evaluation."""
+        """Drop every cached assignment and evaluation, so the next calls ask the
+        server again. The keys a key-less ``track()`` is sent to are kept."""
         self._assignments.clear()
         self._flags.clear()

{controlvar-0.1.1 → controlvar-0.2.0}/controlvar/types.py

@@ -42,7 +42,9 @@ class Assignment:
     returned the control variant instead, with no exposure recorded. ``reason``
     says why: ``"assigned"``, ``"holdout"``, ``"mutual_exclusion"`` or
     ``"targeting"``. Both are ``None`` when the server predates the fields; such
-    a server cannot tell you, so do not read ``None`` as either answer.
+    a server cannot tell you, so do not read ``None`` as either answer. For an
+    experiment that is not ACTIVE, ``assigned`` is ``False`` and ``reason`` is its
+    status (``"draft"``, ``"paused"``, ``"completed"`` or ``"archived"``).
     """
 
     experiment_key: str

{controlvar-0.1.1 → controlvar-0.2.0}/controlvar/version.py

@@ -1,3 +1,3 @@
 """Package version (kept in its own module so ``client`` can build a User-Agent without import cycles)."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"