@pipedog/core 0.0.0 → 0.1.0

package/dist/services/llm_service.d.ts

@@ -0,0 +1,1106 @@
+/**
+ * Base classes for Large Language Model services with function calling support.
+ *
+ * Porting notes:
+ * - Cancelling a function call cancels the task running its handler. In
+ *   JavaScript cancellation is delivered at cancellation points (see
+ *   `@pipedog/asyncio`), so a handler awaiting foreign work (`fetch`, an
+ *   SDK) should pass `currentSignal()` to it, or wrap the await in
+ *   `abortable()`, to stop as promptly as the Python handler would.
+ * - Deprecated upstream APIs are not ported: `FunctionCallParams.tool_resources`,
+ *   `register_direct_function()`, `unregister_direct_function()`, the
+ *   `enable_async_tool_cancellation` option, the warnings for application-set
+ *   turn-completion settings, and the legacy `LLMUpdateSettingsFrame(settings={...})`
+ *   dict path.
+ */
+import { Queue, type Task } from "@pipedog/asyncio";
+import type { BaseLLMAdapter } from "../adapters/base_llm_adapter.ts";
+import { DirectFunctionWrapper } from "../adapters/schemas/direct_function.ts";
+import { ToolsSchema } from "../adapters/schemas/tools_schema.ts";
+import { type CancelFrame, EagerEndOfTurnCancelFrame, type EndFrame, type ErrorFrame, type Frame, FunctionCallFromLLM, FunctionCallResultProperties, InterruptionFrame, LLMContextSummaryRequestFrame, LLMServiceMetadataFrame, type StartFrame } from "../frames/frames.ts";
+import type { PipelineWorker } from "../pipeline/worker.ts";
+import { LLMContext, type LLMSpecificMessage } from "../processors/aggregators/llm_context.ts";
+import { FrameDirection, type FrameProcessorSetup } from "../processors/frame_processor.ts";
+import { SpeculationGate } from "../turns/speculation_gate.ts";
+import { UserTurnCompletionLLMServiceMixin } from "../turns/user_turn_completion_mixin.ts";
+import { FileResolver } from "../utils/file_resolver.ts";
+import type { WorkerRunner } from "../workers/runner.ts";
+import { AIService, type AIServiceOptions } from "./ai_service.ts";
+import { LLMSettings } from "./settings.ts";
+import { WebsocketService, type WebsocketServiceOptions } from "./websocket_service.ts";
+/**
+ * Raised by a method a service doesn't implement (Python's
+ * `NotImplementedError`), e.g. `LLMService.runInference()`.
+ */
+export declare class NotImplementedError extends Error {
+    name: string;
+}
+/** Type alias for a callable that handles LLM function calls. */
+export type FunctionCallHandler = (params: FunctionCallParams) => Promise<void>;
+/**
+ * The two roles a service can fill in an `LLMWithBackend`: the conversational
+ * frontend, or the LLM inside the backend worker.
+ */
+export type LLMWithBackendRole = "frontend" | "backend";
+/**
+ * Function call result callback.
+ *
+ * Used for both final results and intermediate updates. Pass
+ * `properties: new FunctionCallResultProperties({ isFinal: false })` to send an
+ * intermediate update (only valid for async function calls registered with
+ * `cancelOnInterruption: false`).
+ *
+ * - `result`: the result of the function call, or an intermediate update.
+ * - `options.properties`: optional properties. Set `isFinal: false` to send an
+ *   intermediate update instead of the final result.
+ */
+export type FunctionCallResultCallback = (result: unknown, options?: {
+    properties?: FunctionCallResultProperties | null;
+}) => Promise<void>;
+export interface FunctionCallParamsOptions {
+    functionName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    llm: LLMService<any>;
+    pipelineWorker: PipelineWorker;
+    context: LLMContext;
+    resultCallback: FunctionCallResultCallback;
+    appResources?: unknown;
+    workerRunner?: WorkerRunner | null;
+}
+/**
+ * Parameters for a function call.
+ *
+ * - `functionName`: the name of the function being called.
+ * - `toolCallId`: a unique identifier for the function call.
+ * - `arguments`: the arguments for the function.
+ * - `llm`: the LLMService instance being used.
+ * - `pipelineWorker`: the worker running the pipeline this call was made from.
+ *   Carries worker-scoped state, most notably `pipelineWorker.appResources`.
+ * - `context`: the LLM context.
+ * - `resultCallback`: callback to deliver the result of the function call.
+ *   For async function calls (`cancelOnInterruption: false`), call it with
+ *   `properties: new FunctionCallResultProperties({ isFinal: false })` to push
+ *   intermediate updates before the final result.
+ * - `appResources`: the application-defined resources passed to
+ *   `new PipelineWorker(..., { appResources })`. Same object — passed by
+ *   reference, not a copy. Use it to share DB handles, clients, state, feature
+ *   flags, etc. across all of a session's tool handlers.
+ * - `workerRunner`: the runner hosting `pipelineWorker`. Use it to reach
+ *   another worker on the runner by name, e.g.
+ *   `params.workerRunner.getWorker("ui-jobs")`. Always set for a call made
+ *   from a running pipeline; null only when these params were built by hand.
+ *
+ * A handler runs in its own task and is cancelled on interruption, timeout or
+ * an LLM cancel request. Pass `currentSignal()` to `fetch` and other foreign
+ * awaits so they stop too.
+ */
+export declare class FunctionCallParams {
+    functionName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    llm: LLMService<any>;
+    pipelineWorker: PipelineWorker;
+    context: LLMContext;
+    resultCallback: FunctionCallResultCallback;
+    appResources: unknown;
+    workerRunner: WorkerRunner | null;
+    constructor(options: FunctionCallParamsOptions);
+}
+export interface FunctionCallRegistryItemOptions {
+    functionName: string | null;
+    handler: FunctionCallHandler | DirectFunctionWrapper;
+    cancelOnInterruption: boolean;
+    timeoutSecs?: number | null;
+    cancellableByLlm?: boolean;
+    autoRegistered?: boolean;
+}
+/**
+ * Internal record of a registered function-call handler.
+ *
+ * Created by the service when a function is registered — directly via
+ * `registerFunction`, or automatically from a direct function advertised in
+ * an `LLMContext` / `LLMSetToolsFrame`. Application code doesn't construct
+ * these.
+ *
+ * - `functionName`: the name of the function (null for catch-all handler).
+ * - `handler`: the handler for processing function call parameters.
+ * - `cancelOnInterruption`: whether to cancel the call on interruption. When
+ *   false the call is treated as asynchronous: the LLM continues the
+ *   conversation immediately without waiting for the result, and the result
+ *   is injected later via a developer message.
+ * - `timeoutSecs`: optional per-tool timeout in seconds. Overrides the global
+ *   `functionCallTimeoutSecs` for this specific function. A call that runs
+ *   past it is cancelled.
+ * - `cancellableByLlm`: whether the LLM may cancel this call while it runs.
+ *   Only meaningful on an async call (`cancelOnInterruption: false`), since a
+ *   synchronous one holds the LLM until it returns.
+ * - `autoRegistered`: true only for a direct function that was auto-registered
+ *   from an advertised tool set (listed in an `LLMContext` or
+ *   `LLMSetToolsFrame`). False for every explicitly registered handler —
+ *   direct or non-direct — and for the catch-all and built-in handlers.
+ */
+export declare class FunctionCallRegistryItem {
+    functionName: string | null;
+    handler: FunctionCallHandler | DirectFunctionWrapper;
+    cancelOnInterruption: boolean;
+    timeoutSecs: number | null;
+    cancellableByLlm: boolean;
+    autoRegistered: boolean;
+    constructor(options: FunctionCallRegistryItemOptions);
+}
+export interface FunctionCallRunnerItemOptions {
+    registryItem: FunctionCallRegistryItem;
+    functionName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    context: LLMContext;
+    runLlm?: boolean | null;
+    groupId?: string | null;
+    settled?: boolean;
+}
+/**
+ * Internal function call entry for the function call runner.
+ *
+ * The runner executes function calls in order.
+ *
+ * - `registryItem`: the registry item containing handler information.
+ * - `functionName`: the name of the function.
+ * - `toolCallId`: a unique identifier for the function call.
+ * - `arguments`: the arguments for the function.
+ * - `context`: the LLM context.
+ * - `runLlm`: optional flag to control LLM execution after function call.
+ * - `groupId`: shared identifier for all function calls from the same LLM
+ *   response batch. Used to trigger the LLM exactly once when the last call in
+ *   the group completes.
+ * - `settled`: whether the call has already reached a terminal state — a final
+ *   result, a timeout, or a cancellation. Results reported after that are
+ *   rejected, since the rest of the pipeline has stopped tracking the call.
+ */
+export declare class FunctionCallRunnerItem {
+    registryItem: FunctionCallRegistryItem;
+    functionName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    context: LLMContext;
+    runLlm: boolean | null;
+    groupId: string | null;
+    settled: boolean;
+    constructor(options: FunctionCallRunnerItemOptions);
+}
+export interface LLMServiceOptions extends AIServiceOptions {
+    /** Whether to run function calls in parallel or sequentially. Defaults to true. */
+    runInParallel?: boolean;
+    /**
+     * Whether to group parallel function calls so the LLM is triggered exactly
+     * once after all calls in the batch complete. When false, each function
+     * call result triggers the LLM independently as it arrives. Defaults to true.
+     */
+    groupParallelTools?: boolean;
+    /**
+     * Optional timeout in seconds for function calls. A call that runs past it
+     * is cancelled: its handler is cancelled (it gets a `CancelledError`), the
+     * call is settled as cancelled, and inference runs so the LLM can report
+     * that it didn't complete.
+     */
+    functionCallTimeoutSecs?: number | null;
+    /** The runtime-updatable settings for the LLM service. */
+    settings?: LLMSettings | null;
+    /**
+     * Resolves file URLs in the context that this provider can't fetch itself
+     * (see `FileResolver`). Pass one configured with a `fileStorage` to resolve
+     * uploaded-file URLs (`new FileResolver({ fileStorage: runnerArgs.fileStorage })`
+     * when a runner hosts the bot), and share one instance across services that
+     * may consume the same files (e.g. services switched between mid-session)
+     * so downloads are reused. Defaults to a resolver that handles `data:` and
+     * `http(s)` URLs only.
+     */
+    fileResolver?: FileResolver | null;
+}
+/** An adapter class `LLMService.adapterClass` can name. */
+export type LLMAdapterClass = new () => BaseLLMAdapter<object>;
+declare const LLMService_base: typeof AIService & import("../utils/mixin.ts").Ctor<UserTurnCompletionLLMServiceMixin>;
+/**
+ * Base class for all LLM services.
+ *
+ * Handles function calling registration and execution with support for both
+ * parallel and sequential execution modes. Provides event handlers for
+ * completion timeouts and function call lifecycle events.
+ *
+ * The service supports the following event handlers:
+ *
+ * - on_completion_timeout: called when an LLM completion timeout occurs
+ * - on_function_calls_started: called when function calls are received and
+ *   execution is about to start. Built-in tools (e.g. a `cancel_<name>` tool)
+ *   are excluded from this event.
+ * - on_function_calls_cancelled: called after one or more async tool calls are
+ *   cancelled.
+ *
+ * @example
+ * llm.eventHandler("on_completion_timeout", async (service) => {
+ *   logger.warning("LLM completion timed out");
+ * });
+ * llm.eventHandler("on_function_calls_started", async (service, functionCalls: FunctionCallFromLLM[]) => {
+ *   logger.info(`Starting ${functionCalls.length} function calls`);
+ * });
+ * llm.eventHandler("on_function_calls_cancelled", async (service, functionCalls: FunctionCallFromLLM[]) => {
+ *   logger.info(`Cancelled ${functionCalls.length} function calls`);
+ * });
+ *
+ * @throws InvalidEnvVarValueError (from the constructor) if
+ *   `PIPECAT_LOG_LLM_CONTEXT` is set to an unknown mode.
+ */
+export declare class LLMService<TAdapter extends BaseLLMAdapter = BaseLLMAdapter> extends LLMService_base {
+    #private;
+    protected _settings: LLMSettings;
+    protected _adapter: TAdapter;
+    /**
+     * Subclasses should set this to a more specific adapter when necessary.
+     * `null` selects OpenAILLMAdapter, which aligns with most LLM
+     * implementations.
+     */
+    static adapterClass: LLMAdapterClass | null;
+    /**
+     * Returned to the LLM as the tool result when an unavailable function is
+     * called. Deliberately neutral about future availability so the LLM can
+     * pick the function up again if it returns (e.g. via the
+     * `addToolChangeMessages` activation message, or silently on a later
+     * inference). `{function_name}` is substituted at runtime.
+     */
+    static MISSING_FUNCTION_CALL_MESSAGE_TEMPLATE: string;
+    /**
+     * Returned to the LLM as the tool result when a handler raises. It names
+     * the function as the thing that failed. The exception itself is
+     * deliberately left out.
+     */
+    static FUNCTION_CALL_ERROR_MESSAGE_TEMPLATE: string;
+    /**
+     * Whether the provider can enforce a response schema in `runInference()`.
+     *
+     * Services whose provider can set this to true. When only some of its
+     * models can, they also override `modelSupportsResponseSchema()`.
+     */
+    static supportsResponseSchema: boolean;
+    protected _runInParallel: boolean;
+    protected _groupParallelTools: boolean;
+    protected _functionCallTimeoutSecs: number | null;
+    protected _fileResolver: FileResolver;
+    protected _reportsTtfat: boolean | null;
+    protected _filterIncompleteUserTurns: boolean;
+    protected _loggedThinkingDefaultModel: string | null;
+    protected _speculationGate: SpeculationGate;
+    protected _cancelToolNames: Set<string>;
+    protected _warnedCancelCollisions: Set<string>;
+    protected _baseSystemInstruction: string | null;
+    protected _appendedSystemInstructions: string[];
+    protected _composedSystemInstruction: string | null;
+    protected _functions: Map<string | null, FunctionCallRegistryItem>;
+    protected _toolCleanups: (() => Promise<void>)[];
+    protected _redundantRegistrationWarned: Set<string>;
+    protected _explicitlyUnregisteredFunctionNames: Set<string | null>;
+    protected _functionCallTasks: Map<Task<unknown> | null, FunctionCallRunnerItem>;
+    protected _sequentialRunnerTask: Task<unknown> | null;
+    protected _sequentialRunnerQueue: Queue<FunctionCallRunnerItem>;
+    protected _skipTts: boolean | null;
+    protected _summaryTask: Task<unknown> | null;
+    protected _warnedRealtimeServiceNoTurnFrames: boolean;
+    constructor(options?: LLMServiceOptions);
+    /** Return the adapter class to instantiate for this service. */
+    static _resolveAdapterClass(): LLMAdapterClass;
+    /**
+     * Get the LLM adapter instance.
+     *
+     * @returns The adapter instance used for LLM communication.
+     */
+    getLlmAdapter(): TAdapter;
+    /**
+     * Create an LLM-specific message (as opposed to a standard message) for use
+     * in an LLMContext.
+     *
+     * @param message The message content.
+     * @returns A LLMSpecificMessage instance.
+     */
+    createLlmSpecificMessage(message: unknown): LLMSpecificMessage;
+    /**
+     * Log that the service is generating a response from the given context.
+     *
+     * The context is included unless the LLM context log mode is `off`.
+     *
+     * @param context The context sent with the request.
+     */
+    protected _logLlmResponse(context: LLMContext): void;
+    /**
+     * Log that a realtime service is seeding its server-side conversation.
+     *
+     * Realtime services upload the context once per session (and again after a
+     * reset), then send only new items. The context is included unless the LLM
+     * context log mode is `off`.
+     *
+     * @param context The context being uploaded.
+     */
+    protected _logLlmConversationSetup(context: LLMContext): void;
+    protected _logLlmEvent(event: string, context: LLMContext): void;
+    /**
+     * Run a one-shot, out-of-band (i.e. out-of-pipeline) inference with the
+     * given LLM context.
+     *
+     * Must be implemented by subclasses.
+     *
+     * @param context The LLM context containing conversation history.
+     * @param options.maxTokens Optional maximum number of tokens to generate. If
+     *   provided, overrides the service's default max_tokens/max_completion_tokens
+     *   setting.
+     * @param options.systemInstruction Optional system instruction to use for
+     *   this inference. If provided, overrides any system instruction in the
+     *   context.
+     * @param options.responseSchema Optional JSON schema the reply must follow.
+     *   Services that can have the provider enforce it return JSON text matching
+     *   the schema. When the service or its current model cannot enforce one
+     *   (see `supportsResponseSchema`), the schema is ignored with a warning.
+     *   The schema must satisfy the strictest provider in use: every object
+     *   lists all its properties as required and sets `additionalProperties` to
+     *   false.
+     * @returns The LLM's response as a string, or null if no response is generated.
+     */
+    runInference(_context: LLMContext, _options?: {
+        maxTokens?: number | null;
+        systemInstruction?: string | null;
+        responseSchema?: Record<string, unknown> | null;
+    }): Promise<string | null>;
+    /** The schema to send, or null with a warning if it cannot be enforced. */
+    protected _checkResponseSchema(responseSchema: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
+    /** Whether this service's provider can enforce a response schema. */
+    get supportsResponseSchema(): boolean;
+    /**
+     * Whether a model can enforce a response schema, on a provider that can.
+     *
+     * @param model The model name.
+     */
+    static modelSupportsResponseSchema(_model: string): boolean;
+    /**
+     * Whether this service reports time-to-first-answer-token.
+     *
+     * Speech-to-speech services answer in audio, which has no answer token to
+     * measure to, so only text-answering services report it. Derived from
+     * `serviceMetadataFrame()` and cached, since it is read once per streamed
+     * token.
+     */
+    get reportsTtfat(): boolean;
+    /**
+     * Whether this service delivers a tool's intermediate results to the model.
+     *
+     * An intermediate result is one reported with
+     * `new FunctionCallResultProperties({ isFinal: false })` while the call keeps
+     * running. A text service passes them on as context messages. A
+     * speech-to-speech service has to map them onto whatever second channel its
+     * provider offers, and not all of them have one.
+     */
+    get acceptsIntermediateFunctionCallResults(): boolean;
+    /**
+     * Why this service can't take the given role in an `LLMWithBackend`, if it
+     * can't.
+     *
+     * The composite raises with what this returns, so the objection says what
+     * to do instead. Services that work in both roles, which is nearly all of
+     * them, say nothing.
+     *
+     * @param role The role the service is being asked to take.
+     * @returns The reason, or null when the service can take the role.
+     */
+    llmWithBackendRoleObjection(_role: LLMWithBackendRole): string | null;
+    /**
+     * Send a model the thinking default its service lists, and log it once per
+     * model.
+     *
+     * Services that send each model its lowest thinking setting call this when
+     * the request configures no thinking of its own. With
+     * `useProviderThinkingDefault` set, the service sends no default. The first
+     * request for each model logs the setting sent, or that the model runs at
+     * the provider's default, warning when it has no default.
+     *
+     * @param params The request params, updated in place. Each field of
+     *   `defaultParams` is merged into the dict already there, if any.
+     * @param model The model the request is for.
+     * @param defaultParams The request fields to send, or null if the service
+     *   lists no default for the model.
+     * @param options.canThink Whether the model can think, which decides
+     *   whether a model with no default is warned about.
+     * @param options.provider The provider's name, for the log lines.
+     * @param options.settingsFields The settings fields that configure thinking,
+     *   as the log lines name them, such as "`thinking`".
+     */
+    protected _applyThinkingDefault(params: Record<string, unknown>, model: string, defaultParams: Record<string, Record<string, unknown>> | null, options: {
+        canThink: boolean;
+        provider: string;
+        settingsFields: string;
+    }): void;
+    /**
+     * The metadata frame this LLM service broadcasts at start.
+     *
+     * The base returns a plain (non-realtime) frame; realtime (speech-to-speech)
+     * subclasses override this to set `isRealtimeService: true` and, when their
+     * turns are provider-driven, recommend `ExternalUserTurnStrategies` via
+     * `userTurnStrategies`.
+     *
+     * Mostly here for conceptual consistency — today only realtime services
+     * need to override it — but it's a natural placeholder for future
+     * LLM-service metadata.
+     */
+    serviceMetadataFrame(): LLMServiceMetadataFrame;
+    /**
+     * Warn (once) when a realtime service won't emit its own turn frames.
+     *
+     * Realtime services call this from `serviceMetadataFrame()` at the point
+     * they determine whether their turns are provider-driven. When they aren't,
+     * downstream processors that expect `UserStarted/StoppedSpeakingFrame`
+     * (e.g. RTVI) may need local VAD/turn detection.
+     */
+    protected _warnIfRealtimeServiceEmitsNoTurnFrames(emitsTurnFrames: boolean): void;
+    /**
+     * Start the LLM service.
+     *
+     * @param frame The start frame.
+     */
+    start(frame: StartFrame): Promise<void>;
+    /**
+     * Stop the LLM service.
+     *
+     * @param frame The end frame.
+     */
+    stop(frame: EndFrame): Promise<void>;
+    /**
+     * Cancel the LLM service.
+     *
+     * @param frame The cancel frame.
+     */
+    cancel(frame: CancelFrame): Promise<void>;
+    /**
+     * Release LLM service resources at teardown.
+     *
+     * Besides this service's own tasks, runs any cleanup callables carried by
+     * registered tool handlers (e.g. closing an MCP client's connection).
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Append durable text to the system instruction, preserving the user's
+     * prompt.
+     *
+     * The text is composed onto the end of the system instruction (joined with
+     * a blank line) and re-applied on every inference, so it survives
+     * context-message resets (e.g. `new LLMMessagesUpdateFrame({ messages: [] })`).
+     * Intended for framework components that own an LLM and need to add
+     * standard guidance to a user-provided prompt — for example, `UIWorker`
+     * appends the UI wire-format guide. Appended instructions compose after the
+     * user's base prompt and alongside the turn-completion and
+     * async-tool-cancellation instructions.
+     *
+     * @param instruction The instruction text to append.
+     */
+    appendSystemInstruction(instruction: string): void;
+    /**
+     * Whether any registered tool runs asynchronously.
+     *
+     * @returns True when a tool is registered with `cancelOnInterruption: false`,
+     *   which is what makes the async-tool guidance worth composing in. The
+     *   built-in cancellation tool is registered as a synchronous one, so it
+     *   never counts on its own.
+     */
+    protected _hasAsyncTools(): boolean;
+    /**
+     * Rebuild `systemInstruction` from the base prompt and all active addons.
+     *
+     * Joins the user's base system instruction (the single source of truth,
+     * captured at construction and refreshed on runtime `systemInstruction`
+     * updates) with any appended instructions (e.g. the `UIWorker` prompt
+     * guide), turn completion instructions (when enabled), and async tool
+     * cancellation instructions (when enabled). Safe to call repeatedly — it
+     * always rebuilds from the base, so it never compounds, and it logs the
+     * result only when it differs from the previous composition.
+     */
+    protected _composeSystemInstruction(): void;
+    /**
+     * Apply a settings delta, handling turn-completion fields.
+     *
+     * @param delta An LLM settings delta.
+     * @returns Dict mapping changed field names to their previous values.
+     */
+    protected _updateSettings(delta: LLMSettings): Promise<Record<string, unknown>>;
+    /**
+     * Process a frame.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Pushes a frame.
+     *
+     * @param frame The frame to push.
+     * @param direction The direction of frame pushing.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Push LLM text, using turn completion detection if enabled.
+     *
+     * This helper method simplifies text pushing in LLM implementations by
+     * handling the conditional logic for turn completion internally.
+     *
+     * @param text The text content from the LLM to push.
+     */
+    protected _pushLlmText(text: string): Promise<void>;
+    protected _handleInterruptions(_frame: InterruptionFrame): Promise<void>;
+    /**
+     * Stop generating a response whose user turn turned out to be unfinished.
+     *
+     * The tokens are wasted either way; stopping keeps us from paying for the
+     * rest of them. Unlike an interruption this leaves the turn open — the bot
+     * never spoke, and the user is still mid-turn.
+     */
+    protected _handleEagerEndOfTurnCancel(_frame: EagerEndOfTurnCancelFrame): Promise<void>;
+    /**
+     * Handle context summarization request from aggregator.
+     *
+     * Processes a summarization request by generating a compressed summary of
+     * conversation history. Uses the adapter to format the summary according
+     * to the provider's requirements. Broadcasts the result back to the
+     * aggregator for context reconstruction.
+     *
+     * @param frame The summary request frame containing context and parameters.
+     */
+    protected _handleSummaryRequest(frame: LLMContextSummaryRequestFrame): Promise<void>;
+    /**
+     * Background task to generate summary without blocking the pipeline.
+     *
+     * @param frame The summary request frame containing context and parameters.
+     */
+    protected _generateSummaryTask(frame: LLMContextSummaryRequestFrame): Promise<void>;
+    /**
+     * Generate a compressed summary of conversation context.
+     *
+     * Uses the message selection logic to identify which messages to
+     * summarize, formats them as a transcript, and invokes the LLM to generate
+     * a concise summary. The summary is formatted according to the LLM
+     * provider's requirements using the adapter.
+     *
+     * Requires the service to implement `runInference()` for one-shot LLM calls.
+     *
+     * @param frame The summary request frame containing context and configuration.
+     * @returns Tuple of (formatted summary message, lastSummarizedIndex).
+     * @throws Error if there are no messages to summarize, the service doesn't
+     *   support runInference(), or the LLM returns an empty summary.
+     */
+    protected _generateSummary(frame: LLMContextSummaryRequestFrame): Promise<[string, number]>;
+    /**
+     * Register a function handler for LLM function calls.
+     *
+     * Call options resolve with the precedence **explicit argument >
+     * `toolOptions()` attributes > default**. `null`/`undefined` (the default)
+     * means "not provided" — the option falls back to the `toolOptions()` value
+     * on the handler, then to the documented default.
+     *
+     * @param functionName The name of the function to handle. Use null to handle
+     *   all function calls with a catch-all handler.
+     * @param handler The function handler. Should accept a single
+     *   FunctionCallParams parameter.
+     * @param options.cancelOnInterruption Whether to cancel this function call
+     *   when an interruption occurs. When false the call is treated as
+     *   asynchronous: the LLM continues the conversation immediately without
+     *   waiting for the result, and the result is injected later via a
+     *   developer message. Defaults to null (fall back to the `toolOptions()`
+     *   value, then to true). A speech-to-speech service takes intermediate
+     *   results (reported via `new FunctionCallResultProperties({ isFinal: false })`)
+     *   on whatever second channel its provider offers; one that can't says so
+     *   with `acceptsIntermediateFunctionCallResults` and drops them with a
+     *   warning.
+     * @param options.timeoutSecs Optional per-tool timeout in seconds,
+     *   overriding the global `functionCallTimeoutSecs`. A call that runs past it
+     *   is cancelled: the handler is cancelled, the call is settled as
+     *   cancelled, and inference runs so the LLM can report that it didn't
+     *   complete. The deadline covers the handler's execution as a whole, so
+     *   reporting an intermediate result neither clears it nor restarts it.
+     *   Defaults to null (fall back to the `toolOptions()` value, then to the
+     *   global timeout).
+     * @param options.cancellableByLlm Whether the LLM may cancel this call while
+     *   it runs, through the `cancel_<name>` tool advertised alongside it. Pair
+     *   it with `cancelOnInterruption: false`; a synchronous call holds the LLM
+     *   until it returns, so there is no moment at which it could ask for the
+     *   call to stop. Defaults to null (fall back to the `toolOptions()` value,
+     *   then to false).
+     */
+    registerFunction(functionName: string | null, handler: FunctionCallHandler, options?: {
+        cancelOnInterruption?: boolean | null;
+        timeoutSecs?: number | null;
+        cancellableByLlm?: boolean | null;
+    }): void;
+    /**
+     * Track cleanup work a registered tool handler asks to run at teardown.
+     *
+     * A handler backed by a resource that outlives the call — an MCP server
+     * connection, for instance — can carry a zero-argument async callable under
+     * `_pipecatCleanup`. It is awaited when this service is cleaned up, the hook
+     * the pipeline guarantees to run at teardown, so the resource is released
+     * without the developer wiring teardown manually. Handlers sharing a
+     * resource carry the same callable, recorded once.
+     *
+     * Cleanups are kept for the service's lifetime even if their handlers are
+     * later unregistered: the resource may outlive any one tool's
+     * advertisement, and cleanups are expected to be idempotent.
+     */
+    protected _recordToolCleanup(handler: unknown): void;
+    /** Run recorded tool cleanups; errors are logged, not raised. */
+    protected _runToolCleanups(): Promise<void>;
+    /**
+     * Register a direct function handler.
+     *
+     * Shared core behind automatic registration (from an `LLMContext` or
+     * `LLMSetToolsFrame`). Call options resolve by precedence: explicit
+     * argument > `toolOptions()` attributes > default.
+     *
+     * @param handler The direct function to register.
+     * @param options.cancelOnInterruption Explicit override, or null to use the
+     *   handler's value (then the true default).
+     * @param options.timeoutSecs Explicit override, or null to use the handler's
+     *   value (then the null default, i.e. the global timeout).
+     * @param options.cancellableByLlm Explicit override, or null to use the
+     *   handler's value (then the false default).
+     */
+    protected _registerDirectFunction(handler: (...args: any[]) => Promise<unknown>, options?: {
+        cancelOnInterruption?: boolean | null;
+        timeoutSecs?: number | null;
+        cancellableByLlm?: boolean | null;
+    }): void;
+    /**
+     * Resolve whether the LLM may cancel a tool's calls.
+     *
+     * @param functionName The tool's name, for the warning below.
+     * @param explicit The value passed to the register call, or null if omitted.
+     * @param handler The handler, which may carry a `toolOptions()` value.
+     * @param cancelOnInterruption The tool's interruption behaviour, already
+     *   resolved by the caller — resolving it again here would read past
+     *   whatever the caller was told explicitly.
+     * @returns Whether the LLM may cancel this tool's calls.
+     */
+    protected _resolveCancellableByLlm(functionName: string | null, explicit: boolean | null | undefined, handler: unknown, cancelOnInterruption: boolean): boolean;
+    /**
+     * Resolve a tool call option by precedence: explicit > handler attribute >
+     * default.
+     *
+     * An explicit `null` is treated as "not provided" and falls back to the
+     * handler's value, then the default — so `null` can't be passed to force a
+     * default past a handler value (an intentionally unsupported niche; set
+     * `functionCallTimeoutSecs` on the service for that).
+     *
+     * @param functionName The tool's name, for logging.
+     * @param explicit The value passed to the register call, or null if the
+     *   caller omitted it.
+     * @param handler The handler, which may carry `toolOptions()` attributes.
+     * @param attr The attribute to read (e.g. `_pipecatTimeoutSecs`).
+     * @param options.default The value to use when neither an explicit argument
+     *   nor a handler value is present.
+     * @returns The resolved option value.
+     */
+    protected _resolveToolOption(functionName: string | null, explicit: unknown, handler: unknown, attr: string, options: {
+        default: unknown;
+    }): unknown;
+    /**
+     * Whether an advertised handler differs from the one already registered.
+     *
+     * Normalizes a `DirectFunctionWrapper` to its underlying `.function` on both
+     * sides, then compares by identity. Flows reuses one closure per node across
+     * repeated context frames (no change) but builds a fresh closure on
+     * transition (a real change), so identity is the right test.
+     *
+     * @param item The currently registered entry.
+     * @param newHandler The advertised handler — a raw callable or a
+     *   `DirectFunctionWrapper`.
+     * @returns True if `newHandler` is a different callable than `item` holds.
+     */
+    protected _advertisedHandlerChanged(item: FunctionCallRegistryItem, newHandler: unknown): boolean;
+    /**
+     * Register handlers for any tools in the given set that carry one.
+     *
+     * A tool carries a handler when it's advertised as a direct function or as
+     * a `FunctionSchema` with a `handler` set; either way the handler is
+     * registered automatically, so no `registerFunction` call is needed. A
+     * `FunctionSchema` without a handler is advertise-only and registers
+     * nothing.
+     *
+     * Accepts whatever `LLMContext` accepts for tools — a `ToolsSchema`, a plain
+     * list of direct functions / `FunctionSchema` objects, or `NOT_GIVEN` —
+     * normalizing as needed.
+     *
+     * Explicit `registerFunction` registrations are always left untouched, so
+     * explicit registration wins. An auto-registered entry (from a previous
+     * advertised set) is rebound when the new set carries a *different* handler
+     * for the same name — so a re-declared per-node handler takes effect — and
+     * left untouched when the handler is unchanged, so repeated frames don't
+     * churn.
+     *
+     * @param tools The tools to scan for handlers.
+     */
+    protected _registerAdvertisedToolHandlers(tools: unknown): void;
+    /** Mark a registry entry as managed by the advertised tool set. */
+    protected _markAutoRegistered(name: string): void;
+    /**
+     * Warn that a manual registration is unnecessary, once per function.
+     *
+     * Fires when a tool is registered explicitly via `registerFunction` yet its
+     * advertised `FunctionSchema` already carries a handler — the schema alone
+     * would register it. An auto-registered entry (e.g. from a same-named
+     * direct function) is not a manual registration and is left silent.
+     *
+     * @param functionName The name shared by the manual registration and the
+     *   handler-carrying schema. Must already be registered.
+     */
+    protected _warnIfRedundantManualRegistration(functionName: string): void;
+    /**
+     * Return the service's own configured tools, if any.
+     *
+     * Used by the auto-registration mechanism. Tools normally reach a service
+     * through the `LLMContext` on each inference. Some services (the realtime
+     * services) also accept tools configured directly on the service (e.g. via
+     * a constructor option) as an alternative; they override this to return
+     * those tools verbatim, in whatever form they hold them — a `ToolsSchema` or
+     * a provider-native tool list. When the context advertises no tools,
+     * `_syncRegisteredToolHandlers` normalizes the result and registers handlers
+     * for any standard tools it contains; provider-native tools carry no
+     * handlers, so they contribute nothing to register.
+     *
+     * A service that overrides this **must follow the auto-registration
+     * mechanism's preference rules: context tools, then service-configured
+     * tools**.
+     *
+     * @returns The service's configured tools verbatim (e.g. a `ToolsSchema` or
+     *   a provider-native tool list), or null when there are none (the default).
+     */
+    protected _serviceTools(): ToolsSchema | unknown[] | null;
+    /**
+     * Sync the registered handlers with the handlers advertised in `tools`.
+     *
+     * Registers handlers for any tools the set advertises with one (direct
+     * functions, or `FunctionSchema` objects carrying a `handler`), then drops
+     * the handlers we auto-registered for tools it no longer advertises — so
+     * the registry matches what the LLM can see.
+     *
+     * This is the single path for keeping handlers in step with the advertised
+     * tools. The base service runs it on every `LLMContextFrame` (the context
+     * carries the current tool set on each inference). Realtime services that
+     * support runtime tool changes also call it from their own
+     * `LLMSetToolsFrame` handling, since they run continuously and don't get a
+     * context frame per turn. When the context advertises no tools, handlers
+     * fall back to `_serviceTools()` (the service's own configured tools).
+     *
+     * Explicit registrations (`registerFunction`), the catch-all handler, and
+     * built-in tools are never pruned.
+     *
+     * @param tools The advertised tool set (a `ToolsSchema`, a plain list, or
+     *   null / `NOT_GIVEN` for "no tools").
+     */
+    protected _syncRegisteredToolHandlers(tools: unknown): void;
+    /**
+     * Drop auto-registered handlers for tools no longer advertised.
+     *
+     * Only entries with `autoRegistered: true` are eligible; explicit
+     * registrations, the catch-all handler, and built-in tools are untouched.
+     *
+     * @param advertised Names of handler-carrying tools in the new advertised set.
+     */
+    protected _unregisterUnadvertisedToolHandlers(advertised: Set<string | null>): void;
+    /**
+     * Remove a registered function handler.
+     *
+     * This removes the handler but does not stop advertising the tool to the
+     * LLM. To remove a tool cleanly, prefer an `LLMSetToolsFrame` with the
+     * updated tool set — that both stops advertising it and avoids the LLM
+     * trying to call a tool that's no longer there.
+     *
+     * @param functionName The name of the function handler to remove.
+     * @throws Error if no handler is registered under that name.
+     */
+    unregisterFunction(functionName: string | null): void;
+    /**
+     * Remove a registered direct function handler (internal; no warning).
+     *
+     * @param handler The direct function handler to remove.
+     * @throws Error if no handler is registered under its name.
+     */
+    protected _unregisterDirectFunction(handler: (...args: any[]) => Promise<unknown>): void;
+    /**
+     * Check if a function handler is registered.
+     *
+     * @param functionName The name of the function to check.
+     * @returns True if the function is registered or if a catch-all handler
+     *   (null) is registered.
+     */
+    hasFunction(functionName: string): boolean;
+    /**
+     * Whether the named function was registered with cancelOnInterruption=false.
+     *
+     * Mirrors the registry-lookup pattern in `runFunctionCalls()`: a
+     * name-specific entry takes precedence; if there isn't one, fall back to
+     * the null-keyed catch-all entry. Returns false if no entry matches.
+     */
+    protected _functionIsAsync(functionName: string): boolean;
+    /**
+     * Execute a sequence of function calls from the LLM.
+     *
+     * Triggers the on_function_calls_started event and executes functions
+     * either in parallel or sequentially based on the runInParallel setting.
+     *
+     * @param functionCalls The function calls to execute.
+     */
+    runFunctionCalls(functionCalls: readonly FunctionCallFromLLM[]): Promise<void>;
+    protected _createSequentialRunnerTask(): Promise<void>;
+    protected _cancelSequentialRunnerTask(): Promise<void>;
+    protected _cancelSummaryTask(): Promise<void>;
+    protected _cancelAllFunctionCallTasks(): Promise<void>;
+    protected _sequentialRunnerHandler(): Promise<void>;
+    protected _runParallelFunctionCalls(runnerItems: readonly FunctionCallRunnerItem[]): Promise<void>;
+    protected _runSequentialFunctionCalls(runnerItems: readonly FunctionCallRunnerItem[]): Promise<void>;
+    protected _runFunctionCall(runnerItem: FunctionCallRunnerItem): Promise<void>;
+    /** Build a registry item that routes to the missing-function handler. */
+    protected _buildMissingFunctionCallRegistryItem(functionName: string): FunctionCallRegistryItem;
+    /** Return a terminal tool result when the LLM calls an unknown function. */
+    protected _missingFunctionCallHandler(params: FunctionCallParams): Promise<void>;
+    /**
+     * Return the set of standard-tool names currently advertised to the LLM.
+     *
+     * Custom (LLM-specific) tools are not included, since they have no
+     * consistent name field across adapters.
+     */
+    static _advertisedToolNames(context: LLMContext | null | undefined): Set<string>;
+    /**
+     * Log an appropriate message when a tool is called with no handler.
+     *
+     * Distinguishes two cases:
+     *
+     * - **Developer error:** the tool is advertised to the LLM but no handler
+     *   was wired up (a `FunctionSchema` must've been provided with neither
+     *   `handler` nor accompanying `registerFunction` call). Logged at error
+     *   level since this almost always indicates a bug.
+     * - **Hallucination:** the tool is not in the currently advertised tool
+     *   set. Logged at warning level since this is model behavior the
+     *   application can do little about beyond returning a terminal result.
+     */
+    protected _logMissingFunctionCall(functionName: string, context: unknown): void;
+    /**
+     * Whether the LLM may cancel calls of a registered tool.
+     *
+     * The one place that decides it, so what gets advertised and what a cancel
+     * tool will actually stop can't drift apart.
+     *
+     * @param item The registered tool to judge.
+     * @returns True if the tool opted in with `cancellableByLlm`.
+     */
+    protected _isCancellable(item: FunctionCallRegistryItem): boolean;
+    /**
+     * Names of the registered tools the LLM may cancel.
+     *
+     * @returns The tools that opted in with `cancellableByLlm: true`.
+     */
+    protected _cancellableToolNames(): Set<string>;
+    /**
+     * Match the advertised cancel tools to the tools currently registered.
+     *
+     * One cancel tool per cancellable tool, named for it, reconciled from a
+     * single reading of the registry so the advertised set can never drift from
+     * what is actually cancellable. A tool that never opted in has no cancel
+     * tool at all, so there is nothing for the LLM to call against it.
+     */
+    protected _syncCancelTools(): void;
+    /**
+     * Handle a `cancel_<tool>` invocation from the LLM.
+     *
+     * Which work to stop comes from the tool the model called, so the common
+     * case takes no arguments at all. `tool_call_id` only has to be given to
+     * choose between several running calls of the same tool.
+     *
+     * @param params Function call parameters, optionally carrying `tool_call_id`.
+     */
+    protected _cancelToolHandler(params: FunctionCallParams): Promise<void>;
+    /**
+     * Cancel the in-flight function calls selected by a predicate.
+     *
+     * Cancelling a call cancels its handler's task (delivering a
+     * `CancelledError`) so cancel-aware handlers run their cleanup, broadcasts a
+     * `FunctionCallCancelFrame` so the rest of the pipeline can settle the
+     * call, and notifies application code via `on_function_calls_cancelled`.
+     *
+     * @param predicate Selects which in-flight calls to cancel.
+     * @param options.reason Short description of what triggered the
+     *   cancellation, included in the log messages.
+     * @param options.runLlm Whether inference should run once the cancelled
+     *   calls are settled in the context.
+     * @returns The function calls that were cancelled.
+     */
+    protected _cancelFunctionCallTasks(predicate: (item: FunctionCallRunnerItem) => boolean, options: {
+        reason: string;
+        runLlm?: boolean;
+    }): Promise<FunctionCallFromLLM[]>;
+    /**
+     * Settle a cancelled function call downstream.
+     *
+     * @param runnerItem The function call that was cancelled.
+     * @param options.runLlm Whether inference should run once the call is
+     *   settled in the context.
+     * @returns The cancelled call, described for `on_function_calls_cancelled`.
+     */
+    protected _broadcastFunctionCallCancelled(runnerItem: FunctionCallRunnerItem, options?: {
+        runLlm?: boolean;
+    }): Promise<FunctionCallFromLLM>;
+    /**
+     * Cancel a function call that ran past its deadline.
+     *
+     * The handler usually still owns the call and is cancelled outright. If it
+     * happened to finish while the timeout was being processed its task is
+     * already gone and there is nothing left to cancel, but the deadline has
+     * settled the call, so its result is rejected — the pipeline is told the
+     * call is over regardless, or it waits on a result that can never arrive.
+     *
+     * A deadline is the one cancellation nothing else follows up on, so it asks
+     * for inference: without it the LLM never learns the call is over and the
+     * user is left waiting on an answer that never comes.
+     *
+     * @param runnerItem The function call that timed out.
+     */
+    protected _timeoutFunctionCall(runnerItem: FunctionCallRunnerItem): Promise<void>;
+    /**
+     * Cancel every function call in flight, whether or not it survives
+     * interruptions.
+     *
+     * Each handler is cancelled, the call is settled downstream as cancelled,
+     * and `on_function_calls_cancelled` fires. No inference runs for the
+     * cancellations.
+     *
+     * @param options.reason What triggered the cancellation, for the logs.
+     * @returns The calls that were cancelled.
+     */
+    cancelFunctionCalls(options?: {
+        reason?: string;
+    }): Promise<FunctionCallFromLLM[]>;
+    /**
+     * Cancel in-progress function call tasks by their toolCallId.
+     *
+     * @param toolCallId toolCallId to cancel.
+     */
+    protected _cancelFunctionCallsByToolCallId(toolCallId: string): Promise<void>;
+    protected _cancelFunctionCall(functionName: string | null): Promise<void>;
+    protected _functionCallTaskFinished(task: Task<unknown>): void;
+}
+/**
+ * Raised by `_wsSend`/`_wsRecv` after a transparent reconnection.
+ *
+ * Signals that the WebSocket connection was lost and automatically
+ * re-established. The current inference should be restarted — any
+ * connection-local state on the server (e.g. cached responses) is gone.
+ */
+export declare class WebsocketReconnectedError extends Error {
+    name: string;
+}
+export interface WebsocketLLMServiceOptions extends LLMServiceOptions, WebsocketServiceOptions {
+}
+declare const WebsocketLLMService_base: typeof LLMService & (abstract new (...args: any[]) => WebsocketService);
+/**
+ * Base class for websocket-based LLM services.
+ *
+ * Each LLM inference is a discrete request/response exchange: send one
+ * request, receive events inline until a terminal event, then wait for the
+ * next frame to trigger an inference. This contrasts with
+ * `WebsocketTTSService` / `WebsocketSTTService` which stream data
+ * continuously via a background receive loop (`_receiveTaskHandler`). This
+ * class does **not** start a background receive loop.
+ *
+ * Provides connection lifecycle management (connect on setup, disconnect on
+ * stop/cancel), automatic reconnection with exponential backoff, and three
+ * helpers for running each inference:
+ *
+ * 1. `_ensureConnected()` — verify the websocket is alive, reconnect with
+ *    exponential backoff if not.
+ * 2. `_wsSend(message)` — send the inference request as JSON.
+ * 3. `_wsRecv()` — receive and parse response events one at a time until the
+ *    caller sees a terminal event.
+ *
+ * `_wsSend` and `_wsRecv` catch `ConnectionClosed` transparently,
+ * auto-reconnect via `_tryReconnect`, and raise `WebsocketReconnectedError`
+ * so callers know the inference must be restarted. If reconnection fails,
+ * the original `ConnectionClosed` propagates.
+ *
+ * Subclasses must implement:
+ * - `_connectWebsocket()`: establish the websocket connection.
+ * - `_disconnectWebsocket()`: close the websocket and clean up.
+ *
+ * Event handlers:
+ * - on_connection_error: called when a websocket connection error occurs.
+ *
+ * @example
+ * llm.eventHandler("on_connection_error", async (llm: LLMService, error: string) => {
+ *   logger.error(`LLM connection error: ${error}`);
+ * });
+ */
+export declare abstract class WebsocketLLMService<TAdapter extends BaseLLMAdapter = BaseLLMAdapter> extends WebsocketLLMService_base<TAdapter> {
+    constructor(options?: WebsocketLLMServiceOptions);
+    /** Connect: reset flags and establish the websocket. */
+    _connect(): Promise<void>;
+    /** Disconnect: set flags and close the websocket. */
+    _disconnect(): Promise<void>;
+    /**
+     * Set up the service and connect.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /**
+     * Stop the service and close WebSocket connection.
+     *
+     * @param frame The end frame triggering service shutdown.
+     */
+    stop(frame: EndFrame): Promise<void>;
+    /**
+     * Cancel the service and close WebSocket connection.
+     *
+     * @param frame The cancel frame triggering service cancellation.
+     */
+    cancel(frame: CancelFrame): Promise<void>;
+    /**
+     * Send a JSON message over the websocket.
+     *
+     * Guards against sends during intentional disconnect. If the send fails
+     * with `ConnectionClosed`, attempts to reconnect and raises
+     * `WebsocketReconnectedError` on success so the caller can restart the
+     * inference. If reconnection fails, the original `ConnectionClosed`
+     * propagates.
+     *
+     * @param message The message dict to serialize and send.
+     */
+    protected _wsSend(message: Record<string, unknown>): Promise<void>;
+    /**
+     * Receive and parse a JSON message from the websocket.
+     *
+     * If the receive fails with `ConnectionClosed`, attempts to reconnect and
+     * raises `WebsocketReconnectedError` on success. If reconnection fails, the
+     * original `ConnectionClosed` propagates.
+     *
+     * @returns The parsed JSON message as a dict.
+     */
+    protected _wsRecv(): Promise<any>;
+    /**
+     * Ensure the websocket is connected, reconnecting if needed.
+     *
+     * Uses `_tryReconnect` with exponential backoff.
+     *
+     * @throws Error if the connection could not be established.
+     */
+    protected _ensureConnected(): Promise<void>;
+    /**
+     * Not used — messages are received inline during each inference.
+     *
+     * This satisfies the `WebsocketService` abstract method but is never called
+     * because `_receiveTaskHandler` is never started.
+     */
+    _receiveMessages(): Promise<void>;
+    protected _reportError(error: ErrorFrame, options?: {
+        forceTreatAsPermanent?: boolean;
+    }): Promise<void>;
+}
+export {};
+//# sourceMappingURL=llm_service.d.ts.map