llm-exe 3.0.0 → 3.1.0-beta.1

package/dist/types-CDOBItt6.d.mts

@@ -0,0 +1,1223 @@
+import { JSONSchema, FromSchema } from 'json-schema-to-ts';
+
+type PrimitiveValue = bigint | boolean | null | number | string | symbol | undefined;
+type ObjectValue = PrimitiveValue | PlainObject | ObjectArray;
+interface PlainObject {
+    [key: string]: ObjectValue;
+}
+interface ObjectArray extends Array<ObjectValue> {
+}
+interface Serializable {
+    serialize?(): Record<string, any>;
+    deserialize?(): void;
+}
+
+type IChatMessageRole = "system" | "model" | "assistant" | "user" | "function" | "function_call";
+interface IChatMessageContentDetailed {
+    type: string;
+    text?: string;
+    image_url?: {
+        url: string;
+    };
+}
+interface IChatMessageBase {
+    role: IChatMessageRole;
+    content: string | null | IChatMessageContentDetailed[];
+}
+interface IChatUserMessage extends IChatMessageBase {
+    role: Extract<IChatMessageRole, "user">;
+    content: string | IChatMessageContentDetailed[];
+    name?: string;
+}
+interface IChatFunctionMessage extends IChatMessageBase {
+    id?: string;
+    role: Extract<IChatMessageRole, "function">;
+    content: string;
+    name: string;
+}
+interface IChatAssistantMessage extends IChatMessageBase {
+    role: Extract<IChatMessageRole, "assistant" | "model">;
+    content: string;
+    function_call?: undefined;
+}
+interface IChatFunctionCallMessage extends IChatMessageBase {
+    role: Extract<IChatMessageRole, "function_call">;
+    content: null;
+    function_call: {
+        name: string;
+        arguments: string;
+        id?: string;
+    };
+}
+interface IChatSystemMessage extends IChatMessageBase {
+    role: Extract<IChatMessageRole, "system">;
+    content: string;
+}
+interface IChatMessagesPlaceholder {
+    role: "placeholder";
+    content: string;
+}
+type IPromptMessages = (IChatSystemMessage | IChatMessagesPlaceholder)[];
+type IPromptChatMessages = (IChatUserMessage | IChatAssistantMessage | IChatFunctionCallMessage | IChatSystemMessage | IChatMessagesPlaceholder | IChatFunctionMessage)[];
+type IChatMessage = IChatUserMessage | IChatAssistantMessage | IChatFunctionCallMessage | IChatSystemMessage | IChatFunctionMessage;
+type IChatMessages = IChatMessage[];
+
+/**
+ * BaseParser is an abstract class for parsing text and enforcing JSON schema on the parsed data.
+ */
+declare abstract class BaseParser<T = any, TInput = string> {
+    name: string;
+    target: "text" | "function_call";
+    /**
+     * Create a new BaseParser.
+     * @param name - The name of the parser.
+     * @param target - Whether the parser consumes text or function-call output.
+     */
+    constructor(name: string, target?: "text" | "function_call");
+    /**
+     * Parse the given text and return the parsed data.
+     * @abstract
+     * @param text - The text to parse.
+     * @param [attributes] - Optional attributes to use during parsing.
+     * @returns The parsed data.
+     */
+    abstract parse(text: TInput, attributes?: Record<string, any>): T;
+}
+declare abstract class BaseParserWithJson<S extends JSONSchema | undefined = undefined, T = S extends JSONSchema ? FromSchema<S> : Record<string, any>, TInput = string> extends BaseParser<T, TInput> {
+    schema: S;
+    validateSchema: boolean;
+    constructor(name: string, options: ParserSchemaOptions<S>);
+}
+
+/**
+ * v3 parser contract:
+ * Category: pass-through
+ * Mode: string pass-through
+ *
+ * Accepts any string and returns it exactly.
+ * Throws LlmExeError(parser.parse_failed) for non-string input.
+ * Executor output normalization owns OutputResult handling before parser
+ * invocation.
+ *
+ */
+declare class StringParser extends BaseParser<string> {
+    constructor();
+    parse(text: string, _attributes?: Record<string, any>): string;
+}
+
+declare function replaceTemplateString(templateString?: string, substitutions?: Record<string, any>, configuration?: PromptTemplateOptions): string;
+
+declare function replaceTemplateStringAsync(templateString?: string, substitutions?: Record<string, any>, configuration?: PromptTemplateOptions): Promise<string>;
+
+/**
+ * BasePrompt should be extended.
+ */
+declare abstract class BasePrompt<I extends Record<string, any>> {
+    readonly type: PromptType;
+    messages: IPromptMessages | IPromptChatMessages;
+    partials: PromptPartial[];
+    helpers: PromptHelper[];
+    validateInput: ValidateInputMode;
+    replaceTemplateString: typeof replaceTemplateString;
+    replaceTemplateStringAsync: typeof replaceTemplateStringAsync;
+    filters: {
+        pre: ((prompt: string) => string)[];
+        post: ((prompt: string) => string)[];
+    };
+    /**
+     * constructor description
+     * @param initialPromptMessage An initial message to add to the prompt.
+     */
+    constructor(initialPromptMessage?: string, options?: PromptOptions);
+    /**
+     * addToPrompt description
+     * @param content The message content
+     * @param role The role of the user. Defaults to system for base text prompt.
+     * @return instance of BasePrompt.
+     */
+    addToPrompt(content: string, role?: string): BasePrompt<I>;
+    /**
+     * addSystemMessage description
+     * @param content The message content
+     * @return returns BasePrompt so it can be chained.
+     */
+    addSystemMessage(content: string): this;
+    /**
+     * registerPartial description
+     * @param partialOrPartials Additional partials that can be made available to the template parser.
+     * @return BasePrompt so it can be chained.
+     */
+    registerPartial(partialOrPartials: PromptPartial | PromptPartial[]): this;
+    /**
+     * registerHelpers description
+     * @param helperOrHelpers Additional helper functions that can be made available to the template parser.
+     * @return BasePrompt so it can be chained.
+     */
+    registerHelpers(helperOrHelpers: PromptHelper | PromptHelper[]): this;
+    /**
+     * Returns the Handlebars-bearing strings that should be validated, along
+     * with a location label used for error context. Subclasses with structured
+     * message content (e.g. ChatPrompt) should override.
+     */
+    protected getTemplateContents(): {
+        content: string;
+        location: string;
+    }[];
+    protected preflightValidate(values: I): void;
+    /**
+     * format description
+     * @param values The message content
+     * @param separator The separator between messages. defaults to "\n\n"
+     * @return returns messages formatted with template replacement
+     */
+    format(values: I, separator?: string): string | IChatMessages;
+    /**
+     * format description
+     * @param values The message content
+     * @param separator The separator between messages. defaults to "\n\n"
+     * @return returns messages formatted with template replacement
+     */
+    formatAsync(values: I, separator?: string): Promise<string | IChatMessages>;
+    runPromptFilter(prompt: string, filters: ((prompt: string, values: I) => string)[], values: I): string;
+    getReplacements(values: I): Omit<I, "input"> & {
+        input: any;
+        _input: any;
+    };
+    /**
+     * Validates that `input` provides every variable referenced by this prompt's
+     * templates, and that every identifiable helper call is registered.
+     *
+     * @breaking v3: previously returned `this.messages.length > 0` with no
+     * `input` parameter. For the old behavior, read `prompt.messages.length > 0`
+     * directly.
+     *
+     * @throws LlmExeError with code `"prompt.missing_template_variable"` listing
+     * all missing variables and helpers.
+     */
+    validate(input: I): void;
+}
+
+type TextPromptType = "text";
+type ChatPromptType = "chat";
+type PromptType = TextPromptType | ChatPromptType;
+type PromptHelper = {
+    name: string;
+    handler: (args: any) => any;
+};
+type PromptPartial = {
+    name: string;
+    template: string;
+};
+type ValidateInputMode = false | "strict" | "warn";
+interface PromptTemplateOptions {
+    partials?: PromptPartial[];
+    helpers?: PromptHelper[];
+}
+interface PromptOptions extends PromptTemplateOptions {
+    preFilters?: ((prompt: string) => string)[];
+    postFilters?: ((prompt: string) => string)[];
+    replaceTemplateString?: (...args: any[]) => string;
+    /**
+     * Controls whether `format()` preflights input against the variables
+     * referenced by the prompt's templates. See `validate(input)`.
+     *
+     * - `false` (default): no preflight; rendering proceeds.
+     * - `"strict"`: throw `LlmExeError("prompt.missing_template_variable")` before rendering.
+     * - `"warn"`: emit a Node warning via `process.emitWarning` and continue rendering.
+     */
+    validateInput?: ValidateInputMode;
+}
+interface ChatPromptOptions extends PromptOptions {
+    allowUnsafeUserTemplate?: boolean;
+}
+
+/**
+ * BaseExecutor
+ * @template I - Input type.
+ * @template O - Output type.
+ * @template H - Hooks type.
+ */
+declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends BaseExecutorHooks = BaseExecutorHooks, R = any, HI = any> {
+    /**
+     * @property id - internal id of the executor
+     */
+    readonly id: string;
+    /**
+     * @property type - type of executor
+     */
+    type: string;
+    /**
+     * @property created - timestamp date created
+     */
+    readonly created: number;
+    /**
+     * @property name - name of executor
+     */
+    name: string;
+    /**
+     * @property executions -
+     */
+    executions: number;
+    traceId: string | null;
+    /**
+     * @property hooks - hooks to be ran during execution
+     */
+    hooks: any;
+    readonly allowedHooks: any[];
+    /**
+     * @property maxHooksPerEvent - Maximum number of hooks allowed per event
+     */
+    readonly maxHooksPerEvent: number;
+    constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<I, O, R, HI, H>);
+    abstract handler(input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<any>;
+    /**
+     * Build a per-call execution context snapshot. Captures the current
+     * execution metadata so the snapshot reflects state at the time it was
+     * taken (e.g. `handlerInput` becomes available after `getHandlerInput`).
+     */
+    protected snapshotContext(execution: ExecutorExecutionMetadata<I, O>): ExecutionContext<I, O>;
+    /**
+     *
+     * Used to filter the input of the handler.
+     *
+     * Throws a `TypeError` if `_input` is `null` or `undefined`. The declared
+     * input type is `I extends PlainObject`; omitting input or passing an
+     * explicit `null` is a contract violation with no valid coercion, so we
+     * surface it loudly rather than silently wrapping it.
+     *
+     * Non-object inputs (strings, numbers, arrays) are intentionally coerced
+     * to `{ input: value }` via {@link ensureInputIsObject}. This preserves the
+     * convenience pattern used by tool/function callables, which forward raw
+     * string arguments into an executor.
+     *
+     * @param _input
+     * @returns original input formatted for handler
+     */
+    getHandlerInput(_input: I, _metadata: ExecutorExecutionMetadata<I, any>, _options?: any): Promise<any>;
+    /**
+     *
+     * Used to filter the output of the handler
+     * @param _input
+     * @returns output O
+     */
+    getHandlerOutput(out: any, _metadata: ExecutorExecutionMetadata<any, O>, _options?: any, _context?: ExecutionContext<I, O>): O;
+    /**
+     *
+     * execute - Runs the executor
+     * @param _input
+     * @returns handler output
+     */
+    execute(_input: I, _options?: any): Promise<O>;
+    private collectHookErrors;
+    metadata(): Record<string, any>;
+    getMetadata(metadata?: Record<string, any>): ExecutorMetadata;
+    runHook(hook: keyof H, _metadata: ExecutorExecutionMetadata): HookErrorRecord[];
+    setHooks(hooks?: CoreExecutorHookInput<I, O, R, HI, H>): this;
+    removeHook(eventName: keyof H, fn: ListenerFunction): this;
+    on(eventName: keyof H, fn: ListenerFunction): this;
+    off(eventName: keyof H, fn: ListenerFunction): this;
+    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>;
+}
+
+declare abstract class BaseStateItem<T> implements Serializable {
+    protected key: string;
+    protected value: T;
+    protected initialValue: T;
+    constructor(key: string, initialValue: T);
+    setValue(value: T): void;
+    getKey(): string;
+    getValue(): T;
+    resetValue(): void;
+    serializeValue(): {
+        [x: string]: T;
+    };
+    serialize(): {
+        class: string;
+        name: string;
+        value: any;
+    };
+}
+declare class DefaultStateItem extends BaseStateItem<any> {
+    constructor(name: string, defaultValue: any);
+}
+
+declare class Dialogue extends BaseStateItem<IChatMessages> {
+    name: string;
+    constructor(name: string);
+    setUserMessage(content: string | IChatMessageContentDetailed[], name?: string): this;
+    setAssistantMessage(content: string | OutputResultsText): this;
+    setSystemMessage(content: string): this;
+    setToolMessage(content: string, name: string, id?: string): this;
+    setFunctionMessage(content: string, name: string, id?: string): this;
+    /**
+     * Set
+     */
+    setToolCallMessage(input: {
+        name: string;
+        arguments: string;
+        id?: string;
+    }): this;
+    setFunctionCallMessage(input: {
+        name: string;
+        arguments: string;
+        id?: string;
+    } | {
+        function_call: {
+            name: string;
+            arguments: string;
+            id?: string;
+        };
+    }): this;
+    setMessageTurn(userMessage: string, assistantMessage: string, systemMessage?: string): this;
+    /**
+     * Aliases using `add*` naming to match ChatPrompt's API.
+     * These delegate to the corresponding `set*` methods.
+     */
+    addUserMessage(content: string | IChatMessageContentDetailed[], name?: string): this;
+    addAssistantMessage(content: string | OutputResultsText): this;
+    addSystemMessage(content: string): this;
+    addToolMessage(content: string, name: string, id?: string): this;
+    addToolCallMessage(input: {
+        name: string;
+        arguments: string;
+        id?: string;
+    }): this;
+    addFunctionMessage(content: string, name: string, id?: string): this;
+    addFunctionCallMessage(input: {
+        name: string;
+        arguments: string;
+        id?: string;
+    } | {
+        function_call: {
+            name: string;
+            arguments: string;
+            id?: string;
+        };
+    }): this;
+    addMessageTurn(userMessage: string, assistantMessage: string, systemMessage?: string): this;
+    addHistory(messages: IChatMessages): this;
+    setHistory(messages: IChatMessages): this;
+    getHistory(): IChatMessages;
+    serialize(): {
+        class: string;
+        name: string;
+        value: IChatMessage[];
+    };
+    /**
+     * Add LLM output to dialogue history in the order it was returned
+     *
+     * @param output - The LLM output result from llm.call()
+     * @returns this for chaining
+     */
+    addFromOutput(output: OutputResult | BaseLlCall): this;
+}
+
+declare abstract class BaseState {
+    dialogues: {
+        [key in string]: Dialogue;
+    };
+    attributes: Record<string, any>;
+    context: Record<string, BaseStateItem<any>>;
+    constructor();
+    createDialogue(name?: string): Dialogue;
+    useDialogue(name?: string): Dialogue;
+    getDialogue(name?: string): Dialogue;
+    createContextItem<T extends BaseStateItem<any>>(item: T): T;
+    getContext<T>(key: string): BaseStateItem<T>;
+    getContextValue<T>(key: string): T;
+    setAttribute(key: string, value: any): void;
+    deleteAttribute(key: string): void;
+    clearAttributes(): void;
+    serialize(): {
+        dialogues: any;
+        context: any;
+        attributes: any;
+    };
+    abstract saveState(): Promise<void>;
+}
+declare class DefaultState extends BaseState {
+    constructor();
+    saveState(): Promise<void>;
+}
+
+/**
+ * Core Executor With LLM
+ */
+declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser<any, any>, State extends BaseState> extends BaseExecutor<PromptInput<Prompt>, ParserOutput<Parser>, LlmExecutorHooks, BaseLlCall, ReturnType<Prompt["format"]>> {
+    llm: Llm;
+    prompt: Prompt | undefined;
+    promptFn: any;
+    parser: StringParser | Parser;
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<Parser>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
+    /**
+     * Runs the executor against the configured LLM and prompt.
+     *
+     * `null` and `undefined` are rejected with a `TypeError`: the declared
+     * input type requires an object, and silently coercing missing input hides a
+     * clear contract violation. Use `{}` for prompts that declare no template
+     * variables. See issue #410.
+     */
+    execute(_input: PromptInput<Prompt>, _options?: LlmExecutorExecuteOptions): Promise<ParserOutput<Parser>>;
+    handler(_input: PromptInput<Prompt>, _options?: LlmExecutorExecuteOptions, _context?: ExecutionContext<PromptInput<Prompt>, ParserOutput<Parser>>): Promise<any>;
+    getHandlerInput(_input: PromptInput<Prompt>): Promise<any>;
+    getHandlerOutput(out: BaseLlCall, _metadata: ExecutorExecutionMetadata<PromptInput<Prompt>, ParserOutput<Parser>>, _options?: LlmExecutorExecuteOptions, _context?: ExecutionContext<PromptInput<Prompt>, ParserOutput<Parser>>): ParserOutput<Parser>;
+    metadata(): {
+        llm: Record<string, any>;
+    };
+    getTraceId(): string | null;
+}
+
+declare const hookOnComplete = "onComplete";
+declare const hookOnError = "onError";
+declare const hookOnSuccess = "onSuccess";
+
+type ListenerFunction = (...args: any[]) => void;
+type ParserOutput<P> = P extends BaseParser<infer T, any> ? T : never;
+type PromptInput<P> = P extends BasePrompt<infer T> ? T : never;
+interface ExecutorWithLlmOptions<Llm, Prompt, Parser, State> {
+    name?: string;
+    llm: Llm;
+    prompt: Prompt | ((values: PromptInput<Prompt>) => Prompt);
+    parser?: Parser;
+    state?: State;
+    __mock_response_key__?: string;
+}
+interface CoreExecutorInput<I, O> {
+    name?: string;
+    handler: (input: I, context?: ExecutionContext<I, O>) => Promise<O> | O;
+    getHandlerInput?(input: I): Promise<any>;
+    getHandlerOutput?(out: any): O;
+}
+type FunctionOrExecutor<I extends PlainObject | {
+    input: string;
+}, O> = ((input: I) => Promise<O> | O) | BaseExecutor<I, O>;
+interface ExecutorMetadata {
+    id: string;
+    type: string;
+    name: string;
+    created: number;
+    executions: number;
+    metadata?: Record<string, any>;
+}
+interface HookErrorRecord {
+    hook: string;
+    error: unknown;
+    errorMessage: string;
+    errorCategory?: string;
+    errorCode?: string;
+    errorContext?: unknown;
+    errorCause?: unknown;
+}
+interface ExecutorExecutionMetadata<I = any, O = any, R = any, HI = any> {
+    start: null | number;
+    end: null | number;
+    input: I;
+    handlerInput?: HI;
+    handlerOutput?: R;
+    output?: O;
+    errorMessage?: string;
+    error?: Error;
+    errorCategory?: string;
+    errorCode?: string;
+    errorContext?: unknown;
+    errorCause?: unknown;
+    hookErrors?: HookErrorRecord[];
+    metadata?: null | ExecutorMetadata;
+}
+interface ExecutorContext<I = any, O = any, A = Record<string, any>> extends ExecutorExecutionMetadata<I, O> {
+    metadata: ExecutorMetadata;
+    attributes: A;
+}
+/**
+ * Per-call execution context. Built by `BaseExecutor.execute()` and threaded
+ * through `handler()`, `llm.call()`, parsers, and warnings. Provides a single
+ * place to read the resolved trace ID, stable executor identity, and the
+ * mutable execution state for the current run.
+ */
+interface ExecutionContext<I = any, O = any, A = Record<string, any>> {
+    traceId?: string;
+    executor: ExecutorMetadata;
+    execution: ExecutorExecutionMetadata<I, O>;
+    attributes: A;
+}
+interface BaseExecutorHooks {
+    [hookOnError]: ListenerFunction[];
+    [hookOnSuccess]: ListenerFunction[];
+    [hookOnComplete]: ListenerFunction[];
+}
+interface LlmExecutorHooks extends BaseExecutorHooks {
+}
+/**
+ * A single executor hook callback. Receives the per-run execution metadata
+ * (input/output/error fields typed via I/O) followed by the executor's own
+ * identity metadata. This is the shape fired for onSuccess / onError /
+ * onComplete — the metadata fields that are populated differ per event
+ * (`output` on success, `error` on failure), but all are optional on
+ * {@link ExecutorExecutionMetadata}, so one signature covers every hook.
+ */
+type ExecutorHookFunction<I = any, O = any, R = any, HI = any> = (metadata: ExecutorExecutionMetadata<I, O, R, HI>, executor: ExecutorMetadata) => void;
+type CoreExecutorHookInput<I = any, O = any, R = any, HI = any, H = BaseExecutorHooks> = {
+    [key in keyof H]?: ExecutorHookFunction<I, O, R, HI> | ExecutorHookFunction<I, O, R, HI>[];
+};
+interface CoreExecutorExecuteOptions<I = any, O = any, R = any, HI = any, T = BaseExecutorHooks> {
+    hooks?: CoreExecutorHookInput<I, O, R, HI, T>;
+}
+interface CallableExecutorCore {
+    name: string;
+    description: string;
+    parameters?: Record<string, any>;
+}
+interface LlmExecutorExecuteOptions {
+    functions?: CallableExecutorCore[];
+    functionCall?: any;
+    jsonSchema?: Record<string, any>;
+}
+type GenericFunctionCall = "auto" | "none" | "any" | {
+    name: string;
+};
+interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"> extends LlmExecutorExecuteOptions {
+    functions?: CallableExecutorCore[];
+    functionCall?: T;
+    functionCallStrictInput?: boolean;
+    jsonSchema?: Record<string, any>;
+}
+
+type CreateParserType = "json" | "string" | "boolean" | "number" | "stringExtract" | "listToArray" | "listToJson" | "listToKeyValue" | "replaceStringTemplate" | "markdownCodeBlocks" | "markdownCodeBlock";
+interface ParserSchemaOptions<S extends JSONSchema | undefined = undefined> {
+    schema?: S;
+    validateSchema?: boolean;
+}
+type JsonParserMatch = "exact" | "extract";
+interface JsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
+    match?: JsonParserMatch;
+}
+interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
+    keyTransform?: "camelCase" | "preserve";
+}
+
+/**
+ * Internal Formats
+ */
+interface OutputResultsBase {
+    type: "text" | "function_use";
+    text?: string;
+}
+interface OutputResultsText extends OutputResultsBase {
+    type: "text";
+    text: string;
+}
+interface OutputResultsFunction extends OutputResultsBase {
+    type: "function_use";
+    name: string;
+    input: Record<string, any>;
+    functionId: string;
+}
+type OutputResultContent = OutputResultsText | OutputResultsFunction;
+interface OutputResult {
+    id: string;
+    name?: string;
+    created: number;
+    stopReason: string;
+    content: OutputResultContent[];
+    options?: OutputResultContent[][];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    };
+}
+interface EmbeddingOutputResult {
+    id: string;
+    model?: string;
+    created: number;
+    embedding: number[][];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    };
+}
+interface BaseLlmOptions {
+    traceId?: null | string;
+    timeout?: number;
+    maxDelay?: number;
+    numOfAttempts?: number;
+    jitter?: "none" | "full";
+    promptType?: PromptType;
+    endpoint?: string;
+    headers?: Record<string, string>;
+}
+interface GenericEmbeddingOptions extends BaseLlmOptions {
+    model?: string;
+    dimensions?: number;
+}
+interface OpenAiEmbeddingOptions extends GenericEmbeddingOptions {
+    model?: string;
+    openAiApiKey?: string;
+    baseUrl?: string;
+}
+interface AmazonEmbeddingOptions extends GenericEmbeddingOptions {
+    model: string;
+    awsRegion?: string;
+    awsSecretKey?: string;
+    awsAccessKey?: string;
+}
+interface CohereBedrockEmbeddingOptions extends AmazonEmbeddingOptions {
+    inputType?: "search_document" | "search_query" | "classification" | "clustering";
+    truncate?: "NONE" | "START" | "END" | "LEFT" | "RIGHT";
+}
+interface GenericLLm extends BaseLlmOptions {
+    model?: string;
+    system?: string;
+    prompt?: string | {
+        role: string;
+        content: string;
+    }[];
+    temperature?: number;
+    topP?: number;
+    stream?: boolean;
+    streamOptions?: Record<string, any>;
+    maxTokens?: number;
+    stopSequences?: string[];
+    effort?: "minimal" | "low" | "medium" | "high";
+}
+interface OpenAiRequest extends GenericLLm {
+    model: string;
+    frequencyPenalty?: number;
+    logitBias?: Record<string, any> | null;
+    responseFormat?: Record<string, any>;
+    openAiApiKey?: string;
+    useJson?: boolean;
+}
+interface XAiRequest extends GenericLLm {
+    model: string;
+    frequencyPenalty?: number;
+    logitBias?: Record<string, any> | null;
+    responseFormat?: Record<string, any>;
+    xAiApiKey?: string;
+    useJson?: boolean;
+}
+interface AmazonBedrockRequest extends GenericLLm {
+    model: string;
+    awsRegion?: string;
+    awsSecretKey?: string;
+    awsAccessKey?: string;
+}
+interface AnthropicRequest extends GenericLLm {
+    model: string;
+    anthropicApiKey?: string;
+    topK?: number;
+    metadata?: {
+        user_id?: string;
+    };
+    serviceTier?: "auto" | "standard_only";
+}
+interface GeminiRequest extends GenericLLm {
+    model: string;
+    geminiApiKey?: string;
+}
+interface DeepseekRequest extends GenericLLm {
+    model: string;
+    responseFormat?: Record<string, any>;
+    deepseekApiKey?: string;
+    useJson?: boolean;
+}
+type AllEmbedding = {
+    "openai.embedding.v1": {
+        input: OpenAiEmbeddingOptions;
+    };
+    "amazon.embedding.v1": {
+        input: AmazonEmbeddingOptions;
+    };
+    "amazon:cohere.embedding.v1": {
+        input: CohereBedrockEmbeddingOptions;
+    };
+};
+type AllLlm = {
+    "openai.chat.v1": {
+        input: OpenAiRequest;
+    };
+    "openai.chat-mock.v1": {
+        input: OpenAiRequest;
+    };
+    "anthropic.chat.v1": {
+        input: AnthropicRequest;
+    };
+    "amazon:anthropic.chat.v1": {
+        input: AnthropicRequest & AmazonBedrockRequest;
+    };
+    "amazon:meta.chat.v1": {
+        input: AmazonBedrockRequest;
+    };
+    "xai.chat.v1": {
+        input: XAiRequest;
+    };
+    "ollama.chat.v1": {
+        input: GenericLLm;
+    };
+    "google.chat.v1": {
+        input: GeminiRequest;
+    };
+    "deepseek.chat.v1": {
+        input: DeepseekRequest;
+    };
+};
+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.gpt-4": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-4o": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-4o-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.o4-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "anthropic.claude-opus-4-8": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4-7": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-sonnet-4-6": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4-5": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-haiku-4-5": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-sonnet-4-5": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4-6": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4-1": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-sonnet-4-0": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4-0": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-sonnet-4": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-opus-4": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "anthropic.claude-3-7-sonnet": {
+        input: Omit<AnthropicRequest, "model">;
+    };
+    "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">;
+    };
+    "google.gemini-2.5-flash": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-2.5-flash-lite": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-2.5-pro": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-3.1-flash-lite": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-3.5-flash": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-2.0-flash": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-2.0-flash-lite": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "google.gemini-1.5-pro": {
+        input: Omit<GeminiRequest, "model">;
+    };
+    "xai.grok-2": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-3": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-3-mini": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4-fast": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4-1-fast": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4.3": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4.20": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "xai.grok-4.20-reasoning": {
+        input: Omit<XAiRequest, "model">;
+    };
+    "ollama.deepseek-r1": {
+        input: GenericLLm;
+    };
+    "ollama.llama3.3": {
+        input: GenericLLm;
+    };
+    "ollama.llama3.2": {
+        input: GenericLLm;
+    };
+    "ollama.llama3.1": {
+        input: GenericLLm;
+    };
+    "ollama.qwq": {
+        input: GenericLLm;
+    };
+    "ollama.gemma3": {
+        input: GenericLLm;
+    };
+    "ollama.mistral": {
+        input: GenericLLm;
+    };
+    "ollama.qwen2.5": {
+        input: GenericLLm;
+    };
+    "ollama.qwen3": {
+        input: GenericLLm;
+    };
+    "ollama.qwen3.5": {
+        input: GenericLLm;
+    };
+    "ollama.gemma4": {
+        input: GenericLLm;
+    };
+    "ollama.gpt-oss": {
+        input: GenericLLm;
+    };
+    "deepseek.chat": {
+        input: DeepseekRequest;
+    };
+    "deepseek.v4-flash": {
+        input: Omit<DeepseekRequest, "model">;
+    };
+    "deepseek.v4-pro": {
+        input: Omit<DeepseekRequest, "model">;
+    };
+};
+type LlmProviderKey = keyof AllLlm;
+type EmbeddingProviderKey = keyof AllEmbedding;
+type UseLlmKey = keyof AllUseLlmOptions;
+interface BaseLlCall {
+    getResultContent: () => OutputResultContent[];
+    getResultText: () => string;
+    getResult: () => OutputResult;
+}
+interface BaseRequest<_T extends Record<string, any>> {
+    call: (...args: any[]) => Promise<_T>;
+    getTraceId: () => string | null;
+    withTraceId: (traceId: string) => void;
+    getMetadata: () => Record<string, any>;
+}
+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" | "amazon:cohere.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;
+    /**
+     * 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 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 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;
+        };
+    };
+    /**
+     * 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>;
+    };
+    /**
+     * Optional response transformer for chat/LLM configs. The LLM call path
+     * (`llm.call.ts`) defaults to `OutputDefault` when this is omitted.
+     * Embedding configs do not use this — their flow dispatches via
+     * `getEmbeddingOutputParser` instead.
+     */
+    transformResponse?: (result: any, _config?: Config<any>, headers?: Record<string, string>) => OutputResult;
+    /**
+     * Marks this config as deprecated. When set, useLlm() will emit a one-time
+     * deprecation warning to inform users about upcoming model shutdowns.
+     */
+    deprecated?: {
+        shorthand: string;
+        message: string;
+    };
+}
+
+declare const configs: {
+    "deepseek.chat.v1": Config<keyof AllLlm>;
+    "deepseek.chat": Config<keyof AllLlm>;
+    "deepseek.v4-flash": Config<keyof AllLlm>;
+    "deepseek.v4-pro": Config<keyof AllLlm>;
+    "google.gemini-2.0-flash": Config<keyof AllLlm>;
+    "google.gemini-2.0-flash-lite": Config<keyof AllLlm>;
+    "google.gemini-1.5-pro": Config<keyof AllLlm>;
+    "google.gemini-2.5-pro": Config<any>;
+    "google.gemini-2.5-flash-lite": Config<any>;
+    "google.gemini-2.5-flash": Config<any>;
+    "google.chat.v1": Config<keyof AllLlm>;
+    "google.gemini-3.1-flash-lite": Config<keyof AllLlm>;
+    "google.gemini-3.5-flash": Config<keyof AllLlm>;
+    "ollama.chat.v1": Config<keyof AllLlm>;
+    "ollama.deepseek-r1": Config<keyof AllLlm>;
+    "ollama.llama3.3": Config<keyof AllLlm>;
+    "ollama.llama3.2": Config<keyof AllLlm>;
+    "ollama.llama3.1": Config<keyof AllLlm>;
+    "ollama.qwq": Config<keyof AllLlm>;
+    "ollama.gemma3": Config<keyof AllLlm>;
+    "ollama.mistral": Config<keyof AllLlm>;
+    "ollama.qwen2.5": Config<keyof AllLlm>;
+    "ollama.qwen3": Config<keyof AllLlm>;
+    "ollama.qwen3.5": Config<keyof AllLlm>;
+    "ollama.gemma4": Config<keyof AllLlm>;
+    "ollama.gpt-oss": Config<keyof AllLlm>;
+    "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>;
+    "xai.grok-4-1-fast": Config<keyof AllLlm>;
+    "xai.grok-4.3": Config<keyof AllLlm>;
+    "xai.grok-4.20": Config<keyof AllLlm>;
+    "xai.grok-4.20-reasoning": Config<keyof AllLlm>;
+    "amazon:anthropic.chat.v1": Config<keyof AllLlm>;
+    "amazon:meta.chat.v1": Config<keyof AllLlm>;
+    "anthropic.claude-3-opus": Config<any>;
+    "anthropic.claude-3-5-haiku": Config<any>;
+    "anthropic.claude-3-5-sonnet": Config<any>;
+    "anthropic.claude-3-7-sonnet": Config<any>;
+    "anthropic.claude-opus-4": Config<any>;
+    "anthropic.claude-sonnet-4": Config<any>;
+    "anthropic.claude-opus-4-1": Config<any>;
+    "anthropic.claude-opus-4-6": Config<any>;
+    "anthropic.chat.v1": Config<keyof AllLlm>;
+    "anthropic.claude-opus-4-8": Config<keyof AllLlm>;
+    "anthropic.claude-opus-4-7": Config<keyof AllLlm>;
+    "anthropic.claude-sonnet-4-6": Config<keyof AllLlm>;
+    "anthropic.claude-opus-4-5": Config<keyof AllLlm>;
+    "anthropic.claude-haiku-4-5": Config<keyof AllLlm>;
+    "anthropic.claude-sonnet-4-5": Config<keyof AllLlm>;
+    "openai.o4-mini": Config<any>;
+    "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.gpt-4": Config<keyof AllLlm>;
+    "openai.gpt-4o": Config<keyof AllLlm>;
+    "openai.gpt-4o-mini": Config<keyof AllLlm>;
+};
+
+/**
+ * Serialization formats a config can arrive in. `auto` is best-effort
+ * detection (JSON → YAML → markdown) for sources whose extension is unknown.
+ */
+type Format = "json" | "yaml" | "markdown" | "auto";
+/**
+ * A `useLlm` provider key — e.g. "openai.chat.v1", "openai.gpt-4.1",
+ * "openai.chat-mock.v1". NOT a friendly vendor name like "openai".
+ */
+type ProviderKey = keyof typeof configs;
+/**
+ * Construction-time options for the executor (hooks, etc.). This is the
+ * SECOND arg to `createLlm*Executor`, kept distinct from `executorOptions`
+ * (which is execute-time state, the second arg to `.execute()`).
+ *
+ * `CoreExecutorExecuteOptions` now leads with the executor's I/O/R/HI type
+ * params; the hook key set is the LAST param. A config-driven executor can't
+ * know those concrete types, so they stay `any` and only the hook set is
+ * pinned to `LlmExecutorHooks`.
+ */
+type ExecutorCreateOptions = CoreExecutorExecuteOptions<any, any, any, any, LlmExecutorHooks>;
+/**
+ * Canonical normalized config. The JSON Schema in `schema.ts` validates this
+ * shape; every loader funnels into it via `normalizeConfig`.
+ */
+interface ExecutorConfig {
+    provider: ProviderKey;
+    model?: string;
+    system?: string;
+    message: string;
+    parser: CreateParserType;
+    parserOptions?: Record<string, unknown>;
+    llmOptions?: Record<string, unknown>;
+    executorOptions?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}
+/**
+ * Runtime overrides applied over a parsed config. Precedence: caller (patch)
+ * > file > defaults. `data` is deep-merged; every other field is replace-on-set.
+ */
+interface ExecutorConfigPatch {
+    data?: Record<string, unknown>;
+    model?: string;
+    provider?: ProviderKey;
+    parser?: CreateParserType;
+    parserOptions?: Record<string, unknown>;
+    llmOptions?: Record<string, unknown>;
+    executorOptions?: Record<string, unknown>;
+    system?: string;
+    message?: string;
+}
+/**
+ * Per-run overrides for the terminal "run once" helpers (`runConfig`,
+ * `runFile`). `data` deep-merges over `config.data`; `executorOptions`
+ * shallow-merges over `config.executorOptions`.
+ */
+interface RunOverrides {
+    data?: Record<string, unknown>;
+    executorOptions?: Record<string, unknown>;
+}
+
+export { type AllLlm as $, type CallableExecutorCore as A, BaseParser as B, type ChatPromptType as C, DefaultState as D, type ExecutorConfigPatch as E, type FunctionOrExecutor as F, type GenericFunctionCall as G, type PromptPartial as H, type IPromptChatMessages as I, type JsonParserOptions as J, type PromptHelper as K, LlmExecutor as L, replaceTemplateString as M, replaceTemplateStringAsync as N, type OutputResultContent as O, type ParserOutput as P, type OutputResultsText as Q, type RunOverrides as R, StringParser as S, type OutputResultsFunction as T, type IChatMessage as U, type IChatUserMessage as V, type IChatAssistantMessage as W, type IChatSystemMessage as X, configs as Y, type AllUseLlmOptions as Z, type Config as _, type ExecutorConfig as a, type EmbeddingProviderKey as a0, type AllEmbedding as a1, type EmbeddingOutputResult as a2, type Format as a3, BaseStateItem as a4, type CreateParserType as a5, type LlmProvider as a6, type ExecutorContext as a7, type ExecutorExecutionMetadata as a8, type HookErrorRecord as a9, type LlmProviderKey as aa, type UseLlmKey as ab, type JsonParserMatch as ac, type ExecutorCreateOptions as b, BaseParserWithJson as c, type ListToJsonParserOptions as d, type ExecutionContext as e, type OutputResult as f, BasePrompt as g, type PromptOptions as h, type ChatPromptOptions as i, type IChatMessageRole as j, type IChatMessageContentDetailed as k, type IChatMessages as l, type PromptType as m, type PlainObject as n, BaseExecutor as o, type CoreExecutorInput as p, type CoreExecutorExecuteOptions as q, DefaultStateItem as r, Dialogue as s, type BaseLlm as t, BaseState as u, type ExecutorWithLlmOptions as v, type PromptInput as w, type BaseLlCall as x, type LlmExecutorHooks as y, type LlmExecutorWithFunctionsOptions as z };