universal-llm-client 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-llm-client",
-  "version": "4.0.0",
+  "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",
@@ -33,10 +33,15 @@
     "./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"
@@ -89,6 +94,9 @@
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {

package/src/ai-model.ts

@@ -0,0 +1,350 @@
+/**
+ * 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();
+    }
+}

package/src/auditor.ts

@@ -0,0 +1,213 @@
+/**
+ * Universal LLM Client v3 — Auditor (Observability)
+ *
+ * Every LLM interaction (request, response, tool call, retry, failover)
+ * is recorded through the Auditor interface. Frameworks inject their own
+ * Auditor for dashboards, cost tracking, or behavioral scoring.
+ */
+
+import type { TokenUsageInfo, ToolExecutionResult } from './interfaces.js';
+
+// ============================================================================
+// Audit Event
+// ============================================================================
+
+export type AuditEventType =
+    | 'request'
+    | 'response'
+    | 'stream_start'
+    | 'stream_end'
+    | 'tool_call'
+    | 'tool_result'
+    | 'error'
+    | 'retry'
+    | 'failover'
+    | 'structured_request'
+    | 'structured_response'
+    | 'structured_validation_error';
+
+export interface AuditEvent {
+    /** Unix timestamp in ms */
+    timestamp: number;
+    /** Event type */
+    type: AuditEventType;
+    /** Provider that generated this event */
+    provider?: string;
+    /** Model name */
+    model?: string;
+    /** Duration in ms (for request/response pairs) */
+    duration?: number;
+    /** Token usage (for response events) */
+    usage?: TokenUsageInfo;
+    /** Tool execution details (for tool_call/tool_result events) */
+    toolExecution?: ToolExecutionResult;
+    /** Error message (for error/retry events) */
+    error?: string;
+    /** Arbitrary metadata for framework-specific data */
+    metadata?: Record<string, unknown>;
+    /** Schema name for structured output events */
+    schemaName?: string;
+    /** Raw output snippet for validation errors */
+    rawOutput?: string;
+}
+
+// ============================================================================
+// Auditor Interface
+// ============================================================================
+
+/**
+ * Interface for LLM observability.
+ *
+ * Implement this to capture all LLM lifecycle events.
+ * The library calls `record()` at every interaction point.
+ */
+export interface Auditor {
+    /** Record an audit event */
+    record(event: AuditEvent): void;
+    /** Flush any buffered events (optional) */
+    flush?(): Promise<void>;
+}
+
+// ============================================================================
+// Built-in Auditors
+// ============================================================================
+
+/**
+ * Zero-overhead auditor that discards all events.
+ * Used as the default when no auditor is configured.
+ */
+export class NoopAuditor implements Auditor {
+    record(_event: AuditEvent): void {
+        // Intentionally empty
+    }
+}
+
+/**
+ * Structured console logging auditor.
+ * Useful for development and debugging.
+ */
+export class ConsoleAuditor implements Auditor {
+    private prefix: string;
+
+    constructor(prefix: string = '[LLM]') {
+        this.prefix = prefix;
+    }
+
+    record(event: AuditEvent): void {
+        const parts = [
+            this.prefix,
+            event.type.toUpperCase(),
+            event.provider ? `[${event.provider}]` : '',
+            event.model ? `(${event.model})` : '',
+        ].filter(Boolean);
+
+        switch (event.type) {
+            case 'request':
+                console.log(parts.join(' '), '→');
+                break;
+            case 'response':
+                console.log(
+                    parts.join(' '),
+                    event.duration ? `${event.duration}ms` : '',
+                    event.usage ? `${event.usage.totalTokens} tokens` : '',
+                );
+                break;
+            case 'stream_start':
+                console.log(parts.join(' '), 'streaming...');
+                break;
+            case 'stream_end':
+                console.log(
+                    parts.join(' '),
+                    'done',
+                    event.duration ? `${event.duration}ms` : '',
+                );
+                break;
+            case 'tool_call':
+                console.log(parts.join(' '), event.toolExecution?.tool_call_id ?? '');
+                break;
+            case 'tool_result':
+                console.log(
+                    parts.join(' '),
+                    event.toolExecution?.error ? '❌' : '✅',
+                    event.toolExecution?.duration ? `${event.toolExecution.duration}ms` : '',
+                );
+                break;
+            case 'error':
+                console.error(parts.join(' '), event.error ?? 'Unknown error');
+                break;
+            case 'retry':
+                console.warn(parts.join(' '), event.error ?? '', event.metadata ?? '');
+                break;
+            case 'failover':
+                console.warn(parts.join(' '), '→', event.metadata?.['nextProvider'] ?? '');
+                break;
+            case 'structured_request':
+                console.log(
+                    parts.join(' '),
+                    `schema=${event.schemaName ?? 'unknown'}`,
+                    '→',
+                );
+                break;
+            case 'structured_response':
+                console.log(
+                    parts.join(' '),
+                    event.duration ? `${event.duration}ms` : '',
+                    `schema=${event.schemaName ?? 'unknown'}`,
+                );
+                break;
+            case 'structured_validation_error':
+                console.error(
+                    parts.join(' '),
+                    `schema=${event.schemaName ?? 'unknown'}`,
+                    event.error ?? 'Validation failed',
+                    event.rawOutput ? `raw=${event.rawOutput.slice(0, 50)}...` : '',
+                );
+                break;
+        }
+    }
+}
+
+/**
+ * Buffered auditor that collects events for batch processing.
+ * Useful for custom sinks (OpenTelemetry, DataDog, databases, etc.)
+ */
+export class BufferedAuditor implements Auditor {
+    private events: AuditEvent[] = [];
+    private maxBufferSize: number;
+    private onFlush?: (events: AuditEvent[]) => Promise<void>;
+
+    constructor(options: {
+        maxBufferSize?: number;
+        onFlush?: (events: AuditEvent[]) => Promise<void>;
+    } = {}) {
+        this.maxBufferSize = options.maxBufferSize ?? 1000;
+        this.onFlush = options.onFlush;
+    }
+
+    record(event: AuditEvent): void {
+        this.events.push(event);
+        if (this.events.length >= this.maxBufferSize) {
+            // Auto-flush when buffer is full (fire and forget)
+            this.flush().catch(() => {});
+        }
+    }
+
+    /** Get all buffered events */
+    getEvents(): ReadonlyArray<AuditEvent> {
+        return this.events;
+    }
+
+    /** Flush buffered events to the configured sink */
+    async flush(): Promise<void> {
+        if (this.events.length === 0) return;
+        const batch = this.events.splice(0);
+        if (this.onFlush) {
+            await this.onFlush(batch);
+        }
+    }
+
+    /** Clear all buffered events without flushing */
+    clear(): void {
+        this.events.length = 0;
+    }
+}