traffical 0.3.0__tar.gz

traffical-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  # The published npm pin the SDK conforms to. The stale-pin gate below fails
+  # CI when a newer sdk-spec tag exists, so this must be bumped in lockstep.
+  SDK_SPEC_VERSION: "0.7.0"
+  # CI checks out this published sdk-spec tag for the fixtures + schemas.
+  SDK_SPEC_REF: "v0.7.0"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check out sdk-spec (fixtures + schemas)
+        uses: actions/checkout@v6
+        with:
+          repository: traffical/sdk-spec
+          ref: ${{ env.SDK_SPEC_REF }}
+          path: .sdk-spec
+
+      - name: Point tests at the sdk-spec checkout
+        run: echo "TRAFFICAL_SDK_SPEC_PATH=${GITHUB_WORKSPACE}/.sdk-spec" >> "$GITHUB_ENV"
+
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        # --frozen (not --locked): install exactly the locked dependency
+        # versions without asserting uv.lock matches pyproject. release-please
+        # bumps the project version in pyproject.toml but not in uv.lock, so
+        # --locked would fail on every release PR over the project's own version.
+        run: uv sync --frozen
+
+      - name: Tests (unit + sdk-spec conformance)
+        run: uv run pytest
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy src/ tests/
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+  spec-pin-check:
+    # Stale-pin gate: fail when the sdk-spec pin is behind the latest published
+    # tag, so the conformance suite cannot silently lag the spec.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail if SDK_SPEC_VERSION is behind the latest sdk-spec tag
+        run: |
+          set -euo pipefail
+          pinned="${SDK_SPEC_VERSION#v}"
+          latest="$(git ls-remote --tags --refs https://github.com/traffical/sdk-spec \
+            | sed -E 's#.*/tags/v?##' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n1 || true)"
+          if [ -z "$latest" ]; then
+            echo "No published sdk-spec tags found (pre-release); skipping stale-pin gate."
+            exit 0
+          fi
+          newest="$(printf '%s\n%s\n' "$pinned" "$latest" | sort -V | tail -n1)"
+          echo "pinned=$pinned latest=$latest"
+          if [ "$latest" != "$pinned" ] && [ "$newest" = "$latest" ]; then
+            echo "::error::sdk-spec pin $pinned is behind the latest published tag $latest. Bump SDK_SPEC_VERSION."
+            exit 1
+          fi
+          echo "sdk-spec pin is current."
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+      - name: Build wheel and sdist
+        run: uv build
+      - name: Check wheel contents
+        run: |
+          uv run --no-project --with check-wheel-contents check-wheel-contents dist/*.whl
+          unzip -l dist/*.whl | grep -q "traffical/py.typed"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

traffical-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+# Token-based publish. Runs on a GitHub Release (for user-created releases) and
+# via manual dispatch (e.g. to re-publish a release whose auto-publish did not
+# fire). Releases cut by release-please publish inline in release-please.yml —
+# see the note there — because a release created with GITHUB_TOKEN cannot trigger
+# this `release`-triggered workflow.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+      - name: Build wheel and sdist
+        run: uv build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

traffical-0.3.0/.github/workflows/release-please.yml

@@ -0,0 +1,39 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: release
+        with:
+          # Optional RELEASE_PLEASE_TOKEN (a PAT) makes CI run on the release PR;
+          # the default GITHUB_TOKEN cannot trigger downstream workflows.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+
+      # Publish to PyPI in THIS run when release-please cuts a release. Doing it
+      # inline (rather than a separate `release`-triggered workflow) avoids
+      # GitHub's anti-recursion rule: a release created with GITHUB_TOKEN cannot
+      # trigger a downstream `release:` workflow, so publish.yml would never fire
+      # for an automated release.
+      - uses: actions/checkout@v6
+        if: ${{ steps.release.outputs.release_created }}
+      - uses: astral-sh/setup-uv@v8.2.0
+        if: ${{ steps.release.outputs.release_created }}
+      - name: Build wheel and sdist
+        if: ${{ steps.release.outputs.release_created }}
+        run: uv build
+      - name: Publish to PyPI
+        if: ${{ steps.release.outputs.release_created }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

traffical-0.3.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+.DS_Store
+.sdk-spec/

traffical-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

traffical-0.3.0/AGENTS.md

@@ -0,0 +1,29 @@
+# Agent Guidelines for the Traffical Python SDK
+
+## Important Files
+
+- **`CONTRIBUTING.md`** — full development workflow (uv, pytest, mypy, ruff, conformance fixtures).
+  Always read and follow it when making changes.
+
+## Hard Rules
+
+- `src/traffical/engine/` must stay pure: stdlib only, no I/O, no clocks, no globals, frozen dataclasses.
+- Public client methods are fail-open — they return the caller's defaults instead of raising.
+- The cross-language contract in `../sdk-spec` is authoritative. If a conformance vector fails, fix the
+  code, never the fixture.
+- Never manually edit the version (`pyproject.toml` + `SDK_VERSION` in `src/traffical/options.py`)
+  outside a dedicated release commit.
+
+## Workflow
+
+Run from the package root:
+
+```bash
+uv sync
+uv run pytest
+uv run mypy src/traffical   # --strict, configured in pyproject
+uv run ruff check
+```
+
+All three must be green before committing. Conformance fixtures resolve via `TRAFFICAL_SDK_SPEC_PATH`,
+defaulting to the sibling `../sdk-spec` (see `tests/conftest.py`).

traffical-0.3.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.3.0](https://github.com/traffical/python-sdk/compare/v0.2.0...v0.3.0) (2026-07-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* adopt 0.7.0 public API contract (A1) + exposure dedup (S4) + track options
+
+### Features
+
+* adopt 0.7.0 public API contract (A1) + exposure dedup (S4) + track options ([eccbf9d](https://github.com/traffical/python-sdk/commit/eccbf9d929a4a8392a203c6aae31e2772391271b))
+* **config:** honor suggestedRefreshMs from the config response ([1862de9](https://github.com/traffical/python-sdk/commit/1862de95bc613834ff326003ec0ad2d8cc9ba032))
+* emit propensity, modelVersion, configVersion per sdk-spec 0.6.0 ([d7eb8de](https://github.com/traffical/python-sdk/commit/d7eb8de5683b7b6b37dfe0c2cd9f07d614b3df95))
+
+
+### Bug Fixes
+
+* **ci:** use uv sync --frozen; release pre-1.0 (bump-minor-pre-major) ([#3](https://github.com/traffical/python-sdk/issues/3)) ([fc99d8a](https://github.com/traffical/python-sdk/commit/fc99d8aed53496b73e39a21e817d65b79cdd43cb))
+* **config:** discard malformed bundles at ingest (S8) ([255858c](https://github.com/traffical/python-sdk/commit/255858c1f93b4601c8160ab57ecdf1fb75fe898d))
+* **engine:** align condition/stringify/exposure semantics with spec 0.7.0 ([2c00c7b](https://github.com/traffical/python-sdk/commit/2c00c7bc4b625f60b7bef839e1e652bfdd529ba7))
+* **events:** exposure event carries full assignment map (S4) ([2b01705](https://github.com/traffical/python-sdk/commit/2b01705354230d8c71bf491d5c0bbe91b3ce3229))
+
+
+### Documentation
+
+* **ci:** pin sdk-spec 0.7.0, add stale-pin gate, SECURITY.md, README refresh ([ff01a73](https://github.com/traffical/python-sdk/commit/ff01a735d3ae436368d7da24ee97df0cf9fbe342))

traffical-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing to the Traffical Python SDK
+
+Thank you for your interest in contributing!
+
+## Getting started
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (manages the venv and dev dependencies via `pyproject.toml`)
+
+### Setup
+
+```bash
+cd python-sdk
+uv sync
+```
+
+### Everyday commands
+
+Run everything from the `python-sdk` package root:
+
+```bash
+uv run pytest                 # full suite (unit + conformance)
+uv run pytest tests/engine    # just the pure-engine tests
+uv run pytest tests/conformance
+uv run mypy src/traffical     # must pass --strict (configured in pyproject)
+uv run ruff check             # lint
+```
+
+All three (pytest, mypy, ruff) must be green before a PR is mergeable.
+
+## Conformance fixtures (sdk-spec)
+
+The cross-language contract lives in the [sdk-spec](https://github.com/traffical/sdk-spec) repository:
+JSON schemas plus deterministic test vectors (`test-vectors/fixtures/bundle_*.json` +
+`expected_*.json`). `tests/conftest.py` resolves the spec checkout in this order:
+
+1. `TRAFFICAL_SDK_SPEC_PATH` environment variable, if set:
+   ```bash
+   TRAFFICAL_SDK_SPEC_PATH=/path/to/sdk-spec uv run pytest tests/conformance
+   ```
+2. Otherwise the sibling directory `../sdk-spec` (the layout of the traffical-sdk workspace).
+
+A pinned `tests/sdk-spec` git submodule (like the PHP SDK's) is planned for the standalone repository;
+the `conftest.py` resolution order will stay the same, with the submodule becoming the default.
+
+If a conformance test fails, treat the spec as the source of truth: fix the engine, not the fixture.
+Spec changes go through the sdk-spec repository first.
+
+## Project layout
+
+- `src/traffical/engine/` — pure resolution engine: stdlib only, no I/O, no clocks, no globals;
+  frozen dataclasses for models. Keep it that way.
+- `src/traffical/config/` — bundle sources, store/readiness, background pollers.
+- `src/traffical/events/` — event queue, flushers, dedup, BYO assignment logger.
+- `src/traffical/client.py` / `async_client.py` — the public sync/async clients.
+- `tests/` — `engine/`, `client/`, `conformance/` plus `conftest.py` (fixture loading).
+- `examples/` — runnable offline examples; keep them working when the public API changes.
+
+## Code style
+
+- Full type annotations; `mypy --strict` clean.
+- PEP 8 / snake_case public API; the surface mirrors the JS and PHP SDKs
+  (`get_params`, `decide`, `track_exposure`, `track`, `flush_events`, `close`, `wait_for_ready`).
+- No comments that narrate the obvious.
+- Fail-open: public client methods must never raise into application code; defaults win on errors.
+
+## Pull request process
+
+1. Ensure `uv run pytest`, `uv run mypy src/traffical`, and `uv run ruff check` pass.
+2. Update README/examples if the public surface changed.
+3. New behavior needs tests; cross-SDK behavior needs a pointer to the matching JS/PHP reference or
+   sdk-spec section in the PR description.
+
+## Releases
+
+Versioning and publishing are automated with [release-please](https://github.com/googleapis/release-please)
+(the Python-world equivalent of the changesets flow used by `js-sdk`) and PyPI
+[trusted publishing](https://docs.pypi.org/trusted-publishers/). Never bump versions by hand.
+
+### How it works
+
+1. **Commit messages drive version bumps** ([Conventional Commits](https://www.conventionalcommits.org/)):
+   - `fix: ...` → patch (0.1.0 → 0.1.1)
+   - `feat: ...` → minor (0.1.0 → 0.2.0)
+   - `feat!: ...` or a `BREAKING CHANGE:` footer → major (pre-1.0: minor)
+   - `chore:`/`docs:`/`test:`/`refactor:` → no release
+   Where changesets asks "what kind of change is this?" at `bunx changeset` time, here you answer it
+   in the commit (squash-merge) message. PR titles should follow the same convention since PRs are
+   squash-merged.
+2. **Release PR**: on every push to `main`, the `release-please` workflow opens/updates a release PR
+   (the analog of changesets' "Version Packages" PR) that bumps `version` in `pyproject.toml` and
+   `SDK_VERSION` in `src/traffical/options.py` (via the `x-release-please-version` annotation) and
+   updates `CHANGELOG.md`.
+3. **Merging the release PR** tags `vX.Y.Z` and creates a GitHub release.
+4. **The release triggers `publish.yml`**, which builds with `uv build` and publishes to PyPI via
+   trusted publishing (OIDC; the `pypi` GitHub environment, no long-lived API token).
+
+Version state lives in `.release-please-manifest.json` + `release-please-config.json`.
+
+### One-time setup (maintainers)
+
+- On [pypi.org](https://pypi.org/manage/account/publishing/): add a **pending trusted publisher** for
+  project `traffical` → owner `traffical`, repository `python-sdk`, workflow `publish.yml`,
+  environment `pypi`. The first publish claims the name.
+- In the GitHub repo: create the `pypi` environment (optionally with required reviewers as a
+  publish gate). Optional: a `RELEASE_PLEASE_TOKEN` PAT secret so CI runs on release PRs
+  (the default `GITHUB_TOKEN` cannot trigger downstream workflows).
+
+> **Warning:** publishing to PyPI makes the source public (the sdist contains the full package).
+> Do not publish a release while this repository is meant to stay private.
+
+### Release gates
+
+- CI (`ci.yml`) must be green: full test suite including all sdk-spec conformance vector suites
+  against the pinned spec version (`SDK_SPEC_VERSION` in `ci.yml`, fetched from the published
+  `@traffical/sdk-spec` npm package), `mypy --strict`, `ruff check`, `ruff format --check`, and a
+  wheel/sdist build whose contents are checked (`py.typed` present, no test files).
+- Publishing to PyPI happens from CI only, never from developer machines.

traffical-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Traffical
+
+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.

traffical-0.3.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: traffical
+Version: 0.3.0
+Summary: Traffical Python SDK: deterministic experimentation and parameter resolution
+Project-URL: Homepage, https://traffical.io
+Project-URL: Repository, https://github.com/traffical/python-sdk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ab-testing,experimentation,feature-flags,traffical
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Description-Content-Type: text/markdown
+
+# Traffical Python SDK
+
+[Traffical](https://traffical.io) is one control plane for experiments, feature flags, and adaptive
+optimization. Instead of hard-coding decisions, you expose **typed parameters** — numbers, strings, booleans,
+and JSON, not just on/off toggles — and control behavior across web, mobile, push, and backend from a single
+place. Parameters are resolved **locally in the SDK** (sub-millisecond, no network round trips at runtime), and
+metrics are computed **warehouse-native**, against data you own. Start with a feature flag, graduate it to an
+A/B test, and let adaptive optimization shift traffic to the winning variant — all on the same parameter,
+without a deploy.
+
+This package is the **official Python SDK** (Python 3.10+) for Traffical, with first-class sync and asyncio
+clients.
+
+## Features
+
+- **Local, in-process evaluation** — resolve a cached config bundle with no per-decision network call.
+- **Typed parameters with safe defaults** — bool / string / number / JSON, each with a caller-provided
+  fallback; every public call is fail-open (your defaults always win on errors).
+- **Layered experiments & targeting** — Google-style layered isolation, condition/attribute segmentation, and
+  progressive (percentage) rollouts.
+- **Adaptive optimization** — contextual-bandit scoring evaluated client-side.
+- **BYO warehouse-native assignment logging** — route structured assignment rows through your own pipeline
+  (a DB, a queue, Segment, RudderStack) so assignment data never has to leave your infrastructure.
+- **Event tracking** — exposure, decision, and custom track events, batched and flushed on a background
+  thread (or asyncio task), with retries and an atexit safety net.
+- **Fork-safe by construction** — works under gunicorn pre-fork, celery, and anything else that calls
+  `os.fork()` after client creation.
+- **Pure, deterministic engine** — `traffical.engine` is stdlib-only (no I/O, no clocks, no globals) and
+  conformance-tested against the cross-language SDK spec.
+
+## Modes
+
+- **Bundle mode (default)** — the SDK fetches a config bundle, refreshes it on a background poller, and
+  resolves every parameter locally. No per-decision network call.
+- **Server mode** — resolution is delegated to the Traffical edge via `POST /v1/resolve`. Use it when you
+  want zero client-side evaluation logic.
+
+## Installation
+
+```bash
+pip install traffical
+# or
+uv add traffical
+```
+
+Requires Python 3.10+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## Quick start
+
+```python
+from traffical import TrafficalClient, TrafficalClientOptions
+
+client = TrafficalClient(
+    TrafficalClientOptions(
+        api_key="sk_...",
+        project_id="proj_...",
+        env="production",
+        org_id="org_...",
+    )
+)
+client.wait_for_ready(timeout=5.0)
+
+# Resolve parameters with defaults as the fallback.
+params = client.get_params(
+    context={"userId": "user-abc", "country": "US"},
+    defaults={"ui.primaryColor": "#000000", "pricing.discount": 0},
+)
+color = params["ui.primaryColor"]
+
+# decide() returns a Decision (assignments + metadata). Call track_exposure()
+# when the user actually sees the treatment.
+decision = client.decide({"userId": "user-abc"}, {"ui.primaryColor": "#000000"})
+variant = decision.assignments["ui.primaryColor"]
+client.track_exposure(decision)
+
+# Custom analytics events, attributed to the decision. Numeric metrics go in
+# the value / values options (not properties):
+client.track("checkout_completed", value=49.0, decision_id=decision.decision_id)
+
+client.close()  # flushes pending events; also usable as a context manager
+```
+
+`TrafficalClient` supports `with`-statement usage; `close()` is idempotent and flushes the event queue.
+
+## Async quick start
+
+`AsyncTrafficalClient` has the same surface with awaitable `get_params` / `decide` / `flush_events` /
+`close`. Background work runs on the event loop; enter the context manager (or call `start()`) from a
+running loop.
+
+```python
+import asyncio
+
+from traffical import AsyncTrafficalClient, TrafficalClientOptions
+
+
+async def main() -> None:
+    async with AsyncTrafficalClient(
+        TrafficalClientOptions(
+            api_key="sk_...",
+            project_id="proj_...",
+            env="production",
+            org_id="org_...",
+        )
+    ) as client:
+        await client.wait_for_ready(timeout=5.0)
+        decision = await client.decide({"userId": "user-abc"}, {"ui.primaryColor": "#000000"})
+        client.track_exposure(decision)
+
+
+asyncio.run(main())
+```
+
+## Server evaluation mode
+
+Delegate resolution to the edge worker instead of evaluating a local bundle. Each `get_params()` /
+`decide()` performs a `POST /v1/resolve`:
+
+```python
+options = TrafficalClientOptions(
+    api_key="sk_...",
+    project_id="proj_...",
+    env="production",
+    org_id="org_...",
+    evaluation_mode="server",
+)
+```
+
+In server mode `wait_for_ready()` returns immediately (there is no bundle to wait for) and resolve failures
+fall back to your defaults.
+
+## Warehouse-native assignment logging
+
+Pass an `assignment_logger` callable to route structured per-layer rows through your own pipeline. Each
+`AssignmentLogEntry` carries the stable `policy_key` / `allocation_key` used for warehouse joins, plus
+`unit_key`, `layer_id`, `decision_id`, timestamps and SDK metadata. Combine with `disable_cloud_events=True`
+to keep assignment data entirely on your own infrastructure:
+
+```python
+from traffical import AssignmentLogEntry, TrafficalClient, TrafficalClientOptions
+
+
+def log_assignment(entry: AssignmentLogEntry) -> None:
+    my_warehouse.insert("assignments", entry.__dict__)  # DB, queue, CDP, ...
+
+
+client = TrafficalClient(
+    TrafficalClientOptions(
+        api_key="sk_...",
+        project_id="proj_...",
+        env="production",
+        org_id="org_...",
+        assignment_logger=log_assignment,
+        disable_cloud_events=True,  # keep assignment data on your own infra
+    )
+)
+```
+
+The logger fires on every `decide()` (type `"decision"`) and `track_exposure()` (type `"exposure"`),
+independent of `track_decisions`, decision deduplication, and `disable_cloud_events`. Entries are
+deduplicated per `unit:policy:allocation:type` with a 1-hour TTL; set
+`deduplicate_assignment_logger=False` to receive every row.
+
+`AssignmentLogEntry.to_row()` maps the entry onto a flat, warehouse-friendly
+snake_case row. Two field names are deliberately renamed for the warehouse
+convention: the propensity is emitted as **`propensity`** (not `probability`),
+and the entry `id` as **`assignment_id`**. Off-policy training columns
+(`bucket`, `propensity`, `model_version`, `config_version`) are included, and
+any filtered context (`properties`) is spread to the top level as CUPED
+covariates.
+
+## Options reference
+
+`TrafficalClientOptions` is a frozen dataclass; construct it with keyword arguments.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key`, `project_id`, `env`, `org_id` | — | Required scoping + auth |
+| `base_url` | `https://sdk.traffical.io` | Control-plane base URL |
+| `evaluation_mode` | `"bundle"` | `"bundle"` (local) or `"server"` (`POST /v1/resolve`) |
+| `refresh_interval_seconds` | `60.0` | Bundle refresh interval (seconds); `<= 0` fetches once, no background refresh |
+| `config_timeout_seconds` | `10.0` | HTTP timeout for config-bundle fetch (seconds) |
+| `events_timeout_seconds` | `10.0` | HTTP timeout for event delivery (seconds) |
+| `resolve_timeout_seconds` | `5.0` | HTTP timeout for server-mode resolve calls (seconds) |
+| `track_decisions` | `True` | Emit decision events on `decide()` |
+| `decision_dedup_ttl_seconds` | `3600.0` | Decision-event dedup window (seconds) |
+| `deduplicate_exposures` | `True` | Session-dedup exposures per unit/policy/allocation |
+| `exposure_session_ttl_seconds` | `1800.0` | Exposure session-dedup window (seconds; 30 min) |
+| `batch_size` | `10` | Auto-flush threshold |
+| `flush_interval_seconds` | `30.0` | Background flush interval (seconds) |
+| `max_event_queue_size` | `1000` | Bounded event queue; overflow drops oldest |
+| `event_max_retries` | `3` | Delivery retries per batch |
+| `assignment_logger` | `None` | BYO warehouse logger, `(AssignmentLogEntry) -> None` |
+| `deduplicate_assignment_logger` | `True` | Dedup logger rows per unit/policy/allocation/type |
+| `disable_cloud_events` | `False` | Stop sending events to Traffical |
+| `local_config` | `None` | Bootstrap/offline `ConfigBundle` (or raw `dict`) |
+| `config_source` | `None` | Custom bundle source (`FileConfigSource`, `InlineConfigSource`, `CallableConfigSource`, or your own) |
+| `transport`, `async_transport` | `None` | httpx transport seams (e.g. `MockTransport` in tests) |
+
+## Fork safety (gunicorn, celery, …)
+
+Pre-fork servers `os.fork()` after your app module — and your client — are created. Background threads do
+not survive a fork, and inherited locks can be held by threads that no longer exist. The SDK handles this
+automatically via `os.register_at_fork`:
+
+- locks in the event queue, flusher, dedup caches, and config poller are re-armed in the child,
+- dead background threads (event flusher, config poller) are dropped and restarted lazily on next use,
+- each child process flushes its own events; an atexit/`weakref.finalize` safety net stops flushers of
+  clients that are garbage-collected without `close()`.
+
+What you should know:
+
+- Creating the client at module import (pre-fork) is fine and recommended — workers share nothing at runtime.
+- Call `close()` (or `flush_events()`) in worker shutdown hooks if you need a hard delivery guarantee.
+- The asyncio client is bound to the event loop it was started on; create it per process/loop, not pre-fork.
+
+## Cross-language conformance
+
+The Python SDK shares the language-agnostic [Traffical SDK spec](https://github.com/traffical/sdk-spec)
+(0.7.0) with the JS/TS and PHP SDKs: the same SHA-256 v2 (UTF-8 byte) assignment hashing, the same layered
+resolution engine, and the same contextual-bandit scoring. Every release is gated on the spec's
+deterministic conformance vectors — all resolution fixture suites (`basic`, `conditions`,
+`conditions_omitted`, `contextual`, `contextual_boundary`, `contextual_gamma_zero`,
+`contextual_high_floor`, `edge_policies`, `per_layer_unit_key`, `empty_unit_key`, `numeric_unit_key`,
+`unicode`, plus the entity-weight and resolve vectors) — so a given unit buckets identically on every
+platform.
+
+The 0.7.0 drift-remediation vectors lock the cross-SDK behavior decisions this SDK implements: empty layer
+`unitKey` overrides skip the layer (S1), numeric unit keys stringify via ECMAScript `Number::toString`
+(S2), strict condition typing with `.length` paths (S3), single-event exposure with session dedup (S4),
+omitted relational values never match (S5), the `safeGamma`/`effectiveFloor` softmax guards (S6), and
+`modelVersion = generatedAt ?? modelVersion` (S7). Emitted exposure/decision/track payloads are also
+validated against `events.schema.json` and the `events_conformance.json` vectors.
+
+## Examples
+
+Runnable scripts live in [examples/](examples/): a sync quick start, an asyncio variant, and a FastAPI
+integration. They run offline against a local bundle file (`FileConfigSource`), so no API key is needed.
+
+## Development
+
+```bash
+uv sync                                  # create the venv + install dev deps
+uv run pytest                            # full suite (unit + conformance)
+uv run mypy src/traffical                # strict type checking
+uv run ruff check                        # lint
+```
+
+Conformance fixtures are loaded from the sdk-spec checkout, resolved from the `TRAFFICAL_SDK_SPEC_PATH`
+environment variable and defaulting to the sibling `../sdk-spec` directory:
+
+```bash
+TRAFFICAL_SDK_SPEC_PATH=/path/to/sdk-spec uv run pytest tests/conformance
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).