universal-llm-client 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Igor Lins e Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,414 @@
+# universal-llm-client
+
+A universal LLM client for JavaScript/TypeScript with **transparent provider failover**, streaming tool execution, pluggable reasoning strategies, and native observability.
+
+```typescript
+import { AIModel } from 'universal-llm-client';
+
+const model = new AIModel({
+    model: 'gemini-2.5-flash',
+    providers: [
+        { type: 'google', apiKey: process.env.GOOGLE_API_KEY },
+        { type: 'openai', url: 'https://openrouter.ai/api', apiKey: process.env.OPENROUTER_KEY },
+        { type: 'ollama' },
+    ],
+});
+
+const response = await model.chat([
+    { role: 'user', content: 'Hello!' },
+]);
+```
+
+> **One model, multiple backends.** If Google fails, it transparently fails over to OpenRouter, then to local Ollama. Your code never knows the difference.
+
+---
+
+## Features
+
+- 🔄 **Transparent Failover** — Priority-ordered provider chain with retries, health tracking, and cooldowns
+- 🛠️ **Tool Calling** — Register tools once, works across all providers. Autonomous multi-turn execution loop
+- 🌊 **Streaming** — First-class async generator streaming with pluggable decoder strategies
+- 🧠 **Reasoning** — Native `<think>` tag parsing, interleaved reasoning, and model thinking support
+- 🔍 **Observability** — Built-in auditor interface for logging, cost tracking, and behavioral analysis
+- 🌐 **Universal Runtime** — Node.js 22+, Bun, Deno, and modern browsers
+- 🤖 **MCP Native** — Bridge MCP servers to LLM tools with zero glue code
+- 📊 **Embeddings** — Single and batch embedding generation
+
+## Supported Providers
+
+| Provider | Type | Notes |
+|---|---|---|
+| **Ollama** | `ollama` | Local or cloud models, NDJSON streaming, model pulling |
+| **OpenAI** | `openai` | GPT-4o, o3, etc. Also works with OpenRouter, Groq, LM Studio, vLLM |
+| **Google AI Studio** | `google` | Gemini models, system instructions, multimodal |
+| **Vertex AI** | `vertex` | Same as Google AI but with regional endpoints and Bearer tokens |
+| **LlamaCpp** | `llamacpp` | Local llama.cpp / llama-server instances |
+
+---
+
+## Installation
+
+```bash
+bun add universal-llm-client
+# or
+npm install universal-llm-client
+```
+
+**Optional**: For MCP integration:
+```bash
+bun add @modelcontextprotocol/sdk
+```
+
+---
+
+## Quick Start
+
+### Basic Chat
+
+```typescript
+import { AIModel } from 'universal-llm-client';
+
+const model = new AIModel({
+    model: 'qwen3:4b',
+    providers: [{ type: 'ollama' }],
+});
+
+const response = await model.chat([
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is the capital of France?' },
+]);
+
+console.log(response.message.content);
+// "The capital of France is Paris."
+```
+
+### Streaming
+
+```typescript
+for await (const event of model.chatStream([
+    { role: 'user', content: 'Write a haiku about code.' },
+])) {
+    if (event.type === 'text') {
+        process.stdout.write(event.content);
+    } else if (event.type === 'thinking') {
+        // Model reasoning (when supported)
+        console.log('[thinking]', event.content);
+    }
+}
+```
+
+### Tool Calling
+
+```typescript
+model.registerTool(
+    'get_weather',
+    'Get current weather for a location',
+    {
+        type: 'object',
+        properties: {
+            city: { type: 'string', description: 'City name' },
+        },
+        required: ['city'],
+    },
+    async (args) => {
+        const { city } = args as { city: string };
+        return { temperature: 22, condition: 'sunny', city };
+    },
+);
+
+// Autonomous tool execution — the model calls tools and loops until done
+const response = await model.chatWithTools([
+    { role: 'user', content: "What's the weather in Tokyo?" },
+]);
+
+console.log(response.message.content);
+// "The weather in Tokyo is 22°C and sunny."
+console.log(response.toolTrace);
+// [{ name: 'get_weather', args: { city: 'Tokyo' }, result: {...}, duration: 5 }]
+```
+
+### Provider Failover
+
+```typescript
+const model = new AIModel({
+    model: 'gemini-2.5-flash',
+    retries: 2,        // retries per provider before failover
+    timeout: 30000,    // request timeout in ms
+    providers: [
+        { type: 'google', apiKey: process.env.GOOGLE_KEY, priority: 0 },
+        { type: 'openai', url: 'https://openrouter.ai/api', apiKey: process.env.OPENROUTER_KEY, priority: 1 },
+        { type: 'ollama', url: 'http://localhost:11434', priority: 2 },
+    ],
+});
+
+// If Google returns 500, retries twice, then seamlessly tries OpenRouter.
+// If OpenRouter also fails, falls back to local Ollama.
+// Your code sees a single response.
+const response = await model.chat([{ role: 'user', content: 'Hello' }]);
+
+// Check provider health at any time
+console.log(model.getProviderStatus());
+// [{ id: 'google-0', healthy: true }, { id: 'openai-1', healthy: true }, ...]
+```
+
+### Multimodal (Vision)
+
+```typescript
+import { AIModel, multimodalMessage } from 'universal-llm-client';
+
+const model = new AIModel({
+    model: 'gemini-2.5-flash',
+    providers: [{ type: 'google', apiKey: process.env.GOOGLE_KEY }],
+});
+
+const response = await model.chat([
+    multimodalMessage('What do you see in this image?', [
+        'https://example.com/photo.jpg',
+    ]),
+]);
+```
+
+### Embeddings
+
+```typescript
+const embedModel = new AIModel({
+    model: 'nomic-embed-text-v2-moe:latest',
+    providers: [{ type: 'ollama' }],
+});
+
+const vector = await embedModel.embed('Hello world');
+// [0.006, 0.026, -0.009, ...]
+
+const vectors = await embedModel.embedArray(['Hello', 'World']);
+// [[0.006, ...], [0.012, ...]]
+```
+
+### Observability
+
+```typescript
+import { AIModel, ConsoleAuditor, BufferedAuditor } from 'universal-llm-client';
+
+// Simple console logging
+const model = new AIModel({
+    model: 'qwen3:4b',
+    providers: [{ type: 'ollama' }],
+    auditor: new ConsoleAuditor('[LLM]'),
+});
+// [LLM] REQUEST [ollama] (qwen3:4b) →
+// [LLM] RESPONSE [ollama] (qwen3:4b) 1200ms 68 tokens
+
+// Buffered for custom sinks (OpenTelemetry, DB, etc.)
+const auditor = new BufferedAuditor({
+    maxBufferSize: 100,
+    onFlush: async (events) => {
+        await sendToOpenTelemetry(events);
+    },
+});
+```
+
+### MCP Integration
+
+```typescript
+import { AIModel, MCPToolBridge } from 'universal-llm-client';
+
+const model = new AIModel({
+    model: 'qwen3:4b',
+    providers: [{ type: 'ollama' }],
+});
+
+const mcp = new MCPToolBridge({
+    servers: {
+        filesystem: {
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem', './'],
+        },
+        weather: {
+            url: 'https://mcp.example.com/weather',
+        },
+    },
+});
+
+await mcp.connect();
+await mcp.registerTools(model);
+
+// MCP tools are now callable via chatWithTools
+const response = await model.chatWithTools([
+    { role: 'user', content: 'List files in the current directory' },
+]);
+
+await mcp.disconnect();
+```
+
+### Stream Decoders
+
+```typescript
+import { AIModel, createDecoder } from 'universal-llm-client';
+
+// Passthrough — raw text, no parsing
+// Standard Chat — text + native reasoning + tool calls
+// Interleaved Reasoning — parses <think> and <progress> tags from text streams
+
+const decoder = createDecoder('interleaved-reasoning', (event) => {
+    switch (event.type) {
+        case 'text': console.log(event.content); break;
+        case 'thinking': console.log('[think]', event.content); break;
+        case 'progress': console.log('[progress]', event.content); break;
+        case 'tool_call': console.log('[tool]', event.calls); break;
+    }
+});
+
+decoder.push('<think>Let me analyze this</think>The answer is 42');
+decoder.flush();
+
+console.log(decoder.getCleanContent());  // "The answer is 42"
+console.log(decoder.getReasoning());      // "Let me analyze this"
+```
+
+---
+
+## API Reference
+
+### `AIModel`
+
+The universal client. One class, multiple backends.
+
+```typescript
+new AIModel(config: AIModelConfig)
+```
+
+**Config:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `model` | `string` | — | Model name (e.g., `'gemini-2.5-flash'`) |
+| `providers` | `ProviderConfig[]` | — | Ordered list of provider backends |
+| `retries` | `number` | `2` | Retries per provider before failover |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `auditor` | `Auditor` | `NoopAuditor` | Observability sink |
+| `thinking` | `boolean` | `false` | Enable model thinking/reasoning |
+| `debug` | `boolean` | `false` | Debug logging |
+| `defaultParameters` | `object` | — | Default parameters for all requests |
+
+**Provider Config:**
+
+| Property | Type | Description |
+|---|---|---|
+| `type` | `string` | `'ollama'`, `'openai'`, `'google'`, `'vertex'`, `'llamacpp'` |
+| `url` | `string` | Provider URL (has sensible defaults) |
+| `apiKey` | `string` | API key or Bearer token |
+| `priority` | `number` | Lower = tried first (defaults to array index) |
+| `model` | `string` | Override model name for this provider |
+| `region` | `string` | Vertex AI region (e.g., `'us-central1'`) |
+| `apiVersion` | `string` | API version (e.g., `'v1beta'`) |
+
+**Methods:**
+
+| Method | Returns | Description |
+|---|---|---|
+| `chat(messages, options?)` | `Promise<LLMChatResponse>` | Send chat request |
+| `chatWithTools(messages, options?)` | `Promise<LLMChatResponse>` | Chat with autonomous tool execution |
+| `chatStream(messages, options?)` | `AsyncGenerator<DecodedEvent>` | Stream chat response |
+| `embed(text)` | `Promise<number[]>` | Generate single embedding |
+| `embedArray(texts)` | `Promise<number[][]>` | Generate batch embeddings |
+| `registerTool(name, desc, params, handler)` | `void` | Register a callable tool |
+| `registerTools(tools)` | `void` | Register multiple tools |
+| `getModels()` | `Promise<string[]>` | List available models |
+| `getModelInfo()` | `Promise<ModelMetadata>` | Get model metadata |
+| `getProviderStatus()` | `ProviderStatus[]` | Check provider health |
+| `setModel(name)` | `void` | Switch model at runtime |
+| `dispose()` | `Promise<void>` | Clean shutdown |
+
+### `ToolBuilder` / `ToolExecutor`
+
+```typescript
+import { ToolBuilder, ToolExecutor } from 'universal-llm-client';
+
+// Fluent builder
+const tool = new ToolBuilder('search')
+    .description('Search the web')
+    .addParameter('query', 'string', 'Search query', true)
+    .addParameter('limit', 'number', 'Max results', false)
+    .build();
+
+// Execution wrappers
+const safeHandler = ToolExecutor.compose(
+    myHandler,
+    h => ToolExecutor.withTimeout(h, 5000),
+    h => ToolExecutor.safe(h),
+    h => ToolExecutor.withValidation(h, ['query']),
+);
+```
+
+### Auditor Interface
+
+Implement custom observability by providing an `Auditor`:
+
+```typescript
+interface Auditor {
+    record(event: AuditEvent): void;
+    flush?(): Promise<void>;
+}
+```
+
+**Built-in implementations:**
+- `NoopAuditor` — Zero overhead (default)
+- `ConsoleAuditor` — Structured console logging
+- `BufferedAuditor` — Collects events for custom sinks
+
+---
+
+## Architecture
+
+```
+@akaito/universal-llm-client
+├── AIModel          ← Public API (the only class you import)
+├── Router           ← Internal failover engine
+├── BaseLLMClient    ← Abstract client with tool execution
+├── Providers
+│   ├── OllamaClient
+│   ├── OpenAICompatibleClient
+│   └── GoogleClient (AI Studio + Vertex AI)
+├── StreamDecoder    ← Pluggable reasoning strategies
+├── Auditor          ← Observability interface
+├── MCPToolBridge    ← MCP server integration
+└── HTTP Utilities   ← Universal fetch-based transport
+```
+
+### Design Principles
+
+1. **Single import** — `AIModel` is the only class users need
+2. **Provider agnostic** — Same code works with any backend
+3. **Transparent failover** — Health tracking and cooldowns happen behind the scenes
+4. **Zero dependencies** — Core library depends only on native `fetch`
+5. **Agent-ready** — Stateless, composable instances designed as foundation for agent frameworks
+6. **Observable** — Every request, response, tool call, retry, and failover is auditable
+
+---
+
+## Runtime Support
+
+| Runtime | Version | Status |
+|---|---|---|
+| **Node.js** | 22+ | ✅ Full support |
+| **Bun** | 1.0+ | ✅ Full support |
+| **Deno** | 2.0+ | ✅ Full support |
+| **Browsers** | Modern | ✅ No stdio MCP, HTTP transport only |
+
+---
+
+## For Agent Framework Authors
+
+`AIModel` is designed as the transport layer for agentic systems:
+
+- **Stateless** — No conversation history stored. Your framework manages memory
+- **Composable** — Create separate instances for chat, embeddings, vision
+- **Tool tracing** — `chatWithTools()` returns full execution trace
+- **Context budget** — `getModelInfo()` exposes `contextLength`
+- **Auditor as system bus** — Inject custom sinks for cost tracking, behavioral scoring
+- **StreamDecoder as UI bridge** — Select decoder strategy per-call
+
+---
+
+## License
+
+MIT

