universal-llm-client 3.0.0

package/dist/router.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Universal LLM Client v3 — Router (Internal Failover Engine)
+ *
+ * Manages the ordered provider chain with:
+ *  - Priority ordering
+ *  - Per-provider retries
+ *  - Health tracking with failure thresholds
+ *  - Cooldown periods for unhealthy providers
+ *  - Audit integration for every retry/failover event
+ *
+ * Not exposed publicly — AIModel delegates to it.
+ */
+import { BaseLLMClient } from './client.js';
+import type { Auditor } from './auditor.js';
+import type { LLMChatMessage, LLMChatResponse, ChatOptions, ModelMetadata } from './interfaces.js';
+import type { DecodedEvent } from './stream-decoder.js';
+export interface ProviderEntry {
+    /** Unique identifier for this provider entry */
+    id: string;
+    /** The underlying LLM client */
+    client: BaseLLMClient;
+    /** Priority (lower = tried first, defaults to insertion order) */
+    priority: number;
+    /** Override model name for this provider */
+    modelOverride?: string;
+}
+export interface RouterConfig {
+    /** Max retries per provider before failover (default: 2) */
+    retriesPerProvider?: number;
+    /** Max consecutive failures before marking unhealthy (default: 3) */
+    maxFailures?: number;
+    /** Cooldown period in ms for unhealthy providers (default: 30000) */
+    cooldownMs?: number;
+    /** Auditor for observability */
+    auditor?: Auditor;
+}
+export interface ProviderStatus {
+    id: string;
+    healthy: boolean;
+    active: boolean;
+    consecutiveFailures: number;
+    cooldownUntil?: number;
+    model: string;
+}
+export declare class Router {
+    private providers;
+    private health;
+    private auditor;
+    private config;
+    constructor(config?: RouterConfig);
+    addProvider(entry: ProviderEntry): void;
+    removeProvider(id: string): void;
+    setAuditor(auditor: Auditor): void;
+    getStatus(): ProviderStatus[];
+    /**
+     * Execute a function against providers with automatic failover.
+     * Tries each available provider in priority order.
+     */
+    execute<T>(fn: (client: BaseLLMClient) => Promise<T>, context?: string): Promise<T>;
+    /**
+     * Execute a streaming function with failover.
+     * On failure, retries with the next provider from the beginning.
+     */
+    executeStream(fn: (client: BaseLLMClient) => AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>, context?: string): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>;
+    chat(messages: LLMChatMessage[], options?: ChatOptions): Promise<LLMChatResponse>;
+    chatWithTools(messages: LLMChatMessage[], options?: ChatOptions & {
+        maxIterations?: number;
+    }): Promise<LLMChatResponse>;
+    chatStream(messages: LLMChatMessage[], options?: ChatOptions): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>;
+    embed(text: string): Promise<number[]>;
+    embedArray(texts: string[]): Promise<number[][]>;
+    getModels(): Promise<string[]>;
+    getModelInfo(): Promise<ModelMetadata>;
+    registerTool(name: string, description: string, parameters: import('./interfaces.js').LLMFunction['parameters'], handler: import('./interfaces.js').ToolHandler): void;
+    registerTools(tools: Array<{
+        name: string;
+        description: string;
+        parameters: import('./interfaces.js').LLMFunction['parameters'];
+        handler: import('./interfaces.js').ToolHandler;
+    }>): void;
+    private isAvailable;
+    private getAvailableProviders;
+    private getNextAvailableAfter;
+    private recordSuccess;
+    private recordFailure;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

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

package/dist/router.js

@@ -0,0 +1,260 @@
+/**
+ * Universal LLM Client v3 — Router (Internal Failover Engine)
+ *
+ * Manages the ordered provider chain with:
+ *  - Priority ordering
+ *  - Per-provider retries
+ *  - Health tracking with failure thresholds
+ *  - Cooldown periods for unhealthy providers
+ *  - Audit integration for every retry/failover event
+ *
+ * Not exposed publicly — AIModel delegates to it.
+ */
+import { NoopAuditor } from './auditor.js';
+// ============================================================================
+// Router
+// ============================================================================
+export class Router {
+    providers = [];
+    health = new Map();
+    auditor;
+    config;
+    constructor(config = {}) {
+        this.auditor = config.auditor ?? new NoopAuditor();
+        this.config = {
+            retriesPerProvider: config.retriesPerProvider ?? 2,
+            maxFailures: config.maxFailures ?? 3,
+            cooldownMs: config.cooldownMs ?? 30000,
+        };
+    }
+    // ========================================================================
+    // Provider Management
+    // ========================================================================
+    addProvider(entry) {
+        this.providers.push(entry);
+        this.health.set(entry.id, {
+            healthy: true,
+            consecutiveFailures: 0,
+        });
+        // Re-sort by priority
+        this.providers.sort((a, b) => a.priority - b.priority);
+    }
+    removeProvider(id) {
+        this.providers = this.providers.filter(p => p.id !== id);
+        this.health.delete(id);
+    }
+    setAuditor(auditor) {
+        this.auditor = auditor;
+    }
+    getStatus() {
+        return this.providers.map(p => ({
+            id: p.id,
+            healthy: this.isAvailable(p.id),
+            active: true,
+            consecutiveFailures: this.health.get(p.id)?.consecutiveFailures ?? 0,
+            cooldownUntil: this.health.get(p.id)?.cooldownUntil,
+            model: p.modelOverride ?? p.client.model,
+        }));
+    }
+    // ========================================================================
+    // Execution with Failover
+    // ========================================================================
+    /**
+     * Execute a function against providers with automatic failover.
+     * Tries each available provider in priority order.
+     */
+    async execute(fn, context = 'execute') {
+        const available = this.getAvailableProviders();
+        if (available.length === 0) {
+            throw new Error('No available LLM providers. All providers are unhealthy or in cooldown.');
+        }
+        let lastError;
+        for (const provider of available) {
+            for (let attempt = 0; attempt <= this.config.retriesPerProvider; attempt++) {
+                try {
+                    if (attempt > 0) {
+                        this.auditor.record({
+                            timestamp: Date.now(),
+                            type: 'retry',
+                            provider: provider.id,
+                            model: provider.modelOverride ?? provider.client.model,
+                            metadata: { attempt, context },
+                        });
+                    }
+                    const result = await fn(provider.client);
+                    this.recordSuccess(provider.id);
+                    return result;
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    this.auditor.record({
+                        timestamp: Date.now(),
+                        type: 'error',
+                        provider: provider.id,
+                        model: provider.modelOverride ?? provider.client.model,
+                        error: lastError.message,
+                        metadata: { attempt, context },
+                    });
+                }
+            }
+            // All retries exhausted for this provider
+            this.recordFailure(provider.id);
+            // Try next provider (failover)
+            const nextProvider = this.getNextAvailableAfter(provider.id);
+            if (nextProvider) {
+                this.auditor.record({
+                    timestamp: Date.now(),
+                    type: 'failover',
+                    provider: provider.id,
+                    metadata: {
+                        from: provider.id,
+                        nextProvider: nextProvider.id,
+                        context,
+                        reason: lastError?.message,
+                    },
+                });
+            }
+        }
+        throw lastError ?? new Error('All providers failed');
+    }
+    /**
+     * Execute a streaming function with failover.
+     * On failure, retries with the next provider from the beginning.
+     */
+    async *executeStream(fn, context = 'stream') {
+        const available = this.getAvailableProviders();
+        if (available.length === 0) {
+            throw new Error('No available LLM providers for streaming.');
+        }
+        let lastError;
+        for (const provider of available) {
+            try {
+                const stream = fn(provider.client);
+                let returnValue;
+                // We need to yield all values and capture the return
+                while (true) {
+                    const result = await stream.next();
+                    if (result.done) {
+                        returnValue = result.value;
+                        break;
+                    }
+                    yield result.value;
+                }
+                this.recordSuccess(provider.id);
+                return returnValue;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                this.recordFailure(provider.id);
+                this.auditor.record({
+                    timestamp: Date.now(),
+                    type: 'failover',
+                    provider: provider.id,
+                    error: lastError.message,
+                    metadata: { context },
+                });
+                // Continue to next provider
+            }
+        }
+        throw lastError ?? new Error('All providers failed for streaming');
+    }
+    // ========================================================================
+    // Convenience Methods
+    // ========================================================================
+    async chat(messages, options) {
+        return this.execute(client => client.chat(messages, options), 'chat');
+    }
+    async chatWithTools(messages, options) {
+        return this.execute(client => client.chatWithTools(messages, options), 'chatWithTools');
+    }
+    async *chatStream(messages, options) {
+        return yield* this.executeStream(client => client.chatStream(messages, options), 'chatStream');
+    }
+    async embed(text) {
+        return this.execute(client => client.embed(text), 'embed');
+    }
+    async embedArray(texts) {
+        return this.execute(client => client.embedArray(texts), 'embedArray');
+    }
+    async getModels() {
+        // Aggregate models from all providers
+        const allModels = [];
+        for (const provider of this.providers) {
+            try {
+                const models = await provider.client.getModels();
+                allModels.push(...models);
+            }
+            catch {
+                // Skip unavailable providers
+            }
+        }
+        return [...new Set(allModels)];
+    }
+    async getModelInfo() {
+        return this.execute(client => client.getModelInfo(), 'getModelInfo');
+    }
+    // ========================================================================
+    // Tool Registration (broadcast to all providers)
+    // ========================================================================
+    registerTool(name, description, parameters, handler) {
+        for (const provider of this.providers) {
+            provider.client.registerTool(name, description, parameters, handler);
+        }
+    }
+    registerTools(tools) {
+        for (const provider of this.providers) {
+            provider.client.registerTools(tools);
+        }
+    }
+    // ========================================================================
+    // Health Management
+    // ========================================================================
+    isAvailable(id) {
+        const h = this.health.get(id);
+        if (!h)
+            return false;
+        if (h.healthy)
+            return true;
+        // Check if cooldown has expired
+        if (h.cooldownUntil && Date.now() >= h.cooldownUntil) {
+            // Reset for re-testing
+            h.healthy = true;
+            h.consecutiveFailures = 0;
+            h.cooldownUntil = undefined;
+            return true;
+        }
+        return false;
+    }
+    getAvailableProviders() {
+        return this.providers.filter(p => this.isAvailable(p.id));
+    }
+    getNextAvailableAfter(currentId) {
+        const idx = this.providers.findIndex(p => p.id === currentId);
+        for (let i = idx + 1; i < this.providers.length; i++) {
+            if (this.isAvailable(this.providers[i].id)) {
+                return this.providers[i];
+            }
+        }
+        return undefined;
+    }
+    recordSuccess(id) {
+        const h = this.health.get(id);
+        if (h) {
+            h.healthy = true;
+            h.consecutiveFailures = 0;
+            h.cooldownUntil = undefined;
+        }
+    }
+    recordFailure(id) {
+        const h = this.health.get(id);
+        if (!h)
+            return;
+        h.consecutiveFailures++;
+        h.lastFailure = Date.now();
+        if (h.consecutiveFailures >= this.config.maxFailures) {
+            h.healthy = false;
+            h.cooldownUntil = Date.now() + this.config.cooldownMs;
+        }
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

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

package/dist/stream-decoder.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Universal LLM Client v3 — Stream Decoder
+ *
+ * Pluggable interface for decoding raw LLM token streams into typed events.
+ * Consumers select their strategy per-call: passthrough for raw speed,
+ * standard-chat for structured tool calls, or interleaved-reasoning
+ * for models that emit <think>/<progress> tags.
+ */
+import type { LLMToolCall } from './interfaces.js';
+/** Clean, typed events emitted by a stream decoder */
+export type DecodedEvent = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'thinking';
+    content: string;
+} | {
+    type: 'progress';
+    content: string;
+} | {
+    type: 'tool_call';
+    calls: LLMToolCall[];
+};
+/** Callback invoked by the decoder as events become available */
+export type DecoderCallback = (event: DecodedEvent) => void;
+/**
+ * Transform raw LLM tokens into clean typed events.
+ *
+ * Usage:
+ *   const decoder = createDecoder('standard-chat', callback);
+ *   for (const token of stream) decoder.push(token);
+ *   decoder.flush();
+ *   const clean = decoder.getCleanContent();
+ */
+export interface StreamDecoder {
+    /** Feed a raw token from the LLM stream */
+    push(token: string): void;
+    /** Signal end of stream — flush any buffered state */
+    flush(): void;
+    /** Get the accumulated clean text (all structural tags stripped) */
+    getCleanContent(): string;
+    /** Get accumulated reasoning/thinking content (if any) */
+    getReasoning(): string | undefined;
+}
+export type DecoderType = 'passthrough' | 'standard-chat' | 'interleaved-reasoning';
+/**
+ * Bare-bones decoder for raw text completions.
+ * No parsing, no tag awareness. All tokens → text events.
+ */
+export declare class PassthroughDecoder implements StreamDecoder {
+    private content;
+    private readonly callback;
+    constructor(callback: DecoderCallback);
+    push(token: string): void;
+    flush(): void;
+    getCleanContent(): string;
+    getReasoning(): string | undefined;
+}
+/**
+ * Decoder for standard LLM chat patterns — text streaming with native
+ * reasoning and structured API tool calls. No text-level tag parsing.
+ *
+ * Streamed tokens are clean text → emitted as `text` events.
+ * Native reasoning tokens → accepted via `pushReasoning()`.
+ * Structured tool calls → accepted via `pushToolCalls()`.
+ */
+export declare class StandardChatDecoder implements StreamDecoder {
+    private content;
+    private reasoning;
+    private readonly callback;
+    constructor(callback: DecoderCallback);
+    push(token: string): void;
+    /** Feed native reasoning tokens from the provider */
+    pushReasoning(content: string): void;
+    /** Feed structured tool calls from the provider API response */
+    pushToolCalls(calls: LLMToolCall[]): void;
+    flush(): void;
+    getCleanContent(): string;
+    getReasoning(): string | undefined;
+}
+/**
+ * Decoder for models that emit interleaved reasoning tags in text.
+ * Parses <think>...</think> and <progress>...</progress> tags from the
+ * raw token stream and emits typed events for each.
+ *
+ * Handles streaming where tags may be split across chunks.
+ */
+export declare class InterleavedReasoningDecoder implements StreamDecoder {
+    private buffer;
+    private content;
+    private reasoning;
+    private readonly callback;
+    private inThink;
+    private inProgress;
+    constructor(callback: DecoderCallback);
+    push(token: string): void;
+    flush(): void;
+    getCleanContent(): string;
+    getReasoning(): string | undefined;
+    private processBuffer;
+    private findEarliest;
+    private couldBePartialTag;
+}
+export interface DecoderOptions {
+    /** Known tool names for text-based tool call recovery */
+    knownToolNames?: Set<string>;
+}
+/**
+ * Create a stream decoder by type.
+ */
+export declare function createDecoder(type: DecoderType, callback: DecoderCallback, _options?: DecoderOptions): StreamDecoder;
+//# sourceMappingURL=stream-decoder.d.ts.map

package/dist/stream-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-decoder.d.ts","sourceRoot":"","sources":["../src/stream-decoder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC;AAElD,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAM5D;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,2CAA2C;IAC3C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,KAAK,IAAI,IAAI,CAAC;IACd,oEAAoE;IACpE,eAAe,IAAI,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,YAAY,IAAI,MAAM,GAAG,SAAS,CAAC;CACtC;AAMD,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,eAAe,GAAG,uBAAuB,CAAC;AAMpF;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACpD,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAE/B,QAAQ,EAAE,eAAe;IAIrC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzB,KAAK,IAAI,IAAI;IAIb,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM,GAAG,SAAS;CAGrC;AAMD;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAE/B,QAAQ,EAAE,eAAe;IAIrC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzB,qDAAqD;IACrD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKpC,gEAAgE;IAChE,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI;IAIzC,KAAK,IAAI,IAAI;IAIb,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM,GAAG,SAAS;CAGrC;AAMD;;;;;;GAMG;AACH,qBAAa,2BAA4B,YAAW,aAAa;IAC7D,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;gBAEf,QAAQ,EAAE,eAAe;IAIrC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzB,KAAK,IAAI,IAAI;IAgBb,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC,OAAO,CAAC,aAAa;IAyFrB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;CAM5B;AAMD,MAAM,WAAW,cAAc;IAC3B,yDAAyD;IACzD,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,cAAc,GAC1B,aAAa,CAWf"}