@x12i/ai-providers-router 4.8.5 → 4.8.6

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,634 @@ 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
+
+```ts
+import { createRouter, type AIRouterRequest, type AIResponse } from '@x12i/ai-providers-router';
+
+const router = await createRouter();
 
-**Core Providers:**
-* `openai`  → OpenAI
-* `anthropic` → Claude
-* `google` → Gemini
-* `xai` → Grok (xAI)
-* `groq` → GroqCloud (Llama/Mixtral/OSS models)
-* `kimi` → Moonshot/Kimi (if installed)
+const req: AIRouterRequest = {
+  request: {
+    messages: [{ role: 'user', content: 'Write 3 bullets about routers.' }],
+    config: { model: 'gpt-4o-mini', maxTokens: 200 },
+  },
+  provider: 'openai',
+  mode: 'sync',
+};
 
-**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 res: AIResponse = await router.invoke(req);
+console.log(res.outputText);
+console.log(res.usage);
+console.log(res.rawResponse); // always present — lossless provider payload
+```
 
-> Grok ≠ Groq
->
-> * Grok is **xAI** (`xai`)
-> * Groq is **GroqCloud** (`groq`)
+Set provider API keys in your environment (see [Configuration](#configuration)). With no arguments, `createRouter()` auto-discovers settings via ERC.
 
 ---
 
-## OpenRouter Mode
+## Architecture
 
-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.
+```
+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)
+```
 
-### Key Features
+| 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` |
 
-- **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)
+---
 
-### OpenRouter Mode - Completely Automatic
+## Provider IDs
 
-**OpenRouter mode works automatically - no code changes required!**
+**Direct providers** (require matching `@x12i/ai-provider-*` package and API key):
 
-Simply set the `OPEN_ROUTER_KEY` environment variable:
+| ID | Vendor |
+|----|--------|
+| `openai` | OpenAI |
+| `grok` | Grok / xAI |
+| `anthropic` | Claude |
+| `google` | Gemini |
+| `groq` | GroqCloud |
 
-```bash
-export OPEN_ROUTER_KEY=sk-or-your-openrouter-api-key-here
-```
+**OpenRouter** (unified gateway):
 
-That's it! OpenRouter mode is **completely automatic** and works with:
+| ID | Role |
+|----|------|
+| `openrouter` | Explicit OpenRouter transport |
+| Any vendor ID | Routed through OpenRouter when OpenRouter mode is active |
 
-- ✅ **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
+> **Grok ≠ Groq** — Grok is xAI (`grok` / `xai`). Groq is GroqCloud (`groq`).
 
-**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
+---
+
+## OpenRouter mode
+
+OpenRouter is a unified API gateway. When enabled, calls can use familiar provider names (`openai`, `grok`, `anthropic`, …) while traffic routes through OpenRouter with automatic model mapping (e.g. `openai` + `gpt-4o` → `openai/gpt-4o`).
+
+### Enable OpenRouter
+
+Set an API key (canonical name preferred):
+
+```bash
+export OPENROUTER_API_KEY=sk-or-your-key-here
+# Legacy alias also supported:
+# export OPEN_ROUTER_KEY=sk-or-your-key-here
+```
 
-**To disable OpenRouter mode explicitly:**
+OpenRouter mode activates automatically when a valid key is present. To disable explicitly:
 
 ```bash
 export USE_OPENROUTER=false
 ```
 
-**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`).
+Optional ranking headers:
 
-**Troubleshooting:**
+```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
+```
 
-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
 
-The router will automatically use OpenRouter mode when these conditions are met!
+- Works with `createRouter()` and `new LLMProviderRouter()` — auto-registration on first call
+- Provider names stay the same in your code; the router handles routing internally
+- Catalog data (`.metadata/openrouter_catalog_with_vendor_mapping.json`) drives model validation and provider inference
+- When OpenRouter mode is active, direct provider packages are **not** auto-registered (avoids singleton config conflicts)
+- Responses are parsed directly from OpenAI-compatible formats (no `ai-io-normalizer` on the OpenRouter path)
 
-### 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).
 
-```ts
-// Anthropic Claude models
-const claudeReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'claude-3-opus' } }, provider: 'anthropic', mode: 'sync' };
+---
+
+## Configuration
 
-// Google Gemini models
-const geminiReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'gemini-pro' } }, provider: 'google', mode: 'sync' };
+### Zero-config (`createRouter`)
 
-// Groq models (via xAI provider)
-const groqReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'llama-3-70b-8192' } }, provider: 'groq', mode: 'sync' };
+```ts
+import { createRouter } from '@x12i/ai-providers-router';
 
-// All automatically route through OpenRouter when mode is enabled
-const results = await Promise.all([
-  router.invoke(claudeReq),
-  router.invoke(geminiReq),
-  router.invoke(groqReq),
-]);
+const router = await createRouter(); // reads process.env
 ```
 
-### How OpenRouter Mode Works
+### Programmatic (advanced mode)
 
-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
+```ts
+const router = await createRouter({
+  logLevel: 'info',
+  verbose: false,
+  timeoutMs: 60_000,
+  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-...' },
+  },
+});
+```
 
-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
+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` | — | Canonical OpenRouter key |
+| `OPEN_ROUTER_KEY` | — | Legacy alias |
+| `USE_OPENROUTER` | auto | `true` when key present; set `false` to disable |
+| `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)
 
-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
+---
+
+## Logging
 
-### Provider Inference Rules
+The router uses [`@x12i/logxer`](https://www.npmjs.com/package/@x12i/logxer) for structured, package-scoped logging.
 
-When no provider is specified, the router uses **catalog data** to intelligently infer providers from model names. This includes:
+**Package prefix:** `AI_PROVIDER_ROUTER`
 
-- **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:
+```bash
+# Canonical (preferred)
+AI_PROVIDER_ROUTER_LOGS_LEVEL=info
 
