universal-llm-client 4.5.0 → 4.5.1

package/src/tests/thinking.test.ts

@@ -1,65 +0,0 @@
-/**
- * Unit tests for the unified thinking resolver and per-provider budget maps.
- */
-import { describe, test, expect } from 'bun:test';
-import {
-    resolveThinking,
-    isOpenAIReasoningModel,
-    geminiThinkingBudget,
-    anthropicThinkingBudget,
-} from '../thinking.js';
-
-describe('resolveThinking', () => {
-    test('returns undefined when neither per-call nor config is set', () => {
-        expect(resolveThinking(undefined, undefined)).toBeUndefined();
-    });
-
-    test('boolean true/false map to enabled', () => {
-        expect(resolveThinking(undefined, true)).toEqual({ enabled: true });
-        expect(resolveThinking(undefined, false)).toEqual({ enabled: false });
-    });
-
-    test('a level enables thinking and carries the level', () => {
-        expect(resolveThinking('high', undefined)).toEqual({ enabled: true, level: 'high' });
-        expect(resolveThinking(undefined, 'low')).toEqual({ enabled: true, level: 'low' });
-    });
-
-    test('per-call overrides config', () => {
-        expect(resolveThinking(false, true)).toEqual({ enabled: false });
-        expect(resolveThinking('medium', false)).toEqual({ enabled: true, level: 'medium' });
-    });
-
-    test('ignores unknown strings defensively', () => {
-        expect(resolveThinking('ultra' as never, undefined)).toBeUndefined();
-    });
-});
-
-describe('isOpenAIReasoningModel', () => {
-    test('matches o-series and gpt-5 families', () => {
-        for (const m of ['o1', 'o3', 'o4-mini', 'gpt-5', 'gpt-5-mini', 'GPT-5']) {
-            expect(isOpenAIReasoningModel(m)).toBe(true);
-        }
-    });
-    test('does not match chat / vLLM model names', () => {
-        for (const m of ['gpt-4o', 'qwen3.6-nvfp4', 'gemini-3.5-flash', 'claude-sonnet-4-5']) {
-            expect(isOpenAIReasoningModel(m)).toBe(false);
-        }
-    });
-});
-
-describe('budget maps', () => {
-    test('gemini 2.5 budget by level (0/-1 semantics)', () => {
-        expect(geminiThinkingBudget('minimal')).toBe(512);
-        expect(geminiThinkingBudget('low')).toBe(2048);
-        expect(geminiThinkingBudget('medium')).toBe(8192);
-        expect(geminiThinkingBudget('high')).toBe(24576);
-        expect(geminiThinkingBudget(undefined)).toBe(-1); // dynamic
-    });
-
-    test('anthropic budget stays >= 1024 and < max_tokens', () => {
-        expect(anthropicThinkingBudget('high', 32000)).toBe(16384);
-        expect(anthropicThinkingBudget('high', 4096)).toBe(3072); // clamped to max-1024
-        expect(anthropicThinkingBudget(undefined, 4096)).toBe(2048); // bare true
-        expect(anthropicThinkingBudget('low', 4096)).toBe(1024);
-    });
-});

package/src/tests/tools.test.ts

@@ -1,175 +0,0 @@
-/**
- * Tests for tools.ts — ToolBuilder and ToolExecutor
- */
-import { describe, it, expect } from 'bun:test';
-import { ToolBuilder, ToolExecutor, createTimeTool, createRandomNumberTool } from '../tools.js';
-
-describe('ToolBuilder', () => {
-    it('builds a basic tool definition', () => {
-        const tool = new ToolBuilder('test_tool')
-            .description('A test tool')
-            .build();
-
-        expect(tool.type).toBe('function');
-        expect(tool.function.name).toBe('test_tool');
-        expect(tool.function.description).toBe('A test tool');
-        expect(tool.function.parameters.type).toBe('object');
-    });
-
-    it('adds required parameters', () => {
-        const tool = new ToolBuilder('search')
-            .description('Search')
-            .addParameter('query', 'string', 'Search query', true)
-            .build();
-
-        expect(tool.function.parameters.properties).toHaveProperty('query');
-        expect(tool.function.parameters.required).toEqual(['query']);
-    });
-
-    it('adds optional parameters', () => {
-        const tool = new ToolBuilder('search')
-            .description('Search')
-            .addParameter('query', 'string', 'Search query', true)
-            .addParameter('limit', 'number', 'Max results', false)
-            .build();
-
-        expect(tool.function.parameters.properties).toHaveProperty('limit');
-        expect(tool.function.parameters.required).toEqual(['query']);
-    });
-
-    it('adds parameters with extra schema properties', () => {
-        const tool = new ToolBuilder('config')
-            .description('Configure')
-            .addParameter('theme', 'string', 'Color theme', false, {
-                enum: ['light', 'dark'],
-            })
-            .build();
-
-        const themeParam = (tool.function.parameters.properties as Record<string, Record<string, unknown>>)?.['theme'];
-        expect(themeParam?.enum).toEqual(['light', 'dark']);
-    });
-
-    it('builds function definition only', () => {
-        const fn = new ToolBuilder('test')
-            .description('Test')
-            .buildFunction();
-
-        expect(fn.name).toBe('test');
-        expect(fn.description).toBe('Test');
-    });
-});
-
-describe('ToolExecutor', () => {
-    describe('withTimeout', () => {
-        it('resolves if handler completes in time', async () => {
-            const handler = async () => 'result';
-            const wrapped = ToolExecutor.withTimeout(handler, 1000);
-            expect(await wrapped({})).toBe('result');
-        });
-
-        it('rejects if handler exceeds timeout', async () => {
-            const handler = async () => {
-                await new Promise(r => setTimeout(r, 500));
-                return 'too late';
-            };
-            const wrapped = ToolExecutor.withTimeout(handler, 50);
-            expect(wrapped({})).rejects.toThrow('timeout');
-        });
-    });
-
-    describe('safe', () => {
-        it('returns result on success', async () => {
-            const handler = async () => 42;
-            const wrapped = ToolExecutor.safe(handler);
-            expect(await wrapped({})).toBe(42);
-        });
-
-        it('catches errors and returns error object', async () => {
-            const handler = async () => { throw new Error('boom'); };
-            const wrapped = ToolExecutor.safe(handler);
-            const result = await wrapped({}) as { error: string };
-            expect(result.error).toBe('boom');
-        });
-    });
-
-    describe('withValidation', () => {
-        it('passes through if all required fields present', async () => {
-            const handler = async (args: unknown) => args;
-            const wrapped = ToolExecutor.withValidation(handler, ['name']);
-            expect(await wrapped({ name: 'test' })).toEqual({ name: 'test' });
-        });
-
-        it('throws if required field is missing', async () => {
-            const handler = async () => 'ok';
-            const wrapped = ToolExecutor.withValidation(handler, ['name']);
-            expect(wrapped({ other: 'value' })).rejects.toThrow('Missing required argument: name');
-        });
-
-        it('throws if args is not an object', async () => {
-            const handler = async () => 'ok';
-            const wrapped = ToolExecutor.withValidation(handler, ['name']);
-            expect(wrapped(null)).rejects.toThrow('must be an object');
-        });
-    });
-
-    describe('timed', () => {
-        it('returns result with duration', async () => {
-            const handler = async () => 'hello';
-            const wrapped = ToolExecutor.timed(handler);
-            const result = await wrapped({}) as { result: string; duration: number };
-            expect(result.result).toBe('hello');
-            expect(result.duration).toBeGreaterThanOrEqual(0);
-        });
-    });
-
-    describe('compose', () => {
-        it('composes multiple wrappers', async () => {
-            const handler = async () => 'result';
-            const composed = ToolExecutor.compose(
-                handler,
-                h => ToolExecutor.safe(h),
-                h => ToolExecutor.withTimeout(h, 5000),
-            );
-            expect(await composed({})).toBe('result');
-        });
-    });
-});
-
-describe('Common Tools', () => {
-    describe('createTimeTool', () => {
-        it('returns a valid tool definition', () => {
-            const tool = createTimeTool();
-            expect(tool.name).toBe('get_current_time');
-            expect(tool.description).toBeTruthy();
-            expect(tool.parameters.type).toBe('object');
-        });
-
-        it('handler returns time info', async () => {
-            const tool = createTimeTool();
-            const result = await tool.handler({}) as { iso: string; timestamp: number };
-            expect(result.iso).toBeTruthy();
-            expect(result.timestamp).toBeGreaterThan(0);
-        });
-
-        it('handler respects timezone parameter', async () => {
-            const tool = createTimeTool();
-            const result = await tool.handler({ timezone: 'America/New_York' }) as { timezone: string };
-            expect(result.timezone).toBe('America/New_York');
-        });
-    });
-
-    describe('createRandomNumberTool', () => {
-        it('returns a valid tool definition', () => {
-            const tool = createRandomNumberTool();
-            expect(tool.name).toBe('random_number');
-            expect(tool.description).toBeTruthy();
-        });
-
-        it('handler returns number in range', async () => {
-            const tool = createRandomNumberTool();
-            const result = await tool.handler({ min: 1, max: 10 }) as { value: number };
-            expect(result.value).toBeGreaterThanOrEqual(1);
-            expect(result.value).toBeLessThanOrEqual(10);
-        });
-    });
-});

package/src/thinking.ts

@@ -1,73 +0,0 @@
-/**
- * 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;
-}
-
-const LEVELS: readonly string[] = ['minimal', 'low', 'medium', 'high'];
-
-function isLevel(v: unknown): v is ThinkingLevel {
-    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: boolean | ThinkingLevel | undefined,
-    config: boolean | ThinkingLevel | undefined,
-): ResolvedThinking | undefined {
-    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: string): boolean {
-    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: ThinkingLevel | undefined): number {
-    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: ThinkingLevel | undefined, maxTokens: number): number {
-    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));
-}

package/src/tools.ts

@@ -1,246 +0,0 @@
-/**
- * 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';
-
-// ============================================================================
-// 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 {
-    private name: string;
-    private desc: string = '';
-    private properties: Record<string, unknown> = {};
-    private required: string[] = [];
-
-    constructor(name: string) {
-        this.name = name;
-    }
-
-    description(desc: string): this {
-        this.desc = desc;
-        return this;
-    }
-
-    addParameter(
-        name: string,
-        type: string,
-        description: string,
-        isRequired: boolean = false,
-        extra?: Record<string, unknown>,
-    ): this {
-        this.properties[name] = {
-            type,
-            description,
-            ...extra,
-        };
-        if (isRequired) {
-            this.required.push(name);
-        }
-        return this;
-    }
-
-    build(): LLMToolDefinition {
-        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(): LLMFunction {
-        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: ToolHandler, timeoutMs: number): ToolHandler {
-        return async (args: unknown) => {
-            const result = await Promise.race([
-                Promise.resolve(handler(args)),
-                new Promise<never>((_, 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: ToolHandler): ToolHandler {
-        return async (args: unknown) => {
-            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: ToolHandler,
-        requiredFields: string[],
-    ): ToolHandler {
-        return async (args: unknown) => {
-            if (!args || typeof args !== 'object') {
-                throw new Error('Tool arguments must be an object');
-            }
-            const obj = args as Record<string, unknown>;
-            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: ToolHandler): ToolHandler {
-        return async (args: unknown) => {
-            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: ToolHandler,
-        ...wrappers: Array<(h: ToolHandler) => ToolHandler>
-    ): ToolHandler {
-        return wrappers.reduceRight((h, wrapper) => wrapper(h), handler);
-    }
-}
-
-// ============================================================================
-// Common Tool Definitions
-// ============================================================================
-
-/**
- * Create a get_current_time tool definition and handler.
- */
-export function createTimeTool(): {
-    name: string;
-    description: string;
-    parameters: LLMFunction['parameters'];
-    handler: ToolHandler;
-} {
-    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: unknown) => {
-            const { timezone } = (args ?? {}) as { timezone?: string };
-            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(): {
-    name: string;
-    description: string;
-    parameters: LLMFunction['parameters'];
-    handler: ToolHandler;
-} {
-    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: unknown) => {
-            const { min = 0, max = 100 } = (args ?? {}) as { min?: number; max?: number };
-            return {
-                value: Math.floor(Math.random() * (max - min + 1)) + min,
-                min,
-                max,
-            };
-        },
-    };
-}

package/src/zod-adapter.ts

@@ -1,72 +0,0 @@
-/**
- * Zod Adapter for Universal LLM Client
- *
- * Optional entrypoint for projects that use Zod for schema validation.
- * Import from 'universal-llm-client/zod' to use.
- *
- * @module universal-llm-client/zod
- */
-
-import { z } from 'zod';
-import type { SchemaConfig } from './structured-output.js';
-
-/**
- * Create a SchemaConfig from a Zod schema.
- *
- * This bridges Zod's type-safe schema definitions to the library's
- * generic SchemaConfig interface, using Zod 4's native `z.toJSONSchema()`.
- *
- * @template T The type inferred from the Zod schema
- * @param schema The Zod schema
- * @param options Optional name and description for LLM guidance
- * @returns SchemaConfig ready for use with generateStructured, etc.
- *
- * @example
- * ```typescript
- * import { fromZod } from 'universal-llm-client/zod';
- * import { z } from 'zod';
- *
- * const UserSchema = z.object({
- *   name: z.string(),
- *   age: z.number(),
- * });
- *
- * const config = fromZod(UserSchema, { name: 'User' });
- *
- * const user = await model.generateStructured(config, messages);
- * // user.name: string, user.age: number (fully typed)
- * ```
- */
-export function fromZod<T>(
-    schema: z.ZodType<T>,
-    options?: { name?: string; description?: string },
-): SchemaConfig<T> {
-    // Convert Zod schema to JSON Schema using Zod 4's native method
-    const rawJsonSchema = z.toJSONSchema(schema, {
-        target: 'draft-07',
-        unrepresentable: 'any',
-    });
-
-    // Clean up — remove $schema since providers don't need it
-    const jsonSchema = { ...rawJsonSchema } as Record<string, unknown>;
-    delete jsonSchema.$schema;
-
-    return {
-        jsonSchema: jsonSchema as import('./structured-output.js').JSONSchema,
-        validate: (data: unknown): T => {
-            const result = schema.safeParse(data);
-            if (!result.success) {
-                throw result.error;
-            }
-            return result.data;
-        },
-        name: options?.name,
-        description: options?.description,
-    };
-}
-
-// Re-export z for convenience (users importing from /zod likely want it)
-export { z } from 'zod';
-
-// Re-export SchemaConfig for type usage
-export type { SchemaConfig } from './structured-output.js';