API: @loopstack/llm-provider-module

Classes

LlmContextDocument

Document that represents hidden LLM conversation context (never shown in Studio).

Persisted server-side and included by LLM providers when building conversation history (tagged 'message'), but marked internal: true so it is excluded from Studio’s document responses and never renders as a chat bubble. Its role is narrowed to 'user' | 'assistant'. Use it to seed the model with system context, prior steps, or workflow background the end user should not see.


import { LlmContextDocument } from '@loopstack/llm-provider-module';


export class LlmContextDocument extends MessageDocument {
    role: 'user' | 'assistant';
}

LlmDelegateToolCallsTool

Tool that executes the tool calls contained in an LLM response.

Extracts tool-use blocks from the normalized message, resolves them via the ToolRegistry, and runs them through LlmDelegateService , scheduling async completions against the provided callback.transition. Returns an LlmDelegateResult summarizing completed, pending, and errored tool calls, and saves the results as an LlmMessageDocument unless config.save is false.


import { LlmDelegateToolCallsTool } from '@loopstack/llm-provider-module';

Provided by: LlmProviderModule


export class LlmDelegateToolCallsTool extends BaseTool<LlmDelegateToolCallsToolArgs, LlmDelegateToolCallsConfig, LlmDelegateResult> {
    protected handle(args: LlmDelegateToolCallsToolArgs, _ctx: RunContext, options?: ToolCallOptions<LlmDelegateToolCallsConfig>): Promise<ToolEnvelope<LlmDelegateResult>>;
}

LlmGenerateObjectTool

Tool that generates a structured object conforming to a Zod/JSON schema via the configured LLM provider.

Takes a prompt or messages plus an outputSchema (a Zod schema converted to JSON Schema) and resolves provider, model, and system prompt from options.config. Returns an LlmGenerateObjectResult whose data matches the schema, with usage in LlmResultMeta.


import { LlmGenerateObjectTool } from '@loopstack/llm-provider-module';

Provided by: LlmProviderModule


export class LlmGenerateObjectTool extends BaseTool<LlmGenerateObjectArgs, LlmGenerateObjectConfig, LlmGenerateObjectResult, LlmResultMeta> {
    protected handle(args: LlmGenerateObjectArgs, ctx: RunContext, options?: ToolCallOptions<LlmGenerateObjectConfig>): Promise<ToolEnvelope<LlmGenerateObjectResult, LlmResultMeta>>;
}

LlmGenerateTextTool

Tool that generates text with the configured LLM provider.

Accepts a prompt or a messages array and resolves provider, model, system prompt, and tool names from options.config. Resolved tool names are turned into provider tool definitions, and output is streamed to the client when streaming is available. Returns an LlmGenerateTextResult with provider/model usage in LlmResultMeta.


import { LlmGenerateTextTool } from '@loopstack/llm-provider-module';

Provided by: LlmProviderModule


export class LlmGenerateTextTool extends BaseTool<LlmGenerateTextArgs, LlmGenerateTextConfig, LlmGenerateTextResult, LlmResultMeta> {
    protected handle(args: LlmGenerateTextArgs, ctx: RunContext, options?: ToolCallOptions<LlmGenerateTextConfig>): Promise<ToolEnvelope<LlmGenerateTextResult, LlmResultMeta>>;
}

LlmMessageDocument

Document that renders an LLM chat message in Studio.

Extends MessageDocument with a narrowed role of 'user' | 'assistant', an optional message id, structured blocks (LLM content blocks), and a stopReason. Tagged 'message' so it participates in conversation history, and rendered via the llm-message.document.yaml widget.


import { LlmMessageDocument } from '@loopstack/llm-provider-module';


export class LlmMessageDocument extends MessageDocument {
    role: 'user' | 'assistant';
    id?: string;
    blocks?: LlmContentBlock[];
    stopReason?: LlmStopReason;
}

LlmProviderModule

NestJS module that provides the LLM tools (LlmGenerateTextTool, LlmGenerateObjectTool, LlmDelegateToolCallsTool, LlmUpdateToolResultTool) and the provider registry, configured with provider/model defaults.

Registration:

LlmProviderModule (bare import) — registers the global root with the default (empty) config; pair it with a provider module and set provider/model per call.
LlmProviderModule.forRoot(config) — sets the app-wide default LlmModuleConfig (default provider/model). Import once at the root.
LlmProviderModule.forFeature(config) — overrides the config for one module’s tools without re-registering the global root. Use for a feature-scoped default.

Requires: a registered provider module (e.g. ClaudeModule / OpenAiModule) imported alongside it — this module holds the registry, the provider modules populate it.


import { LlmProviderModule } from '@loopstack/llm-provider-module';


