llm-exe 2.3.1 → 2.3.3

package/dist/index.d.mts

@@ -226,14 +226,14 @@ declare class StringExtractParser extends BaseParser<string> {
  * Creates a parser based on the given type.
  * @template S - JSON schema type.
  * @param type - The type of parser to create.
- * @returns An instance of ListToKeyValueParser.
+ * @returns An instance of MarkdownCodeBlocksParser.
  */
 declare function createParser<T extends Extract<CreateParserType, "markdownCodeBlocks">>(type: T, options?: BaseParserOptions): MarkdownCodeBlocksParser;
 /**
  * Creates a parser based on the given type.
  * @template S - JSON schema type.
  * @param type - The type of parser to create.
- * @returns An instance of ListToKeyValueParser.
+ * @returns An instance of MarkdownCodeBlockParser.
  */
 declare function createParser<T extends Extract<CreateParserType, "markdownCodeBlock">>(type: T, options?: BaseParserOptions): MarkdownCodeBlockParser;
 /**
@@ -432,8 +432,8 @@ declare class ChatPrompt<I extends Record<string, any>> extends BasePrompt<I> {
     readonly type: ChatPromptType;
     /**
      * @property parseUserTemplates - Whether or not to allow parsing
-     * user messages with the template engine. This could be a risk,
-     * so we only parse user messages if explicitly set.
+     * user messages with the template engine. Defaults to true.
+     * Set `allowUnsafeUserTemplate: false` in options to disable.
      */
     private parseUserTemplates;
     /**
@@ -468,13 +468,13 @@ declare class ChatPrompt<I extends Record<string, any>> extends BasePrompt<I> {
      */
     addAssistantMessage(content: string): ChatPrompt<I>;
     /**
-     * addFunctionMessage Helper to add an assistant message to the prompt.
+     * addFunctionMessage Helper to add a function message to the prompt.
      * @param content The message content.
      * @return ChatPrompt so it can be chained.
      */
     addFunctionMessage(content: string, name: string, id?: string): ChatPrompt<I>;
     /**
-     * addFunctionCallMessage Helper to add an assistant message to the prompt.
+     * addFunctionCallMessage Helper to add a function_call message to the prompt.
      * @param content The message content.
      * @return ChatPrompt so it can be chained.
      */
@@ -602,6 +602,10 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      */
     hooks: any;
     readonly allowedHooks: any[];
+    /**
+     * @property maxHooksPerEvent - Maximum number of hooks allowed per event
+     */
+    readonly maxHooksPerEvent: number;
     constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<H>);
     abstract handler(input: I, _options?: any): Promise<any>;
     /**
@@ -635,6 +639,18 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
     once(eventName: keyof H, fn: ListenerFunction): this;
     withTraceId(traceId: string): this;
     getTraceId(): string | null;
+    /**
+     * Clear all hooks for a specific event or all events
+     * Useful for preventing memory leaks in long-running processes
+     * @param eventName - The event name to clear hooks for
+     */
+    clearHooks(eventName?: keyof H): this;
+    /**
+     * Get the count of hooks for monitoring memory usage
+     * @param eventName - Optional event name to get count for
+     * @returns Hook count for specific event or all events
+     */
+    getHookCount(eventName?: keyof H): number | Record<string, number>;
 }
 
 /**
@@ -674,7 +690,7 @@ declare class Dialogue extends BaseStateItem<IChatMessages> {
     setUserMessage(content: string | IChatMessageContentDetailed[], name?: string): this;
     setAssistantMessage(content: string | OutputResultsText): this;
     setSystemMessage(content: string): this;
-    setToolMessage(content: string, name: string, id?: string): void;
+    setToolMessage(content: string, name: string, id?: string): this;
     setFunctionMessage(content: string, name: string, id?: string): this;
     /**
      * Set
@@ -683,7 +699,7 @@ declare class Dialogue extends BaseStateItem<IChatMessages> {
         name: string;
         arguments: string;
         id?: string;
-    }): void;
+    }): this;
     setFunctionCallMessage(input: {
         name: string;
         arguments: string;
@@ -938,6 +954,8 @@ interface BaseLlmOptions {
     numOfAttempts?: number;
     jitter?: "none" | "full";
     promptType?: PromptType;
+    endpoint?: string;
+    headers?: Record<string, string>;
 }
 interface GenericEmbeddingOptions extends BaseLlmOptions {
     model?: string;
@@ -966,6 +984,7 @@ interface GenericLLm extends BaseLlmOptions {
     streamOptions?: Record<string, any>;
     maxTokens?: number;
     stopSequences?: string[];
+    effort?: "minimal" | "low" | "medium" | "high";
 }
 interface OpenAiRequest extends GenericLLm {
     model: string;
@@ -984,6 +1003,11 @@ interface AmazonBedrockRequest extends GenericLLm {
 interface AnthropicRequest extends GenericLLm {
     model: string;
     anthropicApiKey?: string;
+    topK?: number;
+    metadata?: {
+        user_id?: string;
+    };
+    serviceTier?: "auto" | "standard_only";
 }
 interface GeminiRequest extends GenericLLm {
     model: string;
@@ -1033,6 +1057,30 @@ type AllLlm = {
     };
 };
 type AllUseLlmOptions = AllLlm & {
+    "openai.gpt-5.2": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5-nano": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-4.1": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-4.1-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-4.1-nano": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.o3": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.o4-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
     "openai.gpt-4": {
         input: OpenAiRequest;
     };
@@ -1042,6 +1090,12 @@ type AllUseLlmOptions = AllLlm & {
     "openai.gpt-4o-mini": {
         input: Omit<OpenAiRequest, "model">;
     };
+    "anthropic.claude-opus-4-6": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-sonnet-4-6": {
+        input: Omit<AnthropicRequest, "model">;
+    };
     "anthropic.claude-sonnet-4-0": {
         input: Omit<AnthropicRequest, "model">;
     };
@@ -1051,18 +1105,24 @@ type AllUseLlmOptions = AllLlm & {
     "anthropic.claude-3-7-sonnet": {
         input: Omit<AnthropicRequest, "model">;
     };
-    "anthropic.claude-3-5-sonnet": {
+    "anthropic.claude-sonnet-4": {
         input: Omit<AnthropicRequest, "model">;
     };
-    "anthropic.claude-3-opus": {
+    "anthropic.claude-opus-4": {
         input: Omit<AnthropicRequest, "model">;
     };
-    "anthropic.claude-3-sonnet": {
+    "anthropic.claude-3-5-sonnet": {
         input: Omit<AnthropicRequest, "model">;
     };
     "anthropic.claude-3-5-haiku": {
         input: Omit<AnthropicRequest, "model">;
     };
+    "anthropic.claude-3-opus": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-3-haiku": {
+        input: Omit<AnthropicRequest, "model">;
+    };
     "google.gemini-2.5-pro-exp-03-25": {
         input: Omit<GeminiRequest, "model">;
     };
@@ -1090,9 +1150,15 @@ type AllUseLlmOptions = AllLlm & {
     "xai.grok-3": {
         input: OpenAiRequest;
     };
+    "xai.grok-3-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
     "xai.grok-4": {
         input: OpenAiRequest;
     };
+    "xai.grok-4-fast": {
+        input: Omit<OpenAiRequest, "model">;
+    };
     "ollama.deepseek-r1": {
         input: GenericLLm;
     };
@@ -1131,25 +1197,106 @@ interface BaseLlm<_T extends BaseLlCall = BaseLlCall> extends BaseRequest<_T> {
 
 type LlmProvider = "openai.chat" | "openai.embedding" | "google.embedding" | "openai.chat-mock" | "anthropic.chat" | "amazon:anthropic.chat" | "amazon:meta.chat" | "amazon:nova.chat" | "amazon.embedding" | "xai.chat" | "google.chat" | "ollama.chat" | "deepseek.chat";
 interface Config<Pk = LlmProviderKey> {
+    /**
+     * Unique identifier for this configuration (e.g., "openai.chat.v1", "anthropic.claude-3-opus")
+     * Used to reference this config when calling useLlm()
+     */
     key: Pk;
