universal-llm-client 3.0.0

package/dist/stream-decoder.js

@@ -0,0 +1,238 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// Passthrough Decoder
+// ============================================================================
+/**
+ * Bare-bones decoder for raw text completions.
+ * No parsing, no tag awareness. All tokens → text events.
+ */
+export class PassthroughDecoder {
+    content = '';
+    callback;
+    constructor(callback) {
+        this.callback = callback;
+    }
+    push(token) {
+        this.content += token;
+        this.callback({ type: 'text', content: token });
+    }
+    flush() {
+        // Nothing to flush — all tokens emitted immediately
+    }
+    getCleanContent() {
+        return this.content;
+    }
+    getReasoning() {
+        return undefined;
+    }
+}
+// ============================================================================
+// Standard Chat Decoder
+// ============================================================================
+/**
+ * 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 class StandardChatDecoder {
+    content = '';
+    reasoning = '';
+    callback;
+    constructor(callback) {
+        this.callback = callback;
+    }
+    push(token) {
+        this.content += token;
+        this.callback({ type: 'text', content: token });
+    }
+    /** Feed native reasoning tokens from the provider */
+    pushReasoning(content) {
+        this.reasoning += content;
+        this.callback({ type: 'thinking', content });
+    }
+    /** Feed structured tool calls from the provider API response */
+    pushToolCalls(calls) {
+        this.callback({ type: 'tool_call', calls });
+    }
+    flush() {
+        // Nothing to flush — all events emitted as they arrive
+    }
+    getCleanContent() {
+        return this.content;
+    }
+    getReasoning() {
+        return this.reasoning || undefined;
+    }
+}
+// ============================================================================
+// Interleaved Reasoning Decoder
+// ============================================================================
+/**
+ * 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 class InterleavedReasoningDecoder {
+    buffer = '';
+    content = '';
+    reasoning = '';
+    callback;
+    inThink = false;
+    inProgress = false;
+    constructor(callback) {
+        this.callback = callback;
+    }
+    push(token) {
+        this.buffer += token;
+        this.processBuffer();
+    }
+    flush() {
+        // Emit any remaining buffer content as text
+        if (this.buffer.length > 0) {
+            if (this.inThink) {
+                this.reasoning += this.buffer;
+                this.callback({ type: 'thinking', content: this.buffer });
+            }
+            else if (this.inProgress) {
+                this.callback({ type: 'progress', content: this.buffer });
+            }
+            else {
+                this.content += this.buffer;
+                this.callback({ type: 'text', content: this.buffer });
+            }
+            this.buffer = '';
+        }
+    }
+    getCleanContent() {
+        return this.content;
+    }
+    getReasoning() {
+        return this.reasoning || undefined;
+    }
+    processBuffer() {
+        let safety = 0;
+        while (this.buffer.length > 0 && safety++ < 200) {
+            if (this.inThink) {
+                const closeIdx = this.buffer.indexOf('</think>');
+                if (closeIdx === -1) {
+                    // Might have partial closing tag at end
+                    if (this.buffer.endsWith('<') || this.buffer.endsWith('</') ||
+                        this.buffer.endsWith('</t') || this.buffer.endsWith('</th') ||
+                        this.buffer.endsWith('</thi') || this.buffer.endsWith('</thin') ||
+                        this.buffer.endsWith('</think')) {
+                        return; // Wait for more data
+                    }
+                    this.reasoning += this.buffer;
+                    this.callback({ type: 'thinking', content: this.buffer });
+                    this.buffer = '';
+                    return;
+                }
+                const thinkContent = this.buffer.slice(0, closeIdx);
+                if (thinkContent) {
+                    this.reasoning += thinkContent;
+                    this.callback({ type: 'thinking', content: thinkContent });
+                }
+                this.buffer = this.buffer.slice(closeIdx + 8); // '</think>'.length
+                this.inThink = false;
+                continue;
+            }
+            if (this.inProgress) {
+                const closeIdx = this.buffer.indexOf('</progress>');
+                if (closeIdx === -1) {
+                    if (this.couldBePartialTag(this.buffer, '</progress>'))
+                        return;
+                    this.callback({ type: 'progress', content: this.buffer });
+                    this.buffer = '';
+                    return;
+                }
+                const progressContent = this.buffer.slice(0, closeIdx);
+                if (progressContent) {
+                    this.callback({ type: 'progress', content: progressContent });
+                }
+                this.buffer = this.buffer.slice(closeIdx + 11); // '</progress>'.length
+                this.inProgress = false;
+                continue;
+            }
+            // Look for opening tags
+            const thinkIdx = this.buffer.indexOf('<think>');
+            const progressIdx = this.buffer.indexOf('<progress>');
+            // Find earliest tag
+            const nextTag = this.findEarliest(thinkIdx, progressIdx);
+            if (nextTag === -1) {
+                // No complete opening tags — check for partial tag at end
+                const lastAngle = this.buffer.lastIndexOf('<');
+                if (lastAngle >= 0 && lastAngle > this.buffer.length - 12) {
+                    // Potential partial tag — emit text before it, keep the rest
+                    const textBefore = this.buffer.slice(0, lastAngle);
+                    if (textBefore) {
+                        this.content += textBefore;
+                        this.callback({ type: 'text', content: textBefore });
+                    }
+                    this.buffer = this.buffer.slice(lastAngle);
+                    return;
+                }
+                // No partial tags — emit all as text
+                this.content += this.buffer;
+                this.callback({ type: 'text', content: this.buffer });
+                this.buffer = '';
+                return;
+            }
+            // Emit text before the tag
+            const textBefore = this.buffer.slice(0, nextTag);
+            if (textBefore) {
+                this.content += textBefore;
+                this.callback({ type: 'text', content: textBefore });
+            }
+            if (nextTag === thinkIdx) {
+                this.buffer = this.buffer.slice(nextTag + 7); // '<think>'.length
+                this.inThink = true;
+            }
+            else {
+                this.buffer = this.buffer.slice(nextTag + 10); // '<progress>'.length
+                this.inProgress = true;
+            }
+        }
+    }
+    findEarliest(a, b) {
+        if (a === -1)
+            return b;
+        if (b === -1)
+            return a;
+        return Math.min(a, b);
+    }
+    couldBePartialTag(buffer, tag) {
+        for (let i = 1; i < tag.length; i++) {
+            if (buffer.endsWith(tag.slice(0, i)))
+                return true;
+        }
+        return false;
+    }
+}
+/**
+ * Create a stream decoder by type.
+ */
+export function createDecoder(type, callback, _options) {
+    switch (type) {
+        case 'passthrough':
+            return new PassthroughDecoder(callback);
+        case 'standard-chat':
+            return new StandardChatDecoder(callback);
+        case 'interleaved-reasoning':
+            return new InterleavedReasoningDecoder(callback);
+        default:
+            throw new Error(`Unknown decoder type: ${type}`);
+    }
+}
+//# sourceMappingURL=stream-decoder.js.map

