@x12i/ai-providers-router 4.6.0

package/.metadata/reasoning-support.json

@@ -0,0 +1,159 @@
+{
+    "schemaVersion": "2025-12-30",
+    "purpose": "Router-owned registry of reasoning-capable model families (cross-vendor) with actionable request/response handling rules",
+    "notes": [
+      "Do NOT assume reasoning support by vendor alone; match specific model patterns/families and keep this registry the source of truth.",
+      "OpenRouter exposes reasoning via `reasoning_details` across multiple vendors (OpenAI, Anthropic, Gemini, xAI).",
+      "When continuing a conversation (especially with Gemini), preserve full `reasoning_details` in follow-up turns or you may get provider errors."
+    ],
+    "reasoningDetails": {
+      "standardField": "reasoning_details",
+      "nonStreamingLocations": [
+        "rawResponse.output[] (Responses-like shape)",
+        "rawResponse.choices[].message.reasoning_details[] (Chat Completions shape)"
+      ],
+      "streamingLocations": [
+        "rawResponse.choices[].delta.reasoning_details[]"
+      ],
+      "supportedItemTypes": [
+        "reasoning.summary",
+        "reasoning.text",
+        "reasoning.encrypted"
+      ]
+    },
+    "requestParamNormalization": {
+      "openaiStyle": {
+        "path": "reasoning.effort",
+        "values": ["low", "medium", "high"],
+        "mutualExclusion": ["reasoning.max_tokens"]
+      },
+      "anthropicStyle": {
+        "path": "reasoning.max_tokens",
+        "type": "integer",
+        "mutualExclusion": ["reasoning.effort"]
+      }
+    },
+    "vendors": [
+      {
+        "vendorId": "openai",
+        "displayName": "OpenAI (via OpenRouter)",
+        "supportsReasoningDetails": true,
+        "requestModes": ["effort"],
+        "requestMapping": {
+          "settableParams": ["reasoning.effort"],
+          "doNotSetTogether": ["reasoning.max_tokens"]
+        },
+        "visibilitySupport": {
+          "summary": true,
+          "text": true,
+          "encrypted": true
+        },
+        "modelMatchRules": [
+          {
+            "ruleId": "openai-reasoning-family",
+            "matchType": "prefix",
+            "pattern": "openai/o",
+            "examples": ["openai/o1", "openai/o3"],
+            "confidence": "high"
+          },
+          {
+            "ruleId": "openai-gpt5-family",
+            "matchType": "prefix",
+            "pattern": "openai/gpt-5",
+            "examples": ["openai/gpt-5-nano", "openai/gpt-5-mini", "openai/gpt-5"],
+            "confidence": "medium",
+            "notes": [
+              "Treat GPT-5 family as reasoning-details capable via OpenRouter. Keeps router behavior consistent and avoids catalog-fallback false negatives."
+            ]
+          }
+        ]
+      },
+      {
+        "vendorId": "xai",
+        "displayName": "xAI (via OpenRouter)",
+        "supportsReasoningDetails": true,
+        "requestModes": ["effort"],
+        "requestMapping": {
+          "settableParams": ["reasoning.effort"],
+          "doNotSetTogether": ["reasoning.max_tokens"]
+        },
+        "visibilitySupport": {
+          "summary": true,
+          "text": true,
+          "encrypted": true
+        },
+        "modelMatchRules": [
+          {
+            "ruleId": "xai-reasoning-family",
+            "matchType": "prefix",
+            "pattern": "x-ai/grok",
+            "examples": ["x-ai/grok-4.1-fast"],
+            "confidence": "medium"
+          }
+        ]
+      },
+      {
+        "vendorId": "anthropic",
+        "displayName": "Anthropic (via OpenRouter)",
+        "supportsReasoningDetails": true,
+        "requestModes": ["max_tokens"],
+        "requestMapping": {
+          "settableParams": ["reasoning.max_tokens"],
+          "doNotSetTogether": ["reasoning.effort"]
+        },
+        "visibilitySupport": {
+          "summary": true,
+          "text": true,
+          "encrypted": true
+        },
+        "modelMatchRules": [
+          {
+            "ruleId": "anthropic-reasoning-family",
+            "matchType": "prefix",
+            "pattern": "anthropic/claude",
+            "examples": ["anthropic/claude-sonnet-4", "anthropic/claude-opus-4.5"],
+            "confidence": "medium",
+            "notes": [
+              "Not every Claude model is necessarily reasoning-enabled; keep this rule scoped to the specific slugs you validate in fixtures."
+            ]
+          }
+        ]
+      },
+      {
+        "vendorId": "google",
+        "displayName": "Google Gemini (via OpenRouter)",
+        "supportsReasoningDetails": true,
+        "requestModes": ["max_tokens"],
+        "requestMapping": {
+          "settableParams": ["reasoning.max_tokens"],
+          "doNotSetTogether": ["reasoning.effort"]
+        },
+        "visibilitySupport": {
+          "summary": true,
+          "text": true,
+          "encrypted": true
+        },
+        "conversationRequirements": [
+          {
+            "requirementId": "preserve-reasoning-details",
+            "description": "When sending the next turn / tool follow-up, preserve the complete `reasoning_details` blocks in the messages you pass back, or Gemini models may reject the request.",
+            "appliesTo": ["google/gemini-*"],
+            "severity": "error-prone"
+          }
+        ],
+        "modelMatchRules": [
+          {
+            "ruleId": "gemini-reasoning-family",
+            "matchType": "prefix",
+            "pattern": "google/gemini",
+            "examples": ["google/gemini-3-pro-preview"],
+            "confidence": "medium",
+            "notes": [
+              "Gemini has both non-reasoning and reasoning variants; validate per-model in your own fixtures and tighten patterns accordingly."
+            ]
+          }
+        ]
+      }
+    ]
+  }
+  

