universal-llm-client 4.3.0 → 4.5.0

package/dist/thinking.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Unified thinking/reasoning resolution shared by all providers.
+ *
+ * Applications set a single `thinking` value — `true`/`false` or a level
+ * ('minimal' | 'low' | 'medium' | 'high') — at the model level and/or per call.
+ * Each provider maps the resolved intent to its native control (Gemini
+ * `thinkingLevel`/`thinkingBudget`, OpenAI `reasoning_effort`, vLLM
+ * `enable_thinking`, Anthropic `budget_tokens`, Ollama `think`).
+ */
+import type { ThinkingLevel } from './interfaces.js';
+export interface ResolvedThinking {
+    /** Whether reasoning should be enabled at all. */
+    enabled: boolean;
+    /** Explicit level when the user provided one (absent for a bare `true`). */
+    level?: ThinkingLevel;
+}
+/**
+ * Resolve the effective thinking intent from a per-call value (highest
+ * precedence) and the model-level config value. Returns `undefined` when
+ * neither is set, so providers omit the control entirely (and don't perturb
+ * servers that reject unknown fields).
+ */
+export declare function resolveThinking(perCall: boolean | ThinkingLevel | undefined, config: boolean | ThinkingLevel | undefined): ResolvedThinking | undefined;
+/** Heuristic: OpenAI reasoning models use `reasoning_effort` (o-series, GPT-5). */
+export declare function isOpenAIReasoningModel(model: string): boolean;
+/**
+ * Gemini 2.5 `thinkingBudget` for a level. 0 disables, -1 is dynamic, and the
+ * Flash range is 0–24576. A bare `true` (no level) maps to dynamic (-1).
+ */
+export declare function geminiThinkingBudget(level: ThinkingLevel | undefined): number;
+/**
+ * Anthropic extended-thinking `budget_tokens` for a level, kept >= 1024 (the
+ * API minimum) and < `maxTokens` (the API requires headroom for the answer).
+ */
+export declare function anthropicThinkingBudget(level: ThinkingLevel | undefined, maxTokens: number): number;
+//# sourceMappingURL=thinking.d.ts.map

package/dist/thinking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinking.d.ts","sourceRoot":"","sources":["../src/thinking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC7B,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,aAAa,CAAC;CACzB;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,OAAO,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,EAC5C,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,GAC5C,gBAAgB,GAAG,SAAS,CAO9B;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAQ7E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOnG"}

package/dist/thinking.js

@@ -0,0 +1,52 @@
+const LEVELS = ['minimal', 'low', 'medium', 'high'];
+function isLevel(v) {
+    return typeof v === 'string' && LEVELS.includes(v);
+}
+/**
+ * Resolve the effective thinking intent from a per-call value (highest
+ * precedence) and the model-level config value. Returns `undefined` when
+ * neither is set, so providers omit the control entirely (and don't perturb
+ * servers that reject unknown fields).
+ */
+export function resolveThinking(perCall, config) {
+    const value = perCall ?? config;
+    if (value === undefined)
+        return undefined;
+    if (value === false)
+        return { enabled: false };
+    if (value === true)
+        return { enabled: true };
+    if (isLevel(value))
+        return { enabled: true, level: value };
+    return undefined; // unknown string — ignore defensively
+}
+/** Heuristic: OpenAI reasoning models use `reasoning_effort` (o-series, GPT-5). */
+export function isOpenAIReasoningModel(model) {
+    return /^(o\d|gpt-5)/i.test(model);
+}
+/**
+ * Gemini 2.5 `thinkingBudget` for a level. 0 disables, -1 is dynamic, and the
+ * Flash range is 0–24576. A bare `true` (no level) maps to dynamic (-1).
+ */
+export function geminiThinkingBudget(level) {
+    switch (level) {
+        case 'minimal': return 512;
+        case 'low': return 2048;
+        case 'medium': return 8192;
+        case 'high': return 24576;
+        default: return -1; // enabled without an explicit level → dynamic
+    }
+}
+/**
+ * Anthropic extended-thinking `budget_tokens` for a level, kept >= 1024 (the
+ * API minimum) and < `maxTokens` (the API requires headroom for the answer).
+ */
+export function anthropicThinkingBudget(level, maxTokens) {
+    const base = level === 'high' ? 16384
+        : level === 'medium' ? 4096
+            : level === 'low' ? 1024
+                : level === 'minimal' ? 1024
+                    : 2048; // bare `true`
+    return Math.max(1024, Math.min(base, maxTokens - 1024));
+}
+//# sourceMappingURL=thinking.js.map