+    /**
+     * The provider type this config is for (e.g., "openai.chat", "anthropic.chat")
+     * Used internally for provider-specific logic
+     */
     provider: LlmProvider;
-    method: string;
+    /**
+     * HTTP method for the API request (typically "POST" for LLM providers)
+     */
+    method: "POST" | "PUT" | "GET";
+    /**
+     * API endpoint URL template. Supports template variables using {{variable}} syntax
+     * Variables are replaced with values from the state object
+     * @example "https://api.openai.com/v1/chat/completions"
+     * @example "https://bedrock-runtime.{{awsRegion}}.amazonaws.com/model/{{model}}/invoke"
+     */
     endpoint: string;
+    /**
+     * HTTP headers template as a JSON string. Supports template variables using {{variable}} syntax
+     * @example '{"Authorization":"Bearer {{openAiApiKey}}", "Content-Type": "application/json"}'
+     * // TODO: make this also accept object and function
+     */
+    headers: string;
     options: {
         [key in string]: {
-            default?: number | string;
+            /**
+             * Default value for this parameter if not provided by the user
+             * Can be a static value or a function that returns the value
+             * @example 4096
+             * @example () => process.env.OPENAI_API_KEY
+             */
+            default?: any;
+            /**
+             * Whether this parameter is required
+             * [true, "error message"] - Required with custom error
+             * [true] - Required with default error message
+             * @example [true, "maxTokens is required for Anthropic"]
+             */
             required?: [boolean, string] | [boolean];
         };
     };
     mapBody: {
         [key in string]: {
+            /**
+             * The target field name in the provider's request body.
+             * Supports dot notation for nested fields (e.g., "response_format.type")
+             */
             key: string;
-            default?: number | string;
-            sanitize?: (i: any, arg: Record<string, any>, arg2: Record<string, any>) => any;
+            /**
+             * Default value to use if the source field is not provided
+             */
+            default?: any;
+            /**
+             * Transform function to convert the value before mapping to the request body
+             * @param value - The input value from the user's state
+             * @param state - The complete user state object containing all parameters
+             * @param config - The current Config object (for access to options, etc.)
+             * @returns The transformed value to be included in the request body
+             */
+            transform?: (value: any, state: Record<string, any>, config: Record<string, any>) => any;
         };
     };