package/.metadata/xai.response-map.json

@@ -0,0 +1 @@
+{}

package/README.md

@@ -0,0 +1,480 @@
+# @x12i/ai-providers-router
+
+A unified **LLM provider router** that routes requests to installed provider packages using the **ProviderModule architecture**.
+
+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
+
+## Architecture
+
+- **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.
+
+---
+
+## Install
+
+```bash
+npm i @x12i/ai-providers-router
+```
+
+Install at least one provider package (examples):
+
+```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
+```
+
+**For OpenRouter mode**: Only `@x12i/ai-provider-openai` is required to access **353 models from 67 providers** through OpenRouter's unified API.
+
+---
+
+## Provider IDs (canonical)
+
+**Core Providers:**
+* `openai`  → OpenAI
+* `anthropic` → Claude
+* `google` → Gemini
+* `xai` → Grok (xAI)
+* `groq` → GroqCloud (Llama/Mixtral/OSS models)
+* `kimi` → Moonshot/Kimi (if installed)
+
+**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
+
+> Grok ≠ Groq
+>
+> * Grok is **xAI** (`xai`)
+> * Groq is **GroqCloud** (`groq`)
+
+---
+
+## OpenRouter Mode
+
+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.
+
+### Key Features
+
+- **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
+
+**OpenRouter mode works automatically - no code changes required!**
+
+Simply set the `OPEN_ROUTER_KEY` environment variable:
+
+```bash
+export OPEN_ROUTER_KEY=sk-or-your-openrouter-api-key-here
+```
+
+That's it! OpenRouter mode is **completely automatic** and works with:
+
+- ✅ **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
+
+**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
+
+**To disable OpenRouter mode 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`).
+
+**Troubleshooting:**
+
+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
+
+The router will automatically use OpenRouter mode when these conditions are met!
+
+### Usage Examples
+
+**Example 1: Using provider names (seamless - no code changes needed):**
+
+```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
+  mode: 'sync',
+};
+
+const res = await router.invoke(req);
+// Model automatically mapped to "openai/gpt-4o" when using OpenRouter
+```
+
+**Example 2: Provider inference (no provider specified):**
+
+```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"
+  },
+  // provider not specified - router infers "openai"
+  mode: 'sync',
+};
+
+const res = await router.invoke(req);
+```
+
+**Example 3: Using OpenRouter model format directly:**
+
+```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
+  mode: 'sync',
+};
+
+const res = await router.invoke(req);
+```
+
+**Example 4: Accessing models without provider packages:**
+
+```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',
+};
+
+const res = await router.invoke(req);
+```
+
+**Example 5: Using diverse models from different providers:**
+
+```ts
+// Anthropic Claude models
+const claudeReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'claude-3-opus' } }, provider: 'anthropic', mode: 'sync' };
+
+// Google Gemini models
+const geminiReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'gemini-pro' } }, provider: 'google', mode: 'sync' };
+
+// Groq models (via xAI provider)
+const groqReq = { request: { messages: [{ role: 'user', content: 'Hello!' }], config: { model: 'llama-3-70b-8192' } }, provider: 'groq', mode: 'sync' };
+
+// All automatically route through OpenRouter when mode is enabled
+const results = await Promise.all([
+  router.invoke(claudeReq),
+  router.invoke(geminiReq),
+  router.invoke(groqReq),
+]);
+```
+
+### How OpenRouter Mode Works
+
+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
+
+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
+
+### Provider Inference Rules
+
+When no provider is specified, the router uses **catalog data** to intelligently infer providers from model names. This includes:
+
+- **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:
+
+  - `gpt-*`, `o1-*`, `openai/*` → `"openai"`
+  - `claude-*`, `anthropic/*` → `"anthropic"`
+  - `grok-*`, `xai/*` → `"grok"`
+  - `gemini-*`, `google/*` → `"google"`
+  - `llama-*`, `meta-llama/*` → `"meta"`
+  - Default → `"openai"` (most common case)
+
+### Model Validation & Catalog Features
+
+The router automatically validates models against the OpenRouter catalog:
+
+- **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
+
+**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
+
+### OpenRouter Configuration
+
+Optional environment variables for OpenRouter rankings:
+
+```bash
+export OPEN_ROUTER_HTTP_REFERER=https://your-site.com
+export OPEN_ROUTER_X_TITLE=Your Site Name
+```
+
+See [Environment Variables documentation](./docs/environment-variables.md) for details.
+
+---
+
+## Zero-config router creation
+
+No arguments are required.
+
+```ts
+import { createRouter } from '@x12i/ai-providers-router';
+
+const router = await createRouter();
+```
+
+Optional router-level config (logging, usage tracking, timeout):
+
+```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) { /* ... */ },
+  },
+});
+```
+
+---
+
+## Request/Response Types
+
+Router uses its own request/response types:
+
+* `AIRouterRequest` (input) - includes unified reasoning controls
+* `AIResponse` (sync output) - includes unified reasoning response
+* `AIStreamEvent` (streaming output) - includes reasoning streaming events
+* `AIBatchResponse` (batch output)
+
+```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)
+  }
+}
+
+// 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
+
+**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)
+
+> ℹ️ **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.
+
+See [Reasoning Integration Guide](./docs/reasoning-integration.md) and [Reasoning Supported Models](./docs/reasoning-supported-models.md) for complete documentation.
+
+---
+
+## Sync call
+
+```ts
+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: {
+      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
+  },
+};
+
+const res: AIResponse = await router.invoke(req);
+
+console.log(res.outputText); // Normalized text (optional)
+console.log(res.rawResponse); // Lossless raw response (always present)
+console.log(res.usage); // Token usage
+```
+
+---
+
+## Streaming call
+
+```ts
+const streamReq: AIRouterRequest = {
+  ...req,
+  mode: 'stream',
+};
+
+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);
+  }
+}
+```
+
+---
+
+## Batch requests
+
+Batch requests use the batch API (gated by ProviderModule capabilities):
+
+```ts
+const items = [
+  { request: { inputData: 'First request', config: { model: 'gpt-4o-mini' } } },
+  { request: { inputData: 'Second request', config: { model: 'gpt-4o-mini' } } },
+];
+
+const batchResult = await router.createBatch('openai', items, {
+  timeoutMs: 120000, // Optional: override default timeout
+  idempotencyKey: 'optional-key', // Optional
+});
+
+console.log(batchResult.items); // Array of results
+console.log(batchResult.rawBatch); // Lossless raw batch response
+```
+
+**Note**: Batch is only available if `provider.capabilities.modes.batch === true`. Router gates execution by ProviderModule capabilities, not transformer supports.
+
+---
+
+## 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`
+
+---
+
+## Provider packages are required
+
+If you call a provider that is not installed, the router throws a clear error 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
+
+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
+
+This router will never auto-install packages.
+
+---
+
+## License
+
+ISC

