@pipedog/core 0.0.0 → 0.1.0

package/dist/workers/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/workers/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/__init__.py
+// Upstream's `__init__.py` is empty: import the package's modules directly.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/workers/llm/backend_llm_worker.d.ts

@@ -0,0 +1,552 @@
+/**
+ * Backend LLM worker for two-tier voice agents.
+ *
+ * A frontend holds the conversation and hands off requests that need tools or
+ * careful reasoning. What the frontend is does not matter to this contract: a
+ * speech-to-speech model delegating on its own, or a pipeline calling a tool.
+ * A `BackendLLMWorker` runs any Pipecat LLM service, with its own context and
+ * multi-step tool calling, to do that work.
+ *
+ * The frontend and the backend exchange messages. A frontend *attaches* to the
+ * worker once, for as long as it lives, and from then on hears everything the
+ * backend produces as a stream: each of its model's turns and reasoning
+ * summaries as a `BackendOutput`, each phase of the function calls it makes as
+ * a `BackendToolCall`, and when it has run out of things to do, that it is
+ * idle. Requests go the other way as messages appended to the backend's
+ * conversation, each answered at once; a message that arrives while the
+ * backend is working joins that work, and the backend's model sorts out what
+ * it means. `_BackendSession` is the caller side of that contract.
+ *
+ * A request is text, so how a frontend words one is its own business.
+ * `_renderTranscriptRequest` renders the conversation as a labelled
+ * transcript, which is what a frontend hands over when its model signals a
+ * handoff without wording a request; a frontend whose model does word one
+ * sends that instead. `OpenAILiveLLMService`'s client delegation and
+ * `LLMWithBackend` both drive the worker this way.
+ *
+ * Porting notes:
+ * - DIVERGENCE: upstream overrides `PipelineWorker.capabilities` with a plain
+ *   dict. TypeScript does not allow an override of a different type, so the
+ *   backend's capabilities are exposed as `backendCapabilities`, and
+ *   `PipelineWorker.capabilities` keeps its meaning.
+ * - `_BackendSession`'s `async with` is `enter()` / `exit()` (or `run(fn)`),
+ *   and its `async for` is `for await`.
+ */
+import { Event } from "@pipedog/asyncio";
+import type { BusJobCancelMessage, BusJobRequestMessage } from "../../bus/messages.ts";
+import { type ErrorFrame, type Frame } from "../../frames/frames.ts";
+import { type JobGroup, JobParams } from "../../pipeline/job_context.ts";
+import { type LLMContext, type LLMContextMessage } from "../../processors/aggregators/llm_context.ts";
+import { type AssistantThoughtMessage, type AssistantTurnStoppedMessage, type LLMAssistantAggregatorParams, LLMUserAggregatorParams } from "../../processors/aggregators/llm_response_universal.ts";
+import type { LLMService } from "../../services/llm_service.ts";
+import type { BaseWorker } from "../base_worker.ts";
+import { LLMContextWorker } from "./llm_context_worker.ts";
+type Dict = Record<string, unknown>;
+/** Name of the job that attaches a frontend to a `BackendLLMWorker`. */
+export declare const ATTACH_JOB_NAME = "attach";
+/** Name of the job that puts a message to an attached `BackendLLMWorker`. */
+export declare const MESSAGE_JOB_NAME = "message";
+/** The `type` of a job update that carries a `BackendOutput`. */
+export declare const OUTPUT_UPDATE_TYPE = "output";
+/** The `type` of a job update that carries a `BackendToolCall`. */
+export declare const TOOL_CALL_UPDATE_TYPE = "tool_call";
+/** The `type` of the update that opens an `attach` job's stream. */
+export declare const ATTACHED_UPDATE_TYPE = "attached";
+/** The `type` of the update that says the backend has nothing left to do. */
+export declare const IDLE_UPDATE_TYPE = "idle";
+/** The `type` of the update that says the backend could not go on. */
+export declare const ERROR_UPDATE_TYPE = "error";
+/**
+ * The mark the backend's model puts at the start of a message it wants the
+ * user told. The message is sent with `prefersSpoken: true`, mark stripped; a
+ * message without it is a note (`prefersSpoken: false`). Strict prompt,
+ * flexible parsing: the model is told to put the mark first, but sometimes
+ * writes a note paragraph and then a marked one, so a mark at the start of a
+ * later line splits the message, a note before it and a spoken message from it
+ * on, rather than losing the result. The turn-completion markers are read the
+ * same way (`user_turn_completion_mixin`).
+ */
+export declare const SPOKEN_MARK = ">>";
+/**
+ * How the backend's model works with the assistant, appended to its system
+ * instruction: who it is, which of what it writes the user hears, and how it
+ * takes requests. The backend's own system instruction says what it does;
+ * this says how what it writes reaches the user.
+ * `new BackendLLMWorker({ pairingInstruction })` replaces it.
+ */
+export declare const BACKEND_PAIRING_INSTRUCTION: string;
+export interface BackendOutputOptions {
+    /** The text the backend produced. */
+    text: string;
+    /** Whether this is a reasoning summary rather than a response. Defaults to false. */
+    isThought?: boolean;
+    /** Whether the backend would like the user to hear this. Defaults to true. */
+    prefersSpoken?: boolean;
+}
+/**
+ * One piece of output from a backend, on its way to the frontend.
+ *
+ * - `text`: the text the backend produced.
+ * - `isThought`: whether this is a reasoning summary rather than a response.
+ * - `prefersSpoken`: whether the backend would like the user to hear this.
+ *   This is just a hint to the frontend: it may choose to follow it or not.
+ *   `OpenAILiveLLMService`'s live model takes it into consideration, but
+ *   ultimately decides what to speak (or not) based on the conversation.
+ */
+export declare class BackendOutput {
+    text: string;
+    isThought: boolean;
+    prefersSpoken: boolean;
+    constructor(options: BackendOutputOptions);
+    /**
+     * Render the output as a job update payload.
+     *
+     * @returns The payload.
+     */
+    toPayload(): Dict;
+    /**
+     * Rebuild an output from a job update payload.
+     *
+     * @param payload The update payload.
+     * @returns The output.
+     */
+    static fromPayload(payload: Dict): BackendOutput;
+}
+/** The phases of a `BackendToolCall`. */
+export type BackendToolCallPhase = "started" | "in_progress" | "result" | "cancelled";
+export interface BackendToolCallOptions {
+    /** `started`, `in_progress`, `result` or `cancelled`. */
+    phase: BackendToolCallPhase;
+    /** Name of the function called. */
+    functionName: string;
+    /** Unique identifier of the call. */
+    toolCallId: string;
+    /** Arguments passed to the function, once known. */
+    arguments?: Record<string, unknown> | null;
+    /** The result, for the `result` phase. */
+    result?: unknown;
+    /**
+     * For the `result` phase, whether the result completes the call rather
+     * than being one of a stream of intermediate results. Defaults to true.
+     */
+    isFinal?: boolean;
+}
+/**
+ * One phase of a function call the backend made while working, on its way to
+ * the frontend.
+ *
+ * The call ran in the backend's own pipeline; the frontend reports it to
+ * clients, as the `ExternalFunctionCall*Frame` `toFrame` builds, and does
+ * nothing else with it. The phases mirror the pipeline's own function-call
+ * frames.
+ *
+ * - `phase`: `started`, `in_progress`, `result` or `cancelled`.
+ * - `functionName`: name of the function called.
+ * - `toolCallId`: unique identifier of the call.
+ * - `arguments`: arguments passed to the function, once known.
+ * - `result`: the result, for the `result` phase.
+ * - `isFinal`: for the `result` phase, whether the result completes the call
+ *   rather than being one of a stream of intermediate results.
+ */
+export declare class BackendToolCall {
+    phase: BackendToolCallPhase;
+    functionName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown> | null;
+    result: unknown;
+    isFinal: boolean;
+    constructor(options: BackendToolCallOptions);
+    /**
+     * Render the call phase as a job update payload.
+     *
+     * @returns The payload.
+     */
+    toPayload(): Dict;
+    /**
+     * Rebuild a call phase from a job update payload.
+     *
+     * @param payload The update payload.
+     * @returns The call phase.
+     */
+    static fromPayload(payload: Dict): BackendToolCall;
+    /**
+     * Build the frame that reports this phase in the frontend's pipeline.
+     *
+     * @returns The frame for the phase.
+     */
+    toFrame(): Frame;
+}
+/** The backend has nothing left to do: no run outstanding, no call in flight. */
+export declare class BackendIdle {
+}
+/**
+ * The backend could not go on with what it was doing.
+ *
+ * - `error`: what went wrong.
+ */
+export declare class BackendError {
+    error: string;
+    constructor(options: {
+        error: string;
+    });
+}
+/** What a `_BackendSession` yields. */
+export type BackendEvent = BackendOutput | BackendToolCall | BackendIdle | BackendError;
+/**
+ * Shapes one of the backend model's outputs before it is sent.
+ *
+ * Returns the output to send in place of `output`, or null to send nothing.
+ */
+export type BackendOutputTransform = (output: BackendOutput) => Promise<BackendOutput | null>;
+/** What `_renderTranscriptRequest` tells the backend to do with a transcript. */
+export declare const TRANSCRIPT_REQUEST_INSTRUCTION: string;
+/**
+ * Appended to a request the frontend worded itself, so the backend tells the
+ * user its result on its own rather than with whatever else it is doing.
+ */
+export declare const EXPLICIT_REQUEST_INSTRUCTION: string;
+/**
+ * Render a request the frontend worded itself, with what the backend should do
+ * with it after.
+ *
+ * @param request The request, as the frontend's model worded it.
+ * @param options.instruction What the backend should do with the request,
+ *   placed after it.
+ * @returns The rendered request.
+ */
+export declare function _renderExplicitRequest(request: string, options?: {
+    instruction?: string;
+}): string;
+/**
+ * Split a message the model wrote into its note and its spoken part, by the
+ * mark.
+ *
+ * @param text The message, stripped.
+ * @returns The note (what precedes the first line that begins with the mark,
+ *   or the whole message when no line does) and the spoken part (what follows
+ *   the mark, with any later mark removed, or empty), each stripped.
+ */
+export declare function _splitSpoken(text: string): [string, string];
+/**
+ * Render a conversation as a labelled transcript for the backend to act on.
+ *
+ * Flattening the conversation into one message keeps the two conversations
+ * apart: the backend's context holds only what the backend itself said as
+ * assistant messages, so it never mistakes the frontend's speech for its own.
+ *
+ * Only user and assistant text crosses today: tool calls, tool results,
+ * images, other non-text content and messages in a service's own format are
+ * skipped, and say so at debug level. Carrying more is a question of how to
+ * render it.
+ *
+ * @param conversation The conversation the user is having with the frontend,
+ *   as standard context messages.
+ * @param options.instruction What the backend should do with the transcript,
+ *   placed after it.
+ * @param options.first Whether this is the backend's first request in the
+ *   conversation. It decides how the transcript is introduced: as the
+ *   conversation so far, or as what has been said since the previous
+ *   delegation. Defaults to true.
+ * @returns The rendered request.
+ */
+export declare function _renderTranscriptRequest(conversation: readonly LLMContextMessage[], options?: {
+    instruction?: string;
+    first?: boolean;
+}): string;
+/** The frontend attached to the worker, for as long as its `attach` job lives. */
+declare class _AttachedFrontend {
+    jobId: string;
+    detached: Event;
+    constructor(options: {
+        jobId: string;
+        detached?: Event;
+    });
+}
+export interface BackendLLMWorkerOptions {
+    /** The backend LLM service. */
+    llm: LLMService;
+    /**
+     * The backend's context, typically carrying its tools. A fresh empty
+     * context when omitted.
+     */
+    context?: LLMContext | null;
+    /**
+     * Unique name for this worker on the bus. Auto-generated when omitted; give
+     * one when the backend runs in another process, where the frontend
+     * addresses it by name.
+     */
+    name?: string | null;
+    /**
+     * Called with each `BackendOutput` the model produces before it is sent, to
+     * adjust its text or whether the user may hear it, or to return null and
+     * send nothing. Outputs the app sends itself are not passed through it
+     * unless the call asks.
+     */
+    transformOutput?: BackendOutputTransform | null;
+    /**
+     * How the model works with the assistant, appended to the LLM's system
+     * instruction: `BACKEND_PAIRING_INSTRUCTION` unless given. One of its own
+     * has to say what that one says: that the assistant sends it requests, that
+     * the user hears what it marks with `SPOKEN_MARK` and nothing else, and how
+     * to take requests that arrive while it works.
+     */
+    pairingInstruction?: string;
+    /**
+     * Optional parameters for the user aggregator. Defaults to external turn
+     * strategies: the backend has no audio, so the default VAD and
+     * turn-analysis strategies (and the model the latter loads) have nothing to
+     * do here.
+     */
+    userParams?: LLMUserAggregatorParams | null;
+    /** Optional parameters for the assistant aggregator. */
+    assistantParams?: LLMAssistantAggregatorParams | null;
+}
+/**
+ * A worker that runs an LLM service as the backend a frontend delegates to.
+ *
+ * The worker owns the backend's conversation: an `LLMContext` plus the
+ * aggregator pair, so multi-step tool calling works as it does in any
+ * pipeline. A frontend attaches once, for as long as it lives, and from then
+ * on hears everything the backend produces; requests it sends are appended to
+ * that conversation as user messages and run the model. `_BackendSession` is
+ * the caller side.
+ *
+ * The worker's LLM does the reasoning its frontend hands off, so it runs at
+ * its provider's default thinking unless its settings configure thinking (see
+ * `LLMSettings.useProviderThinkingDefault`).
+ *
+ * Job contract:
+ *
+ * - `attach`: no payload. Its first update is
+ *   `{"type": "attached", "capabilities": {...}}`; after that, a
+ *   `BackendOutput` payload for each of the model's turns and reasoning
+ *   summaries and each output the app sends with `sendOutput`, a
+ *   `BackendToolCall` payload for each phase of each function call the
+ *   backend makes, `{"type": "idle"}` when the backend has nothing left to
+ *   do, and `{"type": "error", "error": ...}` when it could not go on. The job
+ *   lives until the requester cancels it, which stops the backend's work.
+ *   Refused while another frontend is attached.
+ * - `message`: `{"request": str}`, appended as a user message; responds at
+ *   once with `{"backend": "idle" | "working"}`, what the backend was doing
+ *   when the message arrived. A message that arrives mid-run is taken up
+ *   after the current step, with everything that came before it in view.
+ *
+ * The model decides what the user hears: a message it begins with
+ * `SPOKEN_MARK` asks to be spoken, whether or not the turn also calls tools,
+ * and the mark is stripped; anything else it writes, reasoning summaries
+ * included, is a note that the frontend keeps but does not speak. A mark at
+ * the start of a later line splits the message into a note and a spoken part,
+ * since the model sometimes writes it that way. The backend's own system
+ * instruction says what it does and, in plain words, what the user should be
+ * told; the pairing instruction the worker appends
+ * (`BACKEND_PAIRING_INSTRUCTION`, or the `pairingInstruction` given) is the
+ * only place the mark is named. `transformOutput` can change the flag, or the
+ * text, or drop the output.
+ *
+ * @example
+ * const backend = new BackendLLMWorker({
+ *   llm: new AnthropicLLMService({ apiKey: ... }),
+ *   context: new LLMContext({
+ *     messages: [{ role: "system", content: BACKEND_INSTRUCTIONS }],
+ *     tools: [getWeather],
+ *   }),
+ * });
+ */
+export declare class BackendLLMWorker extends LLMContextWorker {
+    protected _attached: _AttachedFrontend | null;
+    protected _transformOutput: BackendOutputTransform | null;
+    protected _requestsPending: number;
+    protected _runsRequested: number;
+    protected _runsCompleted: number;
+    protected _idleAnnounced: boolean;
+    protected _requestAwaitingRun: number | null;
+    /**
+     * Initialize the backend worker.
+     *
+     * @throws Error If the LLM service declines the role.
+     */
+    constructor(options: BackendLLMWorkerOptions);
+    /** Whether the backend has work in hand: a request or run outstanding, or a call in flight. */
+    get working(): boolean;
+    /** Whether a run is in progress or queued for the model. */
+    protected get _modelBusy(): boolean;
+    /**
+     * What an attached frontend can count on; all of it, for a backend that is
+     * an LLM.
+     *
+     * DIVERGENCE: `capabilities` upstream (see the module notes).
+     */
+    get backendCapabilities(): Record<string, boolean>;
+    /**
+     * Attach a frontend: stream everything the backend produces until the job
+     * is cancelled.
+     *
+     * @param message The job request.
+     */
+    attachFrontend(message: BusJobRequestMessage): Promise<void>;
+    /**
+     * Put a message to the backend, and say what it was doing when it arrived.
+     *
+     * @param message The job request; see the class docs for the payload.
+     */
+    handleMessage(message: BusJobRequestMessage): Promise<void>;
+    protected _refuse(jobId: string, reason: string): Promise<void>;
+    /**
+     * Append a request to the backend's conversation, and run the model on it
+     * if it is idle.
+     *
+     * While a run is in progress or queued, or a synchronous call is in flight,
+     * the request asks for no run of its own: the run that follows the current
+     * step takes it up (see `_requestAwaitingRun`). A run while a synchronous
+     * call is in flight would see the call without its result, which the
+     * adapter cannot send as it is.
+     */
+    protected _queueRequest(request: string): Promise<void>;
+    /** Whether a synchronous call is in flight, whose result will bring the next run. */
+    protected get _synchronousCallInFlight(): boolean;
+    /** Run the model on a request that was waiting for the current step, if nothing else will. */
+    protected _runAwaitingRequest(): Promise<void>;
+    /**
+     * Interrupt the pipeline and cancel every function call in flight.
+     *
+     * An interruption stops the run in progress and the calls that opt into
+     * cancellation on interruption; the async ones, which an interruption
+     * leaves running by design, are cancelled on their own. A request not yet
+     * taken up is dropped with the interruption, and one held for the current
+     * step is let go of, so that neither runs the model on work the frontend
+     * has abandoned: the cancellations that follow would otherwise run a held
+     * request as they settle.
+     */
+    protected _stopWork(reason: string): Promise<void>;
+    /**
+     * Send one output of the app's own to the frontend.
+     *
+     * It reaches the frontend as the model's outputs do, but as given unless
+     * asked: `transformOutput` is not applied to it by default. With no
+     * frontend attached there is nowhere for it to go, and it is dropped with a
+     * warning.
+     *
+     * @param output The output.
+     * @param options.applyTransformOutput Whether to run the output through
+     *   `transformOutput` as the model's outputs are. Defaults to false.
+     */
+    sendOutput(output: BackendOutput, options?: {
+        applyTransformOutput?: boolean;
+    }): Promise<void>;
+    protected _onAssistantTurnStopped(message: AssistantTurnStoppedMessage): Promise<void>;
+    /** Send the idle update once the backend has nothing left to do, once per lull. */
+    protected _announceIdleIfDone(): Promise<void>;
+    /** Relay a phase of one of the backend's own function calls as a job update. */
+    protected _onFunctionCallFrame(frame: Frame): Promise<void>;
+    /**
+     * Stop the model: the frontend that was attached is gone.
+     *
+     * The `attach` job's handler is already cancelled by the time this runs,
+     * and has let go of the attachment; the work in flight stops too, so none
+     * of it is reported after the frontend has let go of it.
+     */
+    onJobCancelled(message: BusJobCancelMessage): Promise<void>;
+    /**
+     * Tell the frontend the backend cannot go on with what it was doing.
+     *
+     * A tool handler that raises is the exception. The LLM service reports that
+     * as `ErrorCategory.APPLICATION`, settles the call with an error result and
+     * carries on, so the model still has something coming.
+     */
+    protected _onPipelineError(frame: ErrorFrame): Promise<void>;
+    protected _onAssistantThought(message: AssistantThoughtMessage): Promise<void>;
+    /** Run an output through `transformOutput`, if there is one. */
+    protected _shape(output: BackendOutput): Promise<BackendOutput | null>;
+    /** Send one output as a job update, after any configured transform. */
+    protected _emit(output: BackendOutput, options?: {
+        applyTransformOutput?: boolean;
+    }): Promise<void>;
+    /** Send a job update to the attached frontend. */
+    protected _sendUpdate(payload: Dict): Promise<void>;
+}
+/** Turn an `attach` stream update into the event it carries, if it carries one. */
+export declare function _eventFromPayload(payload: Dict): BackendEvent | null;
+/**
+ * A frontend's side of the attached contract: one worker, attached for the
+ * session's life.
+ *
+ * Opening the session sends the `attach` job; closing it cancels the job,
+ * which stops the backend's work. In between, the session is an async
+ * iterator over what the backend produces, and `send` puts messages to it.
+ * The iteration ends when the backend goes away, with a `JobError` if it
+ * failed.
+ *
+ * @example
+ * const session = new _BackendSession(worker, "backend");
+ * await session.run(async (session) => {
+ *   await session.send(request);
+ *   for await (const event of session) {
+ *     ...
+ *   }
+ * });
+ */
+export declare class _BackendSession implements AsyncIterableIterator<BackendEvent> {
+    protected _worker: BaseWorker;
+    protected _backendName: string;
+    protected _timeoutSecs: number | null;
+    protected _group: JobGroup | null;
+    protected _capabilities: Record<string, boolean>;
+    /**
+     * Whether the stream ended because this side let go of the backend (the
+     * session was closed, or the attaching worker stopped), as opposed to the
+     * backend going away.
+     */
+    detached: boolean;
+    /**
+     * Initialize the session.
+     *
+     * @param worker The worker attaching (for a pipeline processor,
+     *   `this.pipelineWorker`).
+     * @param backendName Name of the backend worker.
+     * @param options.timeoutSecs How long a message may take to be
+     *   acknowledged, including the wait for the backend to become ready. The
+     *   attachment itself has no timeout. Defaults to 30.
+     */
+    constructor(worker: BaseWorker, backendName: string, options?: {
+        timeoutSecs?: number | null;
+    });
+    /** Name of the backend worker. */
+    get backendName(): string;
+    /** What the backend said it can do, once its stream has opened. */
+    get capabilities(): Record<string, boolean>;
+    /** Open the session (`__aenter__`): send the `attach` job. */
+    enter(): Promise<this>;
+    /** Leave the session (`__aexit__`): close it. */
+    exit(_error?: unknown): Promise<void>;
+    /**
+     * Run `fn` inside the session, as `async with` does: open, run the block,
+     * then close (whether or not the block threw).
+     */
+    run<R>(fn: (session: this) => Promise<R> | R): Promise<R>;
+    /** Detach: cancel the `attach` job, which stops the backend's work. */
+    close(): Promise<void>;
+    [Symbol.asyncIterator](): this;
+    /** The next event from the backend (`__anext__`). */
+    next(): Promise<IteratorResult<BackendEvent>>;
+    /**
+     * Put a message to the backend.
+     *
+     * @param request The text to append to the backend's conversation.
+     * @returns What the backend was doing when the message arrived: `"idle"` or
+     *   `"working"`.
+     * @throws JobError If the backend refused the message or did not answer in
+     *   time.
+     */
+    send(request: string): Promise<string>;
+    /**
+     * Run one short job on the backend and return its response.
+     *
+     * @throws JobError If the backend refused, naming its reason, or did not
+     *   answer in time.
+     */
+    protected _ask(params: JobParams): Promise<Dict>;
+}
+/** The job error with the backend's own reason for it, when its response gave one. */
+export declare function _withReason(error: string, response: Dict | null | undefined): string;
+export {};
+//# sourceMappingURL=backend_llm_worker.d.ts.map