uniqos 0.4.0__tar.gz

uniqos-0.4.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
+coverage/
+*.tsbuildinfo
+.turbo/
+*.tgz
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+build/
+*.whl

uniqos-0.4.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to the `uniqos` Python SDK are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-06-13
+
+Coordinated refresh release. Both SDKs re-vendor the post-S1+S2 canonical OpenAPI contract
+(root `openapi/openapi.json`) and move onto a single `0.4.0` version line. Python jumps
+`0.2.0 → 0.4.0` (skipping `0.3.0`) to align with `@uniqos/sdk`; the two packages now share a
+version. This cuts the previously-Unreleased `504 turn_timeout` handling (below).
+
+### Added
+
+- **`TurnTimeoutError`** — typed error for `504 turn_timeout` (a `/v1/respond` turn that
+  exceeded the server's engine budget and was aborted; ADR-0009). The aborted turn is
+  **not billed**. Mapped both code-first (`turn_timeout`) and by status (504).
+
+### Notes
+
+- **OpenAPI snapshot refreshed; generated models unchanged.** The vendored snapshot was
+  re-vendored to the current contract, but `make generate` is a no-op for Python: code
+  generation is scoped to the 6 named streaming schemas (ADR PY-0004), which are byte-identical
+  in the new contract. The contract's additive changes — `big_five_facets` on personality
+  responses, the formal `504` on `/v1/respond`, the new `/v1/auth/refresh` endpoint — live in
+  the path surface, which Python passes through as snake_case dicts rather than generating. The
+  personality dict simply carries the new `big_five_facets` key; `/v1/auth/refresh` stays outside
+  the integration surface (platform/auth, `docs/api-sdk-delta.md` §4). Behavioral parity with
+  `@uniqos/sdk@0.4.0` is maintained.
+
+### Changed
+
+- **504 is no longer auto-retried.** A budget timeout means the turn was already too
+  slow; a blind retry risks another long turn and — combined with client-vs-server
+  timing — a silent double bill. Retrying a 504 is now the integrator's explicit choice.
+  429 `rate_limit_exceeded` and 500/502/503 retry as before.
+- **Default request timeout raised 30s → 90s** (`DEFAULT_TIMEOUT`), comfortably above the
+  server's ~75s turn ceiling (`ENGINE_TURN_BUDGET_MS` 60s + 15s socket margin, exported
+  as `SERVER_TURN_CEILING_SECONDS`). This guarantees the SDK receives the server's clean
+  `504` instead of abandoning a turn the server may still finish **and bill**.
+  Integrators who set `timeout` below the server budget take on that risk explicitly.
+
+## [0.2.0] - 2026-06-04
+
+### Added
+
+- **`relationships.delete` now accepts `cascade` + `reason` (SPEC-14 §11.4, ADR-0006).** Mirrors
+  `end_users.delete`: keyword-only `cascade` (`Literal["all", "memory_only"]`) and `reason`
+  (`str`). `cascade` selects the deletion granularity (default `all` server-side); `reason`
+  records an optional audit note. Both travel in the DELETE body; omitting them keeps the prior
+  behavior (a bodyless full deletion). Unlike `end_users.delete`, there is **no** `model_only` —
+  the psychological model lives at the user level, not the relationship level (use
+  `end_users.delete(cascade="model_only")` for that). Closes the last TS↔Python `delete` surface
+  asymmetry (see `docs/api-sdk-delta.md`).
+
+### Notes
+
+- Purely additive: the new arguments are keyword-only with `None` defaults, so existing
+  `relationships.delete(relationship_id)` callers are unaffected (no breaking change — unlike the
+  TypeScript `@uniqos/sdk@0.3.0` bump, where `config` shifted from the 2nd to the 3rd positional
+  argument).
+- A type-only regression guard (`tests/static/test_typing.py`, checked by `mypy --strict`, not run
+  by `pytest`) pins `cascade` to the two contract literals and asserts `model_only` is rejected.
+
+## [0.1.0] - 2026-06-02
+
+First published version. Functional parity with the TypeScript SDK (`@uniqos/sdk@0.1.0`),
+implemented idiomatically for Python (snake_case, type hints, `py.typed`).
+
+### Added
+
+- **Sync and async clients** (`UniqOS` / `AsyncUniqOS`) over httpx, with an identical public
+  surface — only the I/O is awaited (ADR PY-0001).
+- **Configuration with fail-fast validation** (SPEC-17 §6): API-key format + environment
+  detection (`uniq_live_` / `uniq_test_`), `base_url` normalization, `timeout`, `max_retries`,
+  and log levels. An invalid key raises `ConfigurationError` before any HTTP call.
+- **Idiomatic namespaces** (SPEC-17 §7): `engine` (+ the `respond` shortcut), `personalities`,
+  `catalog`, `vocabularies`, `end_users`, `relationships` (+ `memory`), `interactions`, `me`,
+  `organizations`, `api_keys`, `billing`.
+- **Typed error hierarchy** with a code-first mapping (SPEC-17 §8): `rate_limit_exceeded` vs
+  `quota_exhausted` are distinguished by `code` on the same HTTP 429;
+  `RateLimitError.retry_after_seconds` is read from the `Retry-After` header.
+- **Automatic retries** with exponential backoff + jitter, honoring `Retry-After`
+  (SPEC-17 §10.2): retries network errors / `429 rate_limit_exceeded` / 500–504; never
+  `quota_exhausted` / 401 / 403 / other 4xx.
+- **Automatic idempotency keys** (UUID v4) on creation POSTs when none is provided, reused
+  across retries; an explicit key is honored (SPEC-17 §10.1, §10.4).
+- **SSE streaming**: `respond(stream=True)` yields the five generated `RespondStreamEvent`
+  variants as typed dataclasses — a sync iterator or an async iterator (SPEC-17 §9). A
+  mid-stream drop raises `NetworkError` with the interruption point.
+- **Configurable logging** (SPEC-17 §11) that never logs the full API key (only the prefix) nor
+  message content beyond 50 characters.
+- **Five runnable examples** (`examples/`) and a quickstart README.
+
+### Implementation notes
+
+- Data model: **dataclasses + `TypedDict`**, with **httpx** as the only runtime dependency
+  (ADR PY-0002). Responses are passed through as snake_case dicts; the streaming events are
+  frozen dataclasses generated from the OpenAPI contract.
+- Generation: `make generate` (datamodel-code-generator) reads the shared root
+  `openapi/openapi.json` snapshot, scoped to the contract's 6 named schemas (ADR PY-0004).
+
+### Compatibility notes
+
+- Streaming consumers that branch exhaustively on `event.type` must handle all five variants
+  (`metadata`, `text`, `guardrail_modulation`, `completion`, `error`).
+- `end_users.delete` accepts `cascade` (`'all' | 'model_only' | 'memory_only'`) and `reason`,
+  ahead of the TypeScript SDK (tracked in `../../docs/api-sdk-delta.md`).
+
+[0.1.0]: https://github.com/filuco2001/uniqos-sdks/releases/tag/python-v0.1.0