package/dist/adapters/grok/GrokAdapter.d.ts

@@ -0,0 +1,50 @@
+import type { ProviderSDKCallSpec, ProviderSDKExecResult, ProviderSDKStreamChunk, ProviderBatchResults } from '@x12i/ai-provider-interface';
+import type { RouterAdapter } from '../../registry/AdapterRegistry.js';
+import type { AIResponse, AIStreamEvent } from '../../router/RouterTypes.js';
+/**
+ * Router-side adapter for Grok/xAI provider
+ * Converts router requests to ProviderSDKCallSpec and parses responses
+ */
+export declare class GrokAdapter implements RouterAdapter {
+    provider: string;
+    buildCallSpec(input: {
+        requestId: string;
+        mode: 'sync' | 'stream';
+        request: any;
+        exec?: {
+            timeoutMs?: number;
+            retries?: number;
+            idempotencyKey?: string;
+            signal?: AbortSignal;
+        };
+    }): Promise<ProviderSDKCallSpec>;
+    parseResponse(input: {
+        requestId: string;
+        request: any;
+        execResult: ProviderSDKExecResult;
+    }): AIResponse;
+    parseStreamChunk(input: {
+        requestId: string;
+        request: any;
+        chunk: ProviderSDKStreamChunk;
+    }): AIStreamEvent[];
+    finalizeStream(input: {
+        requestId: string;
+        request: any;
+        collected: {
+            rawEvents: unknown[];
+            outputText?: string;
+        };
+        finalRaw?: unknown;
+    }): AIResponse;
+    parseBatchItem(input: {
+        requestId: string;
+        request: any;
+        item: ProviderBatchResults['items'][number];
+    }): {
+        requestId: string;
+        rawResponse?: unknown;
+        outputText?: string;
+        error?: any;
+    };
+}