package/dist/thinking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinking.js","sourceRoot":"","sources":["../src/thinking.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,GAAsB,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEvE,SAAS,OAAO,CAAC,CAAU;IACvB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC3B,OAA4C,EAC5C,MAA2C;IAE3C,MAAM,KAAK,GAAG,OAAO,IAAI,MAAM,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC/C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC3D,OAAO,SAAS,CAAC,CAAC,sCAAsC;AAC5D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAChD,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACjE,QAAQ,KAAK,EAAE,CAAC;QACZ,KAAK,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC;QAC3B,KAAK,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC;QACxB,KAAK,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC;QAC3B,KAAK,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC;QAC1B,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,8CAA8C;IACtE,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAgC,EAAE,SAAiB;IACvF,MAAM,IAAI,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK;QACjC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI;YAC3B,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI;gBACxB,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI;oBAC5B,CAAC,CAAC,IAAI,CAAC,CAAC,cAAc;IAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/tools.js.map

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

package/dist/zod-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod-adapter.js","sourceRoot":"","sources":["../src/zod-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,OAAO,CACnB,MAAoB,EACpB,OAAiD;IAEjD,gEAAgE;IAChE,MAAM,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QACzC,MAAM,EAAE,UAAU;QAClB,eAAe,EAAE,KAAK;KACzB,CAAC,CAAC;IAEH,0DAA0D;IAC1D,MAAM,UAAU,GAAG,EAAE,GAAG,aAAa,EAA6B,CAAC;IACnE,OAAO,UAAU,CAAC,OAAO,CAAC;IAE1B,OAAO;QACH,UAAU,EAAE,UAAyD;QACrE,QAAQ,EAAE,CAAC,IAAa,EAAK,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClB,MAAM,MAAM,CAAC,KAAK,CAAC;YACvB,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;AACN,CAAC;AAED,yEAAyE;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC","sourcesContent":["/**\r\n * Zod Adapter for Universal LLM Client\r\n *\r\n * Optional entrypoint for projects that use Zod for schema validation.\r\n * Import from 'universal-llm-client/zod' to use.\r\n *\r\n * @module universal-llm-client/zod\r\n */\r\n\r\nimport { z } from 'zod';\r\nimport type { SchemaConfig } from './structured-output.js';\r\n\r\n/**\r\n * Create a SchemaConfig from a Zod schema.\r\n *\r\n * This bridges Zod's type-safe schema definitions to the library's\r\n * generic SchemaConfig interface, using Zod 4's native `z.toJSONSchema()`.\r\n *\r\n * @template T The type inferred from the Zod schema\r\n * @param schema The Zod schema\r\n * @param options Optional name and description for LLM guidance\r\n * @returns SchemaConfig ready for use with generateStructured, etc.\r\n *\r\n * @example\r\n * ```typescript\r\n * import { fromZod } from 'universal-llm-client/zod';\r\n * import { z } from 'zod';\r\n *\r\n * const UserSchema = z.object({\r\n *   name: z.string(),\r\n *   age: z.number(),\r\n * });\r\n *\r\n * const config = fromZod(UserSchema, { name: 'User' });\r\n *\r\n * const user = await model.generateStructured(config, messages);\r\n * // user.name: string, user.age: number (fully typed)\r\n * ```\r\n */\r\nexport function fromZod<T>(\r\n    schema: z.ZodType<T>,\r\n    options?: { name?: string; description?: string },\r\n): SchemaConfig<T> {\r\n    // Convert Zod schema to JSON Schema using Zod 4's native method\r\n    const rawJsonSchema = z.toJSONSchema(schema, {\r\n        target: 'draft-07',\r\n        unrepresentable: 'any',\r\n    });\r\n\r\n    // Clean up — remove $schema since providers don't need it\r\n    const jsonSchema = { ...rawJsonSchema } as Record<string, unknown>;\r\n    delete jsonSchema.$schema;\r\n\r\n    return {\r\n        jsonSchema: jsonSchema as import('./structured-output.js').JSONSchema,\r\n        validate: (data: unknown): T => {\r\n            const result = schema.safeParse(data);\r\n            if (!result.success) {\r\n                throw result.error;\r\n            }\r\n            return result.data;\r\n        },\r\n        name: options?.name,\r\n        description: options?.description,\r\n    };\r\n}\r\n\r\n// Re-export z for convenience (users importing from /zod likely want it)\r\nexport { z } from 'zod';\r\n\r\n// Re-export SchemaConfig for type usage\r\nexport type { SchemaConfig } from './structured-output.js';\r\n"]}
+{"version":3,"file":"zod-adapter.js","sourceRoot":"","sources":["../src/zod-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,OAAO,CACnB,MAAoB,EACpB,OAAiD;IAEjD,gEAAgE;IAChE,MAAM,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QACzC,MAAM,EAAE,UAAU;QAClB,eAAe,EAAE,KAAK;KACzB,CAAC,CAAC;IAEH,0DAA0D;IAC1D,MAAM,UAAU,GAAG,EAAE,GAAG,aAAa,EAA6B,CAAC;IACnE,OAAO,UAAU,CAAC,OAAO,CAAC;IAE1B,OAAO;QACH,UAAU,EAAE,UAAyD;QACrE,QAAQ,EAAE,CAAC,IAAa,EAAK,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClB,MAAM,MAAM,CAAC,KAAK,CAAC;YACvB,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;AACN,CAAC;AAED,yEAAyE;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-llm-client",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "type": "module",
   "description": "A universal LLM client with transparent provider failover, streaming tool execution, pluggable reasoning, and native observability.",
   "main": "./dist/index.js",
@@ -41,6 +41,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -54,6 +55,8 @@
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit --strict",
+    "demo:diffusion-gemma": "bun run src/demos/diffusion-gemma/server.ts",
+    "demo:diffusion-gemma:engine": "docker compose -f src/demos/diffusion-gemma/docker-compose.yml up -d",
     "prepack": "bun run build",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",

package/src/ai-model.ts

@@ -0,0 +1,400 @@
+/**
+ * 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,
+    type DeepResearchOptions,
+    type DeepResearchResult,
+    type DeepResearchEvent,
+} 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);
+    }
+
+    // ========================================================================
+    // Deep Research (Gemini-only)
+    // ========================================================================
+
+    private getGoogleClient(method: string): GoogleClient {
+        const googleClients = this.router.getClients().filter(
+            (c): c is GoogleClient => c instanceof GoogleClient,
+        );
+        // Prefer an AI Studio client — Vertex AI doesn't support Deep Research.
+        const aiStudio = googleClients.find(c => c.supportsDeepResearch());
+        if (aiStudio) return aiStudio;
+        if (googleClients.length > 0) {
+            throw new Error(
+                `${method} requires an AI Studio Google provider (type: "google"); Vertex AI is not supported for Deep Research.`,
+            );
+        }
+        throw new Error(
+            `${method} requires a Google provider (type: "google"). None is configured.`,
+        );
+    }
+
+    /**
+     * Run an agentic Deep Research interaction (Gemini only): creates it and
+     * polls until completion. Throws if no Google provider is configured.
+     */
+    async deepResearch(input: string, options?: DeepResearchOptions): Promise<DeepResearchResult> {
+        return this.getGoogleClient('deepResearch').deepResearch(input, options);
+    }
+
+    /**
+     * Stream a Deep Research interaction's intermediate thought/text/step events
+     * (Gemini only), returning the final result. Throws if no Google provider.
+     */
+    async *deepResearchStream(
+        input: string,
+        options?: DeepResearchOptions,
+    ): AsyncGenerator<DeepResearchEvent, DeepResearchResult, unknown> {
+        return yield* this.getGoogleClient('deepResearchStream').deepResearchStream(input, options);
+    }
+
+    // ========================================================================
+    // 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,
+            // Preserve `undefined` (not set) vs explicit false so providers can
+            // decide whether to send a thinking toggle at all.
+            thinking: this.config.thinking,
+            region: providerConfig.region,
+            apiVersion: providerConfig.apiVersion,
+            extraHeaders: providerConfig.headers,
+            queryParams: providerConfig.queryParams,
+            authHeader: providerConfig.authHeader,
+            authPrefix: providerConfig.authPrefix,
+            apiBasePath: providerConfig.apiBasePath,
+        };
+
+        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();
+    }
+}