llmz 0.0.13 → 0.0.14

package/dist/tool.d.ts

@@ -1,17 +1,194 @@
 import { TypeOf } from '@bpinternal/zui';
 import { JSONSchema7 } from 'json-schema';
 import { ZuiType } from './types.js';
+/**
+ * Input parameters passed to tool retry functions.
+ *
+ * @template I - The input type for the tool
+ */
 type ToolRetryInput<I> = {
+    /** The original input that was passed to the tool */
     input: I;
+    /** The current attempt number (starting from 1) */
     attempt: number;
+    /** The error that caused the retry, if any */
     error?: unknown;
 };
+/**
+ * Function signature for custom tool retry logic.
+ *
+ * Retry functions receive information about the failed attempt and return a boolean
+ * indicating whether the tool should be retried. This allows for sophisticated
+ * retry strategies based on error types, attempt counts, or other factors.
+ *
+ * @template I - The input type for the tool
+ *
+ * @example
+ * ```typescript
+ * const retryLogic: ToolRetryFn<{ url: string }> = ({ attempt, error }) => {
+ *   // Retry up to 3 times for network errors, but not for auth errors
+ *   if (attempt >= 3) return false
+ *   if (error?.message?.includes('401') || error?.message?.includes('403')) return false
+ *   return error?.message?.includes('network') || error?.message?.includes('timeout')
+ * }
+ * ```
+ */
 export type ToolRetryFn<I> = (args: ToolRetryInput<I>) => boolean | Promise<boolean>;
+/** @internal Utility type to check if T is an object (but not a function) */
 type IsObject<T> = T extends object ? (T extends Function ? false : true) : false;
+/** @internal Utility type that makes object types partial, but leaves primitives unchanged */
 type SmartPartial<T> = IsObject<T> extends true ? Partial<T> : T;
+/**
+ * Context information passed to tool handlers during execution.
+ *
+ * This context provides metadata about the tool call, which can be useful
+ * for logging, debugging, or implementing features like call tracking.
+ */
 type ToolCallContext = {
+    /** Unique identifier for this specific tool call */
     callId: string;
 };
