llmz 0.0.13 → 0.0.14

package/dist/chunk-KG7DT7WD.cjs

@@ -0,0 +1,476 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } var _class;
+
+var _chunk4L6D2A6Ocjs = require('./chunk-4L6D2A6O.cjs');
+
+
+
+
+
+var _chunk276Q6EWPcjs = require('./chunk-276Q6EWP.cjs');
+
+
+
+var _chunkUQOBUJIQcjs = require('./chunk-UQOBUJIQ.cjs');
+
+// src/tool.ts
+var _zui = require('@bpinternal/zui');
+var Tool = (_class = class _Tool {
+  
+  
+  __init() {this.aliases = []}
+  
+  
+  
+  
+  
+  __init2() {this.MAX_RETRIES = 1e3}
+  /**
+   * 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) {
+    if (values === null || values === void 0) {
+      this._staticInputValues = void 0;
+      return this;
+    }
+    const input = this.input ? _zui.transforms.fromJSONSchemaLegacy(this.input) : _zui.z.any();
+    if (input instanceof _zui.z.ZodObject && typeof values !== "object") {
+      throw new Error(
+        `Invalid static input values for tool ${this.name}. Expected an object, but got type "${typeof values}"`
+      );
+    }
+    if (input instanceof _zui.z.ZodArray && !Array.isArray(values)) {
+      throw new Error(
+        `Invalid static input values for tool ${this.name}. Expected an array, but got type "${typeof values}"`
+      );
+    }
+    this._staticInputValues = values;
+    return 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() {
+    let input = this.input ? _zui.transforms.fromJSONSchemaLegacy(this.input) : _zui.z.any();
+    if (!_chunkUQOBUJIQcjs.isEmpty_default.call(void 0, this._staticInputValues)) {
+      const inputExtensions = _chunk276Q6EWPcjs.convertObjectToZuiLiterals.call(void 0, this._staticInputValues);
+      if (input instanceof _zui.z.ZodObject) {
+        input = input.extend(inputExtensions);
+      } else if (input instanceof _zui.z.ZodArray) {
+        input = _zui.z.array(input.element.extend(inputExtensions));
+      } else {
+        input = inputExtensions;
+      }
+    }
+    return input;
+  }
+  /**
+   * Gets the output schema for validation.
+   *
+   * @returns The Zui schema for output validation
+   * @internal
+   */
+  get zOutput() {
+    return this.output ? _zui.transforms.fromJSONSchemaLegacy(this.output) : _zui.z.void();
+  }
+  /**
+   * 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) {
+    const before = this.name;
+    if (!_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, name)) {
+      throw new Error(
+        `Invalid name for tool ${name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
+      );
+    }
+    this.name = name;
+    this.aliases = _chunkUQOBUJIQcjs.uniq_default.call(void 0, [name, ...this.aliases.map((alias) => alias === before ? name : alias)]);
+    return 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(props = {}) {
+    var _a, _b;
+    try {
+      const zInput = this.input ? _zui.transforms.fromJSONSchemaLegacy(this.input) : void 0;
+      const zOutput = this.output ? _zui.transforms.fromJSONSchemaLegacy(this.output) : void 0;
+      return new _Tool({
+        name: _nullishCoalesce(props.name, () => ( this.name)),
+        aliases: _nullishCoalesce(props.aliases, () => ( [...this.aliases])),
+        description: _nullishCoalesce(props.description, () => ( this.description)),
+        metadata: JSON.parse(JSON.stringify(_nullishCoalesce(props.metadata, () => ( this.metadata)))),
+        input: typeof props.input === "function" ? (_a = props.input) == null ? void 0 : _a.call(props, zInput) : props.input instanceof _zui.ZodType ? props.input : zInput,
+        output: typeof props.output === "function" ? (_b = props.output) == null ? void 0 : _b.call(props, zOutput) : props.output instanceof _zui.ZodType ? props.output : zOutput,
+        handler: _nullishCoalesce(props.handler, () => ( this._handler)),
+        retry: _nullishCoalesce(props.retry, () => ( this.retry))
+      }).setStaticInputValues(_nullishCoalesce(props.staticInputValues, () => ( this._staticInputValues)));
+    } catch (e) {
+      throw new Error(`Failed to clone tool "${this.name}": ${e}`);
+    }
+  }
+  
+  /**
+   * 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) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);
+    if (!_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, props.name)) {
+      throw new Error(
+        `Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
+      );
+    }
+    if (props.description !== void 0 && typeof props.description !== "string") {
+      throw new Error(
+        `Invalid description for tool ${props.name}. Expected a string, but got type "${typeof props.description}"`
+      );
+    }
+    if (props.metadata !== void 0 && typeof props.metadata !== "object") {
+      throw new Error(
+        `Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`
+      );
+    }
+    if (typeof props.handler !== "function") {
+      throw new Error(
+        `Invalid handler for tool ${props.name}. Expected a function, but got type "${typeof props.handler}"`
+      );
+    }
+    if (props.aliases !== void 0 && !Array.isArray(props.aliases)) {
+      throw new Error(
+        `Invalid aliases for tool ${props.name}. Expected an array, but got type "${typeof props.aliases}"`
+      );
+    }
+    if (props.aliases && props.aliases.some((alias) => !_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, alias))) {
+      throw new Error(`Invalid aliases for tool ${props.name}. Expected an array of valid identifiers.`);
+    }
+    if (typeof props.input !== "undefined") {
+      if (_chunk276Q6EWPcjs.isZuiSchema.call(void 0, props.input)) {
+        this.input = _zui.transforms.toJSONSchemaLegacy(props.input);
+      } else if (_chunk276Q6EWPcjs.isJsonSchema.call(void 0, props.input)) {
+        this.input = props.input;
+      } else {
+        throw new Error(
+          `Invalid input schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.input}"`
+        );
+      }
+    }
+    if (typeof props.output !== "undefined") {
+      if (_chunk276Q6EWPcjs.isZuiSchema.call(void 0, props.output)) {
+        this.output = _zui.transforms.toJSONSchemaLegacy(props.output);
+      } else if (_chunk276Q6EWPcjs.isJsonSchema.call(void 0, props.output)) {
+        this.output = props.output;
+      } else {
+        throw new Error(
+          `Invalid output schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.output}"`
+        );
+      }
+    }
+    this.name = props.name;
+    this.aliases = _chunkUQOBUJIQcjs.uniq_default.call(void 0, [props.name, ..._nullishCoalesce(props.aliases, () => ( []))]);
+    this.description = props.description;
+    this.metadata = _nullishCoalesce(props.metadata, () => ( {}));
+    this._handler = props.handler;
+    this.setStaticInputValues(props.staticInputValues);
+    this.retry = props.retry;
+  }
+  /**
+   * 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
+   */
+  async execute(input, ctx) {
+    var _a;
+    const pInput = this.zInput.safeParse(input);
+    if (!pInput.success) {
+      throw new Error(`Tool "${this.name}" received invalid input: ${pInput.error.message}`);
+    }
+    let attempt = 0;
+    while (attempt < this.MAX_RETRIES) {
+      try {
+        const result = await this._handler(pInput.data, ctx);
+        const pOutput = this.zOutput.safeParse(result);
+        return pOutput.success ? pOutput.data : result;
+      } catch (err) {
+        const shouldRetry = await ((_a = this.retry) == null ? void 0 : _a.call(this, {
+          input: pInput.data,
+          attempt: ++attempt,
+          error: err
+        }));
+        if (!shouldRetry) {
+          throw err;
+        }
+      }
+    }
+    throw new Error(
+      `Tool "${this.name}" failed after ${this.MAX_RETRIES} attempts. Last error: ${JSON.stringify(input)}`
+    );
+  }
+  /**
+   * 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
+   */
+  async getTypings() {
+    let input = this.input ? _zui.transforms.fromJSONSchemaLegacy(this.input) : void 0;
+    const output = this.output ? _zui.transforms.fromJSONSchemaLegacy(this.output) : _zui.z.void();
+    if ((input == null ? void 0 : input.naked()) instanceof _zui.ZodObject && typeof this._staticInputValues === "object" && !_chunkUQOBUJIQcjs.isEmpty_default.call(void 0, this._staticInputValues)) {
+      const inputExtensions = _chunk276Q6EWPcjs.convertObjectToZuiLiterals.call(void 0, this._staticInputValues);
+      input = input.extend(inputExtensions);
+    } else if (this._staticInputValues !== void 0) {
+      input = _chunk276Q6EWPcjs.convertObjectToZuiLiterals.call(void 0, this._staticInputValues);
+    }
+    const fnType = _zui.z.function(input, _zui.z.promise(output)).title(this.name).describe(_nullishCoalesce(this.description, () => ( "")));
+    return _chunk4L6D2A6Ocjs.getTypings.call(void 0, fnType, {
+      declaration: true
+    });
+  }
+  /**
+   * 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 __initStatic() {this.withUniqueNames = (tools) => {
+    const names = /* @__PURE__ */ new Set();
+    return tools.map((tool) => {
+      if (tools.filter((t) => t.name === tool.name).length === 1) {
+        return tool;
+      }
+      let counter = 1;
+      let toolName = tool.name + counter;
+      while (names.has(toolName)) {
+        toolName = `${tool.name}${++counter}`;
+      }
+      return tool.rename(toolName);
+    });
+  }}
+}, _class.__initStatic(), _class);
+
+
+
+exports.Tool = Tool;