package/dist/ai-model.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Universal LLM Client v3 — AIModel (The Universal Client)
+ *
+ * The only public-facing class. Developers configure one model with
+ * multiple provider backends for transparent failover.
+ *
+ * Provider classes are internal — the user never imports them.
+ */
+import { type AIModelConfig, type LLMChatMessage, type LLMChatResponse, type ChatOptions, type ModelMetadata, type LLMFunction, type ToolHandler } from './interfaces.js';
+import type { DecodedEvent } from './stream-decoder.js';
+import { type ProviderStatus } from './router.js';
+export declare class AIModel {
+    private router;
+    private auditor;
+    private config;
+    constructor(config: AIModelConfig);
+    /** Send a chat request with automatic failover across providers */
+    chat(messages: LLMChatMessage[], options?: ChatOptions): Promise<LLMChatResponse>;
+    /** Chat with automatic tool execution (multi-turn loop) */
+    chatWithTools(messages: LLMChatMessage[], options?: ChatOptions & {
+        maxIterations?: number;
+    }): Promise<LLMChatResponse>;
+    /** Stream chat response with pluggable decoder strategy */
+    chatStream(messages: LLMChatMessage[], options?: ChatOptions): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>;
+    /** Generate embedding for a single text */
+    embed(text: string): Promise<number[]>;
+    /** Generate embeddings for multiple texts */
+    embedArray(texts: string[]): Promise<number[][]>;
+    /** Register a tool callable by the LLM (broadcast to all providers) */
+    registerTool(name: string, description: string, parameters: LLMFunction['parameters'], handler: ToolHandler): void;
+    /** Register multiple tools at once */
+    registerTools(tools: Array<{
+        name: string;
+        description: string;
+        parameters: LLMFunction['parameters'];
+        handler: ToolHandler;
+    }>): void;
+    /** Get available models from all configured providers */
+    getModels(): Promise<string[]>;
+    /** Get metadata about the current model (context length, capabilities) */
+    getModelInfo(): Promise<ModelMetadata>;
+    /** Switch model at runtime (updates all providers) */
+    setModel(name: string): void;
+    /** Get the current model name */
+    get model(): string;
+    /** Get health/status of all configured providers */
+    getProviderStatus(): ProviderStatus[];
+    /** Clean shutdown — flush auditor, disconnect MCP, etc. */
+    dispose(): Promise<void>;
+    private createClient;
+    private normalizeType;
+}
+//# sourceMappingURL=ai-model.d.ts.map