export class LlmProviderModule {
    static forRoot(config: LlmModuleConfig): DynamicModule;
    static forFeature(config: LlmModuleConfig): DynamicModule;
}

LlmUpdateToolResultTool

Tool that records an async tool completion and updates a pending delegate result.

Handles the callback fired when a delegated tool finishes: it merges completedTool into the supplied delegateResult via LlmDelegateService and returns the updated LlmDelegateResult. Once all tool calls complete, results are saved as an LlmMessageDocument unless config.save is false.


import { LlmUpdateToolResultTool } from '@loopstack/llm-provider-module';

Provided by: LlmProviderModule


export class LlmUpdateToolResultTool extends BaseTool<LlmUpdateToolResultToolArgs, LlmUpdateToolResultConfig, LlmDelegateResult> {
    protected handle(args: LlmUpdateToolResultToolArgs, _ctx: RunContext, options?: ToolCallOptions<LlmUpdateToolResultConfig>): Promise<ToolEnvelope<LlmDelegateResult>>;
}

Interfaces

LlmDelegateResult

Result returned by tool-call delegation (LlmDelegateToolCallsTool and LlmUpdateToolResultTool).

allCompleted — whether every delegated tool call has finished.
toolResults — the collected LlmToolResultEntry items.
pendingCount — number of tool calls still awaiting completion.
errorCount / hasErrors / errors — error count, flag, and the LlmToolErrorEntry details.


import { LlmDelegateResult } from '@loopstack/llm-provider-module';


export interface LlmDelegateResult {
    allCompleted: boolean;
    toolResults: LlmToolResultEntry[];
    pendingCount: number;
    errorCount: number;
    hasErrors: boolean;
    errors: LlmToolErrorEntry[];
}

LlmGenerateObjectResult

Result returned by the generateObject provider operation (and LlmGenerateObjectTool) — the structured data matching the output schema plus the native response.


import { LlmGenerateObjectResult } from '@loopstack/llm-provider-module';


export interface LlmGenerateObjectResult {
    data: unknown;
    response: unknown;
}

LlmGenerateTextResult

Result returned by the generateText provider operation (and LlmGenerateTextTool).

message — the normalized assistant message produced by the provider.
response — the unmodified native API response (Anthropic.Message, OpenAI.ChatCompletion, etc.).


import { LlmGenerateTextResult } from '@loopstack/llm-provider-module';


export interface LlmGenerateTextResult {
    message: LlmNormalizedMessage;
    response: unknown;
}

LlmMessage

An inline message authors pass as prompt args — a role plus text and/or structured blocks.


import { LlmMessage } from '@loopstack/llm-provider-module';


export interface LlmMessage {
    role: 'user' | 'assistant';
    text?: string;
    blocks?: LlmContentBlock[];
}

LlmModuleConfig

Config for LlmProviderModule — the default provider and model passed to forRoot() / forFeature().


import { LlmModuleConfig } from '@loopstack/llm-provider-module';


export interface LlmModuleConfig {
    provider?: string;
    model?: string;
}

LlmToolErrorEntry

A single tool-call error collected during delegation (part of LlmDelegateResult).


import { LlmToolErrorEntry } from '@loopstack/llm-provider-module';


export interface LlmToolErrorEntry {
    toolName: string;
    toolCallId: string;
    message: string;
}

LlmToolResultEntry

A single tool-call result collected during delegation (part of LlmDelegateResult).


import { LlmToolResultEntry } from '@loopstack/llm-provider-module';


export interface LlmToolResultEntry {
    type: 'tool_result';
    toolCallId: string;
    content?: string;
    isError?: boolean;
}

LlmUsage

Token usage stats reported by a provider for one LLM call.


import { LlmUsage } from '@loopstack/llm-provider-module';


export interface LlmUsage {
    inputTokens: number;
    outputTokens: number;
    cacheCreationInputTokens?: number;
    cacheReadInputTokens?: number;
    reasoningTokens?: number;
}

Type Aliases

LlmConfig

Config for shared LLM passthrough, inferred from LlmConfigSchema.


import { LlmConfig } from '@loopstack/llm-provider-module';


export type LlmConfig = z.infer<typeof LlmConfigSchema>;

LlmContentBlock

A single block of LLM message content (text, tool call, tool result, etc.).


import { LlmContentBlock } from '@loopstack/llm-provider-module';


export type LlmContentBlock = UIContentBlock;

LlmNormalizedMessage

A provider-normalized LLM message, inferred from LlmNormalizedMessageSchema.


import { LlmNormalizedMessage } from '@loopstack/llm-provider-module';


export type LlmNormalizedMessage = z.infer<typeof LlmNormalizedMessageSchema>;

