universal-llm-client 4.2.0 → 4.3.0

package/package.json

@@ -1,116 +1,115 @@
-{
-  "name": "universal-llm-client",
-  "version": "4.2.0",
-  "type": "module",
-  "description": "A universal LLM client with transparent provider failover, streaming tool execution, pluggable reasoning, and native observability.",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./interfaces": {
-      "import": "./dist/interfaces.js",
-      "types": "./dist/interfaces.d.ts"
-    },
-    "./tools": {
-      "import": "./dist/tools.js",
-      "types": "./dist/tools.d.ts"
-    },
-    "./auditor": {
-      "import": "./dist/auditor.js",
-      "types": "./dist/auditor.d.ts"
-    },
-    "./stream-decoder": {
-      "import": "./dist/stream-decoder.js",
-      "types": "./dist/stream-decoder.d.ts"
-    },
-    "./http": {
-      "import": "./dist/http.js",
-      "types": "./dist/http.d.ts"
-    },
-    "./structured-output": {
-      "import": "./dist/structured-output.js",
-      "types": "./dist/structured-output.d.ts"
-    },
-    "./zod": {
-      "import": "./dist/zod-adapter.js",
-      "types": "./dist/zod-adapter.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "bun run clean && bun run compile",
-    "clean": "rimraf dist",
-    "compile": "tsc --project tsconfig.json",
-    "dev": "tsc --watch --project tsconfig.json",
-    "prepublishOnly": "bun run build",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit --strict",
-    "prepack": "bun run build",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  },
-  "keywords": [
-    "llm",
-    "ai",
-    "artificial-intelligence",
-    "openai",
-    "ollama",
-    "google-gemini",
-    "vertex-ai",
-    "universal",
-    "failover",
-    "streaming",
-    "tool-calling",
-    "function-calling",
-    "mcp",
-    "observability",
-    "typescript",
-    "esm"
-  ],
-  "dependencies": {},
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.8.3",
-    "vitepress": "^1.6.4",
-    "vue": "^3.5.30",
-    "zod": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@modelcontextprotocol/sdk": ">=1.24.0",
-    "zod": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@modelcontextprotocol/sdk": {
-      "optional": true
-    },
-    "zod": {
-      "optional": true
-    }
-  },
-  "engines": {
-    "node": ">=22.0.0",
-    "bun": ">=1.0.0"
-  },
-  "author": "Igor Lins e Silva",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/igorls/universal-llm-client.git"
-  },
-  "homepage": "https://github.com/igorls/universal-llm-client#readme",
-  "bugs": {
-    "url": "https://github.com/igorls/universal-llm-client/issues"
-  }
-}
+{
+  "name": "universal-llm-client",
+  "version": "4.3.0",
+  "type": "module",
+  "description": "A universal LLM client with transparent provider failover, streaming tool execution, pluggable reasoning, and native observability.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./interfaces": {
+      "import": "./dist/interfaces.js",
+      "types": "./dist/interfaces.d.ts"
+    },
+    "./tools": {
+      "import": "./dist/tools.js",
+      "types": "./dist/tools.d.ts"
+    },
+    "./auditor": {
+      "import": "./dist/auditor.js",
+      "types": "./dist/auditor.d.ts"
+    },
+    "./stream-decoder": {
+      "import": "./dist/stream-decoder.js",
+      "types": "./dist/stream-decoder.d.ts"
+    },
+    "./http": {
+      "import": "./dist/http.js",
+      "types": "./dist/http.d.ts"
+    },
+    "./structured-output": {
+      "import": "./dist/structured-output.js",
+      "types": "./dist/structured-output.d.ts"
+    },
+    "./zod": {
+      "import": "./dist/zod-adapter.js",
+      "types": "./dist/zod-adapter.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run compile",
+    "clean": "rimraf dist",
+    "compile": "tsc --project tsconfig.json",
+    "dev": "tsc --watch --project tsconfig.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit --strict",
+    "prepack": "bun run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "artificial-intelligence",
+    "openai",
+    "ollama",
+    "google-gemini",
+    "vertex-ai",
+    "universal",
+    "failover",
+    "streaming",
+    "tool-calling",
+    "function-calling",
+    "mcp",
+    "observability",
+    "typescript",
+    "esm"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.30",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.24.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.0.0"
+  },
+  "author": "Igor Lins e Silva",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/igorls/universal-llm-client.git"
+  },
+  "homepage": "https://github.com/igorls/universal-llm-client#readme",
+  "bugs": {
+    "url": "https://github.com/igorls/universal-llm-client/issues"
+  }
+}

package/src/ai-model.ts