package/dist/stream-decoder.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Universal LLM Client v3 — Tool Utilities
+ *
+ * ToolBuilder: Type-safe tool definition builder with fluent API.
+ * ToolExecutor: Execution wrappers with timeout and validation.
+ */
+import type { LLMFunction, LLMToolDefinition, ToolHandler } from './interfaces.js';
+/**
+ * Fluent builder for LLM tool definitions.
+ *
+ * Usage:
+ *   const tool = new ToolBuilder('get_weather')
+ *       .description('Get current weather for a location')
+ *       .addParameter('location', 'string', 'City name', true)
+ *       .addParameter('units', 'string', 'Temperature units', false, { enum: ['celsius', 'fahrenheit'] })
+ *       .build();
+ */
+export declare class ToolBuilder {
+    private name;
+    private desc;
+    private properties;
+    private required;
+    constructor(name: string);
+    description(desc: string): this;
+    addParameter(name: string, type: string, description: string, isRequired?: boolean, extra?: Record<string, unknown>): this;
+    build(): LLMToolDefinition;
+    /** Build and return the function definition only  */
+    buildFunction(): LLMFunction;
+}
+/**
+ * Utility wrappers for creating safe tool handlers.
+ */
+export declare class ToolExecutor {
+    /**
+     * Wrap a handler with a timeout.
+     * Rejects if the handler doesn't complete within the specified ms.
+     */
+    static withTimeout(handler: ToolHandler, timeoutMs: number): ToolHandler;
+    /**
+     * Wrap a handler to catch errors and return them as strings
+     * instead of throwing.
+     */
+    static safe(handler: ToolHandler): ToolHandler;
+    /**
+     * Wrap a handler with argument validation.
+     * Checks that required fields are present before execution.
+     */
+    static withValidation(handler: ToolHandler, requiredFields: string[]): ToolHandler;
+    /**
+     * Create a handler that measures execution time and
+     * returns both the result and duration.
+     */
+    static timed(handler: ToolHandler): ToolHandler;
+    /**
+     * Compose multiple wrappers around a handler.
+     * Applied from right to left (innermost to outermost).
+     */
+    static compose(handler: ToolHandler, ...wrappers: Array<(h: ToolHandler) => ToolHandler>): ToolHandler;
+}
+/**
+ * Create a get_current_time tool definition and handler.
+ */
+export declare function createTimeTool(): {
+    name: string;
+    description: string;
+    parameters: LLMFunction['parameters'];
+    handler: ToolHandler;
+};
+/**
+ * Create a random_number tool definition and handler.
+ */
+export declare function createRandomNumberTool(): {
+    name: string;
+    description: string;
+    parameters: LLMFunction['parameters'];
+    handler: ToolHandler;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnF;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,QAAQ,CAAgB;gBAEpB,IAAI,EAAE,MAAM;IAIxB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK/B,YAAY,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,OAAe,EAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAYP,KAAK,IAAI,iBAAiB;IAe1B,qDAAqD;IACrD,aAAa,IAAI,WAAW;CAG/B;AAMD;;GAEG;AACH,qBAAa,YAAY;IACrB;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW;IAYxE;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW;IAY9C;;;OAGG;IACH,MAAM,CAAC,cAAc,CACjB,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,MAAM,EAAE,GACzB,WAAW;IAed;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW;IAW/C;;;OAGG;IACH,MAAM,CAAC,OAAO,CACV,OAAO,EAAE,WAAW,EACpB,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC,GACpD,WAAW;CAGjB;AAMD;;GAEG;AACH,wBAAgB,cAAc,IAAI;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACtC,OAAO,EAAE,WAAW,CAAC;CACxB,CAqCA;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACtC,OAAO,EAAE,WAAW,CAAC;CACxB,CAoBA"}

package/dist/tools.js

@@ -0,0 +1,207 @@
+/**
+ * Universal LLM Client v3 — Tool Utilities
+ *
+ * ToolBuilder: Type-safe tool definition builder with fluent API.
+ * ToolExecutor: Execution wrappers with timeout and validation.
+ */
+// ============================================================================
+// ToolBuilder
+// ============================================================================
+/**
+ * Fluent builder for LLM tool definitions.
+ *
+ * Usage:
+ *   const tool = new ToolBuilder('get_weather')
+ *       .description('Get current weather for a location')
+ *       .addParameter('location', 'string', 'City name', true)
+ *       .addParameter('units', 'string', 'Temperature units', false, { enum: ['celsius', 'fahrenheit'] })
+ *       .build();
+ */
+export class ToolBuilder {
+    name;
+    desc = '';
+    properties = {};
+    required = [];
+    constructor(name) {
+        this.name = name;
+    }
+    description(desc) {
+        this.desc = desc;
+        return this;
+    }
+    addParameter(name, type, description, isRequired = false, extra) {
+        this.properties[name] = {
+            type,
+            description,
+            ...extra,
+        };
+        if (isRequired) {
+            this.required.push(name);
+        }
+        return this;
+    }
+    build() {
+        return {
+            type: 'function',
+            function: {
+                name: this.name,
+                description: this.desc,
+                parameters: {
+                    type: 'object',
+                    properties: this.properties,
+                    required: this.required.length > 0 ? this.required : undefined,
+                },
+            },
+        };
+    }
+    /** Build and return the function definition only  */
+    buildFunction() {
+        return this.build().function;
+    }
+}
+// ============================================================================
+// ToolExecutor
+// ============================================================================
+/**
+ * Utility wrappers for creating safe tool handlers.
+ */
+export class ToolExecutor {
+    /**
+     * Wrap a handler with a timeout.
+     * Rejects if the handler doesn't complete within the specified ms.
+     */
+    static withTimeout(handler, timeoutMs) {
+        return async (args) => {
+            const result = await Promise.race([
+                Promise.resolve(handler(args)),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Tool execution timeout after ${timeoutMs}ms`)), timeoutMs)),
+            ]);
+            return result;
+        };
+    }
+    /**
+     * Wrap a handler to catch errors and return them as strings
+     * instead of throwing.
+     */
+    static safe(handler) {
+        return async (args) => {
+            try {
+                return await handler(args);
+            }
+            catch (error) {
+                return {
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        };
+    }
+    /**
+     * Wrap a handler with argument validation.
+     * Checks that required fields are present before execution.
+     */
+    static withValidation(handler, requiredFields) {
+        return async (args) => {
+            if (!args || typeof args !== 'object') {
+                throw new Error('Tool arguments must be an object');
+            }
+            const obj = args;
+            for (const field of requiredFields) {
+                if (obj[field] === undefined || obj[field] === null) {
+                    throw new Error(`Missing required argument: ${field}`);
+                }
+            }
+            return handler(args);
+        };
+    }
+    /**
+     * Create a handler that measures execution time and
+     * returns both the result and duration.
+     */
+    static timed(handler) {
+        return async (args) => {
+            const start = Date.now();
+            const result = await handler(args);
+            return {
+                result,
+                duration: Date.now() - start,
+            };
+        };
+    }
+    /**
+     * Compose multiple wrappers around a handler.
+     * Applied from right to left (innermost to outermost).
+     */
+    static compose(handler, ...wrappers) {
+        return wrappers.reduceRight((h, wrapper) => wrapper(h), handler);
+    }
+}
+// ============================================================================
+// Common Tool Definitions
+// ============================================================================
+/**
+ * Create a get_current_time tool definition and handler.
+ */
+export function createTimeTool() {
+    return {
+        name: 'get_current_time',
+        description: 'Get the current date and time',
+        parameters: {
+            type: 'object',
+            properties: {
+                timezone: {
+                    type: 'string',
+                    description: 'IANA timezone (e.g. "America/New_York"). Defaults to UTC.',
+                },
+            },
+        },
+        handler: (args) => {
+            const { timezone } = (args ?? {});
+            const now = new Date();
+            try {
+                return {
+                    iso: now.toISOString(),
+                    formatted: now.toLocaleString('en-US', {
+                        timeZone: timezone || 'UTC',
+                        dateStyle: 'full',
+                        timeStyle: 'long',
+                    }),
+                    timezone: timezone || 'UTC',
+                    timestamp: now.getTime(),
+                };
+            }
+            catch {
+                return {
+                    iso: now.toISOString(),
+                    formatted: now.toUTCString(),
+                    timezone: 'UTC',
+                    timestamp: now.getTime(),
+                };
+            }
+        },
+    };
+}
+/**
+ * Create a random_number tool definition and handler.
+ */
+export function createRandomNumberTool() {
+    return {
+        name: 'random_number',
+        description: 'Generate a random number within a range',
+        parameters: {
+            type: 'object',
+            properties: {
+                min: { type: 'number', description: 'Minimum value (default 0)' },
+                max: { type: 'number', description: 'Maximum value (default 100)' },
+            },
+        },
+        handler: (args) => {
+            const { min = 0, max = 100 } = (args ?? {});
+            return {
+                value: Math.floor(Math.random() * (max - min + 1)) + min,
+                min,
+                max,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "universal-llm-client",
+  "version": "3.0.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"
+    }
+  },
+  "files": [
+    "dist",
+    "README.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"
+  },
+  "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"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.24.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/igorls/universal-llm-client.git"
+  }
+}