uniqos-0.4.0/Makefile

@@ -0,0 +1,59 @@
+# Developer commands for the uniqos Python SDK.
+# Mirrors the pnpm scripts of the TS SDK; all commands run through uv (ADR PY-0003).
+#
+#   make install   # create the venv and install the package + dev tools
+#   make generate  # regenerate models from the shared OpenAPI snapshot (ADR PY-0004)
+#   make check     # format-check + lint + typecheck + test (what CI runs)
+
+.PHONY: install generate lint format format-check typecheck test build check clean
+
+# Shared OpenAPI snapshot at the monorepo root — the SAME file the TS SDK reads.
+OPENAPI := ../../openapi/openapi.json
+GENERATED := src/uniqos/generated
+
+install:
+	uv sync
+
+# Regenerate the streaming-event dataclasses from the shared OpenAPI snapshot.
+# Scoped to `schemas` (the contract's only 6 named schemas, all streaming — ADR PY-0004).
+# --disable-timestamp keeps the output byte-stable so regeneration is a no-op when the
+# snapshot is unchanged (CI verifies with `git diff --exit-code`).
+generate:
+	uv run datamodel-codegen \
+		--input $(OPENAPI) \
+		--input-file-type openapi \
+		--output $(GENERATED)/stream_events.py \
+		--output-model-type dataclasses.dataclass \
+		--openapi-scopes schemas \
+		--enum-field-as-literal all \
+		--frozen-dataclasses \
+		--keyword-only \
+		--target-python-version 3.10 \
+		--use-standard-collections \
+		--use-union-operator \
+		--use-schema-description \
+		--disable-timestamp
+
+lint:
+	uv run ruff check src tests examples
+
+format:
+	uv run ruff format src tests examples
+
+format-check:
+	uv run ruff format --check src tests examples
+
+typecheck:
+	uv run mypy
+
+test:
+	uv run pytest
+
+build:
+	uv build
+
+check: format-check lint typecheck test
+
+clean:
+	rm -rf dist build .mypy_cache .ruff_cache .pytest_cache
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