@@ -1,350 +0,0 @@
-/**
- * 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 {
-    AIModelApiType,
-    type AIModelConfig,
-    type ProviderConfig,
-    type LLMClientOptions,
-    type LLMChatMessage,
-    type LLMChatResponse,
-    type ChatOptions,
-    type ModelMetadata,
-    type LLMFunction,
-    type ToolHandler,
-} from './interfaces.js';
-import type { DecodedEvent } from './stream-decoder.js';
-import { Router, type RouterConfig, type ProviderStatus } from './router.js';
-import type { Auditor } from './auditor.js';
-import { NoopAuditor } from './auditor.js';
-import { OllamaClient } from './providers/ollama.js';
-import { OpenAICompatibleClient } from './providers/openai.js';
-import { GoogleClient } from './providers/google.js';
-import { AnthropicClient } from './providers/anthropic.js';
-import { BaseLLMClient } from './client.js';
-import {
-    type StructuredOutputResult,
-    type SchemaConfig,
-} from './structured-output.js';
-
-// ============================================================================
-// Default Provider URLs
-// ============================================================================
-
-const DEFAULT_URLS: Record<string, string> = {
-    ollama: 'http://localhost:11434',
-    openai: 'https://api.openai.com',
-    llamacpp: 'http://localhost:8080',
-    anthropic: 'https://api.anthropic.com',
-    // google and vertex build their own URLs internally
-};
-
-// ============================================================================
-// AIModel — The Universal Client
-// ============================================================================
-
-export class AIModel {
-    private router: Router;
-    private auditor: Auditor;
-    private config: AIModelConfig;
-
-    constructor(config: AIModelConfig) {
-        this.config = config;
-        this.auditor = config.auditor ?? new NoopAuditor();
-
-        const routerConfig: 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: LLMChatMessage[],
-        options?: ChatOptions,
-    ): Promise<LLMChatResponse> {
-        return this.router.chat(messages, options);
-    }
-
-    /** Chat with automatic tool execution (multi-turn loop) */
-    async chatWithTools(
-        messages: LLMChatMessage[],
-        options?: ChatOptions & { maxIterations?: number },
-    ): Promise<LLMChatResponse> {
-        return this.router.chatWithTools(messages, options);
-    }
-
-    /** Stream chat response with pluggable decoder strategy */
-    async *chatStream(
-        messages: LLMChatMessage[],
-        options?: ChatOptions,
-    ): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown> {
-        return yield* this.router.chatStream(messages, options);
-    }
-
-    // ========================================================================
-    // Structured Output
-    // ========================================================================
-
-    /**
-     * Generate structured output from the LLM with automatic failover.
-     * Validates the response against the provided Zod schema.
-     * Throws StructuredOutputError on validation failure.
-     *
-     * @template T The output type
-     * @param config Schema configuration (JSON Schema + optional validator)
-     * @param messages Chat messages to send
-     * @param options Additional options (temperature, maxTokens, etc.)
-     * @returns Promise resolving to validated structured output
-     * @throws StructuredOutputError if JSON parsing fails or validation fails
-     *
-     * @example
-     * ```typescript
-     * import { fromZod } from 'universal-llm-client/zod';
-     * const UserConfig = fromZod(z.object({
-     *   name: z.string(),
-     *   age: z.number(),
-     * }));
-     *
-     * const user = await model.generateStructured(UserConfig, [
-     *   { role: 'user', content: 'Generate a user profile' },
-     * ]);
-     * // user.name: string, user.age: number
-     * ```
-     */
-    async generateStructured<T>(
-        config: SchemaConfig<T>,
-        messages: LLMChatMessage[],
-        options?: ChatOptions,
-    ): Promise<T> {
-        return this.router.generateStructured(config, messages, options);
-    }
-
-    /**
-     * Try to generate structured output, returning a result object instead of throwing.
-     * Same as generateStructured but returns { ok: true, value } on success
-     * and { ok: false, error, rawOutput } on failure.
-     *
-     * @template T The output type
-     * @param config Schema configuration (JSON Schema + optional validator)
-     * @param messages Chat messages to send
-     * @param options Additional options (temperature, maxTokens, etc.)
-     * @returns StructuredOutputResult<T> - either success with value or failure with error
-     *
-     * @example
-     * ```typescript
-     * const result = await model.tryParseStructured(config, messages);
-     *
-     * if (result.ok) {
-     *   console.log('User:', result.value.name);
-     * } else {
-     *   console.log('Error:', result.error.message);
-     *   console.log('Raw output:', result.rawOutput);
-     * }
-     * ```
-     */
-    async tryParseStructured<T>(
-        config: SchemaConfig<T>,
-        messages: LLMChatMessage[],
-        options?: ChatOptions,
-    ): Promise<StructuredOutputResult<T>> {
-        return this.router.tryParseStructured(config, messages, options);
-    }
-
-    /**
-     * Stream structured output with partial validated objects.
-     *
-     * Yields partial validated objects as JSON generates, then returns the
-     * complete validated object on stream completion.
-     *
-     * For invalid partial JSON, no yield occurs (partial validation is best-effort).
-     * On stream completion, if the final JSON fails validation, throws StructuredOutputError.
-     *
-     * @template T The output type
-     * @param config Schema configuration (JSON Schema + optional validator)
-     * @param messages Chat messages to send
-     * @param options Additional options (temperature, maxTokens, etc.)
-     * @yields Partial validated objects as the JSON stream progresses
-     * @returns Complete validated object on stream completion
-     * @throws StructuredOutputError if final validation fails
-     *
-     * @example
-     * ```typescript
-     * import { fromZod } from 'universal-llm-client/zod';
-     * const UserConfig = fromZod(z.object({
-     *   name: z.string(),
-     *   age: z.number(),
-     * }));
-     *
-     * const stream = model.generateStructuredStream(UserConfig, [
-     *   { role: 'user', content: 'Generate a user' },
-     * ]);
-     *
-     * for await (const partial of stream) {
-     *   console.log('Partial user:', partial);
-     * }
-     * ```
-     */
-    async *generateStructuredStream<T>(
-        config: SchemaConfig<T>,
-        messages: LLMChatMessage[],
-        options?: ChatOptions,
-    ): AsyncGenerator<T, T, unknown> {
-        return yield* this.router.generateStructuredStream(config, messages, options);
-    }
-
-    // ========================================================================
-    // Embeddings
-    // ========================================================================
-
-    /** Generate embedding for a single text */
-    async embed(text: string): Promise<number[]> {
-        return this.router.embed(text);
-    }
-
-    /** Generate embeddings for multiple texts */
-    async embedArray(texts: string[]): Promise<number[][]> {
-        return this.router.embedArray(texts);
-    }
-
-    // ========================================================================
-    // Tool Registration
-    // ========================================================================
-
-    /** Register a tool callable by the LLM (broadcast to all providers) */
-    registerTool(
-        name: string,
-        description: string,
-        parameters: LLMFunction['parameters'],
-        handler: ToolHandler,
-    ): void {
-        this.router.registerTool(name, description, parameters, handler);
-    }
-
-    /** Register multiple tools at once */
-    registerTools(
-        tools: Array<{
-            name: string;
-            description: string;
-            parameters: LLMFunction['parameters'];
-            handler: ToolHandler;
-        }>,
-    ): void {
-        this.router.registerTools(tools);
-    }
-
-    // ========================================================================
-    // Model Management
-    // ========================================================================
-
-    /** Get available models from all configured providers */
-    async getModels(): Promise<string[]> {
-        return this.router.getModels();
-    }
-
-    /** Get metadata about the current model (context length, capabilities) */
-    async getModelInfo(): Promise<ModelMetadata> {
-        return this.router.getModelInfo();
-    }
-
-    /** Switch model at runtime (updates all providers) */
-    setModel(name: string): void {
-        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(): string {
-        return this.config.model;
-    }
-
-    // ========================================================================
-    // Provider Status
-    // ========================================================================
-
-    /** Get health/status of all configured providers */
-    getProviderStatus(): ProviderStatus[] {
-        return this.router.getStatus();
-    }
-
-    // ========================================================================
-    // Lifecycle
-    // ========================================================================
-
-    /** Clean shutdown — flush auditor, disconnect MCP, etc. */
-    async dispose(): Promise<void> {
-        await this.auditor.flush?.();
-    }
-
-    // ========================================================================
-    // Internal: Provider Factory
-    // ========================================================================
-
-    private createClient(providerConfig: ProviderConfig): BaseLLMClient {
-        const type = this.normalizeType(providerConfig.type);
-        const modelName = providerConfig.model ?? this.config.model;
-
-        const clientOptions: LLMClientOptions = {
-            model: modelName,
-            url: providerConfig.url ?? DEFAULT_URLS[type] ?? '',
-            apiType: type as AIModelApiType,
-            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);
-
-            case 'anthropic':
-                return new AnthropicClient(clientOptions, this.auditor);
-
-            default:
-                throw new Error(`Unknown provider type: ${type}`);
-        }
-    }
-
-    private normalizeType(type: string): string {
-        return type.toLowerCase();
-    }
-}