universal-llm-client 4.2.0 → 4.5.0

package/src/tools.ts

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