-  - `gpt-*`, `o1-*`, `openai/*` → `"openai"`
-  - `claude-*`, `anthropic/*` → `"anthropic"`
-  - `grok-*`, `xai/*` → `"grok"`
-  - `gemini-*`, `google/*` → `"google"`
-  - `llama-*`, `meta-llama/*` → `"meta"`
-  - Default → `"openai"` (most common case)
+# Legacy (still supported when _LOGS_LEVEL is unset)
+AI_PROVIDER_ROUTER_LOG_LEVEL=info
 
-### Model Validation & Catalog Features
+# Log full AI request/response payloads (router-specific, separate from log level)
+AI_PROVIDER_ROUTER_VERBOSE=true
+```
 
-The router automatically validates models against the OpenRouter catalog:
+**Log levels:** `error` · `warn` · `info` · `debug` · `verbose` · `off`
 
-- **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
+When neither `_LOGS_LEVEL` nor `_LOG_LEVEL` is set and no programmatic `logLevel` is passed, logxer defaults to `warn`. The router's `createRouter()` zero-config path resolves `AI_PROVIDER_ROUTER_LOG_LEVEL` with default `info`.
 
-**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
+**Programmatic:**
 
-### OpenRouter Configuration
+```ts
+import { createRouter, createLogger, getLogger } from '@x12i/ai-providers-router';
 
-Optional environment variables for OpenRouter rankings:
+const router = await createRouter({ logLevel: 'debug', verbose: true });
 
-```bash
-export OPEN_ROUTER_HTTP_REFERER=https://your-site.com
-export OPEN_ROUTER_X_TITLE=Your Site Name
+// Or inject a custom logger instance
+const router2 = await createRouter({ logger: createLogger({ level: 'info', verbose: false }) });
 ```
 
-See [Environment Variables documentation](./docs/environment-variables.md) for details.
+Verbose mode logs sanitized AI request/response payloads (passwords, secrets, and API keys are redacted). Cross-cutting log sinks (console, file, format) are configured at the host/app level via logxer — not per-package.
 
 ---
 
-## 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`.
 
-console.log(res.outputText); // Normalized text (optional)
-console.log(res.rawResponse); // Lossless raw response (always present)
-console.log(res.usage); // Token usage
+### Interceptors
+
+```ts
+router.addRequestInterceptor(async (req, provider) => {
+  // mutate or replace request before execution
+  return req;
+});
+
+router.addResponseInterceptor(async (res, provider) => {
+  // mutate or replace response after execution
+  return res;
+});
 ```
 
+OpenRouter mode registers a request interceptor automatically to route vendor calls through OpenRouter while preserving the original provider name for model mapping.
+
+### 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).
+
+---
+
+## 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[]` |
 
-console.log(batchResult.items); // Array of results
-console.log(batchResult.rawBatch); // Lossless raw batch response
+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 also **auto-registered on first invoke** when matching API keys are in the environment (unless OpenRouter mode is active).
+
+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.
+---
 
-**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
+## Development and testing
 
-Examples:
+```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
+```
+
+Requires **Node.js ≥ 18**.
+
+---
 