LlmResultMeta

Metadata returned by the LLM tools (LlmResultMeta carries the resolved provider, model, and LlmUsage).


import { LlmResultMeta } from '@loopstack/llm-provider-module';


export type LlmResultMeta = {
    provider: string;
    model: string;
    usage?: LlmUsage;
};

LlmStopReason

The reason an LLM turn stopped (end_turn, tool_use, max_tokens, stop_sequence).


import { LlmStopReason } from '@loopstack/llm-provider-module';


export type LlmStopReason = NonNullable<LlmNormalizedMessage['stopReason']>;

Variables

LlmConfigSchema

Zod schema for the shared LLM config — import in parent workflows/tools to pass model through as args.


import { LlmConfigSchema } from '@loopstack/llm-provider-module';


LlmConfigSchema: z.ZodObject<{
    model: z.ZodOptional<z.ZodString>;
}, z.core.$strip>

LlmContentBlockSchema

Zod schema for a single LLM content block (text, tool call, tool result, etc.).


import { LlmContentBlockSchema } from '@loopstack/llm-provider-module';


LlmContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
    type: z.ZodLiteral<"text">;
    text: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    type: z.ZodLiteral<"thinking">;
    text: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    type: z.ZodLiteral<"tool_call">;
    id: z.ZodString;
    name: z.ZodString;
    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
}, z.core.$strip>, z.ZodObject<{
    type: z.ZodLiteral<"server_tool_use">;
    id: z.ZodString;
    name: z.ZodString;
    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
}, z.core.$strip>, z.ZodObject<{
    type: z.ZodLiteral<"server_tool_result">;
    toolUseId: z.ZodString;
    content: z.ZodUnknown;
}, z.core.$strip>, z.ZodObject<{
    type: z.ZodLiteral<"tool_result">;
    toolCallId: z.ZodString;
    content: z.ZodString;
    isError: z.ZodBoolean;
}, z.core.$strip>], "type">

LlmDelegateToolCallsConfigSchema

Zod schema for llm_delegate_tool_calls tool config (result persistence options).


import { LlmDelegateToolCallsConfigSchema } from '@loopstack/llm-provider-module';


LlmDelegateToolCallsConfigSchema: z.ZodObject<{
    save: z.ZodOptional<z.ZodBoolean>;
    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>

LlmDelegateToolCallsToolSchema

Zod schema for llm_delegate_tool_calls tool args (the LLM message and the callback.transition to fire on completion).


import { LlmDelegateToolCallsToolSchema } from '@loopstack/llm-provider-module';


LlmDelegateToolCallsToolSchema: z.ZodObject<{
    message: z.ZodObject<{
        role: z.ZodEnum<{
            user: "user";
            assistant: "assistant";
        }>;
        blocks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
            type: z.ZodLiteral<"text">;
            text: z.ZodString;
        }, z.core.$strip>, z.ZodObject<{
            type: z.ZodLiteral<"thinking">;
            text: z.ZodString;
        }, z.core.$strip>, z.ZodObject<{
            type: z.ZodLiteral<"tool_call">;
            id: z.ZodString;
            name: z.ZodString;
            args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
        }, z.core.$strip>, z.ZodObject<{
            type: z.ZodLiteral<"server_tool_use">;
            id: z.ZodString;
            name: z.ZodString;
            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
        }, z.core.$strip>, z.ZodObject<{
            type: z.ZodLiteral<"server_tool_result">;
            toolUseId: z.ZodString;
            content: z.ZodUnknown;
        }, z.core.$strip>, z.ZodObject<{
            type: z.ZodLiteral<"tool_result">;
            toolCallId: z.ZodString;
            content: z.ZodString;
            isError: z.ZodBoolean;
        }, z.core.$strip>], "type">>>;
        id: z.ZodOptional<z.ZodString>;
        text: z.ZodString;
        stopReason: z.ZodOptional<z.ZodEnum<{
            end_turn: "end_turn";
            tool_use: "tool_use";
            max_tokens: "max_tokens";
            stop_sequence: "stop_sequence";
        }>>;
    }, z.core.$strip>;
    callback: z.ZodObject<{
        transition: z.ZodString;
    }, z.core.$strip>;
}, z.core.$strip>

LlmGenerateObjectArgsSchema

Zod schema for llm_generate_object tool args (prompt/messages plus the outputSchema the result must conform to).


import { LlmGenerateObjectArgsSchema } from '@loopstack/llm-provider-module';


LlmGenerateObjectArgsSchema: z.ZodObject<{
    prompt: z.ZodOptional<z.ZodString>;
    messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
        role: z.ZodEnum<{
            user: "user";
            assistant: "assistant";
        }>;
        content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodAny>]>;
    }, z.core.$strip>>>;
    outputSchema: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
}, z.core.$strip>