+/**
+ * Tool represents a callable function that agents can use to interact with external systems.
+ *
+ * Tools are the core building blocks of LLMz agents, providing type-safe interfaces between
+ * the generated TypeScript code and external APIs, databases, file systems, or any other
+ * service your agent needs to interact with.
+ *
+ * ## Key Features
+ * - **Type Safety**: Full TypeScript inference with Zui/Zod schema validation
+ * - **Input/Output Validation**: Automatic validation of inputs and outputs against schemas
+ * - **Retry Logic**: Built-in retry mechanisms with custom retry functions
+ * - **Static Values**: Pre-configure parameters that won't change between calls
+ * - **Tool Cloning**: Create variations of existing tools with modified behavior
+ * - **TypeScript Generation**: Generate type definitions for LLM context
+ * - **Error Handling**: Comprehensive error handling with detailed validation messages
+ *
+ * ## Basic Usage
+ *
+ * ### Simple Tool
+ * ```typescript
+ * const weatherTool = new Tool({
+ *   name: 'getCurrentWeather',
+ *   description: 'Gets current weather conditions for a city',
+ *   input: z.object({
+ *     city: z.string().describe('City name'),
+ *     units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+ *   }),
+ *   output: z.object({
+ *     temperature: z.number(),
+ *     condition: z.string(),
+ *     humidity: z.number(),
+ *   }),
+ *   async handler({ city, units }) {
+ *     const response = await fetch(`/api/weather?city=${city}&units=${units}`)
+ *     return response.json()
+ *   },
+ * })
+ * ```
+ *
+ * ### Using Tools in Execute
+ * ```typescript
+ * const result = await execute({
+ *   instructions: 'Get the weather for San Francisco and recommend clothing',
+ *   tools: [weatherTool],
+ *   client,
+ * })
+ * ```
+ *
+ * ## Advanced Patterns
+ *
+ * ### Static Input Values
+ * Pre-configure parameters that shouldn't change:
+ * ```typescript
+ * const restrictedWeatherTool = weatherTool.setStaticInputValues({
+ *   units: 'celsius' // Always use celsius, agent can't override
+ * })
+ * ```
+ *
+ * ### Retry Logic
+ * Add resilience with custom retry logic:
+ * ```typescript
+ * const resilientTool = new Tool({
+ *   name: 'apiCall',
+ *   // ... other properties
+ *   async handler({ endpoint }) {
+ *     const response = await fetch(endpoint)
+ *     if (!response.ok) throw new Error(`API error: ${response.status}`)
+ *     return response.json()
+ *   },
+ *   retry: ({ attempt, error }) => {
+ *     // Retry up to 3 times for network errors, but not auth errors
+ *     if (attempt >= 3) return false
+ *     if (error.message.includes('401') || error.message.includes('403')) return false
+ *     return true
+ *   },
+ * })
+ * ```
+ *
+ * ### Tool Cloning
+ * Create variations of existing tools:
+ * ```typescript
+ * const enhancedWeatherTool = weatherTool.clone({
+ *   name: 'getEnhancedWeather',
+ *   description: 'Gets weather with additional forecasting',
+ *   output: (original) => original!.extend({
+ *     forecast: z.array(z.object({
+ *       day: z.string(),
+ *       temperature: z.number(),
+ *       condition: z.string(),
+ *     })),
+ *   }),
+ *   async handler(input) {
+ *     const basicWeather = await weatherTool.execute(input, ctx)
+ *     const forecast = await getForecast(input.city)
+ *     return { ...basicWeather, forecast }
+ *   },
+ * })
+ * ```
+ *
+ * ## Schema Design Best Practices
+ *
+ * ### Rich Descriptions
+ * Use detailed descriptions to help the LLM understand when and how to use tools:
+ * ```typescript
+ * input: z.object({
+ *   query: z.string()
+ *     .min(1)
+ *     .max(500)
+ *     .describe('Search query - be specific and include relevant keywords'),
+ *   maxResults: z.number()
+ *     .min(1)
+ *     .max(50)
+ *     .default(10)
+ *     .describe('Maximum number of results to return (1-50, default: 10)'),
+ *   includeSnippets: z.boolean()
+ *     .default(true)
+ *     .describe('Whether to include content snippets in results'),
+ * })
+ * ```
+ *
+ * ### Enums for Controlled Values
+ * Use enums to restrict inputs to valid options:
+ * ```typescript
+ * input: z.object({
+ *   operation: z.enum(['create', 'read', 'update', 'delete'])
+ *     .describe('CRUD operation to perform'),
+ *   format: z.enum(['json', 'csv', 'xml'])
+ *     .default('json')
+ *     .describe('Output format for the response'),
+ * })
+ * ```
+ *
+ * ## Error Handling
+ *
+ * Tools automatically handle:
+ * - **Input validation**: Invalid inputs throw descriptive errors
+ * - **Output validation**: Outputs are validated but invalid outputs are still returned
+ * - **Handler errors**: Exceptions in handlers are caught and can trigger retries
+ * - **Type coercion**: Basic type coercion where possible
+ *
+ */
 export declare class Tool<I extends ZuiType = ZuiType, O extends ZuiType = ZuiType> {
     private _staticInputValues?;
     name: string;
@@ -22,10 +199,136 @@ export declare class Tool<I extends ZuiType = ZuiType, O extends ZuiType = ZuiTy
     output?: JSONSchema7;
     retry?: ToolRetryFn<TypeOf<I>>;
     MAX_RETRIES: number;
+    /**
+     * Sets static input values that will be automatically applied to all tool calls.
+     *
+     * Static values allow you to pre-configure certain parameters that shouldn't change
+     * between calls, effectively removing them from the LLM's control while ensuring
+     * they're always present when the tool executes.
+     *
+     * @param values - Partial input values to apply statically. Set to null/undefined to clear.
+     * @returns The tool instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Create a tool with configurable parameters
+     * const searchTool = new Tool({
+     *   name: 'search',
+     *   input: z.object({
+     *     query: z.string(),
+     *     maxResults: z.number().default(10),
+     *     includeSnippets: z.boolean().default(true),
+     *   }),
+     *   handler: async ({ query, maxResults, includeSnippets }) => {
+     *     // Implementation
+     *   },
+     * })
+     *
+     * // Create a restricted version with static values
+     * const restrictedSearch = searchTool.setStaticInputValues({
+     *   maxResults: 5, // Always limit to 5 results
+     *   includeSnippets: false, // Never include snippets
+     * })
+     *
+     * // LLM can only control 'query' parameter now
+     * // The tool will always use maxResults: 5, includeSnippets: false
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clear static values
+     * const unrestricted = restrictedTool.setStaticInputValues(null)
+     * ```
+     */
     setStaticInputValues(values: SmartPartial<TypeOf<I>>): this;
+    /**
+     * Gets the computed input schema with static values applied.
+     *
+     * This property returns the final input schema that will be used for validation,
+     * including any static input values that have been set via setStaticInputValues().
+     *
+     * @returns The Zui schema for input validation
+     * @internal
+     */
     get zInput(): import("@bpinternal/zui").ZodTypeAny;
+    /**
+     * Gets the output schema for validation.
+     *
+     * @returns The Zui schema for output validation
+     * @internal
+     */
     get zOutput(): import("@bpinternal/zui").ZodTypeAny | import("@bpinternal/zui").ZodVoid;
+    /**
+     * Renames the tool and updates its aliases.
+     *
+     * @param name - New name for the tool (must be a valid identifier)
+     * @returns The tool instance for method chaining
+     * @throws Error if the name is not a valid identifier
+     *
+     * @example
+     * ```typescript
+     * const weatherTool = new Tool({ name: 'getWeather', ... })
+     * weatherTool.rename('getCurrentWeather')
+     * console.log(weatherTool.name) // 'getCurrentWeather'
+     * ```
+     */
     rename(name: string): this;
+    /**
+     * Creates a new tool based on this one with modified properties.
+     *
+     * Clone allows you to create variations of existing tools with different names,
+     * schemas, handlers, or other configuration. This is useful for creating specialized
+     * versions of tools or adding additional functionality.
+     *
+     * @param props - Properties to override in the cloned tool
+     * @returns A new Tool instance with the specified modifications
+     * @throws Error if cloning fails due to invalid configuration
+     *
+     * @example
+     * ```typescript
+     * // Create a basic search tool
+     * const basicSearch = new Tool({
+     *   name: 'search',
+     *   input: z.object({ query: z.string() }),
+     *   output: z.object({ results: z.array(z.string()) }),
+     *   handler: async ({ query }) => ({ results: await search(query) }),
+     * })
+     *
+     * // Clone with enhanced output schema
+     * const enhancedSearch = basicSearch.clone({
+     *   name: 'enhancedSearch',
+     *   description: 'Search with additional metadata',
+     *   output: (original) => original!.extend({
+     *     totalResults: z.number(),
+     *     searchTime: z.number(),
+     *   }),
+     *   handler: async ({ query }) => {
+     *     const startTime = Date.now()
+     *     const results = await search(query)
+     *     return {
+     *       results: results.items,
+     *       totalResults: results.total,
+     *       searchTime: Date.now() - startTime,
+     *     }
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clone with restricted access
+     * const restrictedTool = adminTool.clone({
+     *   name: 'userTool',
+     *   handler: async (input, ctx) => {
+     *     // Add authorization check
+     *     if (!isAuthorized(ctx.callId)) {
+     *       throw new Error('Unauthorized access')
+     *     }
+     *     return adminTool.execute(input, ctx)
+     *   },
+     * })
+     * ```
+     */
     clone<IX extends ZuiType = I, OX extends ZuiType = O>(props?: Partial<{
         name: string;
         aliases?: string[];
@@ -38,6 +341,82 @@ export declare class Tool<I extends ZuiType = ZuiType, O extends ZuiType = ZuiTy
         retry: ToolRetryFn<TypeOf<IX>>;
     }>): Tool<IX, OX>;
     private _handler;
+    /**
+     * Creates a new Tool instance.
+     *
+     * @param props - Tool configuration properties
+     * @param props.name - Unique tool name (must be valid TypeScript identifier)
+     * @param props.description - Human-readable description for the LLM
+     * @param props.input - Zui/Zod schema for input validation (optional)
+     * @param props.output - Zui/Zod schema for output validation (optional)
+     * @param props.handler - Async function that implements the tool logic
+     * @param props.aliases - Alternative names for the tool (optional)
+     * @param props.metadata - Additional metadata for the tool (optional)
+     * @param props.staticInputValues - Default input values (optional)
+     * @param props.retry - Custom retry logic function (optional)
+     *
+     * @throws Error if name is not a valid identifier
+     * @throws Error if description is not a string
+     * @throws Error if metadata is not an object
+     * @throws Error if handler is not a function
+     * @throws Error if aliases contains invalid identifiers
+     * @throws Error if input/output schemas are invalid
+     *
+     * @example
+     * ```typescript
+     * const weatherTool = new Tool({
+     *   name: 'getCurrentWeather',
+     *   description: 'Fetches current weather data for a given city',
+     *   aliases: ['weather', 'getWeather'], // Alternative names
+     *
+     *   input: z.object({
+     *     city: z.string().min(1).describe('City name to get weather for'),
+     *     units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+     *     includeHourly: z.boolean().default(false),
+     *   }),
+     *
+     *   output: z.object({
+     *     temperature: z.number(),
+     *     description: z.string(),
+     *     humidity: z.number().min(0).max(100),
+     *     hourlyForecast: z.array(z.object({
+     *       hour: z.number(),
+     *       temp: z.number(),
+     *       condition: z.string(),
+     *     })).optional(),
+     *   }),
+     *
+     *   async handler({ city, units, includeHourly }) {
+     *     const response = await fetch(`/api/weather?city=${encodeURIComponent(city)}&units=${units}`)
+     *     const data = await response.json()
+     *
+     *     const result = {
+     *       temperature: data.main.temp,
+     *       description: data.weather[0].description,
+     *       humidity: data.main.humidity,
+     *     }
+     *
+     *     if (includeHourly) {
+     *       result.hourlyForecast = data.hourly?.slice(0, 24) || []
+     *     }
+     *
+     *     return result
+     *   },
+     *
+     *   // Optional: Add retry logic for network errors
+     *   retry: ({ attempt, error }) => {
+     *     return attempt < 3 && error.message.includes('network')
+     *   },
+     *
+     *   // Optional: Add metadata
+     *   metadata: {
+     *     category: 'weather',
+     *     rateLimit: 100,
+     *     cacheable: true,
+     *   },
+     * })
+     * ```
+     */
     constructor(props: {
         name: string;
         aliases?: string[];
@@ -49,8 +428,70 @@ export declare class Tool<I extends ZuiType = ZuiType, O extends ZuiType = ZuiTy
         handler: (args: TypeOf<I>, ctx: ToolCallContext) => Promise<TypeOf<O>>;
         retry?: ToolRetryFn<TypeOf<I>>;
     });
+    /**
+     * Executes the tool with the given input and context.
+     *
+     * This method handles input validation, retry logic, output validation, and error handling.
+     * It's called internally by the LLMz execution engine when generated code calls the tool.
+     *
+     * @param input - Input data to pass to the tool handler
+     * @param ctx - Tool call context containing call ID and other metadata
+     * @returns Promise resolving to the tool's output
+     * @throws Error if input validation fails
+     * @throws Error if tool execution fails after all retries
+     *
+     * @example
+     * ```typescript
+     * // Direct tool execution (usually done by LLMz internally)
+     * const result = await weatherTool.execute(
+     *   { city: 'San Francisco', units: 'fahrenheit' },
+     *   { callId: 'call_123' }
+     * )
+     * console.log(result.temperature) // 72
+     * ```
+     *
+     * @internal This method is primarily used internally by the LLMz execution engine
+     */
     execute(input: TypeOf<I>, ctx: ToolCallContext): Promise<TypeOf<O>>;
+    /**
+     * Generates TypeScript type definitions for this tool.
+     *
+     * This method creates TypeScript function declarations that are included in the
+     * LLM's context to help it understand how to call the tool correctly. The generated
+     * types include parameter types, return types, and JSDoc comments with descriptions.
+     *
+     * @returns Promise resolving to TypeScript declaration string
+     */
     getTypings(): Promise<string>;
+    /**
+     * Ensures all tools in an array have unique names by appending numbers to duplicates.
+     *
+     * When multiple tools have the same name, this method renames them by appending
+     * incrementing numbers (tool1, tool2, etc.) to avoid conflicts. Tools with already
+     * unique names are left unchanged.
+     *
+     * You usually don't need to call this method directly, as LLMz will automatically detect and rename tools with conflicting names.
+     *
+     * @param tools - Array of tools to process for unique names
+     * @returns Array of tools with guaranteed unique names
+     *
+     * @example
+     * ```typescript
+     * const tools = [
+     *   new Tool({ name: 'search', handler: async () => {} }),
+     *   new Tool({ name: 'search', handler: async () => {} }),
+     *   new Tool({ name: 'unique', handler: async () => {} }),
+     *   new Tool({ name: 'search', handler: async () => {} }),
+     * ]
+     *
+     * const uniqueTools = Tool.withUniqueNames(tools)
+     * console.log(uniqueTools.map(t => t.name))
+     * // Output: ['search1', 'search1', 'unique', 'search']
+     * // Note: The last occurrence keeps the original name
+     * ```
+     *
+     * @static
+     */
     static withUniqueNames: (tools: Tool<any, any>[]) => Tool<any, any>[];
 }
 export {};