ai_api_unified 3.2.0__tar.gz → 3.6.0__tar.gz

{ai_api_unified-3.2.0 → ai_api_unified-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ai_api_unified
-Version: 3.2.0
+Version: 3.6.0
 Summary: Unified access layer for AI completions (LLM), embedding (semantic), image, video, and voice services
 License: MIT
 Keywords: llm,openai,anthropic,claude,bedrock,gemini,vertex,embeddings,completion,video,voice,api
@@ -77,7 +77,7 @@ Project-URL: Issues, https://github.com/davecthomas/ai-api-unified/issues
 Project-URL: Repository, https://github.com/davecthomas/ai-api-unified
 Description-Content-Type: text/markdown
 
-# ai-api-unified 3.2.0
+# ai-api-unified 3.6.0
 
 [![CI](https://github.com/davecthomas/ai-api-unified/actions/workflows/ci.yml/badge.svg)](https://github.com/davecthomas/ai-api-unified/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/ai-api-unified.svg)](https://pypi.org/project/ai-api-unified/)
@@ -117,11 +117,11 @@ The current package architecture is registry-backed and lazy-loaded:
 More than 100 models from 10 model makers (OpenAI, Anthropic, Google,
 Amazon, DeepSeek, Alibaba Qwen, Z.ai, Voyage AI, ElevenLabs, and Microsoft)
 behind one interface, plus any server that speaks the OpenAI API. Switching
-models is a configuration change: set the capability's engine (for example
-`COMPLETIONS_ENGINE`) and model (`COMPLETIONS_MODEL_NAME`).
+models is a configuration change: set the capability's engine and model in
+`models.json` (for example `completions.engine` and `completions.model`).
 
 <!-- supported-models:start -->
-| Capability | Provider | Engine (`*_ENGINE`) | Models |
+| Capability | Provider | Engine (`<section>.engine`) | Models |
 | --- | --- | --- | --- |
 | Completions | OpenAI | `openai`, `openai-responses` | `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` (default), `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano` ⚠ until 2026-10-23, `o4-mini` ⚠ until 2026-10-23, `gpt-4o`, `gpt-4o-mini` |
 | Completions | Anthropic | `claude` | `claude-fable-5-1`, `claude-opus-5-5`, `claude-fable-5`, `claude-opus-5` (default), `claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5` |
@@ -131,7 +131,7 @@ models is a configuration change: set the capability's engine (for example
 | Completions | Amazon Bedrock: DeepSeek | `bedrock` | `deepseek.v3.2`, `us.deepseek.r1-v1:0` |
 | Completions | Amazon Bedrock: Qwen (Alibaba) | `bedrock` | `qwen.qwen3-next-80b-a3b`, `qwen.qwen3-235b-a22b-2507-v1:0`, `qwen.qwen3-coder-next`, `qwen.qwen3-32b-v1:0` |
 | Completions | Amazon Bedrock: GLM (Z.ai) | `bedrock` | `zai.glm-5`, `zai.glm-4.7`, `zai.glm-4.7-flash` |
-| Completions | Any OpenAI-compatible server (vLLM, Ollama, LiteLLM, ...) | `openai-compatible` | any model the server hosts (`COMPLETIONS_MODEL_NAME`) |
+| Completions | Any OpenAI-compatible server (vLLM, Ollama, LiteLLM, ...) | `openai-compatible` | any model the server hosts (`completions.model`) |
 | Embeddings | OpenAI | `openai` | `text-embedding-3-small` (default), `text-embedding-3-large`, `text-embedding-ada-002` |
 | Embeddings | Google | `google-gemini` | `gemini-embedding-001` (default), `gemini-embedding-2` (multimodal) |
 | Embeddings | Voyage AI | `voyage` | `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-code-4`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-3-lite`, `voyage-3` (default), `voyage-3-large`, `voyage-code-3`, `voyage-finance-2`, `voyage-law-2` |
@@ -287,30 +287,34 @@ poetry install --all-extras --with dev
 | `similarity_score`               | NumPy-based similarity helpers                                         |
 | `dev`                            | Optional dev dependencies from `[project.optional-dependencies]`       |
 
-### Environment File
+### Environment File and models.json
 
-Copy [`env_template`](env_template) to `.env` and fill in only the providers you use.
-
-The OSS template defaults to Google API-key auth:
+Two files: `.env` holds credentials and endpoint overrides; `models.json`
+holds every model selection. Copy [`env_template`](env_template) to `.env`
+and fill in only the providers you use, and copy
+[`models_sample.json`](models_sample.json) to `models.json` and keep the
+sections you need. The sample defaults to Google with API-key auth:
 
 ```dotenv
-COMPLETIONS_ENGINE=google-gemini
-EMBEDDING_ENGINE=google-gemini
-IMAGE_ENGINE=google-gemini
-VIDEO_ENGINE=google-gemini
-AI_VOICE_ENGINE=google
-
 GOOGLE_GEMINI_API_KEY=...
 GOOGLE_AUTH_METHOD=api_key
+```
 
-COMPLETIONS_MODEL_NAME=gemini-3.7-flash
-EMBEDDING_MODEL_NAME=gemini-embedding-001
-IMAGE_MODEL_NAME=gemini-3.1-flash-image
-VIDEO_MODEL_NAME=veo-3.1-lite-generate-preview
-DEFAULT_GEMINI_TTS_MODEL=gemini-2.5-pro-tts
+```json
+{
+  "completions": {"engine": "google-gemini", "model": "gemini-3.7-flash", "thinking": "medium"},
+  "embeddings":  {"engine": "google-gemini", "model": "gemini-embedding-001"},
+  "images":      {"engine": "google-gemini", "model": "gemini-3.1-flash-image"},
+  "videos":      {"engine": "google-gemini", "model": "veo-3.1-lite-generate-preview"},
+  "voice":       {"engine": "google", "tts_model": "gemini-2.5-pro-tts"}
+}
 ```
 
-Leave `EMBEDDING_DIMENSIONS` unset unless you deliberately want a provider-specific override. The library preserves provider defaults.
+Leave `embeddings.dimensions` at `0` unless you deliberately want a
+provider-specific size. The library preserves provider defaults. A `.env`
+from before `models.json` still works: each selection key it carries
+overrides the file and logs a deprecation warning; `scripts/migrate2json.py`
+moves them (see Configuration).
 
 ### Smoke Test
 
@@ -334,13 +338,15 @@ print(response)
 
 ### Completions with automatic fallback
 
-Add one setting and the same client keeps serving when the primary model
+Add one list and the same client keeps serving when the primary model
 cannot. The chain below runs Claude first, then OpenAI, then Gemini:
 
-```bash
-COMPLETIONS_ENGINE=claude
-COMPLETIONS_MODEL_NAME=claude-opus-5
-COMPLETIONS_FALLBACKS=openai:gpt-5.6-luna,google-gemini:gemini-3.7-flash
+```json
+"completions": {
+  "engine": "claude",
+  "model": "claude-opus-5",
+  "fallbacks": ["openai:gpt-5.6-luna", "google-gemini:gemini-3.7-flash"]
+}
 ```
 
 ```python
@@ -396,7 +402,7 @@ if client.capabilities.supports_token_counting:
 ### OpenAI Responses engine
 
 OpenAI exposes two completions engines. The default `openai` engine uses Chat
-Completions; the `openai-responses` engine (`COMPLETIONS_ENGINE=openai-responses`)
+Completions; the `openai-responses` engine (`completions.engine: "openai-responses"`)
 uses the Responses API, OpenAI's successor to Chat Completions. Both implement
 `send_prompt`, `strict_schema_prompt`, and
 `send_prompt_streaming`. The Responses engine is text-only for now; use the
@@ -411,10 +417,12 @@ surface as the `openai` engine: `send_prompt`, streaming,
 `send_conversation` with tools, `send_structured_output`,
 `strict_schema_prompt`, and the async variants.
 
+```json
+"completions": {"engine": "openai-compatible", "model": "Qwen/Qwen3-32B"}
+```
+
 ```dotenv
-COMPLETIONS_ENGINE=openai-compatible
 OPENAI_COMPATIBLE_BASE_URL=http://localhost:8000/v1   # required
-COMPLETIONS_MODEL_NAME=Qwen/Qwen3-32B                 # required
 OPENAI_COMPATIBLE_API_KEY=...                         # optional for local servers
 OPENAI_COMPATIBLE_STRUCTURED_OUTPUT=json_schema       # or json_object
 OPENAI_COMPATIBLE_CONTEXT_WINDOW=131072               # optional context guard
@@ -451,9 +459,11 @@ engine additionally implements the async variants and batch completions. Use
 `claude` for the current model lineup on Anthropic's own endpoint; use
 `anthropic` when your Claude access is provisioned through AWS.
 
+```json
+"completions": {"engine": "claude", "model": "claude-opus-5"}
+```
+
 ```dotenv
-COMPLETIONS_ENGINE=claude
-COMPLETIONS_MODEL_NAME=claude-opus-5
 ANTHROPIC_API_KEY=...
 ```
 
@@ -510,6 +520,85 @@ has no per-call timeout). See the support matrix below.
 Unsupported combinations raise the typed `AiProviderCapabilityUnsupportedError`
 and each engine's `client.capabilities` flags report support at runtime.
 
+### Thinking levels
+
+How much a model thinks before answering is one provider-neutral setting,
+`AIThinkingLevel`, with six values: `off`, `minimal`, `low`, `medium`,
+`high`, `max`. Configuration and application code use the level; each
+engine applies it through its provider's own control, and no code or config
+names a provider field. The default is `medium`.
+
+```python
+from ai_api_unified import AIFactory, AIThinkingLevel
+
+client = AIFactory.get_ai_completions_client(thinking="high")   # or "thinking": "high" in models.json
+client.thinking_level = AIThinkingLevel.LOW                      # change the default for later calls
+
+text = client.send_prompt("...", other_params=params_with(thinking=AIThinkingLevel.MAX))
+turn = client.send_conversation(system, messages, provider_options={"thinking_level": "off"})
+result = client.send_structured_output(prompt, response_model=Summary,
+                                       provider_options={"thinking_level": "low"})
+
+turn.thinking.requested, turn.thinking.applied, turn.thinking.exact   # AIThinkingResolution
+client.last_thinking                                                   # for send_prompt and friends
+```
+
+Precedence: the call (`other_params.thinking` on the text methods; the
+reserved `thinking_level` key in `provider_options` on `send_conversation`
+and `send_structured_output`, stripped before the options reach the
+provider), then the client (`thinking_level`, set by the `thinking=`
+factory argument), then `completions.thinking` in `models.json`, then
+`medium`. The level has no `.env` key: it is a model selection, and those
+live in the file. The factory applies one level to the primary,
+its fallbacks, and every router tier, so a request that fails over keeps its
+level.
+
+`client.capabilities.thinking` lists the standard levels the model honors
+exactly (`None` when the model has no thinking control). A requested level
+outside that list resolves to the nearest one the model supports, and a tie
+goes to the lower level, since lower thinking is cheaper and the caller
+asked for no more. The library records both levels: on `result.thinking` and
+`client.last_thinking` (`requested`, `applied`, `exact`, and a `reason`
+such as `unsupported_level`, `no_thinking_control`, `forced_tool_choice`,
+`assistant_prefill`, or `max_tokens_too_small`), on every completions
+observability event (`thinking_requested`, `thinking_applied`,
+`thinking_exact`), and in an `ai_thinking_event` log line when they differ.
+
+How each engine applies a level:
+
+| Engine | Models | `off` | `minimal` | `low` / `medium` / `high` / `max` |
+|---|---|---|---|---|
+| `claude`, Bedrock Claude | Fable 5 / 5.1, Opus 5.5 (always on) | nearest: `low` | nearest: `low` | `output_config.effort` |
+| `claude`, Bedrock Claude | Opus 5, Haiku 5.5, Sonnet 5, Opus 4.6 to 4.8, Sonnet 4.6 | `thinking.type: disabled` | nearest: `off` | `thinking.type: adaptive` + `output_config.effort` |
+| `claude`, Bedrock Claude | Sonnet 5.5 | `thinking.type: between_tools` | nearest: `off` | `thinking.type: adaptive` + `output_config.effort` |
+| `claude`, Bedrock Claude | Haiku 4.5, Sonnet 4.5, Opus 4.5, Opus 4.1, Sonnet 4, Opus 4, 3.7 Sonnet | omit `thinking` | nearest: `off` | `thinking.budget_tokens` 1024 / 4096 / 16384 / 32768, capped at `max_tokens` less 1024 kept for the answer |
+| `claude`, Bedrock Claude | Claude 3 Opus and Haiku, 3.5 Sonnet and Haiku | no control | no control | no control |
+| `openai`, `openai-responses` | GPT-5.1 and later, GPT-6 | `reasoning_effort: none` (not on GPT-6 Astra) | nearest | `low` / `medium` / `high` / `xhigh` |
+| `openai`, `openai-responses` | GPT-5, GPT-5 mini, nano, pro, codex, and dated snapshots | nearest: `minimal` | `minimal` | `low` / `medium` / `high` / nearest: `high` |
+| `openai`, `openai-responses` | o-series | nearest: `low` | nearest: `low` | `low` / `medium` / `high` / nearest: `high` |
+| `openai`, `openai-compatible` | GPT-4.1, GPT-4o, uncataloged | no control | no control | no control |
+| `google-gemini` | Gemini 3 Flash and later | nearest: `minimal` | `thinking_level: MINIMAL` | `LOW` / `MEDIUM` / `HIGH` / nearest: `HIGH` |
+| `google-gemini` | Gemini 3 Pro | nearest: `low` | nearest: `low` | `LOW` / nearest / `HIGH` / nearest: `HIGH` |
+| `google-gemini` | Gemini 2.5 Flash, Flash Lite | `thinking_budget: 0` | nearest: `off` | `thinking_budget` 1024 / 8192 / 16384 / 24576 |
+| `google-gemini` | Gemini 2.5 Pro | nearest: `low` | nearest: `low` | `thinking_budget` 1024 / 8192 / 16384 / 32768 |
+| Bedrock | Nova, DeepSeek, Qwen, GLM | no control | no control | no control |
+
+On Bedrock the Claude fields travel under `additionalModelRequestFields`.
+The engines merge these fields before `provider_options`, so a caller's own
+`thinking`, `reasoning_effort`, or `thinking_config` still wins. Three
+request shapes turn thinking off on models that allow it, with the reason
+recorded: a forced `tool_choice` (Claude rejects the pair), an assistant
+prefill (Bedrock's `strict_schema_prompt` on pre-4.6 Claude), and a
+`max_tokens` with no room for the 1024-token minimum budget after 1024
+tokens are kept for the answer. Bedrock's `send_prompt` and streaming
+defaults of 256 tokens rise to 4096 on budget-era Claude models when the
+caller sets no cap, so the configured level is applied.
+
+The tables follow each provider's documentation as of October 2026 and the
+live test (`poetry run pytest -m nonmock tests/test_thinking_levels_nonmock.py -q`)
+exercises the configured models. When a model rejects a value the table
+lists, the provider returns its own 400; correct the table entry.
+
 ### Structured output extraction (send_structured_output)
 
 `send_structured_output` is the single-shot extraction call: prose in, a parsed
@@ -695,7 +784,7 @@ Engine retry behavior:
   `AWS_MAX_ATTEMPTS` environment variable.
 
 Every engine accepts `retry_policy` at the constructor, through configuration
-(`COMPLETIONS_RETRY_POLICY=none`), or per call
+(`completions.retry_policy: "none"` in `models.json`), or per call
 (`provider_options={"retry_policy": "none"}`; on Bedrock the per-call
 override collapses that call's schedule). HTTP-level failures raise
 `AiProviderRequestError`, whose `status_code` attribute lets caller backoff
@@ -897,7 +986,7 @@ Anthropic serves none.
   whose capabilities declare `supports_async` (currently `voyage`); others
   raise `AiProviderCapabilityUnsupportedError`.
 - The `voyage` engine honors `retry_policy="none"` (constructor or
-  `COMPLETIONS_RETRY_POLICY=none`) and wraps provider failures in
+  `completions.retry_policy`) and wraps provider failures in
   `AiProviderRequestError` carrying `status_code`, matching the completions
   clients.
 
@@ -923,7 +1012,7 @@ Every embeddings client exposes a `capabilities` descriptor stating which input
 types the configured model supports. Text-only models raise
 `AiProviderCapabilityUnsupportedError` from `generate_embeddings_multimodal`.
 Google `gemini-embedding-2` embeds interleaved text, images, video, audio, and
-PDFs into one vector space (set `EMBEDDING_MODEL_NAME=gemini-embedding-2`):
+PDFs into one vector space (set `embeddings.model` to `gemini-embedding-2`):
 
 ```python
 from ai_api_unified import (
@@ -932,7 +1021,7 @@ from ai_api_unified import (
     SupportedDataType,
 )
 
-client = AIFactory.get_ai_embedding_client()  # EMBEDDING_MODEL_NAME=gemini-embedding-2
+client = AIFactory.get_ai_embedding_client()  # embeddings.model: gemini-embedding-2
 
 if SupportedDataType.IMAGE in client.capabilities.supported_data_types:
     with open("bicycle.png", "rb") as file_image:
@@ -1010,9 +1099,11 @@ print(result.job.status, result.artifacts[0].file_path)
 
 Environment:
 
+```json
+"videos": {"engine": "google-gemini", "model": "veo-3.1-lite-generate-preview"}
+```
+
 ```dotenv
-VIDEO_ENGINE=google-gemini
-VIDEO_MODEL_NAME=veo-3.1-lite-generate-preview
 GOOGLE_GEMINI_API_KEY=...
 GOOGLE_AUTH_METHOD=api_key
 ```
@@ -1046,9 +1137,11 @@ for reference only; use the `google-gemini` or `nova-reel` video engine.
 
 Environment:
 
+```json
+"videos": {"engine": "openai", "model": "sora-2"}
+```
+
 ```dotenv
-VIDEO_ENGINE=openai
-VIDEO_MODEL_NAME=sora-2
 OPENAI_API_KEY=...
 ```
 
@@ -1094,7 +1187,7 @@ with open(f"out{voice.default_audio_format.file_extension}", "wb") as output_fil
 `get_default_voice()` and `default_audio_format` supply the provider's own
 defaults. Use `stream_audio(text)` for the streaming variant.
 
-`AIFactory.get_ai_voice_client()` reads `AI_VOICE_ENGINE` and accepts an
+`AIFactory.get_ai_voice_client()` reads `voice.engine` from `models.json` and accepts an
 explicit `voice_engine` override, matching the other capability constructors.
 It delegates to `AIVoiceFactory.create()`, which remains supported and callable
 with no arguments.
@@ -1107,7 +1200,7 @@ originating caller id unless the application sets one through the
 observability context.
 
 The OpenAI voice client shares `AIOpenAIBase` with the other OpenAI-backed
-capabilities, so it honors `COMPLETIONS_RETRY_POLICY` and `OPENAI_BASE_URL_OVERRIDE`,
+capabilities, so it honors `completions.retry_policy` and `OPENAI_BASE_URL_OVERRIDE`,
 and accepts the same `retry_policy` and `base_url` constructor arguments:
 
 ```python
@@ -1122,8 +1215,8 @@ Only the `openai` voice engine accepts these; passing them to `google`,
 `azure`, or `elevenlabs` raises `AiProviderCapabilityUnsupportedError` rather
 than ignoring them.
 
-A blank retry-policy setting (`COMPLETIONS_RETRY_POLICY=`) is treated as
-unconfigured and falls back to `default` across every OpenAI-backed capability.
+A blank `completions.retry_policy` is treated as unconfigured and falls back
+to `default` across every OpenAI-backed capability.
 
 ## Classification
 
@@ -1138,7 +1231,7 @@ prompt and parsing an answer. The model router (a later section) is one consumer
 ```python
 from ai_api_unified import AIFactory, AIClassificationChoice
 
-client = AIFactory.get_ai_classifier_client()   # CLASSIFIER_ENGINE from env
+client = AIFactory.get_ai_classifier_client()   # classifier.engine from models.json
 result = client.classify_choice(
     "My invoice shows two charges for one order.",
     [
@@ -1208,8 +1301,8 @@ logger; it is never a silent zero.
 
 | Setting | Meaning |
 | ------- | ------- |
-| `CLASSIFIER_ENGINE` | Engine token. When unset, `openai-decisions` is used if `OPENAI_API_KEY` is set; otherwise the factory raises. |
-| `CLASSIFIER_MODEL_NAME` | Model override; blank falls back to `COMPLETIONS_MODEL_NAME` for structured-output engines, then the engine's default (`gpt-6-luna` for `openai-decisions`). |
+| `classifier.engine` (`models.json`) | Engine token. When unset, `openai-decisions` is used if `OPENAI_API_KEY` is set; otherwise the factory raises. |
+| `classifier.model` | Model override; blank falls back to `completions.model` for structured-output engines, then the engine's default (`gpt-6-luna` for `openai-decisions`). |
 | `AIFactory.get_ai_classifier_client(classifier_engine=, model_name=, base_url=)` | Arguments override the settings. |
 
 Exports: `AIBaseClassifier`, `AIClassifierCapabilitiesBase`,
@@ -1238,20 +1331,21 @@ so it acts only on failures another model could serve.
 
 ### Setting up a chain
 
-From configuration, which is the usual way:
+From `models.json`, which is the usual way:
 
-```bash
-# The primary stays where it always was.
-COMPLETIONS_ENGINE=claude
-COMPLETIONS_MODEL_NAME=claude-opus-5
-
-# Ordered engine:model pairs to try after the primary fails.
-COMPLETIONS_FALLBACKS=openai:gpt-5.6-luna,google-gemini:gemini-3.7-flash
-
-# Optional. Which failures trigger a move; this is the default.
-COMPLETIONS_FALLBACK_ON=unavailable,rate_limited,quota_exhausted,auth_rejected
+```json
+"completions": {
+  "engine": "claude",
+  "model": "claude-opus-5",
+  "fallbacks": ["openai:gpt-5.6-luna", "google-gemini:gemini-3.7-flash"],
+  "fallback_on": "unavailable,rate_limited,quota_exhausted,auth_rejected"
+}
 ```
 
+`fallbacks` lists the `engine:model` pairs to try, in order, after the
+primary fails; `fallback_on` names the failures that trigger a move (the
+value above is the default).
+
 Or in code, which overrides the settings:
 
 ```python
@@ -1270,14 +1364,17 @@ client = AIFactory.get_ai_completions_client(
 
 Rules for the chain:
 
-- The split in `COMPLETIONS_FALLBACKS` is on the first colon only, so Bedrock
+- The split in each `fallbacks` entry is on the first colon only, so Bedrock
   ids keep theirs: `bedrock:amazon.nova-lite-v1:0`. A pair with no model
   (`google-gemini`) uses that engine's default model.
 - Each fallback engine needs its own credentials and optional extra, exactly
   as it would if it were the primary.
 - The factory checks every fallback engine token against the provider
   registry when it builds the client, so a typo fails at startup, long
-  before any outage.
+  before any outage. The [configured-model check](#configured-model-check)
+  then probes each fallback model with its engine's credentials and prunes,
+  with a WARNING, any that does not exist or cannot be reached (no key,
+  rejected key, extra not installed).
 - Passing `fallbacks=[]` in code turns the chain off even when the setting
   is present.
 
@@ -1288,11 +1385,13 @@ Rules for the chain:
 2. If the engine raises `AiProviderRequestError` with a `fallback_reason` in
    the configured set, the client logs a warning naming both candidates and
    the reason, and sends the request to the next candidate.
-3. The client builds a fallback the first time a request needs it. When a
-   build fails (missing extra, bad credentials, unsupported option), the
-   client logs it once and skips that candidate for the rest of the
-   process, so a broken fallback never breaks startup or blocks the rest
-   of the chain.
+3. The client builds a fallback the first time a request needs it. The
+   configured-model check has already pruned fallbacks that are missing or
+   unreachable, so a build failure here is rare (an unsupported option,
+   for example). A key revoked after startup fails the request instead,
+   as `AUTH_REJECTED` (see step 5). When a build fails, the client logs it
+   once and skips that candidate for the rest of the process, so it never
+   blocks the rest of the chain.
 4. The client skips, with a warning, a fallback that lacks a capability the
    call needs (structured output, tool use, async, streaming).
 5. After a `QUOTA_EXHAUSTED` or `AUTH_REJECTED` failure, the client skips
@@ -1310,11 +1409,12 @@ Rules for the chain:
 | `AUTH_REJECTED` | yes | 401/403, a revoked or invalid API key, a disabled organization, expired AWS credentials |
 | `MODEL_UNAVAILABLE` | no | 404, an unknown or retired model id, a model not offered in the region |
 | `TIMEOUT` | no | the call's `request_timeout_seconds` passed with no answer |
-| `None` | never | validation errors, a safety refusal |
+| `INVALID_OUTPUT` | no | a structured answer that is not valid JSON, not a JSON object, or fails the response model (`StructuredOutputValidationError`) |
+| `None` | never | a safety refusal, request validation before any call |
 
 `MODEL_UNAVAILABLE` is off by default because an unknown model id usually
 means a configuration typo, and a working fallback would hide it. Turn it on
-with `fallback_on` or `COMPLETIONS_FALLBACK_ON` when you want an unknown or
+with `fallback_on` when you want an unknown or
 retired model to fail over.
 
 `TIMEOUT` is off by default because the deadline is yours, and a failover
@@ -1336,6 +1436,15 @@ often a configuration error too; the `failover` and `served_by_fallback` log
 events (below) record it while traffic keeps flowing. Remove
 `auth_rejected` from `fallback_on` to make it fail loudly instead.
 
+`INVALID_OUTPUT` is off by default because the provider billed the bad answer, and
+failing over buys a second billed answer on another model: a spending
+decision. The error is `StructuredOutputValidationError`, a `ValueError` (so
+existing handlers keep working) that carries the discarded answer's `usage`,
+`raw_text`, and `finish_reason`. Turn the reason on to let the chain try the
+next model, and the router escalate, on bad output; each discarded answer
+then shows on the request's cost report as a wasted line item (see
+"Per-request cost").
+
 A safety refusal is never a trigger: retrying a
 refused request on another model is a policy decision, not a reliability one,
 and it belongs in your code if you want it.
@@ -1443,8 +1552,8 @@ across the chain.
 
 | Setting | Meaning |
 | ------- | ------- |
-| `COMPLETIONS_FALLBACKS` | Ordered `engine:model` pairs tried after the primary fails. Blank or unset means no chain. |
-| `COMPLETIONS_FALLBACK_ON` | Comma-separated `AiFallbackReason` values that trigger a move. Default `unavailable,rate_limited,quota_exhausted,auth_rejected`. |
+| `completions.fallbacks` (`models.json`) | Ordered `engine:model` pairs tried after the primary fails. Empty or absent means no chain. |
+| `completions.fallback_on` | `AiFallbackReason` values (a list, or comma-separated) that trigger a move. Default `unavailable,rate_limited,quota_exhausted,auth_rejected`. |
 | `fallbacks=` (factory argument) | Same as the setting, as `(engine, model)` tuples or `AIFallbackCandidate` objects; overrides the setting. `[]` turns the chain off. |
 | `fallback_on=` (factory argument) | Same as the setting, as reasons or their values; overrides the setting. |
 
@@ -1502,9 +1611,8 @@ can read.
 }
 ```
 
-Point `COMPLETIONS_ROUTER_CONFIG` at the file (or set it to the JSON
-itself), keep `COMPLETIONS_ENGINE` and `COMPLETIONS_MODEL_NAME` as they
-are, and call the factory as usual:
+Put it in the `router` section of `models.json`, keep `completions.engine`
+and `completions.model` as they are, and call the factory as usual:
 
 ```python
 client = AIFactory.get_ai_completions_client()      # an AiRouterCompletions
@@ -1513,19 +1621,20 @@ print(client.last_tier, client.last_decision)
 ```
 
 In code, pass `router=AIRouterConfig(...)` instead. The configured
-completions LLM, with its `COMPLETIONS_FALLBACKS` chain, is the **default
+completions LLM, with its `completions.fallbacks` chain, is the **default
 route**: where calls go when no classifier is available, when the
 classifier fails, or when `default_tier` is unset.
 
 ### The classifier
 
 The router uses a classification engine (see Classification). Resolution
-order: `COMPLETIONS_ROUTER_CLASSIFIER` (`engine:model`), then the config's
-`classifier`, then the classification factory's own resolution
-(`CLASSIFIER_ENGINE`, then `openai-decisions` when `OPENAI_API_KEY` is
-set). Set either to `none` to route without a classifier; if the
-classifier cannot be built, the router logs `classifier_unavailable` once
-and degrades to the default route, and never raises at startup.
+order: the router's own `classifier` entry, then the top-level
+`classifier` section of `models.json`, then `openai-decisions` when
+`OPENAI_API_KEY` is set. Set either to `none` to route without a classifier. The
+configured-model check probes the classifier model with the tiers; if it
+is missing or unreachable, or the classifier cannot be built, the router
+logs `classifier_unavailable` once and degrades to the default route, and
+never raises at startup.
 
 The classifier reads the latest user message only, cut to the engine's
 `max_input_chars`. The system prompt is left out: it is long, constant,
@@ -1548,9 +1657,10 @@ and `classifier.instructions` prepends your own guidance.
 5. If the chain runs out of candidates on a trigger reason
    (`fallback_on`), the router escalates to the next tier up and logs
    `tier_exhausted`; with `on_exhausted: raise`, on a non-trigger error, or
-   on the top tier, the error propagates; if a tier's primary cannot be
-   built, the router logs `tier_unbuildable` once and skips the tier the
-   same way.
+   on the top tier, the error propagates. Tier models that are missing or
+   unreachable were pruned at startup by the configured-model check; if a
+   tier's primary still cannot be built, the router logs
+   `tier_unbuildable` once and skips the tier the same way.
 
 ### Seeing where a request went
 
@@ -1587,8 +1697,8 @@ cost by tier needs no extra work. The classifier call itself carries
 
 | Setting | Meaning |
 | ------- | ------- |
-| `COMPLETIONS_ROUTER_CONFIG` | Path to a JSON file, or inline JSON, with `tiers`, optional `classifier`, `default_tier`, `on_exhausted`, `fallback_on`. |
-| `COMPLETIONS_ROUTER_CLASSIFIER` | `engine:model` for the router's classifier, or `none`. Overrides the config's `classifier`. |
+| `router` (`models.json`) | `tiers`, optional `classifier`, `default_tier`, `on_exhausted`, `fallback_on`. |
+| `classifier` (`models.json`) | The classifier the router uses when its own `classifier` entry is absent; `{"engine": "none"}` routes without one. |
 | `AIFactory.get_ai_completions_client(router=AIRouterConfig(...))` | Code-first configuration; overrides the setting. |
 
 Exports: `AiRouterCompletions`, `AIRouterConfig`, `AIRouterTier`,
@@ -1596,13 +1706,33 @@ Exports: `AiRouterCompletions`, `AIRouterConfig`, `AIRouterTier`,
 
 ## Configured-model check
 
-A fallback chain or a router names models the process expects to call
-later. A typo, a retired id, or a model not offered in your region would
-otherwise surface only when that model is finally tried, in the middle of
-a failover. So whenever you configure a chain or a router, the factory
-verifies every configured model before it builds the client: the
-completions LLM, each chain candidate, each tier candidate, and the
-router's classifier.
+Every model the completions client may call is checked before the client
+is returned: the completions LLM, each fallback, each router tier
+candidate, and the router's classifier. The check asks two questions:
+does the provider serve this model, and can this process reach it with
+the credentials the engine will use? A typo, a retired id, a model not
+offered in your region, or a fallback whose key is missing then shows up
+at startup, not in the middle of a failover.
+
+### When it runs
+
+- On every `AIFactory.get_ai_completions_client()` call, with or without
+  a chain or router. A lone primary is checked too.
+- Each model is probed at most once per process for a given engine,
+  model id, base URL, and credentials. Later factory calls reuse the
+  result and make no network call. A probe runs again only when one of
+  those four changes: an edited `models.json` that names a new model or
+  base URL, or a rotated key. Credentials enter the memo key as a
+  one-way hash of the settings the probe reads (for example
+  `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL_OVERRIDE`); the key itself
+  is never stored. AWS credentials from an instance role or an SSO cache
+  are not in the hash; set `AWS_PROFILE` or the key variables when you
+  need a rotation to force a recheck, or call
+  `AiModelChecker.reset_cache()`.
+- A probe that failed for a transient reason (timeout, 5xx, dropped
+  connection) is not cached, so the next factory call probes that model
+  again.
+- `models.json` itself is reloaded when its modification time changes.
 
 ### What it does
 
@@ -1611,32 +1741,37 @@ router's classifier.
   the raw id, Bedrock `get_foundation_model` (or `get_inference_profile`
   for `us.`, `eu.`, `apac.`, and `global.` ids) in `AWS_REGION`, an
   OpenAI-compatible server's `/models` list, and the Decisions API's fixed
-  model set.
-- Calls run in parallel, and the checker probes each `(engine, model,
-  base_url)` once per process however many clients, chains, or tiers name
-  it. Startup
-  pays one round trip, and later factory calls pay nothing.
-- The factory prunes a model the provider reports **missing** from the
-  effective configuration with a WARNING: `configured model openai:gpt-nope
-  is not available and will be ignored`. A chain drops the candidate; a
-  router tier drops the candidate, and the router drops a tier left with no
-  models. A request for a dropped tier (by the classifier, a `route`
-  override, or `for_tier`) goes to the next **higher** surviving tier, never
-  a lower one, and to the default route when nothing is above. A dropped
-  `default_tier` moves the same way.
+  model set. Calls run in parallel, so startup pays one round trip.
+- Each model gets one status:
+
+| Status | Meaning | Effect |
+| ------ | ------- | ------ |
+| `available` | The provider returned the model's metadata. | Kept. |
+| `missing` | The provider has no such model (404, or an id outside a fixed catalog). | Pruned, WARNING. |
+| `unreachable` | The engine cannot call the model: no key, a key rejected as invalid (401, Gemini `API_KEY_INVALID`, Bedrock `UnrecognizedClient` / `InvalidSignature` / `ExpiredToken`, no AWS credentials), no base URL for an OpenAI-compatible server, or the engine's extra not installed. | Pruned, WARNING. |
+| `unverifiable` | The probe cannot ask, but nothing says the call would fail: the engine default model (no id configured), a permission denial (403, Bedrock `AccessDenied`) that may cover only the catalog call, Vertex auth, or a server without a model catalog. | Kept, INFO. |
+| `error` | The probe failed for another reason (timeout, 5xx, network). | Kept, WARNING; not cached. |
+
+- A pruned fallback leaves the chain: `configured model openai:gpt-nope
+  is not available and will be ignored`, or `configured model
+  claude:claude-haiku-4-5 cannot be reached and will be ignored`. A
+  pruned tier candidate leaves its tier, and the router drops a tier left
+  with no models. A request for a dropped tier (by the classifier, a
+  `route` override, or `for_tier`) goes to the next **higher** surviving
+  tier, never a lower one, and to the default route when nothing is
+  above. A dropped `default_tier` moves the same way.
 - The primary completions model cannot be pruned: it is the default
-  route, so when it is missing the factory raises.
-- A missing classifier model logs `classifier_unavailable`, and the router
-  degrades to its default route.
-- A model the probe cannot ask about (no credentials, no extra installed,
-  credentials rejected, a server with no model catalog, Vertex auth) is
-  **unverifiable** and kept, logged at INFO. A probe error (network, 5xx)
-  keeps the model and logs a WARNING. Neither counts as missing.
+  route. A missing primary raises `ValueError`; an unreachable one raises
+  `AiProviderConfigurationError` (the engine's own error comes first when
+  its constructor already refuses, for example a missing extra).
+- A missing or unreachable classifier model logs `classifier_unavailable`,
+  and the router degrades to its default route.
 
 Log records go to `ai_api_unified.util.ai_model_checker` with an
-`ai_model_check_event` field: `model_missing` (WARNING), `model_check_error`
-(WARNING), `model_unverifiable` (INFO), `model_available` (DEBUG); the
-factory adds `router_tier_pruned` and `router_disabled` (WARNING) on
+`ai_model_check_event` field: `model_missing` (WARNING),
+`model_unreachable` (WARNING), `model_check_error` (WARNING),
+`model_unverifiable` (INFO), `model_available` (DEBUG); the factory adds
+`router_tier_pruned` and `router_disabled` (WARNING) on
 `ai_api_unified.ai_factory`. `AIFactory.last_model_check_report()` returns
 the results of the most recent check.
 
@@ -1644,10 +1779,7 @@ the results of the most recent check.
 
 | Setting | Meaning |
 | ------- | ------- |
-| `AI_MODEL_CHECK` | `prune` (default): drop missing models with a warning. `strict`: raise on any missing model. `off`: skip the check. |
-
-A client with only a primary and no chain or router runs no check: the
-engine fails on its own at build.
+| `model_check.mode` (`models.json`) | `prune` (default): drop missing and unreachable fallbacks and tier models with a warning. `strict`: raise on any of them. `off`: skip the check. `model_check.timeout_seconds` bounds each probe (default 10). |
 
 ### Checking your own configuration
 
@@ -1655,8 +1787,8 @@ engine fails on its own at build.
 poetry run pytest -m nonmock tests/test_configured_models_nonmock.py -q -s --models-config ./models.json
 ```
 
-prints every model the file names with its status and fails on any the
-provider reports missing. To watch the pruning itself:
+prints every model the file names with its status and fails on any that
+is missing or unreachable. To watch the pruning itself:
 
 ```bash
 poetry run pytest -m nonmock tests/test_model_check_nonmock.py -q -s
@@ -1683,7 +1815,7 @@ the value may also be inline JSON).
 {
   "allow": ["claude:*", "google-gemini:*", "openai-decisions:*"],
   "deny":  ["openai:gpt-4*", "bedrock"],
-  "completions": {"engine": "google-gemini", "model": "gemini-2.5-flash",
+  "completions": {"engine": "google-gemini", "model": "gemini-2.5-flash", "thinking": "medium",
                   "fallbacks": ["claude:claude-sonnet-5"],
                   "fallback_on": "unavailable,rate_limited,quota_exhausted,auth_rejected"},
   "classifier":  {"engine": "openai-decisions", "model": "gpt-6-luna"},
@@ -1705,19 +1837,17 @@ poetry run python scripts/migrate2json.py            # writes ./models.json
 poetry run python scripts/migrate2json.py --comment-env   # and comments the moved keys out of .env
 ```
 
-It places each selection key in its section, embeds the router file named
-by `COMPLETIONS_ROUTER_CONFIG`, fills structural defaults from
-`models_sample.json`, leaves the allow and deny lists empty, and never
-touches secrets.
+It places each selection in its section, embeds a router file the old
+`.env` pointed at, fills structural defaults from `models_sample.json`,
+leaves the allow and deny lists empty, and never touches secrets.
 
-Each section stands in for the `.env` keys of the same capability
-(`completions.model` for `COMPLETIONS_MODEL_NAME`, `embeddings.engine` for
-`EMBEDDING_ENGINE`, `router` for `COMPLETIONS_ROUTER_CONFIG`, and so on),
-so nothing else in the library changes. Precedence, highest first: an
-explicit factory argument, a process environment variable, a `.env` value,
-the file, the library default. Every key in the tables below still works
-and overrides the file when set, which lets a deployment pin one value
-without editing the file. Secrets (API keys, AWS credentials), `AWS_REGION`,
+The old selection keys are deprecated. One left in `.env` or the process
+environment is still accepted and overrides the file, so a deployment does
+not break, and the library logs one warning per key naming the
+`models.json` field and the migrator command
+(`ai_config_event=deprecated_selection_key`). Precedence, highest first: an
+explicit factory argument, a deprecated environment key, the file, the
+library default. Secrets (API keys, AWS credentials), `AWS_REGION`,
 base-URL overrides, and `AI_MIDDLEWARE_CONFIG_PATH` stay in `.env`.
 
 ### Allow and deny lists
@@ -1738,43 +1868,43 @@ classifier, and the embeddings, image, and video selections.
   model, raises `ValueError` naming the pattern. Runtime never calls a
   denied model.
 
-### Required Engine Selectors
+### Engine selectors
+
+There is no implicit default provider. Set the engine for each capability
+you use in `models.json`:
+
+| `models.json` field | Valid values |
+| ------------------- | ------------ |
+| `completions.engine` | `openai`, `openai-responses`, `openai-compatible`, `claude`, `google-gemini`, `bedrock`, Bedrock-routed aliases such as `nova`, `anthropic`, `llama`, `mistral`, `cohere`, `ai21`, `rerank` |
+| `embeddings.engine`  | `openai`, `titan`, `google-gemini`, `voyage` |
+| `classifier.engine`  | `openai-decisions`, `openai`, `openai-responses`, `openai-compatible`, `claude`, `google-gemini`, `bedrock`, `anthropic` (see Classification) |
+| `images.engine`      | `openai`, `google-gemini`, `nova-canvas`, `bedrock`, `nova` |
+| `videos.engine`      | `openai`, `google-gemini`, `bedrock`, `nova`, `nova-reel` |
+| `voice.engine`       | `openai`, `google`, `azure`, `elevenlabs` |
+
+### Model selections
 
-There is no implicit default provider. Set the selector for each capability
-you use, in `models.json` or as a variable:
+Every section of `models.json` is documented in
+[`models_sample.json`](models_sample.json). The fields, by section:
 
-| Environment variable | Valid values                                                                                                                  |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `COMPLETIONS_ENGINE` | `openai`, `openai-responses`, `openai-compatible`, `claude`, `google-gemini`, `bedrock`, Bedrock-routed aliases such as `nova`, `anthropic`, `llama`, `mistral`, `cohere`, `ai21`, `rerank` |
-| `EMBEDDING_ENGINE`   | `openai`, `titan`, `google-gemini`                                                                                            |
-| `CLASSIFIER_ENGINE`  | `openai-decisions`, `openai`, `openai-responses`, `openai-compatible`, `claude`, `google-gemini`, `bedrock`, `anthropic` (see Classification) |
-| `IMAGE_ENGINE`       | `openai`, `google-gemini`, `nova-canvas`, `bedrock`, `nova`                                                                   |
-| `VIDEO_ENGINE`       | `openai`, `google-gemini`, `bedrock`, `nova`, `nova-reel`                                                                     |
-| `AI_VOICE_ENGINE`    | `openai`, `google`, `azure`, `elevenlabs`                                                                                     |
+| Section | Fields |
+| ------- | ------ |
+| `completions` | `engine`, `model`, `fallbacks` (see Model fallback), `fallback_on`, `retry_policy`, `thinking` (see Thinking levels) |
+| `classifier` | `engine`, `model`, `base_url`, `timeout_seconds`, `instructions` |
+| `router` | `tiers`, `classifier`, `default_tier`, `on_exhausted`, `fallback_on` (see Model routing) |
+| `model_check` | `mode` (`prune`, `strict`, `off`), `timeout_seconds` (see Configured-model check) |
+| `embeddings` | `engine`, `model` (`gemini-embedding-2` enables multimodal embeddings), `dimensions` (`0` keeps the provider default) |
+| `images` | `engine`, `model` |
+| `videos` | `engine`, `model`, `output_dir`, `poll_interval_seconds`, `timeout_seconds` |
+| `voice` | `engine`, `tts_model`, `language` |
+| `geo_residency` | `US`, `USA`, or `United States` normalize to US routing where supported |
 
-### Common Model Settings
+### Settings that stay in `.env`
 
 | Environment variable        | Notes                                                                                       |
 | --------------------------- | ------------------------------------------------------------------------------------------- |
-| `COMPLETIONS_MODEL_NAME`    | Optional completions model override                                                         |
-| `COMPLETIONS_FALLBACKS`     | Optional ordered `engine:model` pairs tried after the primary fails (see Model fallback)     |
-| `COMPLETIONS_FALLBACK_ON`   | Optional comma-separated `AiFallbackReason` values that trigger a fallback; default `unavailable,rate_limited,quota_exhausted,auth_rejected` |
 | `AI_MODELS_CONFIG` | Path to `models.json`/`.yaml`, or inline JSON; unset uses `./models.json` when present; blank turns the file off |
-| `COMPLETIONS_ROUTER_CONFIG` | Override of the file's `router` section: a JSON file path or inline JSON mapping tiers to `engine:model` chains (see Model routing) |
-| `COMPLETIONS_ROUTER_CLASSIFIER` | Optional `engine:model` for the router's classifier, or `none`; default is the classification factory's resolution |
-| `AI_MODEL_CHECK` | Optional: `prune` (default), `strict`, or `off` for the configured-model check (see Configured-model check) |
-| `AI_MODEL_CHECK_TIMEOUT_SECONDS` | Optional per-probe timeout for the configured-model check (default 10) |
-| `EMBEDDING_MODEL_NAME`      | Optional embeddings model override. `gemini-embedding-2` enables multimodal embeddings.     |
-| `CLASSIFIER_MODEL_NAME`     | Optional classification model override; blank falls back to `COMPLETIONS_MODEL_NAME`, then the engine default |
-| `IMAGE_MODEL_NAME`          | Optional image model override                                                               |
-| `VIDEO_MODEL_NAME`          | Optional video model override                                                               |
-| `VIDEO_OUTPUT_DIR`          | Optional local output directory for materialized video artifacts                            |
-| `VIDEO_POLL_INTERVAL_SECONDS` | Optional default poll interval for video job waits                                        |
-| `VIDEO_TIMEOUT_SECONDS`     | Optional default timeout for blocking video generation                                      |
 | `BEDROCK_VIDEO_OUTPUT_S3_URI` | Required for Nova Reel unless provided per request                                        |
-| `DEFAULT_GEMINI_TTS_MODEL`  | Optional Google voice model override                                                        |
-| `EMBEDDING_DIMENSIONS`      | Optional embeddings dimension override. Leave unset for provider defaults.                  |
-| `AI_API_GEO_RESIDENCY`      | Optional geo hint. `US`, `USA`, or `United States` normalize to US routing where supported. |
 | `AI_MIDDLEWARE_CONFIG_PATH` | Optional YAML config path for observability and PII middleware                              |
 | `ANTHROPIC_BASE_URL_OVERRIDE` | Optional API base-URL override for the `claude` engine (https required) |
 | `OPENAI_BASE_URL_OVERRIDE`  | Optional API base-URL override for the OpenAI engines (https required) |
@@ -1863,15 +1993,8 @@ Required:
 
 - `OPENAI_API_KEY`
 
-Common optional settings:
-
-- `OPENAI_BASE_URL`
-- `COMPLETIONS_MODEL_NAME`
-- `EMBEDDING_MODEL_NAME`
-- `IMAGE_MODEL_NAME`
-- `VIDEO_MODEL_NAME`
-- `EMBEDDING_DIMENSIONS`
-- `AI_API_GEO_RESIDENCY`
+Optional: `OPENAI_BASE_URL_OVERRIDE`. Models and dimensions are selected in
+`models.json`.
 
 #### Anthropic (native Claude API)
 
@@ -1879,9 +2002,7 @@ Required for the `claude` completions engine:
 
 - `ANTHROPIC_API_KEY`
 
-Common optional settings:
-
-- `COMPLETIONS_MODEL_NAME` (defaults to `claude-opus-5`)
+The model is `completions.model` in `models.json` (default `claude-opus-5`).
 
 Claude via Amazon Bedrock (the `anthropic` engine) does not use
 `ANTHROPIC_API_KEY`; it authenticates with AWS credentials like the other
@@ -1899,15 +2020,8 @@ Required:
 - `AWS_REGION`
 - standard AWS credentials in environment or runtime IAM context
 
-Common optional settings:
-
-- `COMPLETIONS_MODEL_NAME`
-- `EMBEDDING_MODEL_NAME`
-- `IMAGE_MODEL_NAME`
-- `VIDEO_MODEL_NAME`
-- `BEDROCK_VIDEO_OUTPUT_S3_URI`
-- `EMBEDDING_DIMENSIONS`
-- `AI_API_GEO_RESIDENCY`
+Optional: `BEDROCK_VIDEO_OUTPUT_S3_URI` (Nova Reel). Models and dimensions
+are selected in `models.json`.
 
 If your AWS profile uses `aws login` (a `login_session` profile), install
 `botocore[crt]` as well; botocore needs it to read those credentials.
@@ -1917,9 +2031,11 @@ If your AWS profile uses `aws login` (a `login_session` profile), install
 AWS hosts these models itself, so requests go to AWS under your AWS account
 and never reach DeepSeek, Alibaba, or Z.ai.
 
+```json
+"completions": {"engine": "bedrock", "model": "deepseek.v3.2"}
+```
+
 ```dotenv
-COMPLETIONS_ENGINE=bedrock
-COMPLETIONS_MODEL_NAME=deepseek.v3.2
 AWS_REGION=us-east-1
 AWS_PROFILE=<your profile>
 ```
@@ -2001,7 +2117,7 @@ Required:
 Optional:
 
 - `MICROSOFT_COGNITIVE_SERVICES_ENDPOINT`
-- `AI_VOICE_LANGUAGE`
+- `voice.language` in `models.json`
 
 #### ElevenLabs
 
@@ -2207,6 +2323,63 @@ capability.supports_org_id, capability.supports_org_name, capability.requirement
 #                    iam:ListAccountAliases; identity falls back to id-only without it")
 ```
 
+#### Per-request cost
+
+A request's total cost includes every call it made: classification, failed
+attempts, fallbacks, and escalations. One routed structured-output request
+can be four provider calls: the classifier, a 529 on the first tier, a
+fallback on the same tier, and an escalation that answers. Each call still
+emits its own `ai_api_call_cost` event; the request adds one total on top.
+
+Every client keeps the report for the last request it ran as the outermost
+call:
+
+```python
+result = client.send_structured_output(prompt, response_model=Summary)
+report = client.last_request_cost          # AIRequestCostReport
+report.total_usd                           # Decimal, every priced call
+report.classifier_usd                      # the router's classifier call
+report.wasted_usd                          # billed answers nobody used
+report.billed_calls, report.failed_calls   # 3 and 1 in the example above
+report.served_by                           # "claude:claude-opus-5"
+for item in report.calls:                  # AIRequestCostLineItem, in call order
+    item.role, item.route_tier, item.outcome, item.usd_cost, item.served
+```
+
+A failed attempt is a line item with no cost and no tokens; it still counts
+as a call. A failed attempt the provider billed, a structured answer that
+could not be parsed or validated (`StructuredOutputValidationError`) or a
+truncated one (`StructuredResponseTokenLimitError`), keeps the usage the
+exception carries, so the report prices it and counts it in `billed_calls`
+and `wasted_usd`; its per-call cost event carries `outcome: "error"`. A model
+with no registry pricing counts as billed but unpriced
+(`unpriced_calls`), so `total_usd` understates the request by its cost.
+The ledger records calls whether or not the observability middleware is on.
+
+To roll several library calls into one logical request, such as a workflow
+step, open the scope yourself. Nested scopes join the outer one, and the
+clients inside keep no report of their own:
+
+```python
+from ai_api_unified import request_cost_scope
+
+with request_cost_scope("summarize-contract") as scope:
+    router.send_structured_output(prompt, response_model=Summary)
+    router.send_prompt("One-line title for this summary.")
+scope.report.total_usd      # both calls, every attempt behind them
+```
+
+When `emit_cost` is on, the outermost scope emits one `ai_api_request_cost`
+event on the cost topic as it closes (normally or on an exception):
+`request_id`, `operation`, `status`, `caller_id`, `session_id`,
+`workflow_id`, `served_by`, `served_by_tier`, `served_by_method`,
+`total_usd`, `classifier_usd`, `wasted_usd`, `billed_calls`,
+`failed_calls`, `unpriced_calls`, `elapsed_ms`, and `calls` (a compact list
+with `call_id`, `role`, `model`, `outcome`, `usd_cost`, `served`). The
+`request_id` is the router's `route_id` when routed, and every per-call
+event under the request carries it as `tag_request_id`, so the per-call
+events and the total join on one key.
+
 ### PII Redaction
 
 PII redaction is optional and requires one of:
@@ -2365,12 +2538,12 @@ git push origin v<version>
 
 ## Troubleshooting
 
-- `COMPLETIONS_ENGINE must be configured explicitly` or similar: set the required engine selector for that capability.
+- An engine `must be configured explicitly` error: set that capability's `engine` in `models.json`.
 - `AiProviderDependencyUnavailableError`: install the extra for the selected provider.
 - Google auth errors: the OSS default is `GOOGLE_AUTH_METHOD=api_key`. If you switch to `service_account`, point `GOOGLE_APPLICATION_CREDENTIALS` at a valid local JSON credential file. Set `GOOGLE_PROJECT_ID` and `GOOGLE_LOCATION` when required.
-- Unexpected embeddings dimensions: leave `EMBEDDING_DIMENSIONS` unset unless you intentionally want a non-default size.
+- Unexpected embeddings dimensions: leave `embeddings.dimensions` at `0` unless you intentionally want a non-default size.
 - Google image generation or TTS failures in live tests often come from account or service state: a disabled cloud API, or missing paid-plan access. Check those before suspecting a library bug.
-- `AI_API_GEO_RESIDENCY=US` is a best-effort routing hint. Only providers that expose regional routing controls can honor it directly.
+- `geo_residency: "US"` is a best-effort routing hint. Only providers that expose regional routing controls can honor it directly.
 
 ## License