import { Jsonifiable, JsonValue, JsonObject } from 'type-fest'; export { SetOptional, SetRequired, Simplify } from 'type-fest'; import { z, ZodType } from 'zod'; import { KyInstance } from 'ky'; export { KyInstance } from 'ky'; import { ThrottledFunction } from 'p-throttle'; export { ThrottledFunction } from 'p-throttle'; export { default as delay } from 'delay'; type CreateAIFunctionArgs = { /** Name of the function. */ name: string; /** Description of the function. */ description: string; /** * Zod schema or AgenticSchema for the function parameters. * * You can use a JSON Schema for more dynamic tool sources such as MCP by * using the `createJsonSchema` utility function. */ inputSchema: InputSchema; /** * Whether to enable strict structured output generation based on the given * input schema. (this is a feature of the OpenAI API) * * Defaults to `true`. */ strict?: boolean; /** * Optional tags to help organize functions. */ tags?: string[]; }; type AIFunctionImplementation = (params: inferInput) => MaybePromise; /** * Create a function meant to be used with OpenAI tool or function calling. * * The returned function will parse the arguments string and call the * implementation function with the parsed arguments. * * The `spec` property of the returned function is the spec for adding the * function to the OpenAI API `functions` property. */ declare function createAIFunction(args: CreateAIFunctionArgs, /** Underlying function implementation. */ execute: AIFunctionImplementation): AIFunction; declare function createAIFunction(args: CreateAIFunctionArgs & { /** Underlying function implementation. */ execute: AIFunctionImplementation; }): AIFunction; type PrivateAIFunctionMetadata = CreateAIFunctionArgs & { methodName: string; }; declare global { interface SymbolConstructor { readonly metadata: unique symbol; } } declare abstract class AIFunctionsProvider { protected _functions?: AIFunctionSet; /** * An `AIFunctionSet` containing all of the AI-compatible functions exposed * by this class. * * This property is useful for manipulating AI functions across multiple * sources, picking specific functions, ommitting certain functions, etc. */ get functions(): AIFunctionSet; /** * Returns the AIFunctions provided by this class filtered by the given tags. */ getFunctionsFilteredByTags(...tags: string[]): AIFunctionSet; /** * Returns the AIFunctions provided by this class which match a custom filter * function. */ getFunctionsFilteredBy(filterFn: (fn: AIFunction) => boolean | undefined): AIFunctionSet; } declare function aiFunction, Return extends MaybePromise>(args: CreateAIFunctionArgs): (_targetMethod: (this: This, input: inferInput, ...optionalArgs: OptionalArgs) => Return, context: ClassMethodDecoratorContext, ...optionalArgs: OptionalArgs) => Return>) => void; interface LegacyMsg { content: string | null; role: Msg.Role; function_call?: Msg.Call.Function; tool_calls?: Msg.Call.Tool[]; tool_call_id?: string; name?: string; } /** Used for multimodal chat messages. */ type ChatMessageContentPart = { type: 'text'; text: string; } | { type: 'image_url'; image_url: { url: string; detail?: 'low' | 'high' | 'auto' | (string & {}); }; } | { type: 'input_audio'; input_audio: { data: string; format: 'mp3' | 'wav' | (string & {}); }; } | { type: 'refusal'; refusal: string; }; /** * Generic/default OpenAI message without any narrowing applied. */ interface Msg { /** * The role of the messages author. One of `system`, `user`, `assistant`, * 'tool', or `function`. */ role: Msg.Role; /** * The contents of the message. `content` may be null for assistant messages * with function calls or `undefined` for assistant messages if a `refusal` * was given by the model. */ content?: string | null; /** * The reason the model refused to generate this message or `undefined` if the * message was generated successfully. */ refusal?: string | null; /** * The name and arguments of a function that should be called, as generated * by the model. */ function_call?: Msg.Call.Function; /** * The tool calls generated by the model, such as function calls. */ tool_calls?: Msg.Call.Tool[]; /** * Tool call that this message is responding to. */ tool_call_id?: string; /** * The name of the author of this message. `name` is required if role is * `function`, and it should be the name of the function whose response is in the * `content`. May contain a-z, A-Z, 0-9, and underscores, with a maximum length of * 64 characters. */ name?: string; } /** Narrowed OpenAI Message types. */ declare namespace Msg { /** Possible roles for a message. */ type Role = 'system' | 'developer' | 'user' | 'assistant' | 'function' | 'tool'; namespace Call { /** * The name and arguments of a function that should be called, as generated * by the model. */ type Function = { /** * The arguments to call the function with, as generated by the model in * JSON format. */ arguments: string; /** The name of the function to call. */ name: string; }; /** The tool calls generated by the model, such as function calls. */ type Tool = { /** The ID of the tool call. */ id: string; /** The type of the tool. Currently, only `function` is supported. */ type: 'function'; /** The function that the model called. */ function: Call.Function; }; } /** Message with text content for the system. */ type System = { role: 'system'; content: string; name?: string; }; /** Message with text content for the developer. */ type Developer = { role: 'developer'; content: string; name?: string; }; /** Message with text content from the user. */ type User = { role: 'user'; name?: string; content: string; }; /** Message with text content from the assistant. */ type Assistant = { role: 'assistant'; name?: string; content: string; }; /** Message with refusal reason from the assistant. */ type Refusal = { role: 'assistant'; name?: string; refusal: string; }; /** Message with arguments to call a function. */ type FuncCall = { role: 'assistant'; name?: string; content: null; function_call: Call.Function; }; /** Message with the result of a function call. */ type FuncResult = { role: 'function'; name: string; content: string; }; /** Message with arguments to call one or more tools. */ type ToolCall = { role: 'assistant'; name?: string; content: null; tool_calls: Call.Tool[]; }; /** Message with the result of a tool call. */ type ToolResult = { role: 'tool'; tool_call_id: string; content: string; }; } /** Utility functions for creating and checking message types. */ declare namespace Msg { /** Create a system message. Cleans indentation and newlines by default. */ function system(content: string, opts?: { /** Custom name for the message. */ name?: string; /** Whether to clean extra newlines and indentation. Defaults to true. */ cleanContent?: boolean; }): Msg.System; /** Create a developer message. Cleans indentation and newlines by default. */ function developer(content: string, opts?: { /** Custom name for the message. */ name?: string; /** Whether to clean extra newlines and indentation. Defaults to true. */ cleanContent?: boolean; }): Msg.Developer; /** Create a user message. Cleans indentation and newlines by default. */ function user(content: string, opts?: { /** Custom name for the message. */ name?: string; /** Whether to clean extra newlines and indentation. Defaults to true. */ cleanContent?: boolean; }): Msg.User; /** Create an assistant message. Cleans indentation and newlines by default. */ function assistant(content: string, opts?: { /** Custom name for the message. */ name?: string; /** Whether to clean extra newlines and indentation. Defaults to true. */ cleanContent?: boolean; }): Msg.Assistant; /** * Create an assistant refusal message. Cleans indentation and newlines by * default. */ function refusal(refusal: string, opts?: { /** Custom name for the message. */ name?: string; /** Whether to clean extra newlines and indentation. Defaults to true. */ cleanRefusal?: boolean; }): Msg.Refusal; /** Create a function call message with argumets. */ function funcCall(funcCall: { /** Name of the function to call. */ name: string; /** Arguments to pass to the function. */ arguments: string; }, opts?: { /** The name descriptor for the message.(message.name) */ name?: string; }): Msg.FuncCall; /** Create a function result message. */ function funcResult(content: Jsonifiable, name: string): Msg.FuncResult; /** Create a function call message with argumets. */ function toolCall(toolCalls: Msg.Call.Tool[], opts?: { /** The name descriptor for the message.(message.name) */ name?: string; }): Msg.ToolCall; /** Create a tool call result message. */ function toolResult(content: Jsonifiable, toolCallId: string, opts?: { /** The name of the tool which was called */ name?: string; }): Msg.ToolResult; /** Get the narrowed message from an EnrichedResponse. */ function getMessage(response: any): Msg.Assistant | Msg.Refusal | Msg.FuncCall | Msg.ToolCall; /** Narrow a message received from the API. It only responds with role=assistant */ function narrowResponseMessage(msg: Msg): Msg.Assistant | Msg.Refusal | Msg.FuncCall | Msg.ToolCall; /** Check if a message is a system message. */ function isSystem(message: Msg): message is Msg.System; /** Check if a message is a developer message. */ function isDeveloper(message: Msg): message is Msg.Developer; /** Check if a message is a user message. */ function isUser(message: Msg): message is Msg.User; /** Check if a message is an assistant message. */ function isAssistant(message: Msg): message is Msg.Assistant; /** Check if a message is an assistant refusal message. */ function isRefusal(message: Msg): message is Msg.Refusal; /** Check if a message is a function call message with arguments. */ function isFuncCall(message: Msg): message is Msg.FuncCall; /** Check if a message is a function result message. */ function isFuncResult(message: Msg): message is Msg.FuncResult; /** Check if a message is a tool calls message. */ function isToolCall(message: Msg): message is Msg.ToolCall; /** Check if a message is a tool call result message. */ function isToolResult(message: Msg): message is Msg.ToolResult; /** Narrow a ChatModel.Message to a specific type. */ function narrow(message: Msg.System): Msg.System; function narrow(message: Msg.Developer): Msg.Developer; function narrow(message: Msg.User): Msg.User; function narrow(message: Msg.Assistant): Msg.Assistant; function narrow(message: Msg.Assistant): Msg.Refusal; function narrow(message: Msg.FuncCall): Msg.FuncCall; function narrow(message: Msg.FuncResult): Msg.FuncResult; function narrow(message: Msg.ToolCall): Msg.ToolCall; function narrow(message: Msg.ToolResult): Msg.ToolResult; } /** * Used to mark schemas so we can support both Zod and custom schemas. */ declare const schemaSymbol: unique symbol; /** * Structured schema used across Agentic, which wraps either a Zod schema or a * JSON Schema. * * JSON Schema support is important to support more dynamic tool sources such as * MCP. */ type AgenticSchema = { /** * The JSON Schema. */ readonly jsonSchema: JSONSchema; /** * Parses the value, validates that it matches this schema, and returns a * typed version of the value if it does. Throw an error if the value does * not match the schema. */ readonly parse: ParseFn; /** * Parses the value, validates that it matches this schema, and returns a * typed version of the value if it does. Returns an error message if the * value does not match the schema, and will never throw an error. */ readonly safeParse: SafeParseFn; /** * Used to mark schemas so we can support both Zod and custom schemas. */ [schemaSymbol]: true; /** * Schema type for inference. */ _type: TData; /** * Source Zod schema if this object was created from a Zod schema. */ _source?: any; }; declare function isAgenticSchema(value: unknown): value is AgenticSchema; declare function isZodSchema(value: unknown): value is z.ZodType; declare function asAgenticSchema(schema: z.Schema | AgenticSchema, opts?: { strict?: boolean; }): AgenticSchema; declare function asZodOrJsonSchema(schema: z.Schema | AgenticSchema): z.Schema | JSONSchema; /** * Create an AgenticSchema from a JSON Schema. * * All `AIFunction` input schemas accept either a Zod schema or a custom JSON * Schema. Use this function to wrap JSON schemas for use with `AIFunction`. * * Note that JSON Schemas are not validated by default, so you have to pass * in an optional `parse` function (using `ajv`, for instance) if you'd like to * validate them at runtime. */ declare function createJsonSchema(jsonSchema: JSONSchema, { parse, safeParse, source }?: { parse?: ParseFn; safeParse?: SafeParseFn; source?: any; }): AgenticSchema; declare function createAgenticSchemaFromZodSchema(zodSchema: z.Schema, opts?: { strict?: boolean; }): AgenticSchema; declare function augmentSystemMessageWithJsonSchema({ schema, system, schemaPrefix, schemaSuffix }: { schema: JSONSchema; system?: string; schemaPrefix?: string; schemaSuffix?: string; }): string; type Nullable = T | null; type DeepNullable = T extends object ? { [K in keyof T]: DeepNullable; } : Nullable; type MaybePromise = T | Promise; type JSONSchema = Record; type RelaxedJsonifiable = Jsonifiable | Record; interface AIFunctionSpec { /** AI Function name. */ name: string; /** Description of what the function does. */ description: string; /** JSON schema spec of the function's input parameters */ parameters: JSONSchema; /** * The type of the function tool. Always `function`. */ type: 'function'; /** * Whether to enable strict schema adherence when generating the function * parameters. Currently only supported by OpenAI's * [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). */ strict: boolean; } interface AIToolSpec { type: 'function'; function: AIFunctionSpec; } /** * A Zod object schema or a custom schema created from a JSON schema via * `createSchema()`. */ type AIFunctionInputSchema = z.ZodObject | AgenticSchema; type inferInput = InputSchema extends AgenticSchema ? InputSchema['_type'] : InputSchema extends z.ZodTypeAny ? z.infer : never; /** The implementation of the function, with arg parsing and validation. */ type AIFunctionImpl = Omit<(input: string | Msg) => MaybePromise, 'name' | 'toString' | 'arguments' | 'caller' | 'prototype' | 'length'>; /** * Flexible type which accepts any AI-function-like object, including: * - `AIFunctionSet` - Sets of AI functions * - `AIFunctionsProvider` - Client classes which expose an `AIFunctionSet` * via the `.functions` property * - `AIFunction` - Individual functions */ type AIFunctionLike = AIFunctionsProvider | AIFunction | AIFunctionSet; /** * A function meant to be used with LLM function calling. */ interface AIFunction { /** * Invokes the underlying AI function `execute` but first validates the input * against this function's `inputSchema`. This method is callable and is * meant to be passed the raw LLM JSON string or an OpenAI-compatible Message. */ (input: string | Msg): MaybePromise; /** The schema for the input object (zod or custom schema). */ inputSchema: InputSchema; /** Parse the function arguments from a message. */ parseInput(input: string | Msg): inferInput; /** The JSON schema function spec for the OpenAI API `functions` property. */ spec: AIFunctionSpec; /** * The underlying function implementation without any arg parsing or validation. */ execute: (params: inferInput | any) => MaybePromise; /** Optional tags to help organize functions. */ tags?: string[]; } type SafeParseResult = { success: true; data: TData; } | { success: false; error: string; }; type ParseFn = (value: unknown) => TData; type SafeParseFn = (value: unknown) => SafeParseResult; type AIFunctionSetOptions = { transformNameKeysFn?: (name: string) => string; }; /** * A set of AI functions intended to make it easier to work with large sets of * AI functions across different clients. * * This class mimics a built-in `Set`, but with additional utility * methods like `pick`, `omit`, and `map`. * * Function names are case-insensitive to make it easier to match them with * possible LLM hallucinations. */ declare class AIFunctionSet implements Iterable { protected readonly _map: Map; protected readonly _transformNameKeysFn: (name: string) => string; constructor(aiFunctionLikeObjects?: AIFunctionLike[], { transformNameKeysFn }?: AIFunctionSetOptions); get size(): number; add(fn: AIFunction): this; get(name: string): AIFunction | undefined; set(name: string, fn: AIFunction): this; has(name: string): boolean; clear(): void; delete(name: string): boolean; pick(...keys: string[]): AIFunctionSet; omit(...keys: string[]): AIFunctionSet; map(fn: (fn: AIFunction) => T): T[]; /** * Returns a new AIFunctionSet containing only the AIFunctions in this set * matching the given tags. */ getFilteredByTags(...tags: string[]): AIFunctionSet; /** * Returns a new AIFunctionSet containing only the AIFunctions in this set * matching a custom filter function. */ getFilteredBy(filterFn: (fn: AIFunction) => boolean | undefined): AIFunctionSet; /** * Returns the functions in this set as an array compatible with OpenAI's * chat completions `functions`. */ get specs(): AIFunctionSpec[]; /** * Returns the functions in this set as an array compatible with OpenAI's * chat completions `tools`. */ get toolSpecs(): AIToolSpec[]; /** * Returns the tools in this set compatible with OpenAI's `responses` API. * * Note that this is currently the same type as `AIFunctionSet.specs`, but * they are separate APIs which may diverge over time, so if you're using the * OpenAI `responses` API, you should reference this property. */ get responsesToolSpecs(): AIFunctionSpec[]; get entries(): IterableIterator; [Symbol.iterator](): Iterator; } /** * Test AI tool with one function `echo`, which echoes the input. */ declare class EchoAITool extends AIFunctionsProvider { echo({ query }: { query: string; }): Promise; } /** * Test AI function `echo`, which echoes the input. */ declare const echoAIFunction: AIFunction, string>; declare class RetryableError extends Error { } declare class AbortError extends Error { } declare class ParseError extends RetryableError { } declare class TimeoutError extends Error { } /** * Parses a string which is expected to contain a structured JSON value. * * The JSON value is fuzzily parsed in order to support common issues like * missing commas, trailing commas, and unquoted keys. * * The JSON value is then parsed against a `zod` schema to enforce the shape of * the output. * * @returns parsed output */ declare function parseStructuredOutput(value: unknown, outputSchema: ZodType): T; declare function safeParseStructuredOutput(value: unknown, outputSchema: ZodType): SafeParseResult; /** * Extracts JSON objects or arrays from a string. * * @param input - string to extract JSON from * @param jsonStructureType - type of JSON structure to extract * @returns array of extracted JSON objects or arrays */ declare function extractJSONFromString(input: string, jsonStructureType: 'object' | 'array'): JsonValue[]; /** * Parses an array output from a string. * * @param output - string to parse * @returns parsed array */ declare function parseArrayOutput(output: string): JsonValue[]; /** * Parses an object output from a string. * * @param output - string to parse * @returns parsed object */ declare function parseObjectOutput(output: string): JsonObject; /** * Parses a boolean output from a string. * * @param output - string to parse * @returns parsed boolean */ declare function parseBooleanOutput(output: string): boolean; /** * Parses a number output from a string. * * @param output - string to parse * @param outputSchema - zod number schema * @returns parsed number */ declare function parseNumberOutput(output: string, outputSchema: z.ZodNumber): number; declare function assert(value: unknown, message?: string | Error): asserts value; /** * From `inputObj`, create a new object that does not include `keys`. * * @example * ```js * omit({ a: 1, b: 2, c: 3 }, 'a', 'c') // { b: 2 } * ``` */ declare const omit: | object, K extends keyof any>(inputObj: T, ...keys: K[]) => Omit; /** * From `inputObj`, create a new object that only includes `keys`. * * @example * ```js * pick({ a: 1, b: 2, c: 3 }, 'a', 'c') // { a: 1, c: 3 } * ``` */ declare const pick: | object, K extends keyof T>(inputObj: T, ...keys: K[]) => Pick; declare function pruneUndefined>(obj: T): NonNullable<{ [K in keyof T]: Exclude; }>; declare function pruneNullOrUndefined>(obj: T): NonNullable<{ [K in keyof T]: Exclude; }>; declare function pruneNullOrUndefinedDeep>(obj: T): NonNullable<{ [K in keyof T]: Exclude; }>; declare function pruneEmpty>(obj: T): NonNullable<{ [K in keyof T]: Exclude; }>; declare function pruneEmptyDeep(value?: T): undefined | (T extends Record ? { [K in keyof T]: Exclude; } : T extends Array ? Array> : Exclude); declare function getEnv(name: string): string | undefined; /** * Function that does nothing. */ declare const noop: () => undefined; /** * Throttles HTTP requests made by a ky instance. * * Very useful for enforcing rate limits. */ declare function throttleKy(ky: KyInstance, throttleFn: (function_: (...args_: Arguments) => ReturnValue) => ThrottledFunction<(...args_: Arguments) => ReturnValue>): KyInstance; /** * Creates a new `URLSearchParams` object with all values coerced to strings * that correctly handles arrays of values as repeated keys (or CSV) and * correctly removes `undefined` keys and values. */ declare function sanitizeSearchParams(searchParams: Record | object, { csv }?: { /** * Whether to use comma-separated-values for arrays or multiple entries. * * Defaults to `false` and will use multiple entries. */ csv?: boolean; }): URLSearchParams; /** * Stringifies a JSON value in a way that's optimized for use with LLM prompts. * * Replacement for `JSON.stringify` when working with LLMs. * * @example * ```ts * stringifyForModel({ a: 1, b: 2 }) // '{"a":1,"b":2}' * ``` */ declare function stringifyForModel(jsonObject?: RelaxedJsonifiable, replacer?: (number | string)[] | null, space?: string | number): string; /** * Cleans a string by removing extra newlines and indentation. * * @see: https://github.com/dmnd/dedent */ declare function cleanStringForModel(text: string): string; declare function isAIFunction(obj: any): obj is AIFunction; declare function getErrorMessage(error?: unknown): string; declare function getShortDateString(date?: Date): string; /** Generate a JSON Schema from a Zod schema. */ declare function zodToJsonSchema(schema: z.ZodType, { strict }?: { strict?: boolean; }): JSONSchema; export { type AIFunction, type AIFunctionImpl, type AIFunctionImplementation, type AIFunctionInputSchema, type AIFunctionLike, AIFunctionSet, type AIFunctionSetOptions, type AIFunctionSpec, AIFunctionsProvider, type AIToolSpec, AbortError, type AgenticSchema, type ChatMessageContentPart, type CreateAIFunctionArgs, type DeepNullable, EchoAITool, type JSONSchema, type LegacyMsg, type MaybePromise, Msg, type Nullable, ParseError, type ParseFn, type PrivateAIFunctionMetadata, type RelaxedJsonifiable, RetryableError, type SafeParseFn, type SafeParseResult, TimeoutError, aiFunction, asAgenticSchema, asZodOrJsonSchema, assert, augmentSystemMessageWithJsonSchema, cleanStringForModel, createAIFunction, createAgenticSchemaFromZodSchema, createJsonSchema, echoAIFunction, extractJSONFromString, getEnv, getErrorMessage, getShortDateString, type inferInput, isAIFunction, isAgenticSchema, isZodSchema, noop, omit, parseArrayOutput, parseBooleanOutput, parseNumberOutput, parseObjectOutput, parseStructuredOutput, pick, pruneEmpty, pruneEmptyDeep, pruneNullOrUndefined, pruneNullOrUndefinedDeep, pruneUndefined, safeParseStructuredOutput, sanitizeSearchParams, schemaSymbol, stringifyForModel, throttleKy, zodToJsonSchema };