@x12i/ai-providers-router 4.8.5 → 4.8.8

package/README.md

@@ -1,24 +1,50 @@
 # @x12i/ai-providers-router
 
-A unified **LLM provider router** that routes requests to installed provider packages using the **ProviderModule architecture**.
+Unified **LLM provider router** for Node.js. Routes requests to installed provider packages using the **ProviderModule** architecture from [`@x12i/ai-provider-interface`](https://www.npmjs.com/package/@x12i/ai-provider-interface).
 
-This router:
-- **OpenRouter Mode**: Access 353+ models from 67 providers using catalog-driven routing
-- Chooses a provider/model (and optionally a fallback chain)
-- Loads ProviderModules from installed provider packages (lazy import)
-- Uses router-side adapters to convert requests to ProviderSDKCallSpec
-- Executes via ProviderModule.execute() / stream() / submitBatch()
-- Parses responses using router-side adapters
-- Returns standardized responses with lossless rawResponse
+**Highlights**
 
-## Architecture
+- **Multi-provider routing** — OpenAI, Grok, and more via lazy-loaded provider packages
+- **OpenRouter mode** — Access 350+ models from 60+ providers through one API key
+- **Sync, stream, and batch** — Gated by each provider's declared capabilities
+- **Fallback chains** — Automatic provider/model failover with full attempt traces
+- **Structured diagnostics** — Usage, cost, timing, and ordered `metadata.attempts[]`
+- **Reasoning support** — Cross-vendor effort, visibility, and encrypted trace handling
+- **ERC 2.0** — Zero-config initialization from environment variables
+- **Structured logging** — Powered by [`@x12i/logxer`](https://www.npmjs.com/package/@x12i/logxer)
+
+> This router **never installs** provider packages at runtime. You must install the packages you intend to use.
 
-- **ProviderModule**: Provider packages export ProviderModules that implement `@x12i/ai-provider-interface`
-- **Router Adapters**: Router-side adapters convert router requests to ProviderSDKCallSpec and parse responses
-- **Capability Gating**: Router gates execution by `provider.capabilities.modes.sync/stream/batch` (ProviderModule is source of truth)
-- **Execution Semantics**: Router owns execution semantics (timeoutMs, retries, idempotencyKey, signal)
+---
 
-> Important: This router **never installs** provider packages at runtime.
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Architecture](#architecture)
+- [Provider IDs](#provider-ids)
+- [OpenRouter mode](#openrouter-mode)
+- [Configuration](#configuration)
+- [Logging](#logging)
+- [API usage](#api-usage)
+  - [Sync](#sync-call)
+  - [Streaming](#streaming-call)
+  - [Batch](#batch-requests)
+  - [Request and response types](#request-and-response-types)
+  - [Trace diagnostics](#trace-diagnostics)
+  - [Reasoning](#reasoning)
+  - [Fallback chains](#fallback-chains)
+  - [Interceptors](#interceptors)
+  - [Health checks](#health-checks)
+- [AIGateway](#aigateway)
+- [Response normalization and cost](#response-normalization-and-cost)
+- [Error types](#error-types)
+- [Manual setup (advanced)](#manual-setup-advanced)
+- [Public API exports](#public-api-exports)
+- [Provider packages](#provider-packages)
+- [Development and testing](#development-and-testing)
+- [Related documentation](#related-documentation)
+- [License](#license)
 
 ---
 
@@ -28,470 +54,685 @@ This router:
 npm i @x12i/ai-providers-router
 ```
 
-Install at least one provider package (examples):
+**Bundled provider packages** (included as dependencies):
+
+- `@x12i/ai-provider-openai` — OpenAI and OpenRouter-compatible APIs
+- `@x12i/ai-provider-grok` — Grok / xAI
+
+**Optional provider packages** (install when you need direct access):
 
 ```bash
-npm i @x12i/ai-provider-openai
 npm i @x12i/ai-provider-anthropic
 npm i @x12i/ai-provider-google
-npm i @x12i/ai-provider-xai
 npm i @x12i/ai-provider-groq
+# ... other @x12i/ai-provider-* packages
 ```
 
-**For OpenRouter mode**: Only `@x12i/ai-provider-openai` is required to access **353 models from 67 providers** through OpenRouter's unified API.
+For **OpenRouter mode**, only `@x12i/ai-provider-openai` is required to reach models from many vendors through OpenRouter's unified API.
 
 ---
 
-## Provider IDs (canonical)
+## Quick start
 
-**Core Providers:**
-* `openai`  → OpenAI
-* `anthropic` → Claude
-* `google` → Gemini
-* `xai` → Grok (xAI)
-* `groq` → GroqCloud (Llama/Mixtral/OSS models)
-* `kimi` → Moonshot/Kimi (if installed)
+```ts
+import { createRouter, type AIRouterRequest, type AIResponse } from '@x12i/ai-providers-router';
 
-**OpenRouter Mode (67 providers supported):**
-* `openrouter` → OpenRouter (unified gateway to all providers)
-* All provider names work seamlessly (automatic routing through OpenRouter)
-* Access to 353+ models from providers like Meta, Mistral, Cohere, Perplexity, and many more
+const router = await createRouter();
+
+const req: AIRouterRequest = {
+  request: {
+    messages: [{ role: 'user', content: 'Write 3 bullets about routers.' }],
+    config: { model: 'gpt-4o-mini', maxTokens: 200 },
+  },
+  provider: 'openai',
+  mode: 'sync',
+};
+
+const res: AIResponse = await router.invoke(req);
+console.log(res.outputText);
+console.log(res.usage);
+console.log(res.rawResponse); // always present — lossless provider payload
+```
+
+Set provider API keys in your environment (see [Configuration](#configuration)). With no arguments, `createRouter()` auto-discovers settings via ERC.
+
+---
+
+## Architecture
+
+```
+AIRouterRequest
+  → request interceptors (e.g. OpenRouter routing)
+  → ProviderModule (from installed @x12i/ai-provider-* package)
+  → router-side adapter (request → ProviderSDKCallSpec)
+  → provider.execute() | stream() | submitBatch()
+  → router-side adapter (ProviderSDKExecResult → AIResponse)
+  → response interceptors
+  → AIResponse (with lossless rawResponse)
+```
 
-> Grok ≠ Groq
->
-> * Grok is **xAI** (`xai`)
-> * Groq is **GroqCloud** (`groq`)
+| Layer | Role |
+|-------|------|
+| **ProviderModule** | Provider packages implement `@x12i/ai-provider-interface` |
+| **Router adapters** | Convert router requests to `ProviderSDKCallSpec` and parse responses |
+| **Capability gating** | Router checks `provider.capabilities.modes.sync/stream/batch` |
+| **Execution semantics** | Router owns `timeoutMs`, retries, `idempotencyKey`, `AbortSignal` |
 
 ---
 
-## OpenRouter Mode
+## Provider IDs
+
+**Direct providers** (require matching `@x12i/ai-provider-*` package and API key):
 
-OpenRouter is a unified API gateway that provides access to multiple AI models from different providers. When OpenRouter mode is enabled, **all provider calls automatically route through OpenRouter** while maintaining a seamless API experience.
+| ID | Vendor |
+|----|--------|
+| `openai` | OpenAI |
+| `grok` | Grok / xAI |
+| `anthropic` | Claude |
+| `google` | Gemini |
+| `groq` | GroqCloud |
 
-### Key Features
+**OpenRouter** (unified gateway):
 
-- **Comprehensive Model Catalog**: Access **353 models** from **67 providers** using catalog data automatically loaded from OpenRouter APIs
-- **Seamless API**: Use the same provider names (`"openai"`, `"grok"`, `"anthropic"`, etc.) - no code changes needed
-- **Smart Provider Inference**: Uses catalog data to automatically infer providers from model names (e.g., `"gpt-4o"` → `"openai"`)
-- **Model Validation**: Validates models against available OpenRouter catalog and warns about invalid models
-- **Provider Aliases**: Supports vendor mappings (e.g., `xai` models route to `grok` provider)
-- **Model Name Mapping**: Automatically converts provider + model to OpenRouter format (e.g., `provider: "openai"` + `model: "gpt-4o"` → `"openai/gpt-4o"`)
-- **Access any OpenRouter model**: Call models even without direct provider packages (e.g., `"meta-llama/llama-3-70b-instruct"`)
-- **Unified Reasoning API**: Cross-vendor reasoning support with effort control and visibility options (see [Reasoning Integration](./docs/reasoning-integration.md))
-- **No ai-io-normalizer**: OpenRouter responses are parsed directly (faster, simpler)
+| ID | Role |
+|----|------|
+| `openrouter` | Explicit OpenRouter transport |
+| Any vendor ID | Routed through OpenRouter when preferred (`USE_OPENROUTER=true`, default) or as fallback when no direct key |
 
-### OpenRouter Mode - Completely Automatic
+> **Grok ≠ Groq** — Grok is xAI (`grok` / `xai`). Groq is GroqCloud (`groq`).
+
+---
 
-**OpenRouter mode works automatically - no code changes required!**
+## OpenRouter mode
 
-Simply set the `OPEN_ROUTER_KEY` environment variable:
+OpenRouter is a unified API gateway. With an `OPENROUTER_API_KEY`, the router can reach models from many vendors through one key — using familiar provider names (`openai`, `grok`, `anthropic`, …) and automatic model mapping (e.g. `openai` + `gpt-4o` → `openai/gpt-4o`).
+
+### Enable OpenRouter
+
+Set an API key (canonical name preferred):
 
 ```bash
-export OPEN_ROUTER_KEY=sk-or-your-openrouter-api-key-here
+export OPENROUTER_API_KEY=sk-or-your-key-here
+# Legacy alias also supported:
+# export OPEN_ROUTER_KEY=sk-or-your-key-here
 ```
 
-That's it! OpenRouter mode is **completely automatic** and works with:
+Optional ranking headers:
 
-- ✅ **Factory initialization**: `await createRouter()` - automatically registers OpenRouter provider module
-- ✅ **Manual initialization**: `new LLMProviderRouter()` - automatically detects OpenRouter mode via environment variable
-- ✅ **Any provider name**: Use `config.provider: "openai"`, `"grok"`, `"anthropic"`, etc. - all route through OpenRouter automatically
+```bash
+export OPENROUTER_HTTP_REFERER=https://your-site.com   # legacy: OPEN_ROUTER_HTTP_REFERER
+export OPENROUTER_X_TITLE=Your Site Name               # legacy: OPEN_ROUTER_X_TITLE
+```
+
+### `USE_OPENROUTER` — prefer vs fallback
+
+`USE_OPENROUTER` does **not** turn OpenRouter on or off. The router always registers OpenRouter when a key is present. This flag controls **whether OpenRouter is preferred over direct provider keys**.
 
-**How it works:**
-- When `OPEN_ROUTER_KEY` is set, the router automatically detects OpenRouter mode
-- All provider requests (openai, grok, anthropic, etc.) automatically route through OpenRouter
-- No need to register individual provider modules - OpenRouter handles everything
-- Works seamlessly whether you use `createRouter()` or manual `new LLMProviderRouter()` initialization
+| `USE_OPENROUTER` | `OPENROUTER_API_KEY` | Direct provider key (e.g. `OPENAI_API_KEY`) | What happens |
+|------------------|----------------------|---------------------------------------------|--------------|
+| unset or `true` *(default)* | set | set or unset | **Prefer OpenRouter** — all vendor calls route through OpenRouter, even when a direct key exists |
+| unset or `true` | set | not set | Route through OpenRouter |
+| `false` | set | set for requested vendor | **Direct provider** — use the vendor's own key/API |
+| `false` | set | not set for requested vendor | **OpenRouter fallback** — e.g. request `anthropic` with no `ANTHROPIC_API_KEY` still works via OpenRouter |
 
-**To disable OpenRouter mode explicitly:**
+**Default:** prefer OpenRouter whenever `OPENROUTER_API_KEY` is set (`USE_OPENROUTER` defaults to `true`).
+
+To use direct provider keys when available, while keeping OpenRouter as fallback for vendors without keys:
 
 ```bash
 export USE_OPENROUTER=false
+export OPENROUTER_API_KEY=sk-or-...
+export OPENAI_API_KEY=sk-...          # openai requests → direct OpenAI
+# no ANTHROPIC_API_KEY              # anthropic requests → OpenRouter fallback
 ```
 
-**Note**: When OpenRouter mode is enabled, direct provider packages are not registered to avoid conflicts. All calls route through OpenRouter using the integrated catalog data (`.metadata/openrouter_catalog_with_vendor_mapping.json`).
+Programmatic override:
 
-**Troubleshooting:**
+```ts
+const router = await createRouter({
+  useOpenRouter: false, // direct when keys exist; OpenRouter fallback otherwise
+});
+```
 
-If you see errors like "No provider specified and no providers registered":
-1. ✅ Check that `OPEN_ROUTER_KEY` is set: `echo $OPEN_ROUTER_KEY`
-2. ✅ Verify the key is valid (not empty, doesn't start with "ENV.")
-3. ✅ Ensure `config.provider` is specified in your request (e.g., `config: { provider: "openai", model: "gpt-4o" }`)
-4. ✅ The OpenRouter adapter is always registered - no additional setup needed
+### Behavior summary
 
-The router will automatically use OpenRouter mode when these conditions are met!
+- **OpenRouter is always available** when `OPENROUTER_API_KEY` is set — used as the default transport or as fallback
+- **`USE_OPENROUTER=true` (default):** routes through OpenRouter even if `OPENAI_API_KEY`, `GROK_API_KEY`, etc. are also set; direct provider packages are not auto-registered (avoids singleton config conflicts)
+- **`USE_OPENROUTER=false`:** auto-registers direct providers when their API keys exist; OpenRouter handles any vendor without a direct key
+- Works with `createRouter()` and `new LLMProviderRouter()` — auto-registration on first call
+- Provider names stay the same in your code; the router handles transport selection internally
+- Catalog data (`.metadata/openrouter_catalog_with_vendor_mapping.json`) drives model validation and provider inference
+- Responses on the OpenRouter path are parsed directly from OpenAI-compatible formats (no `ai-io-normalizer`)
 
-### Usage Examples
+### Examples
 
-**Example 1: Using provider names (seamless - no code changes needed):**
+**Same provider name, OpenRouter underneath:**
 
 ```ts
-const router = await createRouter();
-
-// Works exactly the same whether OpenRouter mode is on or off
 const req: AIRouterRequest = {
-  request: {
-    messages: [{ role: 'user', content: 'Hello!' }],
-    config: { model: 'gpt-4o' },
-  },
-  provider: 'openai',  // Still use "openai" - router handles routing
+  request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'gpt-4o' } },
+  provider: 'openai',
   mode: 'sync',
 };
-
-const res = await router.invoke(req);
-// Model automatically mapped to "openai/gpt-4o" when using OpenRouter
+await router.invoke(req);
 ```
 
-**Example 2: Provider inference (no provider specified):**
+**OpenRouter model format directly:**
 
 ```ts
-// Router infers provider from model name
 const req: AIRouterRequest = {
   request: {
     messages: [{ role: 'user', content: 'Hello!' }],
-    config: { model: 'gpt-4o' },  // Infers "openai" from "gpt-4o"
+    config: { model: 'anthropic/claude-3-opus' },
   },
-  // provider not specified - router infers "openai"
+  provider: 'openrouter',
   mode: 'sync',
 };
-
-const res = await router.invoke(req);
+await router.invoke(req);
 ```
 
-**Example 3: Using OpenRouter model format directly:**
+**Provider inference from model name** (no `provider` field):
 
 ```ts
-// Call any OpenRouter-supported model using OpenRouter's format
 const req: AIRouterRequest = {
-  request: {
-    messages: [{ role: 'user', content: 'Hello!' }],
-    config: { model: 'anthropic/claude-3-opus' },  // Direct OpenRouter format
-  },
-  provider: 'openrouter',  // Use "openrouter" provider
+  request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'gpt-4o' } },
   mode: 'sync',
 };
-
-const res = await router.invoke(req);
+await router.invoke(req); // infers openai
 ```
 
-**Example 4: Accessing models without provider packages:**
+### Troubleshooting
 
-```ts
-// Access Meta Llama models without installing @x12i/ai-provider-meta
-const req: AIRouterRequest = {
-  request: {
-    messages: [{ role: 'user', content: 'Hello!' }],
-    config: { model: 'meta-llama/llama-3-70b-instruct' },
-  },
-  provider: 'openrouter',
-  mode: 'sync',
-};
+If you see *"No provider specified and no providers registered"*:
 
-const res = await router.invoke(req);
-```
+1. Confirm `OPENROUTER_API_KEY` (or `OPEN_ROUTER_KEY`) is set and non-empty
+2. Ensure the key does not start with `ENV.` (unresolved placeholder)
+3. Set `config.provider` in the request (e.g. `{ provider: 'openai', model: 'gpt-4o' }`)
+4. The OpenRouter adapter is always registered — no extra setup required
 
-**Example 5: Using diverse models from different providers:**
+See also [debugging guide](./docs/debugging-no-provider-error.md).
+
+---
+
+## Configuration
+
+### Zero-config (`createRouter`)
 
 ```ts
-// Anthropic Claude models
-const claudeReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'claude-3-opus' } }, provider: 'anthropic', mode: 'sync' };
+import { createRouter } from '@x12i/ai-providers-router';
 
-// Google Gemini models
-const geminiReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'gemini-pro' } }, provider: 'google', mode: 'sync' };
+const router = await createRouter(); // reads process.env
+```
 
-// Groq models (via xAI provider)
-const groqReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'llama-3-70b-8192' } }, provider: 'groq', mode: 'sync' };
+### Programmatic (advanced mode)
 
-// All automatically route through OpenRouter when mode is enabled
-const results = await Promise.all([
-  router.invoke(claudeReq),
-  router.invoke(geminiReq),
-  router.invoke(groqReq),
-]);
+```ts
+const router = await createRouter({
+  logLevel: 'info',
+  verbose: false,
+  timeoutMs: 60_000,
+  useOpenRouter: true, // default: prefer OpenRouter when OPENROUTER_API_KEY is set
+  fallbackChain: [{ provider: 'openai', model: 'gpt-4o-mini' }, { provider: 'grok', model: 'grok-2' }],
+  openrouter: { apiKey: 'sk-or-...', httpReferer: 'https://example.com', xTitle: 'My App' },
+  usageTracker: {
+    recordRequest(e) {
+      // provider, timestamp, duration, tokens, cost, success
+    },
+  },
+  providerConfigs: {
+    openai: { apiKey: 'sk-...', baseURL: 'https://api.openai.com/v1' },
+    grok: { apiKey: 'xai-...' },
+  },
+});
 ```
 
-### How OpenRouter Mode Works
+Passing any explicit config object to `createRouter(config)` overrides zero-config env discovery for that call.
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| **Router** | | |
+| `AI_PROVIDER_ROUTER_LOGS_LEVEL` | *(see logging)* | Canonical log threshold via logxer (`error`, `warn`, `info`, `debug`, `verbose`, `off`) |
+| `AI_PROVIDER_ROUTER_LOG_LEVEL` | `info` | Legacy alias for log level (used when `_LOGS_LEVEL` is unset) |
+| `AI_PROVIDER_ROUTER_VERBOSE` | `false` | Log full AI request/response payloads (sanitized) |
+| `AI_PROVIDER_ROUTER_TIMEOUT_MS` | `60000` | Default operation timeout (ms) |
+| **OpenAI** | | |
+| `OPENAI_API_KEY` | — | Required for direct OpenAI calls |
+| `OPENAI_API_BASE` | — | Custom API base URL |
+| `OPENAI_ORGANIZATION` | — | Organization ID |
+| **Grok / xAI** | | |
+| `GROK_API_KEY` | — | Required for direct Grok calls |
+| `XAI_API_BASE` | — | Custom xAI base URL |
+| **OpenRouter** | | |
+| `OPENROUTER_API_KEY` | — | Enables OpenRouter (always registered when set) |
+| `OPEN_ROUTER_KEY` | — | Legacy alias for `OPENROUTER_API_KEY` |
+| `USE_OPENROUTER` | `true` | Prefer OpenRouter over direct keys when OR key is set; set `false` to use direct providers when keys exist (OpenRouter remains fallback) |
+| `OPENROUTER_HTTP_REFERER` | — | Optional ranking header |
+| `OPENROUTER_X_TITLE` | — | Optional ranking header |
+| **Other providers** | | |
+| `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, … | — | Used when those providers are installed |
+
+Full reference: [Environment variables](./docs/environment-variables.md) · [Configuration guide](./docs/CONFIGURATION_GUIDE.md)
 
-1. **Request Interceptor**: When OpenRouter mode is enabled, a request interceptor:
-   - Preserves the original provider name (e.g., `"openai"`, `"grok"`) in `request.config.provider`
-   - Routes the request to `"openrouter"` provider
-   - Infers provider from model name if not specified
+---
 
-2. **Model Name Mapping**: The `OpenRouterAdapter`:
-   - Reads the original provider from `request.config.provider`
-   - Maps model names: `"gpt-4o"` + `provider: "openai"` → `"openai/gpt-4o"`
-   - Handles models already in OpenRouter format (with `/`) as-is
+## Logging
 
-3. **Response Parsing**: Responses are parsed directly from OpenAI formats (no ai-io-normalizer):
-   - **Chat Completions**: Extracts `choices[0].message.content` for text
-   - **Responses API (v1)**: Handles `output` array with text and encrypted reasoning items
-   - Extracts `usage` for token counts from both formats
-   - Adds `status: 'completed'` for compatibility
+The router uses [`@x12i/logxer`](https://www.npmjs.com/package/@x12i/logxer) for structured, package-scoped logging.
 
-### Provider Inference Rules
+**Package prefix:** `AI_PROVIDER_ROUTER`
 
-When no provider is specified, the router uses **catalog data** to intelligently infer providers from model names. This includes:
+```bash
+# Canonical (preferred)
+AI_PROVIDER_ROUTER_LOGS_LEVEL=info
 
-- **Exact Model Matching**: Recognizes all 353 OpenRouter models by their exact IDs
-- **Alias Support**: Handles model aliases from the catalog
-- **Vendor Mapping**: Maps vendor IDs to provider slugs (e.g., `xai` → `grok`)
-- **Fallback Patterns**: Uses legacy pattern matching when catalog data is unavailable:
+# Legacy (still supported when _LOGS_LEVEL is unset)
+AI_PROVIDER_ROUTER_LOG_LEVEL=info
 
-  - `gpt-*`, `o1-*`, `openai/*` → `"openai"`
-  - `claude-*`, `anthropic/*` → `"anthropic"`
-  - `grok-*`, `xai/*` → `"grok"`
-  - `gemini-*`, `google/*` → `"google"`
-  - `llama-*`, `meta-llama/*` → `"meta"`
-  - Default → `"openai"` (most common case)
+# Log full AI request/response payloads (router-specific, separate from log level)
+AI_PROVIDER_ROUTER_VERBOSE=true
+```
 
-### Model Validation & Catalog Features
+**Log levels:** `error` · `warn` · `info` · `debug` · `verbose` · `off`
 
-The router automatically validates models against the OpenRouter catalog:
+When neither `_LOGS_LEVEL` nor `_LOG_LEVEL` is set, no `logLevel` / `logging` is passed, and the logxer registry has no entry, the router defaults to **`info`** (not logxer's package-only default of `warn`). `createRouter()` loads `LOGXER_PACKAGE_LEVELS` / `LOGXER_PACKAGE_LOGS_DEFAULT` via `applyPackageLogLevelsFromEnv()` after `.env`.
 
-- **Model Availability**: Warns when requesting models not available in OpenRouter
-- **Alias Resolution**: Automatically resolves model aliases to canonical OpenRouter IDs
-- **Capability Checking**: Validates model parameters against supported capabilities
-- **Graceful Fallbacks**: Falls back to legacy logic if catalog loading fails
-- **Format Support**: Handles both OpenAI Chat Completions and Responses API v1 formats
-- **Encrypted Reasoning**: Processes encrypted reasoning traces (model thinking is privacy-protected)
-- **Reasoning Parameter Support**: Enables reasoning effort levels for compatible models
+**Host apps (logxer ≥ 4.5)** — provider packages (`@x12i/ai-provider-openai`, etc.) are **not** on the logxer 4.5 stack. Stack/registry options apply **only** to this router's logs (`AI_PROVIDER_ROUTER`). Configure your other libraries from `@x12i/logxer` in the host; pass the same `StackLoggingOptions` into `createRouter` when you want one object for the whole app:
 
-**Catalog Data Sources:**
-- **67 Providers**: All current OpenRouter providers
-- **353 Models**: Complete model catalog with aliases and capabilities
-- **Vendor Mappings**: Direct API mappings for accurate routing
-- **Auto-updating**: Uses latest catalog data from OpenRouter APIs
+```ts
+import { configurePackageLogLevels, type StackLoggingOptions } from '@x12i/logxer';
+import { createRouter, ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
+
+configurePackageLogLevels({
+  default: 'warn',
+  levels: {
+    MY_GATEWAY: 'info',
+    [ROUTER_LOG_ENV_PREFIX]: 'debug',
+  },
+});
+
+const logging: StackLoggingOptions = {
+  packageLevels: { [ROUTER_LOG_ENV_PREFIX]: 'debug' },
+};
 
-### OpenRouter Configuration
+const router = await createRouter({ logging, verbose: true });
+```
 
-Optional environment variables for OpenRouter rankings:
+Bulk env for this package (loaded by `createRouter()` after `.env`):
 
 ```bash
-export OPEN_ROUTER_HTTP_REFERER=https://your-site.com
-export OPEN_ROUTER_X_TITLE=Your Site Name
+LOGXER_PACKAGE_LEVELS=AI_PROVIDER_ROUTER:info
+AI_PROVIDER_ROUTER_LOGS_LEVEL=error   # wins over bulk for this prefix only
 ```
 
-See [Environment Variables documentation](./docs/environment-variables.md) for details.
+**Programmatic (router only):**
+
+```ts
+const router = await createRouter({ logLevel: 'debug', verbose: true });
+const router2 = await createRouter({ logger: createLogger({ level: 'info', verbose: false }) });
+```
+
+Verbose mode logs sanitized AI request/response payloads. Cross-cutting sinks (console, file, format) are configured in the **host** via `@x12i/logxer` — not via provider packages.
 
 ---
 
-## Zero-config router creation
+## API usage
 
-No arguments are required.
+### Sync call
 
 ```ts
-import { createRouter } from '@x12i/ai-providers-router';
+import { createRouter, type AIRouterRequest, type AIResponse } from '@x12i/ai-providers-router';
 
 const router = await createRouter();
+
+const req: AIRouterRequest = {
+  request: {
+    inputData: 'Write 3 bullets about routers.',
+    config: { model: 'gpt-4o-mini', maxTokens: 200, temperature: 0.7 },
+  },
+  provider: 'openai',
+  mode: 'sync',
+  exec: {
+    timeoutMs: 60_000,
+    idempotencyKey: 'optional-key',
+    signal: abortController.signal,
+  },
+};
+
+const res: AIResponse = await router.invoke(req);
 ```
 
-Optional router-level config (logging, usage tracking, timeout):
+### Streaming call
 
 ```ts
-const router = await createRouter({
-  logLevel: 'info',
-  verbose: false,
-  timeoutMs: 60000, // Default timeout for all operations (ERC: AI_PROVIDER_ROUTER_TIMEOUT_MS)
-  usageTracker: {
-    recordRequest(e) { /* ... */ },
-  },
+const streamReq: AIRouterRequest = { ...req, mode: 'stream' };
+
+for await (const ev of router.stream(streamReq)) {
+  switch (ev.type) {
+    case 'provider_raw':
+      console.log('Raw:', ev.raw);
+      break;
+    case 'output_text_delta':
+      process.stdout.write(ev.delta);
+      break;
+    case 'reasoning_summary_delta':
+    case 'reasoning_trace_delta':
+      // reasoning stream chunks
+      break;
+    case 'completed':
+      console.log('Final:', ev.response.outputText);
+      break;
+    case 'error':
+      console.error(ev.error);
+      break;
+  }
+}
+```
+
+### Batch requests
+
+Batch is available only when `provider.capabilities.modes.batch === true`:
+
+```ts
+const items = [
+  { request: { inputData: 'First', config: { model: 'gpt-4o-mini' } } },
+  { request: { inputData: 'Second', config: { model: 'gpt-4o-mini' } } },
+];
+
+const batchResult = await router.createBatch('openai', items, {
+  timeoutMs: 120_000,
+  idempotencyKey: 'batch-1',
 });
+
+console.log(batchResult.items);
+console.log(batchResult.rawBatch);
 ```
 
----
+### Request and response types
 
-## Request/Response Types
+| Type | Purpose |
+|------|---------|
+| `AIRouterRequest` | Router input (`request`, `provider`, `mode`, `exec`) |
+| `AIResponse` | Sync output (`outputText`, `rawResponse`, `usage`, `reasoning`, `metadata`) |
+| `AIStreamEvent` | Streaming events (`output_text_delta`, `completed`, `error`, …) |
+| `AIBatchResponse` | Batch results |
+| `RouterConfig` | Router-level settings |
+| `ProviderModelRef` | `{ provider?, engine?, model? }` for fallback chains |
 
-Router uses its own request/response types:
+### Trace diagnostics
 
-* `AIRouterRequest` (input) - includes unified reasoning controls
-* `AIResponse` (sync output) - includes unified reasoning response
-* `AIStreamEvent` (streaming output) - includes reasoning streaming events
-* `AIBatchResponse` (batch output)
+Every `AIResponse` includes stable, provider-agnostic diagnostics in `metadata`:
 
-### Authoritative trace diagnostics (stable contract)
+| Field | Description |
+|-------|-------------|
+| `metadata.provider` | Final provider used |
+| `metadata.modelUsed` | Actual model that served the response |
+| `metadata.costUsd` / `metadata.cost` | USD cost when reported (e.g. OpenRouter `usage.cost`) |
+| `metadata.costStatus` | `'priced'` or `'unpriced'` |
+| `metadata.maxTokensRequested` | Effective generation cap |
+| `metadata.requestIds` | `{ routerRequestId, providerRequestId?, openrouterRequestId? }` |
+| `metadata.timing` | `{ startedAt, endedAt, durationMs }` |
+| `metadata.latencyMs` | Alias for `timing.durationMs` |
+| `metadata.attempts[]` | Ordered retry + fallback trace |
+| `response.output.parsed` | Structured fields when `outputContract` is set |
 
-For downstream orchestration, `AIResponse` includes stable, provider-agnostic diagnostics:
+### Reasoning
 
-- `response.usage?: { promptTokens; completionTokens; totalTokens }`
-- `response.metadata` (keys when known):
-  - `metadata.provider`: final provider used for the successful call (or last attempt)
-  - `metadata.modelUsed`: the actual model that served the response
-  - `metadata.maxTokensRequested`: final effective generation cap applied (if determinable)
-  - `metadata.costUsd` / `metadata.cost`: normalized USD cost when the provider reports it (e.g. OpenRouter `usage.cost`)
-  - `metadata.costStatus`: `'priced'` when `costUsd` is set; `'unpriced'` when usage exists but no cost was returned
-  - `response.output.parsed`: structured fields when `outputContract` is on the request (markdown sections → camelCase keys)
-  - `metadata.requestIds`: `{ routerRequestId, providerRequestId?, openrouterRequestId? }`
-  - `metadata.timing`: `{ startedAt, endedAt, durationMs }` (provider-call timing)
-  - `metadata.latencyMs`: alias for `metadata.timing.durationMs`
-  - `metadata.attempts[]`: ordered attempts across retries + fallbacks (authoritative execution trace)
+Request unified reasoning controls via `request.config.reasoning`:
 
 ```ts
-import type { AIRouterRequest, AIResponse } from '@x12i/ai-providers-router';
-
-// Request reasoning with extended effort levels
 config: {
   reasoning: {
-    effort: 'high',        // or 'low', 'medium', 'high', 'xhigh' (xhigh normalized to high)
-    maxTokens: 2000,        // optional: for Anthropic/Gemini models (max_tokens mode)
-    visibility: 'trace',     // or 'none', 'summary' (best-effort; downgraded if not returned)
-    onUnsupported: 'downgrade'  // or 'error' (throws), 'ignore' (silent)
-  }
+    effort: 'high',           // low | medium | high | xhigh (xhigh → high)
+    maxTokens: 2000,          // Anthropic/Gemini max_tokens mode
+    visibility: 'trace',      // none | summary | trace (best-effort)
+    onUnsupported: 'downgrade', // downgrade | error | ignore
+  },
 }
-
-// Access unified reasoning response
-response.reasoning.artifacts.encrypted  // Encrypted reasoning traces
-response.reasoning.applied.effort       // What was actually applied (may differ from requested)
-response.reasoning.applied.visibility  // What visibility was actually returned
-response.reasoning.availability        // Model capability flags
-response.reasoning.warnings             // Any downgrade/normalization warnings
 ```
 
-**Reasoning Features:**
-- ✅ **Effort Control**: `low`, `medium`, `high`, `xhigh` (xhigh auto-normalized to high)
-- ✅ **Max Tokens Control**: Direct `maxTokens` budget for Anthropic/Gemini models
-- ✅ **Encrypted Traces**: Access encrypted reasoning artifacts (ciphertext not decryptable by user; only metadata/prefix logged)
-- ✅ **Summary Visibility**: Human-readable reasoning summary (best-effort; returned only if provider returns `reasoning_details` with `reasoning.summary`; otherwise downgraded with warning)
-- ✅ **Trace Visibility**: Encrypted or readable reasoning traces (best-effort; satisfied by either `reasoning.encrypted` artifacts or `reasoning.text` chunks; downgraded if not available)
-- ✅ **Model Detection**: Automatic detection of reasoning-capable models via JSON registry (cross-vendor support)
-- ✅ **Extended Support**: Works with OpenAI o-series models (o1, o3, o4 series - 10+ models), xAI Grok models, Anthropic Claude reasoning models, and Google Gemini reasoning models
+Response fields: `response.reasoning.applied`, `response.reasoning.artifacts`, `response.reasoning.warnings`.
 
-**Supported Models**: Currently detected via router-owned JSON registry (`.metadata/reasoning-support.json`):
-- **OpenAI o-series** (`openai/o*` pattern): `openai/o1`, `openai/o1-pro`, `openai/o3`, `openai/o3-mini`, `openai/o3-pro`, `openai/o3-deep-research`, `openai/o3-mini-high`, `openai/o4-mini`, `openai/o4-mini-deep-research`, `openai/o4-mini-high`
-- **xAI Grok** (`x-ai/grok*` pattern): `x-ai/grok-4.1-fast` and other reasoning-enabled Grok models
-- **Anthropic Claude** (`anthropic/claude*` pattern): Reasoning-enabled Claude models (uses `max_tokens` mode)
-- **Google Gemini** (`google/gemini*` pattern): Reasoning-enabled Gemini models (uses `max_tokens` mode)
+Supported models are tracked in `.metadata/reasoning-support.json`.
 
-> ℹ️ **Note**: Summary/trace visibility are **best-effort** and depend on what the provider actually returns in `reasoning_details`. If the provider doesn't return the requested visibility type, the router downgrades to `none` and adds a `VISIBILITY_DOWNGRADED` warning. Encrypted reasoning artifacts are **not decryptable** by the user; only metadata (id, format, index) and a ciphertext prefix (first 32 chars) are logged for debugging. Many other vendors have reasoning-capable models (Amazon Nova, Aion Labs, Alibaba Tongyi, AllenAI OLMO, Arcee AI, Baidu ERNIE, ByteDance Seed, DeepCogito, MoonshotAI Kimi, Qwen, THUDM GLM, and more), including models with "thinking" or "thought" capabilities, but they are not yet implemented. See [Reasoning Supported Models](./docs/reasoning-supported-models.md) for the complete list.
+- [Reasoning integration guide](./docs/reasoning-integration.md)
+- [Supported models](./docs/reasoning-supported-models.md)
 
-See [Reasoning Integration Guide](./docs/reasoning-integration.md) and [Reasoning Supported Models](./docs/reasoning-supported-models.md) for complete documentation.
+### Fallback chains
 
----
+On failure, the router tries the next candidate in order. Attempts are recorded in `metadata.attempts[]`. On exhaustion, throws `FallbackExhaustedError`.
 
-## Sync call
+**Router-level default chain:**
 
 ```ts
-import { createRouter, type AIRouterRequest, type AIResponse } from '@x12i/ai-providers-router';
+const router = await createRouter({
+  fallbackChain: [
+    { provider: 'openai', model: 'gpt-4o' },
+    { provider: 'grok', model: 'grok-2' },
+  ],
+});
+```
 
-const router = await createRouter();
+**Per-request chain** (in `request.config`):
 
-const req: AIRouterRequest = {
-  request: {
-    inputData: 'Write 3 bullets about routers.',
-    config: {
-      maxTokens: 200,
-      temperature: 0.7,
-      model: 'gpt-4o-mini',
-    },
-  },
-  provider: 'openai',
-  mode: 'sync',
-  exec: {
-    timeoutMs: 60000, // Optional: override default timeout
-    idempotencyKey: 'optional-key', // Optional: for idempotent requests
+```ts
+request: {
+  config: {
+    model: 'gpt-4o',
+    fallbackChain: [
+      { provider: 'openai', model: 'gpt-4o-mini' },
+      { engine: 'grok', model: 'grok-2' }, // engine is alias for provider
+    ],
+    // Legacy: provider-only fallback (same model)
+    // fallbackProviders: ['grok', 'openai'],
   },
-};
+},
+```
 
-const res: AIResponse = await router.invoke(req);
+Precedence: `request.config.fallbackChain` → `request.config.fallbackEngines` → `router.fallbackChain` → `request.config.fallbackProviders`.
+
+### Interceptors
+
+```ts
+router.addRequestInterceptor(async (req, provider) => {
+  // mutate or replace request before execution
+  return req;
+});
 
-console.log(res.outputText); // Normalized text (optional)
-console.log(res.rawResponse); // Lossless raw response (always present)
-console.log(res.usage); // Token usage
+router.addResponseInterceptor(async (res, provider) => {
+  // mutate or replace response after execution
+  return res;
+});
 ```
 
+OpenRouter registers a request interceptor when `USE_OPENROUTER=true` (default) to route vendor calls through OpenRouter while preserving the original provider name for model mapping. When `USE_OPENROUTER=false`, the interceptor is skipped; `resolveProviderName` uses direct providers when registered and falls back to OpenRouter otherwise.
+
+### Health checks
+
+```ts
+const result = await router.checkHealth('openai');
+// { provider: 'openai', healthy: true, latencyMs: 1234 }
+// or { provider: 'openai', healthy: false, latencyMs: 5000, error: '...' }
+```
+
+Runs a minimal sync invoke with a 5 s timeout.
+
 ---
 
-## Streaming call
+## AIGateway
+
+Thin wrapper around the router for gateway-style requests (instructions + inputData):
 
 ```ts
-const streamReq: AIRouterRequest = {
-  ...req,
-  mode: 'stream',
-};
+import { AIGateway, createRouter } from '@x12i/ai-providers-router';
 
-for await (const ev of router.stream(streamReq)) {
-  if (ev.type === 'provider_raw') {
-    // Raw provider event (always emitted for debugging)
-    console.log('Raw event:', ev.raw);
-  } else if (ev.type === 'output_text_delta') {
-    // Normalized text delta
-    process.stdout.write(ev.delta);
-  } else if (ev.type === 'completed') {
-    // Final response
-    console.log('Final:', ev.response.outputText);
-  } else if (ev.type === 'error') {
-    console.error('Error:', ev.error);
-  }
-}
+const gateway = new AIGateway(await createRouter());
+
+const response = await gateway.invoke({
+  instructions: 'You are a helpful assistant.',
+  inputData: 'Explain routers in one sentence.',
+  config: { provider: 'openai', model: 'gpt-4o-mini' },
+  mode: 'sync',
+});
 ```
 
+Also accepts full `AIRouterRequest` shapes (`{ request, provider, mode }`) and unwraps them automatically.
+
+Optional strict provider/model pinning: set `config.enforceProviderModel: true` to throw on mismatch instead of silently switching.
+
 ---
 
-## Batch requests
+## Response normalization and cost
 
-Batch requests use the batch API (gated by ProviderModule capabilities):
+Exported helpers for downstream activity persistence and output contracts:
 
 ```ts
-const items = [
-  { request: { inputData: 'First request', config: { model: 'gpt-4o-mini' } } },
-  { request: { inputData: 'Second request', config: { model: 'gpt-4o-mini' } } },
-];
+import {
+  applyResponseNormalization,
+  resolveCostReporting,
+  extractCostUsdFromRouterResponse,
+  extractCostUsdFromProviderUsage,
+  enrichParsedForOutputContract,
+  resolveOutputContractFieldKeys,
+  parseMarkdownSectionsFromContent,
+} from '@x12i/ai-providers-router';
+```
 
-const batchResult = await router.createBatch('openai', items, {
-  timeoutMs: 120000, // Optional: override default timeout
-  idempotencyKey: 'optional-key', // Optional
-});
+- **Cost** — Normalizes OpenRouter and provider usage into `metadata.costUsd` / `costStatus`
+- **Output contract** — When `outputContract` is on the request, markdown sections map to camelCase keys in `output.parsed`
+
+See [normalization field support](./docs/normalization-field-support.md).
+
+---
 
-console.log(batchResult.items); // Array of results
-console.log(batchResult.rawBatch); // Lossless raw batch response
+## Error types
+
+| Error | When |
+|-------|------|
+| `ProviderNotFoundError` | Requested provider is not registered |
+| `ProviderNotInstalledError` | Provider package not installed (includes `npm install` hint) |
+| `ProviderTimeoutError` | Request exceeded `timeoutMs` (`code: 'ETIMEDOUT'`) |
+| `FallbackExhaustedError` | All fallback candidates failed; check `.attempts[]` |
+
+On partial provider failures, `FallbackExhaustedError` may carry a router-shaped partial payload for gateway extraction (`PartialRouterPayload`).
+
+---
+
+## Manual setup (advanced)
+
+For full control without `createRouter()`:
+
+```ts
+import { LLMProviderRouter } from '@x12i/ai-providers-router';
+import * as openaiModule from '@x12i/ai-provider-openai';
+
+const router = new LLMProviderRouter({ logLevel: 'info', timeoutMs: 60_000 });
+
+router.configureProvider('openai', { apiKey: process.env.OPENAI_API_KEY! });
+router.registerProvider(openaiModule, 'initializeClient');
+
+const providers = router.listProviders(); // ['openai']
+const registry = router.getProviderRegistry();
+const adapters = router.getAdapterRegistry();
 ```
 
-**Note**: Batch is only available if `provider.capabilities.modes.batch === true`. Router gates execution by ProviderModule capabilities, not transformer supports.
+Providers are **auto-registered on first invoke** when matching API keys are in the environment. When `USE_OPENROUTER=true` (default) and `OPENROUTER_API_KEY` is set, direct providers are skipped in favor of OpenRouter. With `USE_OPENROUTER=false`, both direct providers and OpenRouter can be registered simultaneously.
+
+Legacy config file support:
+
+```ts
+import { createRouterFromConfig } from '@x12i/ai-providers-router';
+const router = await createRouterFromConfig('./router-config.json');
+```
 
 ---
 
-## How it works (high level)
-
-1. Router receives an `AIRouterRequest`
-2. **Request Interceptors** (if OpenRouter mode enabled):
-   - Preserve original provider name for model mapping
-   - Route requests to OpenRouter provider
-   - Infer provider from model name if not specified
-3. Router loads ProviderModule from installed provider package (lazy import)
-4. Router checks `provider.capabilities.modes` to gate execution
-5. Router-side adapter converts request to `ProviderSDKCallSpec`
-   - **OpenRouterAdapter**: Maps provider + model to OpenRouter format (e.g., `"openai/gpt-4o"`)
-6. Router calls ProviderModule:
-
-   * `provider.execute(spec)` (sync)
-   * `provider.stream(spec)` (streaming)
-   * `provider.submitBatch(specs)` (batch)
-7. Router-side adapter parses `ProviderSDKExecResult` to `AIResponse`
-   - **OpenRouterAdapter**: Parses OpenAI Chat Completions format directly (no ai-io-normalizer)
-8. Router returns standardized response with lossless `rawResponse`
+## Public API exports
+
+```ts
+// Router
+export { LLMProviderRouter, createRouter, createRouterFromConfig }
+
+// Types
+export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent,
+  AIBatchResponse, AIBatchRequestItem, NormalizedRouterOutput, ProviderModelRef,
+  HealthCheckResult, ProviderId, CreateRouterConfig }
+
+// Errors
+export { ProviderNotFoundError, FallbackExhaustedError,
+  ProviderNotInstalledError, ProviderTimeoutError }
+export type { FallbackAttempt, PartialRouterPayload }
+
+// Interceptors
+export type { RequestInterceptor, ResponseInterceptor }
+
+// Logger
+export { Logger, getLogger, createLogger }
+export type { LogLevel, LoggerConfig }
+
+// Gateway
+export { AIGateway }
+export type { EnhancedLLMResponse }
+
+// Normalization
+export { applyResponseNormalization, resolveCostReporting,
+  extractCostUsdFromRouterResponse, extractCostUsdFromProviderUsage,
+  hasNonZeroTokenUsage, enrichParsedForOutputContract,
+  resolveOutputContractFieldKeys, contractSpecToFieldKeys,
+  parseMarkdownSectionsFromContent }
+export type { ActivityCostStatus, ResolvedCostReporting }
+
+// Registries and adapters (advanced)
+export { ProviderRegistry, AdapterRegistry, OpenAIAdapter, GrokAdapter }
+```
 
 ---
 
-## Provider packages are required
+## Provider packages
+
+| Provider ID | Package | API key env |
+|-------------|---------|-------------|
+| `openai` | `@x12i/ai-provider-openai` | `OPENAI_API_KEY` |
+| `grok` | `@x12i/ai-provider-grok` | `GROK_API_KEY` |
+| `anthropic` | `@x12i/ai-provider-anthropic` | `ANTHROPIC_API_KEY` |
+| `google` | `@x12i/ai-provider-google` | `GOOGLE_API_KEY` |
+| `groq` | `@x12i/ai-provider-groq` | `GROQ_API_KEY` |
+| OpenRouter mode | `@x12i/ai-provider-openai` (bundled) | `OPENROUTER_API_KEY` |
 
-If you call a provider that is not installed, the router throws a clear error with install instructions.
+Missing packages produce a clear `ProviderNotInstalledError` with install instructions.
 
-**Exception**: When OpenRouter mode is enabled, you only need `@x12i/ai-provider-openai` installed (OpenRouter uses OpenAI-compatible API). You can access **any of the 353 models from 67 providers** without installing individual provider packages.
+---
+
+## Development and testing
+
+```bash
+npm run build          # compile TypeScript
+npm test               # build + run all .tests/**/*.test.js
+npm run test:openai    # live OpenAI call (requires OPENAI_API_KEY)
+npm run test:openrouter
+npm run test:reasoning
+npm run erc:verify     # ERC manifest verification
+```
 
-**Supported Providers in OpenRouter Mode:**
-- All major providers: OpenAI, Anthropic, Google, xAI (Grok), Groq, Meta, Mistral, Cohere, etc.
-- 67 total providers from the OpenRouter catalog
-- 353 models with full capability support
+Requires **Node.js ≥ 18**.
 
-Examples:
+---
 
-* Provider `openai` requires `@x12i/ai-provider-openai`
-* Provider `grok` requires `@x12i/ai-provider-grok`
-* **OpenRouter mode**: Only requires `@x12i/ai-provider-openai` to access all OpenRouter-supported models
+## Related documentation
 
-This router will never auto-install packages.
+| Document | Topic |
+|----------|-------|
+| [Configuration guide](./docs/CONFIGURATION_GUIDE.md) | Full request/config reference |
+| [Environment variables](./docs/environment-variables.md) | Complete env var list |
+| [Reasoning integration](./docs/reasoning-integration.md) | Reasoning API details |
+| [Reasoning supported models](./docs/reasoning-supported-models.md) | Model registry |
+| [Request/response flow](./docs/request-response-flow.md) | Internal flow |
+| [Debugging no-provider error](./docs/debugging-no-provider-error.md) | OpenRouter troubleshooting |
+| [Normalization fields](./docs/normalization-field-support.md) | Output contract and cost |
 
 ---
 
 ## License
 
-ISC
+MIT