docs: add AGENTS.md/CLAUDE.md agent guide, refresh README

Add an AGENTS.md agent guide (CLAUDE.md symlinked to it, matching the otari
repo) covering the SDK architecture, both auth modes, the endpoint-coverage
drift gate, and the exact uv build/test/lint commands. README: add the 409
BatchNotCompleteError row, correct the stale 'built on the OpenAI Python SDK'
claim, retitle the heading to 'Otari Python Client SDK', and rebrand
otari-gateway wording to otari. Drop the internal 'Option C' codename from
source docstrings/comments.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: njbrake

AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+Guidance for agentic coding tools working in this repository.
+Scope: entire repo.
+
+`CLAUDE.md` is a symlink to this file. Always edit `AGENTS.md` directly; never modify `CLAUDE.md`.
+
+## Project Snapshot
+- Project: `otari` (PyPI package name `otari`) — the **Python client SDK** for the otari
+  gateway / platform. `OtariClient` (sync) and `AsyncOtariClient` (async) talk to a running
+  gateway over HTTP.
+- Language/runtime: Python 3.11+ (CI matrix: 3.11, 3.12, 3.13).
+- Package manager + task runner: `uv`.
+- Source root: `src/otari` (imported as `otari`).
+- Tests: `tests/unit` (mocked, offline) and `tests/integration` (real gateway).
+
+## Architecture (Big Picture)
+This SDK is a **thin, hand-written shell over an OpenAPI-generated typed core**. Read these
+together before changing request behavior.
+
+- **Generated core — `src/otari/_client/`**: produced by OpenAPI Generator from the gateway's
+  OpenAPI spec. It is **generated, not hand-edited.** Regeneration happens upstream in the
+  gateway repo (`.github/workflows/gateway-sdk-codegen.yml`), which opens a
+  `sdk-codegen/client-core` PR here. The core is **excluded from ruff and mypy**
+  (`pyproject.toml`: `extend-exclude` / mypy `exclude`). Do not edit it to fix a lint error;
+  fix the shell or the upstream spec/generator instead.
+- **Hand-written shell** (everything else under `src/otari/`):
+  - `client.py` / `async_client.py` — ergonomic `OtariClient` / `AsyncOtariClient` with
+    `completion`, `response`, `message`, `embedding`, `moderation`, `rerank`, `list_models`,
+    batch operations, and a `control_plane` accessor.
+  - `_base.py` — shared logic: auth-mode resolution, default headers, URL normalization, and
+    the single seam where generated `ApiException` is caught and mapped to typed errors.
+  - `_streaming.py` — hand-written SSE shim. The generated core buffers and **cannot stream**,
+    so streaming endpoints use raw `httpx` + a line/event parser. Chat streaming yields typed
+    `ChatCompletionChunk`; responses/messages streaming yields raw event `dict`s (no chunk
+    model exists for those).
+  - `errors.py` — typed error hierarchy (`OtariError` base + subclasses).
+  - `types.py` — re-exports of generated models plus hand-written TypedDicts (batch/options).
+  - `control_plane.py` — wrapper over the management endpoints (keys/users/budgets/pricing/usage).
+
+### Two auth modes (must both keep working)
+Resolved in `_base.py` from constructor args, then environment:
+- **Platform** (`OTARI_AI_TOKEN` / `platform_token`): `Authorization: Bearer <token>`, base URL
+  defaults to `https://api.otari.ai`.
+- **Self-hosted** (`api_key` + `api_base`, env `GATEWAY_API_KEY` / `GATEWAY_API_BASE`):
+  `Otari-Key` header; `api_base` is **required** in this mode.
+Error mapping applies in both modes; do not regress one when changing the other.
+
+### Endpoint-coverage drift gate
+`tests/unit/test_endpoint_coverage.py` fetches the canonical gateway spec
+(`https://raw.githubusercontent.com/mozilla-ai/otari/main/docs/public/openapi.json`) and
+asserts every gateway endpoint is accounted for in `sdk-endpoints.txt` (`[covered]` or
+`[excluded]` with a reason). A new gateway endpoint with no wrapper and no explicit exclusion
+fails CI. When you add or intentionally skip an endpoint, update `sdk-endpoints.txt`.
+
+## Setup Commands
+- Install (dev): `uv sync --extra dev`
+
+## Test Commands
+- Full suite: `uv run pytest`
+- Unit only: `uv run pytest tests/unit`
+- Single test: `uv run pytest tests/unit/test_client.py::TestOtariClient::test_completion -v`
+- Drift gate (needs network): `uv run pytest tests/unit/test_endpoint_coverage.py -v`
+- Integration tests under `tests/integration/` spawn / require a real gateway and are skipped
+  when one is not available.
+
+## Lint / Typecheck / Build Commands
+- Lint: `uv run ruff check .`
+- Typecheck (mypy strict): `uv run mypy src/`
+- Build: `uv build`
+
+## Repository Conventions
+- `from __future__ import annotations` at the top of modules; `TYPE_CHECKING` for type-only
+  imports; import `Callable`/`Iterator` from `collections.abc`.
+- mypy is `strict`; the generated `otari._client` is excluded. New/changed shell code must be
+  fully typed. Use `@overload` for streaming polymorphism (`stream=True` vs not), as `client.py`
+  already does.
+- Public API is exported from `src/otari/__init__.py` (clients, errors, types); don't remove or
+  rename exports without auditing callers.
+- Unit tests mock at the transport seam (the generated core's REST client) and use `respx` for
+  the raw-`httpx` streaming path. Test classes are `Test<Feature>`.
+
+## Change Validation Checklist
+- Touched request handling, auth, or errors → run `tests/unit` and confirm both auth modes still
+  map errors correctly.
+- Touched streaming → run the streaming tests; verify chat yields `ChatCompletionChunk` and
+  responses/messages yield raw dicts.
+- Added/removed an endpoint wrapper → update `sdk-endpoints.txt` and run the drift gate.
+- Always run `uv run ruff check .` and `uv run mypy src/` before opening a PR.
+
+## Notes for Agents
+- Never hand-edit `src/otari/_client/`; it is regenerated from the gateway spec.
+- Prefer minimal, targeted edits; match existing typing and import style in touched files.
+- Preserve security-relevant behavior (header/auth handling, error-detail boundaries).

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -4,21 +4,23 @@
 
 <div align="center">
 
-# otari (Python)
+# Otari Python Client SDK
 
 ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
 [![PyPI](https://img.shields.io/pypi/v/otari)](https://pypi.org/project/otari/)
 <a href="https://discord.gg/4gf3zXrQUc">
     <img src="https://img.shields.io/static/v1?label=Chat%20on&message=Discord&color=blue&logo=Discord&style=flat-square" alt="Discord">
 </a>
 
-**Python client for [otari-gateway](https://github.com/mozilla-ai/otari).**
-Communicate with any LLM provider through the gateway using a single, typed interface.
+**Python client for [otari](https://github.com/mozilla-ai/otari), the open-source core that powers [otari.ai](https://otari.ai).**
+Communicate with any LLM provider through otari using a single, typed interface.
 
 [TypeScript SDK](https://github.com/mozilla-ai/otari-sdk-ts) | [Documentation](https://mozilla-ai.github.io/otari/) | [Platform (Beta)](https://otari.ai/)
 
 </div>
 
+> New to otari? The [otari repo](https://github.com/mozilla-ai/otari) explains what it is and why you’d use it.
+
 ## Quickstart
 
 Generate an API token at [otari.ai/organization-settings/api-tokens](https://otari.ai/organization-settings/api-tokens), then add a provider key (e.g. OpenAI) at [otari.ai/organization-settings/provider-keys](https://otari.ai/organization-settings/provider-keys) so the gateway can route requests to that provider. Then use the client:
@@ -46,7 +48,7 @@ Prefer to keep secrets out of code? Set `OTARI_AI_TOKEN` in your environment and
 
 ## Self-hosting the gateway
 
-Prefer to run the gateway yourself instead of using the hosted otari.ai? Follow the setup in the [otari gateway repo](https://github.com/mozilla-ai/otari), then point the SDK at it:
+Prefer to run the gateway yourself instead of using the hosted otari.ai? Follow the setup in the [otari repo](https://github.com/mozilla-ai/otari), then point the SDK at it:
 
 ```python
 client = OtariClient(
@@ -57,14 +59,14 @@ client = OtariClient(
 
 The SDK sends `api_key` via the custom `Otari-Key: Bearer …` header. Env: `GATEWAY_API_BASE` + `GATEWAY_API_KEY`.
 
-Make sure your gateway has provider keys configured (e.g. OpenAI) so it can route requests upstream — see the [otari gateway repo](https://github.com/mozilla-ai/otari) for setup.
+Make sure your gateway has provider keys configured (e.g. OpenAI) so it can route requests upstream — see the [otari repo](https://github.com/mozilla-ai/otari) for setup.
 
 ## Installation
 
 ### Requirements
 
 - Python 3.11 or newer
-- A running [otari-gateway](https://mozilla-ai.github.io/otari/gateway/overview/) instance
+- A running [otari](https://mozilla-ai.github.io/otari/gateway/overview/) instance
 
 ### Install
 
@@ -91,33 +93,6 @@ export GATEWAY_API_KEY="your-key-here"
 
 Alternatively, pass credentials directly when creating the client (see [Usage](#usage) examples).
 
-## otari-gateway
-
-This Python SDK is a client for [otari-gateway](https://github.com/mozilla-ai/otari), an **optional** FastAPI-based proxy server that adds enterprise-grade features on top of the core library:
-
-- **Budget Management** - Enforce spending limits with automatic daily, weekly, or monthly resets
-- **API Key Management** - Issue, revoke, and monitor virtual API keys without exposing provider credentials
-- **Usage Analytics** - Track every request with full token counts, costs, and metadata
-- **Multi-tenant Support** - Manage access and budgets across users and teams
-
-The gateway sits between your applications and LLM providers, exposing an OpenAI-compatible API that works with any supported provider.
-
-### Quick Start
-
-```bash
-docker run \
-  -e GATEWAY_MASTER_KEY="your-secure-master-key" \
-  -e OPENAI_API_KEY="your-api-key" \
-  -p 8000:8000 \
-  ghcr.io/mozilla-ai/otari/gateway:latest
-```
-
-> **Note:** You can use a specific release version instead of `latest` (e.g., `1.2.0`). See [available versions](https://github.com/orgs/mozilla-ai/packages/container/package/otari%2Fgateway).
-
-### Managed Platform (Beta)
-
-Prefer a hosted experience? The [otari platform](https://otari.ai/) provides a managed control plane for keys, usage tracking, and cost visibility across providers, while still building on the same `otari` interfaces.
-
 ## Usage
 
 > **Migrating from a previous version?** `OtariClient` is now **synchronous** — call its methods directly (no `await`). For asynchronous code, switch to `AsyncOtariClient`, which keeps the previous `await`-based API. See [Async usage](#async-usage).
@@ -285,6 +260,7 @@ except RateLimitError as e:
 | 401, 403 | `AuthenticationError` | Invalid or missing credentials |
 | 402 | `InsufficientFundsError` | Budget or credits exhausted |
 | 404 | `ModelNotFoundError` | Model not found, or no provider key configured for the requested provider. The exception's `message` carries the gateway's detail. |
+| 409 | `BatchNotCompleteError` | Batch results requested before the batch finished |
 | 429 | `RateLimitError` | Rate limit exceeded (includes `retry_after`) |
 | 502 | `UpstreamProviderError` | Upstream provider unreachable |
 | 504 | `GatewayTimeoutError` | Gateway timed out waiting for provider |
@@ -313,15 +289,6 @@ async with AsyncOtariClient(api_base="http://localhost:8000") as client:
     )
 ```
 
-## Why choose `otari`?
-
-- **Simple, unified interface** - Single client for all providers through the gateway, switch models with just a string change
-- **Developer friendly** - Full type hints for better IDE support and clear, actionable error messages
-- **Leverages the OpenAI SDK** - Built on the official OpenAI Python SDK for maximum compatibility
-- **Sync and async** - Use the synchronous `OtariClient` or the asynchronous `AsyncOtariClient`, both with the same typed interface
-- **Stays framework-agnostic** so it can be used across different projects and use cases
-- **Battle-tested** - Powers our own production tools ([any-agent](https://github.com/mozilla-ai/any-agent))
-
 ## Development
 
 ```bash

src/otari/_base.py

@@ -7,7 +7,7 @@
 :class:`~otari.async_client.AsyncOtariClient`) construct their own generated
 ``_client`` and httpx clients and implement the I/O methods on top of this base.
 
-Option C: the inference path is a thin shell over the OpenAPI-generated core in
+The inference path is a thin shell over the OpenAPI-generated core in
 :mod:`otari._client` (typed models + per-endpoint API classes). The generated
 ``ApiException`` is the single error type all generated calls raise; this module
 maps it to the typed otari exception hierarchy in :mod:`otari.errors`.

src/otari/async_client.py

@@ -1,6 +1,6 @@
 """AsyncOtariClient: asynchronous Python client for the otari gateway.
 
-Option C: a thin async shell over the OpenAPI-generated core in
+A thin async shell over the OpenAPI-generated core in
 :mod:`otari._client`. The generated core is synchronous (urllib3-based), so
 non-streaming calls are dispatched to a worker thread via ``asyncio.to_thread``;
 streaming is natively async over ``httpx.AsyncClient`` and the SSE shim in

src/otari/client.py

@@ -1,6 +1,6 @@
 """OtariClient: synchronous Python client for the otari gateway.
 
-Option C: a thin, ergonomic shell over the OpenAPI-generated core in
+A thin, ergonomic shell over the OpenAPI-generated core in
 :mod:`otari._client`. Non-streaming calls go through the generated typed API
 classes (returning typed models such as ``ChatCompletion``); streaming calls go
 through the hand-written SSE shim in :mod:`otari._streaming`; generated

src/otari/control_plane.py

@@ -1,7 +1,7 @@
 """Typed client for the gateway control-plane (management) endpoints.
 
 Wraps the OpenAPI-generated :mod:`otari._client` core (the same core that backs
-the inference path under Option C). The control-plane endpoints (API keys,
+the inference path). The control-plane endpoints (API keys,
 users, budgets, pricing, usage) authenticate with
 ``Authorization: Bearer <admin/master key>``, which is distinct from the
 ``Otari-Key`` virtual key used for inference. Obtain an instance via

tests/unit/conftest.py

@@ -1,6 +1,6 @@
 """Shared test helpers for mocking the generated core's transport.
 
-Option C wires the SDK over the OpenAPI-generated core (:mod:`otari._client`),
+The SDK is a thin shell over the OpenAPI-generated core (:mod:`otari._client`),
 whose non-streaming calls go through ``RESTClientObject.request`` (urllib3) and
 whose streaming path is a hand-written raw httpx request. These helpers mock both
 seams without a live gateway:

tests/unit/test_async_client.py

@@ -1,4 +1,4 @@
-"""Tests for the asynchronous AsyncOtariClient (Option C: generated-core shell).
+"""Tests for the asynchronous AsyncOtariClient (generated-core shell).
 
 The async client dispatches the (synchronous) generated calls off-thread via
 ``asyncio.to_thread`` and streams natively over ``httpx.AsyncClient``. Non-

tests/unit/test_client.py

@@ -1,4 +1,4 @@
-"""Tests for the synchronous OtariClient (Option C: generated-core shell).
+"""Tests for the synchronous OtariClient (generated-core shell).
 
 Covers constructor / auth-mode wiring, request shaping, typed response parsing,
 generated ``ApiException`` -> typed error mapping, and the hand-written SSE