universal-llm-client 4.1.0 → 4.3.0

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/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';