-    headers: string;
-    prompt?: (messages: IChatMessages) => any;
+    /**
+     * Maps executor-level options (jsonSchema, functions, functionCall) to provider-specific request formats
+     * @optional - Only needed if provider supports these features
+     */
+    mapOptions?: {
+        /**
+         * Transform JSON schema into provider-specific format
+         * @param schema - The JSON schema object
+         * @param options - Executor options (e.g., functionCallStrictInput)
+         * @param currentInput - Current accumulated input state (for merging)
+         * @param config - The full config object
+         * @returns Provider-specific request body additions
+         */
+        jsonSchema?: (schema: any, options: any, currentInput?: Record<string, any>, config?: Config) => Record<string, any>;
+        /**
+         * Transform function call mode into provider-specific format
+         * @param call - Function call mode ("auto", "any", "none", or specific function)
+         * @param options - Executor options
+         * @param currentInput - Current accumulated input state (for merging)
+         * @param config - The full config object
+         * @returns Provider-specific request body additions
+         */
+        functionCall?: (call: any, options?: any, currentInput?: Record<string, any>, config?: Config) => Record<string, any>;
+        /**
+         * Transform function definitions into provider-specific format
+         * @param functions - Array of function definitions
+         * @param options - Executor options (e.g., functionCallStrictInput)
+         * @param currentInput - Current accumulated input state (for merging)
+         * @param config - The full config object
+         * @returns Provider-specific request body additions
+         */
+        functions?: (functions: any[], options?: any, currentInput?: Record<string, any>, config?: Config) => Record<string, any>;
+    };
+    transformResponse: (result: any, _config?: Config<any>) => OutputResult;
 }
 
 declare function enforceResultAttributes<O>(input: any): {
@@ -1355,24 +1502,42 @@ declare const configs: {
     "xai.chat.v1": Config<keyof AllLlm>;
     "xai.grok-2": Config<keyof AllLlm>;
     "xai.grok-3": Config<keyof AllLlm>;
+    "xai.grok-3-mini": Config<keyof AllLlm>;
     "xai.grok-4": Config<keyof AllLlm>;
+    "xai.grok-4-fast": Config<keyof AllLlm>;
     "amazon:anthropic.chat.v1": Config<keyof AllLlm>;
     "amazon:meta.chat.v1": Config<keyof AllLlm>;
     "anthropic.chat.v1": Config<keyof AllLlm>;
-    "anthropic.claude-sonnet-4-0": Config<keyof AllLlm>;
-    "anthropic.claude-opus-4-0": Config<keyof AllLlm>;
+    "anthropic.claude-opus-4-6": Config<keyof AllLlm>;
+    "anthropic.claude-sonnet-4-6": Config<keyof AllLlm>;
+    "anthropic.claude-sonnet-4": Config<keyof AllLlm>;
+    "anthropic.claude-opus-4": Config<keyof AllLlm>;
     "anthropic.claude-3-7-sonnet": Config<keyof AllLlm>;
     "anthropic.claude-3-5-sonnet": Config<keyof AllLlm>;
     "anthropic.claude-3-5-haiku": Config<keyof AllLlm>;
     "anthropic.claude-3-opus": Config<keyof AllLlm>;
+    "anthropic.claude-3-haiku": Config<keyof AllLlm>;
     "openai.chat.v1": Config<keyof AllLlm>;
     "openai.chat-mock.v1": Config<keyof AllLlm>;
+    "openai.gpt-5.2": Config<keyof AllLlm>;
+    "openai.gpt-5-mini": Config<keyof AllLlm>;
+    "openai.gpt-5-nano": Config<keyof AllLlm>;
+    "openai.gpt-4.1": Config<keyof AllLlm>;
+    "openai.gpt-4.1-mini": Config<keyof AllLlm>;
+    "openai.gpt-4.1-nano": Config<keyof AllLlm>;
+    "openai.o3": Config<keyof AllLlm>;
+    "openai.o4-mini": Config<keyof AllLlm>;
     "openai.gpt-4o": Config<keyof AllLlm>;
     "openai.gpt-4o-mini": Config<keyof AllLlm>;
 };
 
-declare function useLlm<T extends keyof typeof configs>(provider: T, options?: AllUseLlmOptions[T]["input"]): {
-    call: (messages: string | IChatMessages, options?: LlmExecutorWithFunctionsOptions) => Promise<BaseLlCall>;
+declare function useLlm<T extends keyof typeof configs>(provider: T, options?: AllUseLlmOptions[T]["input"]): BaseLlm;
+declare function useLlmConfiguration<T extends keyof typeof configs>(config: Config<any>): (options?: AllUseLlmOptions[T]["input"]) => {
+    call: (messages: string | IChatMessages, options?: LlmExecutorWithFunctionsOptions) => Promise<{
+        getResultContent: (index?: number) => OutputResultContent[];
+        getResultText: (index?: number) => string;
+        getResult: () => OutputResult;
+    }>;
     getTraceId: () => string | null;
     withTraceId: (id: string) => void;
     getMetadata: () => {
@@ -1387,6 +1552,14 @@ declare function useLlm<T extends keyof typeof configs>(provider: T, options?: A
     };
 };
 
+declare function createOpenAiCompatibleConfiguration<K extends Config["key"]>(overrides: {
+    key: string;
+    provider: string;
+    endpoint: string;
+    apiKeyMapping: [string, string];
+    transformResponse?: any;
+}): Config<keyof AllLlm>;
+
 declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, options: AllEmbedding[T]["input"]): {
     call: (messages: string | string[], options?: LlmExecutorWithFunctionsOptions) => Promise<{
         getEmbedding: (index?: number) => number[];
@@ -1406,4 +1579,4 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ExecutorContext, type IChatMessages, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type OpenAIModelName, OpenAiFunctionParser, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createParser, createPrompt, createState, createStateItem, defineSchema, guards, registerHelpers, registerPartials, useExecutors, useLlm, index as utils };
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ExecutorContext, type IChatMessages, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type OpenAIModelName, OpenAiFunctionParser, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };