universal-llm-client 4.2.0 → 4.5.0

package/src/tests/thinking.test.ts

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

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