LlmGenerateObjectConfigSchema

Zod schema for llm_generate_object tool config (provider, model, system, providerConfig).


import { LlmGenerateObjectConfigSchema } from '@loopstack/llm-provider-module';


LlmGenerateObjectConfigSchema: z.ZodObject<{
    provider: z.ZodOptional<z.ZodString>;
    system: z.ZodOptional<z.ZodString>;
    model: z.ZodOptional<z.ZodString>;
    messagesSearchTag: z.ZodOptional<z.ZodString>;
    providerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>

LlmGenerateTextArgsSchema

Zod schema for llm_generate_text tool args (prompt and/or messages).


import { LlmGenerateTextArgsSchema } from '@loopstack/llm-provider-module';


LlmGenerateTextArgsSchema: z.ZodObject<{
    prompt: z.ZodOptional<z.ZodString>;
    messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
        role: z.ZodEnum<{
            user: "user";
            assistant: "assistant";
        }>;
        content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodAny>]>;
    }, z.core.$strip>>>;
}, z.core.$strip>

LlmGenerateTextConfigSchema

Zod schema for llm_generate_text tool config (provider, model, system, tools, providerConfig, and persistence options).


import { LlmGenerateTextConfigSchema } from '@loopstack/llm-provider-module';


LlmGenerateTextConfigSchema: z.ZodObject<{
    provider: z.ZodOptional<z.ZodString>;
    system: z.ZodOptional<z.ZodString>;
    model: z.ZodOptional<z.ZodString>;
    messagesSearchTag: z.ZodOptional<z.ZodString>;
    providerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
    save: z.ZodOptional<z.ZodBoolean>;
    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>

LlmNormalizedMessageSchema

Zod schema for a normalized LLM message, with optional id, text, structured blocks, and stopReason.


import { LlmNormalizedMessageSchema } from '@loopstack/llm-provider-module';


LlmNormalizedMessageSchema: z.ZodObject<{
    role: z.ZodEnum<{
        user: "user";
        assistant: "assistant";
    }>;
    blocks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
        type: z.ZodLiteral<"text">;
        text: z.ZodString;
    }, z.core.$strip>, z.ZodObject<{
        type: z.ZodLiteral<"thinking">;
        text: z.ZodString;
    }, z.core.$strip>, z.ZodObject<{
        type: z.ZodLiteral<"tool_call">;
        id: z.ZodString;
        name: z.ZodString;
        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    }, z.core.$strip>, z.ZodObject<{
        type: z.ZodLiteral<"server_tool_use">;
        id: z.ZodString;
        name: z.ZodString;
        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    }, z.core.$strip>, z.ZodObject<{
        type: z.ZodLiteral<"server_tool_result">;
        toolUseId: z.ZodString;
        content: z.ZodUnknown;
    }, z.core.$strip>, z.ZodObject<{
        type: z.ZodLiteral<"tool_result">;
        toolCallId: z.ZodString;
        content: z.ZodString;
        isError: z.ZodBoolean;
    }, z.core.$strip>], "type">>>;
    id: z.ZodOptional<z.ZodString>;
    text: z.ZodString;
    stopReason: z.ZodOptional<z.ZodEnum<{
        end_turn: "end_turn";
        tool_use: "tool_use";
        max_tokens: "max_tokens";
        stop_sequence: "stop_sequence";
    }>>;
}, z.core.$strip>

LlmUpdateToolResultConfigSchema

Zod schema for llm_update_tool_result tool config (result persistence options).


import { LlmUpdateToolResultConfigSchema } from '@loopstack/llm-provider-module';


LlmUpdateToolResultConfigSchema: z.ZodObject<{
    save: z.ZodOptional<z.ZodBoolean>;
    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>

LlmUpdateToolResultToolSchema

Zod schema for llm_update_tool_result tool args (the pending delegateResult and the completedTool to merge in).


import { LlmUpdateToolResultToolSchema } from '@loopstack/llm-provider-module';


LlmUpdateToolResultToolSchema: z.ZodObject<{
    delegateResult: z.ZodObject<{
        allCompleted: z.ZodBoolean;
        toolResults: z.ZodArray<z.ZodAny>;
        pendingCount: z.ZodNumber;
        errorCount: z.ZodOptional<z.ZodNumber>;
        hasErrors: z.ZodOptional<z.ZodBoolean>;
        errors: z.ZodOptional<z.ZodArray<z.ZodAny>>;
    }, z.core.$strip>;
    completedTool: z.ZodAny;
}, z.core.$strip>