universal-llm-client 4.0.0 → 4.2.0

package/src/tests/tools.test.ts

@@ -0,0 +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);
+        });
+    });
+});

package/src/tools.ts

@@ -0,0 +1,246 @@
+/**
+ * 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

@@ -0,0 +1,72 @@
+/**
+ * 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';