package/dist/ai-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-model.d.ts","sourceRoot":"","sources":["../src/ai-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEH,KAAK,aAAa,EAGlB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAuB7E,qBAAa,OAAO;IAChB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IA6BjC,mEAAmE;IAC7D,IAAI,CACN,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,eAAe,CAAC;IAI3B,2DAA2D;IACrD,aAAa,CACf,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC,eAAe,CAAC;IAI3B,2DAA2D;IACpD,UAAU,CACb,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GACtB,cAAc,CAAC,YAAY,EAAE,eAAe,GAAG,IAAI,EAAE,OAAO,CAAC;IAQhE,2CAA2C;IACrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI5C,6CAA6C;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAQtD,uEAAuE;IACvE,YAAY,CACR,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,EACrC,OAAO,EAAE,WAAW,GACrB,IAAI;IAIP,sCAAsC;IACtC,aAAa,CACT,KAAK,EAAE,KAAK,CAAC;QACT,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;QACtC,OAAO,EAAE,WAAW,CAAC;KACxB,CAAC,GACH,IAAI;IAQP,yDAAyD;IACnD,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpC,0EAA0E;IACpE,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;IAI5C,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM5B,iCAAiC;IACjC,IAAI,KAAK,IAAI,MAAM,CAElB;IAMD,oDAAoD;IACpD,iBAAiB,IAAI,cAAc,EAAE;IAQrC,2DAA2D;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,YAAY;IAmCpB,OAAO,CAAC,aAAa;CAGxB"}

package/dist/ai-model.js

@@ -0,0 +1,159 @@
+/**
+ * Universal LLM Client v3 — AIModel (The Universal Client)
+ *
+ * The only public-facing class. Developers configure one model with
+ * multiple provider backends for transparent failover.
+ *
+ * Provider classes are internal — the user never imports them.
+ */
+import { Router } from './router.js';
+import { NoopAuditor } from './auditor.js';
+import { OllamaClient } from './providers/ollama.js';
+import { OpenAICompatibleClient } from './providers/openai.js';
+import { GoogleClient } from './providers/google.js';
+// ============================================================================
+// Default Provider URLs
+// ============================================================================
+const DEFAULT_URLS = {
+    ollama: 'http://localhost:11434',
+    openai: 'https://api.openai.com',
+    llamacpp: 'http://localhost:8080',
+    // google and vertex build their own URLs internally
+};
+// ============================================================================
+// AIModel — The Universal Client
+// ============================================================================
+export class AIModel {
+    router;
+    auditor;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.auditor = config.auditor ?? new NoopAuditor();
+        const routerConfig = {
+            retriesPerProvider: config.retries ?? 2,
+            auditor: this.auditor,
+        };
+        this.router = new Router(routerConfig);
+        // Initialize providers in order
+        for (let i = 0; i < config.providers.length; i++) {
+            const providerConfig = config.providers[i];
+            const client = this.createClient(providerConfig);
+            const id = `${this.normalizeType(providerConfig.type)}-${i}`;
+            this.router.addProvider({
+                id,
+                client,
+                priority: providerConfig.priority ?? i,
+                modelOverride: providerConfig.model,
+            });
+        }
+    }
+    // ========================================================================
+    // Chat
+    // ========================================================================
+    /** Send a chat request with automatic failover across providers */
+    async chat(messages, options) {
+        return this.router.chat(messages, options);
+    }
+    /** Chat with automatic tool execution (multi-turn loop) */
+    async chatWithTools(messages, options) {
+        return this.router.chatWithTools(messages, options);
+    }
+    /** Stream chat response with pluggable decoder strategy */
+    async *chatStream(messages, options) {
+        return yield* this.router.chatStream(messages, options);
+    }
+    // ========================================================================
+    // Embeddings
+    // ========================================================================
+    /** Generate embedding for a single text */
+    async embed(text) {
+        return this.router.embed(text);
+    }
+    /** Generate embeddings for multiple texts */
+    async embedArray(texts) {
+        return this.router.embedArray(texts);
+    }
+    // ========================================================================
+    // Tool Registration
+    // ========================================================================
+    /** Register a tool callable by the LLM (broadcast to all providers) */
+    registerTool(name, description, parameters, handler) {
+        this.router.registerTool(name, description, parameters, handler);
+    }
+    /** Register multiple tools at once */
+    registerTools(tools) {
+        this.router.registerTools(tools);
+    }
+    // ========================================================================
+    // Model Management
+    // ========================================================================
+    /** Get available models from all configured providers */
+    async getModels() {
+        return this.router.getModels();
+    }
+    /** Get metadata about the current model (context length, capabilities) */
+    async getModelInfo() {
+        return this.router.getModelInfo();
+    }
+    /** Switch model at runtime (updates all providers) */
+    setModel(name) {
+        this.config.model = name;
+        // The model name change will be picked up by the providers
+        // through the router on next request
+    }
+    /** Get the current model name */
+    get model() {
+        return this.config.model;
+    }
+    // ========================================================================
+    // Provider Status
+    // ========================================================================
+    /** Get health/status of all configured providers */
+    getProviderStatus() {
+        return this.router.getStatus();
+    }
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+    /** Clean shutdown — flush auditor, disconnect MCP, etc. */
+    async dispose() {
+        await this.auditor.flush?.();
+    }
+    // ========================================================================
+    // Internal: Provider Factory
+    // ========================================================================
+    createClient(providerConfig) {
+        const type = this.normalizeType(providerConfig.type);
+        const modelName = providerConfig.model ?? this.config.model;
+        const clientOptions = {
+            model: modelName,
+            url: providerConfig.url ?? DEFAULT_URLS[type] ?? '',
+            apiType: type,
+            apiKey: providerConfig.apiKey,
+            timeout: this.config.timeout ?? 30000,
+            retries: this.config.retries ?? 2,
+            debug: this.config.debug ?? false,
+            defaultParameters: this.config.defaultParameters,
+            thinking: this.config.thinking ?? false,
+            region: providerConfig.region,
+            apiVersion: providerConfig.apiVersion,
+        };
+        switch (type) {
+            case 'ollama':
+                return new OllamaClient(clientOptions, this.auditor);
+            case 'openai':
+            case 'llamacpp':
+                return new OpenAICompatibleClient(clientOptions, this.auditor);
+            case 'google':
+            case 'vertex':
+                return new GoogleClient(clientOptions, this.auditor);
+            default:
+                throw new Error(`Unknown provider type: ${type}`);
+        }
+    }
+    normalizeType(type) {
+        return type.toLowerCase();
+    }
+}
+//# sourceMappingURL=ai-model.js.map

package/dist/ai-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-model.js","sourceRoot":"","sources":["../src/ai-model.ts"],"names":[],"mappings":"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"}