uniqos-0.4.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: uniqos
+Version: 0.4.0
+Summary: Official uniqOS SDK — Personality & Emotional Intelligence Engine + Relational Memory for AI agents.
+Project-URL: Homepage, https://docs.uniqos.ai
+Project-URL: Documentation, https://docs.uniqos.ai
+Project-URL: Repository, https://github.com/filuco2001/uniqos-sdks
+Author: uniqOS
+License-Expression: MIT
+Keywords: agents,ai,emotional-intelligence,personality,relational-memory,sdk,uniqos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# uniqos
+
+Official Python SDK for [uniqOS](https://uniqos.ai) — a Personality & Emotional Intelligence
+Engine + Relational Memory layer for AI agents.
+
+- Sync **and** async clients (`UniqOS` / `AsyncUniqOS`)
+- Typed errors, automatic retries with backoff, automatic idempotency keys
+- SSE streaming as a plain iterator
+- Fully type-hinted (`py.typed`); one runtime dependency (`httpx`)
+- Python 3.10+
+
+## Install
+
+```bash
+pip install uniqos
+```
+
+## Quickstart
+
+```python
+from uniqos import UniqOS
+
+client = UniqOS(api_key="uniq_test_...")
+response = client.respond(personality_id="pers_...", message="hola")
+```
+
+`response` is the parsed JSON (snake_case, mirroring the API): `response["response"]` is the
+agent's reply.
+
+Get an API key from the [uniqOS dashboard](https://uniqos.ai). Keys start with `uniq_live_`
+(production) or `uniq_test_` (sandbox); the SDK detects the environment from the prefix and
+rejects a malformed key immediately.
+
+## Async
+
+```python
+from uniqos import AsyncUniqOS
+
+async with AsyncUniqOS(api_key="uniq_test_...") as client:
+    response = await client.respond(personality_id="pers_...", message="hola")
+```
+
+Both clients expose the identical surface (`client.personalities`, `client.end_users`,
+`client.billing`, …); the async one just awaits.
+
+## Streaming
+
+```python
+stream = client.respond(personality_id="pers_...", message="tell me a story", stream=True)
+for event in stream:
+    if event.type == "text":
+        print(event.delta, end="", flush=True)
+    elif event.type == "completion":
+        print(f"\n[{event.latency_ms}ms]")
+```
+
+The five event types (`metadata`, `text`, `guardrail_modulation`, `completion`, `error`) are
+typed dataclasses with attribute access. Async uses `async for`.
+
+## Errors
+
+```python
+from uniqos import RateLimitError, QuotaExhaustedError
+
+try:
+    response = client.respond(personality_id="pers_...", message="hi")
+except RateLimitError as err:
+    print(f"Rate limited. Retry after {err.retry_after_seconds}s")
+except QuotaExhaustedError as err:
+    print(f"Quota exhausted: {err.details}")
+```
+
+Every error carries `code`, `message`, `request_id`, `http_status`, and `details`. Catch
+`UniqOSError` for anything the SDK can raise. The SDK retries transient failures
+(`429 rate_limit_exceeded`, `500/502/503`, network) automatically with exponential backoff; it
+never retries `quota_exhausted`, `401`, `403`, or `504 turn_timeout` (see Configuration below).
+
+## Configuration
+
+```python
+client = UniqOS(
+    api_key="uniq_test_...",
+    base_url="https://api.uniqos.ai",  # host only; do NOT include /v1
+    timeout=90,                         # seconds; default 90s; 0 disables
+    max_retries=3,                      # 0 disables retries (504 is never auto-retried)
+    log_level="warning",               # debug | info | warning | error | silent
+    logger=my_logger,                   # optional: any object with debug/info/warning/error
+)
+```
+
+> **Default timeout is 90s**, deliberately above the server's ~75s turn ceiling, so a slow
+> turn surfaces as the server's clean `504 turn_timeout` (a `TurnTimeoutError`) instead of a
+> client-side abort. A `504 turn_timeout` is **not retried automatically**: the turn already
+> ran to the budget, so a blind retry risks a second long turn and — combined with
+> client-vs-server timing — a double bill (ADR-0009). Retrying it is your explicit choice.
+
+The SDK never logs the full API key (only the prefix) nor message content beyond 50 chars.
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples): `hello_world.py`, `stateful.py`,
+`streaming.py`, `error_handling.py`, and `dogfood.py`.
+
+**With a real (or local) API** — set the environment and run:
+
+```bash
+export UNIQOS_API_KEY="uniq_test_..."
+export UNIQOS_PERSONALITY_ID="pers_..."
+# optional, for a local backend:
+export UNIQOS_BASE_URL="http://localhost:3000"
+
+python examples/hello_world.py
+```
+
+**Without a network** — the test suite drives every code path against a mocked HTTP layer
+([`respx`](https://lundberg.github.io/respx/)), so no live API is needed to exercise the SDK:
+
+```python
+import httpx, respx
+from uniqos import UniqOS
+
+@respx.mock
+def test_it():
+    respx.post("https://api.uniqos.ai/v1/respond").mock(
+        return_value=httpx.Response(200, json={"response": "hi"})
+    )
+    with UniqOS(api_key="uniq_test_abcd1234") as client:
+        assert client.respond(personality_id="p_1", message="hi")["response"] == "hi"
+```
+
+## Documentation
+
+Full reference and guides live at [docs.uniqos.ai](https://docs.uniqos.ai). This README and the
+in-editor docstrings cover the essentials; the deep documentation is not duplicated here.
+
+## License
+
+MIT

uniqos-0.4.0/README.md

@@ -0,0 +1,138 @@
+# uniqos
+
+Official Python SDK for [uniqOS](https://uniqos.ai) — a Personality & Emotional Intelligence
+Engine + Relational Memory layer for AI agents.
+
+- Sync **and** async clients (`UniqOS` / `AsyncUniqOS`)
+- Typed errors, automatic retries with backoff, automatic idempotency keys
+- SSE streaming as a plain iterator
+- Fully type-hinted (`py.typed`); one runtime dependency (`httpx`)
+- Python 3.10+
+
+## Install
+
+```bash
+pip install uniqos
+```
+
+## Quickstart
+
+```python
+from uniqos import UniqOS
+
+client = UniqOS(api_key="uniq_test_...")
+response = client.respond(personality_id="pers_...", message="hola")
+```
+
+`response` is the parsed JSON (snake_case, mirroring the API): `response["response"]` is the
+agent's reply.
+
+Get an API key from the [uniqOS dashboard](https://uniqos.ai). Keys start with `uniq_live_`
+(production) or `uniq_test_` (sandbox); the SDK detects the environment from the prefix and
+rejects a malformed key immediately.
+
+## Async
+
+```python
+from uniqos import AsyncUniqOS
+
+async with AsyncUniqOS(api_key="uniq_test_...") as client:
+    response = await client.respond(personality_id="pers_...", message="hola")
+```
+
+Both clients expose the identical surface (`client.personalities`, `client.end_users`,
+`client.billing`, …); the async one just awaits.
+
+## Streaming
+
+```python
+stream = client.respond(personality_id="pers_...", message="tell me a story", stream=True)
+for event in stream:
+    if event.type == "text":
+        print(event.delta, end="", flush=True)
+    elif event.type == "completion":
+        print(f"\n[{event.latency_ms}ms]")
+```
+
+The five event types (`metadata`, `text`, `guardrail_modulation`, `completion`, `error`) are
+typed dataclasses with attribute access. Async uses `async for`.
+
+## Errors
+
+```python
+from uniqos import RateLimitError, QuotaExhaustedError
+
+try:
+    response = client.respond(personality_id="pers_...", message="hi")
+except RateLimitError as err:
+    print(f"Rate limited. Retry after {err.retry_after_seconds}s")
+except QuotaExhaustedError as err:
+    print(f"Quota exhausted: {err.details}")
+```
+
+Every error carries `code`, `message`, `request_id`, `http_status`, and `details`. Catch
+`UniqOSError` for anything the SDK can raise. The SDK retries transient failures
+(`429 rate_limit_exceeded`, `500/502/503`, network) automatically with exponential backoff; it
+never retries `quota_exhausted`, `401`, `403`, or `504 turn_timeout` (see Configuration below).
+
+## Configuration
+
+```python
+client = UniqOS(
+    api_key="uniq_test_...",
+    base_url="https://api.uniqos.ai",  # host only; do NOT include /v1
+    timeout=90,                         # seconds; default 90s; 0 disables
+    max_retries=3,                      # 0 disables retries (504 is never auto-retried)
+    log_level="warning",               # debug | info | warning | error | silent
+    logger=my_logger,                   # optional: any object with debug/info/warning/error
+)
+```
+
+> **Default timeout is 90s**, deliberately above the server's ~75s turn ceiling, so a slow
+> turn surfaces as the server's clean `504 turn_timeout` (a `TurnTimeoutError`) instead of a
+> client-side abort. A `504 turn_timeout` is **not retried automatically**: the turn already
+> ran to the budget, so a blind retry risks a second long turn and — combined with
+> client-vs-server timing — a double bill (ADR-0009). Retrying it is your explicit choice.
+
+The SDK never logs the full API key (only the prefix) nor message content beyond 50 chars.
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples): `hello_world.py`, `stateful.py`,
+`streaming.py`, `error_handling.py`, and `dogfood.py`.
+
+**With a real (or local) API** — set the environment and run:
+
+```bash
+export UNIQOS_API_KEY="uniq_test_..."
+export UNIQOS_PERSONALITY_ID="pers_..."
+# optional, for a local backend:
+export UNIQOS_BASE_URL="http://localhost:3000"
+
+python examples/hello_world.py
+```
+
+**Without a network** — the test suite drives every code path against a mocked HTTP layer
+([`respx`](https://lundberg.github.io/respx/)), so no live API is needed to exercise the SDK:
+
+```python
+import httpx, respx
+from uniqos import UniqOS
+
+@respx.mock
+def test_it():
+    respx.post("https://api.uniqos.ai/v1/respond").mock(
+        return_value=httpx.Response(200, json={"response": "hi"})
+    )
+    with UniqOS(api_key="uniq_test_abcd1234") as client:
+        assert client.respond(personality_id="p_1", message="hi")["response"] == "hi"
+```
+
+## Documentation
+
+Full reference and guides live at [docs.uniqos.ai](https://docs.uniqos.ai). This README and the
+in-editor docstrings cover the essentials; the deep documentation is not duplicated here.
+
+## License
+
+MIT

uniqos-0.4.0/docs/dev.md

@@ -0,0 +1,92 @@
+# Developing the `uniqos` Python SDK
+
+Conventions for this package. The decisions behind them live in the ADRs at
+`../../docs/adr/py-0001..0004`. The TypeScript SDK (`../typescript`) is the reference
+pattern; this package mirrors its structure and behavior with idiomatic Python.
+
+## Setup
+
+```bash
+cd packages/python
+make install        # uv sync — creates .venv and installs the package + dev tools
+```
+
+Requires [uv](https://docs.astral.sh/uv/). Everything else (ruff, mypy, pytest,
+datamodel-code-generator) is a dev dependency installed by `uv sync`.
+
+## Commands
+
+| Command          | What it does                                          |
+| ---------------- | ----------------------------------------------------- |
+| `make generate`  | Regenerate models from the shared OpenAPI snapshot    |
+| `make format`    | `ruff format` the code                                |
+| `make lint`      | `ruff check`                                          |
+| `make typecheck` | `mypy --strict` over `src/uniqos`                     |
+| `make test`      | `pytest`                                              |
+| `make build`     | `uv build` → wheel + sdist in `dist/`                 |
+| `make check`     | format-check + lint + typecheck + test (what CI runs) |
+
+## Layout
+
+```
+src/uniqos/
+  __init__.py        # public surface + __version__ (single source of the version)
+  py.typed           # PEP 561 marker — the package ships types
+  client.py          # UniqOS (sync)               — Bloque 2
+  async_client.py    # AsyncUniqOS (async)          — Bloque 2
+  errors.py          # typed error hierarchy        — Bloque 3
+  resources/         # idiomatic namespaces          — Bloque 4
+  generated/         # AUTO-GENERATED, never edit    — Bloque 1
+  _core/             # pure shared core (transport, config, retry, logging, streaming)
+tests/               # pytest; mock httpx with respx (no live network)
+examples/            # runnable examples            — Bloque 6
+```
+
+## Core conventions
+
+- **snake_case passthrough.** Request/response fields mirror the API verbatim. No
+  casing translation — in Python this is also the idiomatic form.
+- **dataclasses + TypedDict, no runtime modeling (ADR PY-0002).** The only runtime
+  dependency is `httpx`. Streaming events are generated frozen dataclasses (the
+  contract's only named schemas); request payloads and key returned entities are
+  hand-written `TypedDict`s; the long tail is `dict[str, Any]` passthrough. We do
+  **not** validate responses at runtime — like the TS SDK, we trust the contract and
+  type structurally. The only fail-fast validation is client configuration
+  (api_key format, invalid option combinations).
+- **Shared pure core, two thin clients (ADR PY-0001).** `_core/` holds I/O-agnostic
+  logic (config, errors, retry policy, SSE parsing) used by both `UniqOS` (over
+  `httpx.Client`) and `AsyncUniqOS` (over `httpx.AsyncClient`). Add a method to one
+  client → add it to the other; a surface-parity test guards against drift.
+- **Never edit `generated/`.** It is overwritten by `make generate` from the vendored
+  snapshot and excluded from hand-maintenance. CI regenerates and fails on any diff.
+- **Secrets & message content never logged.** Only the api_key prefix
+  (`uniq_test_kx7H...`); message content truncated to 50 chars at debug (SPEC-17 §11.3).
+
+## Code generation
+
+`make generate` runs `datamodel-code-generator` over the shared snapshot and writes
+`src/uniqos/generated/stream_events.py` — the **frozen dataclasses** for the five SSE
+events plus their nested objects, and the `RespondStreamEvent` union (ADR PY-0004).
+
+It is scoped to `--openapi-scopes schemas`: the contract's _only_ 6 named schemas are
+the streaming ones, so nothing else is generated. Everything else in the SDK is
+hand-written. `--disable-timestamp` keeps the output byte-stable, so **regenerating an
+unchanged snapshot is a no-op** — CI runs `make generate` then `git diff --exit-code`
+and fails if the committed file drifts. The formatter (black/isort, pinned via
+`uv.lock`) makes the output reproducible across machines and CI.
+
+ruff skips `generated/` (it is machine-emitted); mypy `--strict` still type-checks it.
+Never edit the file by hand — change the contract and regenerate.
+
+## OpenAPI snapshot
+
+Both SDKs read the **same** vendored snapshot at the monorepo root,
+[`../../openapi/openapi.json`](../../openapi/openapi.json). To refresh the contract,
+update the API, export its OpenAPI, refresh the snapshot, review the diff, regenerate,
+and commit — see `../../openapi/README.md`.
+
+## Style
+
+ruff (`line-length = 100`, target `py310`) for both format and lint; mypy `--strict`.
+Match the surrounding code: function over lambda for exported helpers, `async`/`await`,
+named exports, Google-style docstrings on public methods (SPEC-17 §14.4).

uniqos-0.4.0/examples/README.md

@@ -0,0 +1,26 @@
+# Examples
+
+Runnable scripts for the `uniqos` SDK:
+
+| File                | What it shows                                              |
+| ------------------- | ---------------------------------------------------------- |
+| `hello_world.py`    | A single stateless `respond` call                          |
+| `stateful.py`       | Persistent `user_id`, multi-turn relational memory         |
+| `streaming.py`      | Token-by-token SSE (`for event in stream`)                 |
+| `error_handling.py` | Catching `RateLimitError` / `QuotaExhaustedError` / others |
+| `dogfood.py`        | Smoke test against a local (or remote) API                 |
+
+## Running
+
+Set the environment and run any script directly:
+
+```bash
+export UNIQOS_API_KEY="uniq_test_..."
+export UNIQOS_PERSONALITY_ID="pers_..."
+export UNIQOS_BASE_URL="http://localhost:3000"   # optional, for a local backend
+
+python examples/hello_world.py
+```
+
+To exercise the SDK **without a network**, see the mocked-`httpx` (`respx`) pattern in the
+[package README](../README.md#examples) and the test suite under [`../tests/`](../tests).

uniqos-0.4.0/examples/dogfood.py

@@ -0,0 +1,39 @@
+"""Dogfood smoke test — exercise the SDK against a local (or remote) API.
+
+Mirror of the TypeScript SDK's dogfood smoke. Reads a couple of endpoints and runs one
+stateless turn, printing what came back.
+
+Run against a local API:
+    export UNIQOS_API_KEY="uniq_test_..."
+    export UNIQOS_BASE_URL="http://localhost:3000"
+    export UNIQOS_PERSONALITY_ID="pers_..."
+    python examples/dogfood.py
+"""
+
+import os
+
+from uniqos import UniqOS
+
+DOGFOOD_USER = "dogfood_user_chess_001"
+
+
+def main() -> None:
+    client = UniqOS(
+        api_key=os.environ["UNIQOS_API_KEY"],
+        base_url=os.environ.get("UNIQOS_BASE_URL", "http://localhost:3000"),
+    )
+    with client:
+        print(f"environment: {client.environment}  base_url: {client.base_url}")
+
+        page = client.interactions.list(user_id=DOGFOOD_USER)
+        print(f"interactions for {DOGFOOD_USER}: {len(page.get('data', []))}")
+
+        result = client.respond(
+            personality_id=os.environ["UNIQOS_PERSONALITY_ID"],
+            message="Hello from the Python dogfood smoke test.",
+        )
+        print("respond:", result.get("response", result))
+
+
+if __name__ == "__main__":
+    main()