-* 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

package/dist/logger.d.ts

@@ -2,7 +2,8 @@
  * Logging utility for AI Provider Router
  * Provides structured logging with proper log levels and verbose mode support
  */
-export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+import { type LogLevel } from '@x12i/logxer';
+export type { LogLevel };
 export interface LoggerConfig {
     verbose?: boolean;
     level?: LogLevel;
@@ -19,46 +20,42 @@ export declare class Logger {
      * Update logger configuration
      */
     setConfig(config: LoggerConfig): void;
-    /**
-     * Check if a log level should be logged
-     */
-    private shouldLog;
     /**
      * Log error messages
      */
-    error(message: string, data?: any): void;
+    error(message: string, data?: Record<string, unknown>): void;
     /**
      * Log warning messages
      */
-    warn(message: string, data?: any): void;
+    warn(message: string, data?: Record<string, unknown>): void;
     /**
      * Log informational messages
      */
-    info(message: string, data?: any): void;
+    info(message: string, data?: Record<string, unknown>): void;
     /**
      * Log debug messages
      */
-    debug(message: string, data?: any): void;
+    debug(message: string, data?: Record<string, unknown>): void;
     /**
      * Log verbose messages (only when verbose mode is enabled)
      */
-    logVerbose(message: string, data?: any): void;
+    logVerbose(message: string, data?: Record<string, unknown>): void;
     /**
      * Log AI request (unfiltered, only in verbose mode)
      */
-    logAIRequest(provider: string, request: any, metadata?: any): void;
+    logAIRequest(provider: string, request: unknown, metadata?: Record<string, unknown>): void;
     /**
      * Log AI response (unfiltered, only in verbose mode)
      */
-    logAIResponse(provider: string, response: any, metadata?: any): void;
+    logAIResponse(provider: string, response: unknown, metadata?: Record<string, unknown>): void;
     /**
      * Log AI request/response pair (unfiltered, only in verbose mode)
      */
-    logAIIteraction(provider: string, request: any, response: any, duration?: number, metadata?: any): void;
+    logAIIteraction(provider: string, request: unknown, response: unknown, duration?: number, metadata?: Record<string, unknown>): void;
     /**
      * Sanitize data for logging (remove sensitive info, handle circular refs)
      */
-    sanitizeForLogging(data: any): any;
+    sanitizeForLogging(data: unknown): unknown;
 }
 /**
  * Get or create the default logger instance

package/dist/logger.js

@@ -2,16 +2,23 @@
  * Logging utility for AI Provider Router
  * Provides structured logging with proper log levels and verbose mode support
  */
-import logxer from '@x12i/logxer';
-const logs = logxer || console;
+import { createLogxer } from '@x12i/logxer';
+const LOGXER_PACKAGE = {
+    packageName: 'AI Provider Router',
+    envPrefix: 'AI_PROVIDER_ROUTER',
+    debugNamespace: 'ai-providers-router',
+};
+function createGateway(level) {
+    return createLogxer(LOGXER_PACKAGE, level !== undefined ? { logLevel: level } : undefined);
+}
 /**
  * Logger class that wraps logxer with proper log levels
  */
 export class Logger {
     constructor(config = {}) {
-        this.verbose = config.verbose || false;
-        this.level = config.level || 'info';
-        this.gateway = logs || console;
+        this.verbose = config.verbose ?? false;
+        this.gateway = createGateway(config.level);
+        this.level = config.level ?? this.gateway.getConfig().logLevel;
     }
     /**
      * Update logger configuration
@@ -22,84 +29,40 @@ export class Logger {
         }
         if (config.level !== undefined) {
             this.level = config.level;
+            this.gateway = createGateway(config.level);
         }
     }
-    /**
-     * Check if a log level should be logged
-     */
-    shouldLog(level) {
-        const levels = ['error', 'warn', 'info', 'debug', 'verbose'];
-        const currentIndex = levels.indexOf(this.level);
-        const messageIndex = levels.indexOf(level);
-        return messageIndex <= currentIndex;
-    }
     /**
      * Log error messages
      */
     error(message, data) {
-        if (!this.shouldLog('error'))
-            return;
-        if (this.gateway?.error) {
-            this.gateway.error(message, data || {});
-        }
-        else {
-            console.error(`[ERROR] ${message}`, data || '');
-        }
+        this.gateway.error(message, data ?? {});
     }
     /**
      * Log warning messages
      */
     warn(message, data) {
-        if (!this.shouldLog('warn'))
-            return;
-        if (this.gateway?.warn) {
-            this.gateway.warn(message, data || {});
-        }
-        else {
-            console.warn(`[WARN] ${message}`, data || '');
-        }
+        this.gateway.warn(message, data ?? {});
     }
     /**
      * Log informational messages
      */
     info(message, data) {
-        if (!this.shouldLog('info'))
-            return;
-        if (this.gateway?.info) {
-            this.gateway.info(message, data || {});
-        }
-        else {
-            console.log(`[INFO] ${message}`, data || '');
-        }
+        this.gateway.info(message, data ?? {});
     }
     /**
      * Log debug messages
      */
     debug(message, data) {
-        if (!this.shouldLog('debug'))
-            return;
-        if (this.gateway?.debug) {
-            this.gateway.debug(message, data || {});
-        }
-        else {
-            console.debug(`[DEBUG] ${message}`, data || '');
-        }
+        this.gateway.debug(message, data ?? {});
     }
     /**
      * Log verbose messages (only when verbose mode is enabled)
      */
     logVerbose(message, data) {
-        if (!this.verbose || !this.shouldLog('verbose'))
+        if (!this.verbose)
             return;
-        if (this.gateway?.verbose) {
-            this.gateway.verbose(message, data || {});
-        }
-        else if (this.gateway?.trace) {
-            this.gateway.trace(message, data || {});
-        }
-        else {
-            console.log(`[VERBOSE] ${message}`, data || '');
-        }
+        this.gateway.verbose(message, data ?? {});
     }
     /**
      * Log AI request (unfiltered, only in verbose mode)
@@ -110,7 +73,7 @@ export class Logger {
         this.logVerbose('AI Request Sent', {
             provider,
             request: this.sanitizeForLogging(request),
-            metadata: metadata || {},
+            metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
         });
     }
@@ -123,7 +86,7 @@ export class Logger {
         this.logVerbose('AI Response Received', {
             provider,
             response: this.sanitizeForLogging(response),
-            metadata: metadata || {},
+            metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
         });
     }
@@ -138,7 +101,7 @@ export class Logger {
             request: this.sanitizeForLogging(request),
             response: this.sanitizeForLogging(response),
             duration: duration ? `${duration}ms` : undefined,
-            metadata: metadata || {},
+            metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
         });
     }
@@ -149,43 +112,35 @@ export class Logger {
         if (data === null || data === undefined) {
             return data;
         }
-        // Handle circular references and large objects
         const seen = new WeakSet();
         const sanitize = (obj, depth = 0) => {
-            // Prevent infinite recursion
             if (depth > 10) {
                 return '[Max Depth Reached]';
             }
-            // Handle primitives
             if (obj === null || obj === undefined) {
                 return obj;
             }
             if (typeof obj === 'string' || typeof obj === 'number' || typeof obj === 'boolean') {
                 return obj;
             }
-            // Handle circular references
             if (typeof obj === 'object') {
                 if (seen.has(obj)) {
                     return '[Circular Reference]';
                 }
                 seen.add(obj);
-                // Handle arrays
                 if (Array.isArray(obj)) {
                     return obj.map((item) => sanitize(item, depth + 1));
                 }
-                // Handle Buffer (common in file uploads)
                 if (Buffer.isBuffer(obj)) {
                     return `[Buffer: ${obj.length} bytes]`;
                 }
-                // Handle objects
                 const result = {};
                 for (const key in obj) {
                     if (Object.prototype.hasOwnProperty.call(obj, key)) {
-                        // Skip sensitive keys (can be extended)
                         if (key.toLowerCase().includes('password') ||
                             key.toLowerCase().includes('secret') ||
                             key.toLowerCase().includes('apikey') ||
-                            key.toLowerCase().includes('token') && key !== 'token') {
+                            (key.toLowerCase().includes('token') && key !== 'token')) {
                             result[key] = '[REDACTED]';
                         }
                         else {
@@ -200,7 +155,6 @@ export class Logger {
         return sanitize(data);
     }
 }
-// Default logger instance
 let defaultLogger = null;
 /**
  * Get or create the default logger instance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.5",
+  "version": "4.8.6",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "@x12i/ai-provider-grok": "^3.2.0",
     "@x12i/ai-provider-interface": "^3.2.1",
     "@x12i/ai-provider-openai": "^3.2.1",
-    "@x12i/logxer": "^4.3.6",
+    "@x12i/logxer": "^4.4.0",
     "ai-io-normalizer": "^6.0.3"
   },
   "devDependencies": {