@pipedog/core 0.0.0 → 0.2.0

package/dist/pipeline/job_context.js

@@ -0,0 +1,450 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/pipeline/job_context.py
+/**
+ * Worker group types for structured concurrent worker execution.
+ *
+ * Porting notes:
+ * - `async with ctx:` becomes `await ctx.run(async (ctx) => { ... })`, or the
+ *   explicit `await ctx.enter()` / `await ctx.exit(error)` pair.
+ * - `async for event in ctx` is `for await (const event of ctx)`.
+ * - The deprecated `resolve_job_params()` (and the per-argument job spelling
+ *   it absorbs) is not ported.
+ */
+import { Event, Queue, shield } from "@pipedog/asyncio";
+/**
+ * Configuration for a job sent to a single worker.
+ *
+ * - `name`: optional job name, routing the request to the matching
+ *   `job({ name })` handler on the worker.
+ * - `payload`: optional structured data describing the work.
+ * - `timeout`: optional timeout in seconds, covering both the wait for the
+ *   worker to become ready and the job itself.
+ * - `label`: optional human-readable description of the work, e.g.
+ *   `"Research: Radiohead"`. A `UIWorker` titles the client's progress card
+ *   with it.
+ * - `cancellable`: whether an external requester, such as the client UI, may
+ *   ask for the job to be cancelled. Cancellation the worker initiates itself
+ *   (shutdown, timeout, `cancelOnError`) proceeds either way.
+ */
+export class JobParams {
+    name;
+    payload;
+    timeout;
+    label;
+    cancellable;
+    constructor(options = {}) {
+        this.name = options.name ?? null;
+        this.payload = options.payload ?? null;
+        this.timeout = options.timeout ?? null;
+        this.label = options.label ?? null;
+        this.cancellable = options.cancellable ?? true;
+    }
+}
+/**
+ * Configuration for a job sent to several workers at once.
+ *
+ * Carries every `JobParams` field, which apply to the group as a whole, plus
+ * how the group reacts to one of its workers failing.
+ *
+ * - `cancelOnError`: whether a worker responding with an error status cancels
+ *   the rest of the group.
+ */
+export class JobGroupParams extends JobParams {
+    cancelOnError;
+    constructor(options = {}) {
+        super(options);
+        this.cancelOnError = options.cancelOnError ?? true;
+    }
+}
+/**
+ * Status of a completed worker.
+ *
+ * String values, so they compare naturally with plain strings and serialize
+ * without extra handling.
+ *
+ * - `COMPLETED`: the worker finished successfully.
+ * - `CANCELLED`: the worker was cancelled by the requester.
+ * - `FAILED`: the worker failed due to a logical or business error.
+ * - `ERROR`: the worker encountered an unexpected runtime error.
+ */
+export const JobStatus = {
+    COMPLETED: "completed",
+    CANCELLED: "cancelled",
+    FAILED: "failed",
+    ERROR: "error",
+};
+/** Raised when a worker is cancelled due to a worker error or timeout. */
+export class JobError extends Error {
+    name = "JobError";
+}
+/** Raised when a worker group is cancelled due to a worker error or timeout. */
+export class JobGroupError extends Error {
+    name = "JobGroupError";
+}
+/**
+ * Collected results from a completed job group.
+ *
+ * - `jobId`: the shared job identifier.
+ * - `responses`: collected responses keyed by worker name.
+ */
+export class JobGroupResponse {
+    jobId;
+    responses;
+    constructor(options) {
+        this.jobId = options.jobId;
+        this.responses = options.responses;
+    }
+}
+/**
+ * An event received from a worker during a single-worker job.
+ *
+ * - `type`: the event type.
+ * - `data`: optional event payload.
+ */
+export class JobEvent {
+    static UPDATE = "update";
+    static STREAM_START = "stream_start";
+    static STREAM_DATA = "stream_data";
+    static STREAM_END = "stream_end";
+    type;
+    data;
+    constructor(options) {
+        this.type = options.type;
+        this.data = options.data ?? null;
+    }
+}
+/**
+ * An event received from a worker during job group execution.
+ *
+ * - `type`: the event type.
+ * - `workerName`: the name of the worker that sent the event.
+ * - `data`: optional event payload.
+ */
+export class JobGroupEvent {
+    static UPDATE = "update";
+    static STREAM_START = "stream_start";
+    static STREAM_DATA = "stream_data";
+    static STREAM_END = "stream_end";
+    type;
+    workerName;
+    data;
+    constructor(options) {
+        this.type = options.type;
+        this.workerName = options.workerName;
+        this.data = options.data ?? null;
+    }
+}
+/**
+ * Tracks a group of workers launched together.
+ *
+ * - `jobId`: shared identifier for all workers in this group.
+ * - `workerNames`: names of the workers in the group, in dispatch order.
+ * - `responses`: collected responses keyed by worker name.
+ * - `timeoutTask`: optional task that cancels the group on timeout.
+ * - `cancelOnError`: whether to cancel the group if a worker errors.
+ * - `label`: optional human-readable description of the work, from
+ *   `JobGroupParams.label`.
+ * - `cancellable`: whether an external requester may ask for the group to be
+ *   cancelled, from `JobGroupParams.cancellable`.
+ * - `terminated`: names of the workers that have reached a terminal state,
+ *   whether by responding or by ending their stream.
+ * - `eventQueue`: optional queue for streaming events to a `JobGroupContext`
+ *   async iterator.
+ */
+export class JobGroup {
+    jobId;
+    workerNames;
+    responses;
+    timeoutTask;
+    cancelOnError;
+    label;
+    cancellable;
+    terminated;
+    eventQueue;
+    _done = new Event();
+    _error = null;
+    constructor(options) {
+        this.jobId = options.jobId;
+        this.workerNames = options.workerNames;
+        this.responses = options.responses ?? {};
+        this.timeoutTask = options.timeoutTask ?? null;
+        this.cancelOnError = options.cancelOnError ?? true;
+        this.label = options.label ?? null;
+        this.cancellable = options.cancellable ?? true;
+        this.terminated = options.terminated ?? new Set();
+        this.eventQueue = options.eventQueue ?? null;
+    }
+    /** Whether the group has completed or failed. */
+    get isDone() {
+        return this._done.isSet();
+    }
+    /**
+     * Wait for all workers in the group to respond.
+     *
+     * @throws JobGroupError If the group was cancelled due to error or timeout.
+     */
+    async wait() {
+        await this._done.wait();
+        if (this._error) {
+            throw new JobGroupError(this._error);
+        }
+    }
+    /** Signal that all workers have responded. */
+    complete() {
+        this._done.set();
+        if (this.eventQueue) {
+            this.eventQueue.putNowait(null);
+        }
+    }
+    /**
+     * Signal that the group was cancelled.
+     *
+     * @param reason Human-readable reason for the failure.
+     */
+    fail(reason = null) {
+        this._error = reason;
+        this._done.set();
+        if (this.eventQueue) {
+            this.eventQueue.putNowait(null);
+        }
+    }
+    toString() {
+        return `JobGroup(job_id=${this.jobId}, worker_names=${JSON.stringify(this.workerNames)})`;
+    }
+}
+/**
+ * Async context manager and iterator for structured job group execution.
+ *
+ * Sends job requests on enter, waits for all responses on exit. Supports
+ * `for await` to receive intermediate events (updates and streaming data)
+ * from workers while waiting for completion.
+ *
+ * On normal completion, results are available via `responses`. On worker
+ * error (with `cancelOnError: true`) or timeout, throws `JobGroupError`. If
+ * the block throws, remaining jobs are cancelled.
+ *
+ * @example
+ * const tg = this.jobGroup(["w1", "w2"], { params: new JobGroupParams({ payload: data }) });
+ * await tg.run(async (tg) => {
+ *   for await (const event of tg) {
+ *     console.log(`${event.workerName} [${event.type}]:`, event.data);
+ *   }
+ * });
+ *
+ * for (const [name, result] of Object.entries(tg.responses)) {
+ *   console.log(name, result);
+ * }
+ */
+export class JobGroupContext {
+    _worker;
+    _workerNames;
+    _params;
+    _group = null;
+    /**
+     * Initialize the JobGroupContext.
+     *
+     * @param worker The parent `BaseWorker` that owns this job group.
+     * @param workerNames Names of the workers to send the job to.
+     * @param options.params How to run the group. Defaults to `JobGroupParams` defaults.
+     */
+    constructor(worker, workerNames, options = {}) {
+        this._worker = worker;
+        this._workerNames = workerNames;
+        this._params = options.params ?? new JobGroupParams();
+    }
+    /** The shared job identifier for this group. */
+    get jobId() {
+        if (!this._group) {
+            throw new Error("Job group has not been started");
+        }
+        return this._group.jobId;
+    }
+    /** Collected responses keyed by worker name. */
+    get responses() {
+        if (!this._group) {
+            throw new Error("Job group has not been started");
+        }
+        return this._group.responses;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            if (!this._group?.eventQueue)
+                return;
+            const event = await this._group.eventQueue.get();
+            if (event === null)
+                return;
+            yield event;
+        }
+    }
+    /** Send the job requests (`__aenter__`). */
+    async enter() {
+        const group = await this._worker.createJobGroupAndRequestJob([...this._workerNames], {
+            params: this._params,
+        });
+        group.eventQueue = new Queue();
+        this._group = group;
+        return this;
+    }
+    /**
+     * Leave the block (`__aexit__`): cancel the remaining jobs if the block
+     * threw, otherwise wait for every response.
+     *
+     * @param error What the block threw, if anything (`undefined` when it
+     *   completed normally).
+     */
+    async exit(error) {
+        if (error !== undefined) {
+            if (this._group && this._worker.jobGroups.has(this._group.jobId)) {
+                // Shield the cleanup so it completes even if the surrounding worker
+                // is being cancelled (e.g. tool interruption).
+                const jobId = this._group.jobId;
+                await shield(() => this._worker.cancelJobGroup(jobId, { reason: "context exited with error" }));
+            }
+            return;
+        }
+        if (this._group === null)
+            throw new Error("Job group has not been started");
+        await this._group.wait();
+    }
+    /**
+     * Run `fn` inside the context, as `async with` does: enter, run the block,
+     * then exit. An error thrown by the block cancels the group and is
+     * re-thrown.
+     */
+    async run(fn) {
+        await this.enter();
+        let result;
+        try {
+            result = await fn(this);
+        }
+        catch (e) {
+            await this.exit(e ?? new Error("context exited with error"));
+            throw e;
+        }
+        await this.exit();
+        return result;
+    }
+}
+/**
+ * Async context manager and iterator for a single-worker job.
+ *
+ * Sends a job request on enter, waits for the response on exit. Supports
+ * `for await` to receive intermediate events (updates and streaming data)
+ * from the worker while waiting for completion.
+ *
+ * On normal completion, the result is available via `response`. On worker
+ * error or timeout, throws `JobError`. If the block throws, the job is
+ * cancelled.
+ *
+ * @example
+ * const t = this.job("worker", { params: new JobParams({ payload: data }) });
+ * await t.run(async (t) => {
+ *   for await (const event of t) {
+ *     console.log(`[${event.type}]:`, event.data);
+ *   }
+ * });
+ *
+ * console.log(t.response);
+ */
+export class JobContext {
+    _worker;
+    _workerName;
+    _params;
+    _group = null;
+    /**
+     * Initialize the JobContext.
+     *
+     * @param worker The parent `BaseWorker` that owns this job.
+     * @param workerName Name of the worker to send the job to.
+     * @param options.params How to run the job. Defaults to `JobParams` defaults.
+     */
+    constructor(worker, workerName, options = {}) {
+        this._worker = worker;
+        this._workerName = workerName;
+        this._params = options.params ?? new JobParams();
+    }
+    /** The job identifier. */
+    get jobId() {
+        if (!this._group) {
+            throw new Error("Job has not been started");
+        }
+        return this._group.jobId;
+    }
+    /** The worker's response payload. */
+    get response() {
+        if (!this._group) {
+            throw new Error("Job has not been started");
+        }
+        return this._group.responses[this._workerName] ?? {};
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            if (!this._group?.eventQueue)
+                return;
+            const event = await this._group.eventQueue.get();
+            if (event === null)
+                return;
+            yield new JobEvent({ type: event.type, data: event.data });
+        }
+    }
+    /** Send the job request (`__aenter__`). */
+    async enter() {
+        const group = await this._worker.createJobGroupAndRequestJob([this._workerName], {
+            params: new JobGroupParams({ ...this._params }),
+        });
+        group.eventQueue = new Queue();
+        this._group = group;
+        return this;
+    }
+    /**
+     * Leave the block (`__aexit__`): cancel the job if the block threw,
+     * otherwise wait for the response.
+     *
+     * @param error What the block threw, if anything (`undefined` when it
+     *   completed normally).
+     * @throws JobError If the worker failed or timed out.
+     */
+    async exit(error) {
+        if (error !== undefined) {
+            if (this._group && this._worker.jobGroups.has(this._group.jobId)) {
+                // Shield the cleanup so it completes even if the surrounding worker
+                // is being cancelled (e.g. tool interruption).
+                const jobId = this._group.jobId;
+                await shield(() => this._worker.cancelJobGroup(jobId, { reason: "context exited with error" }));
+            }
+            return;
+        }
+        if (this._group === null)
+            throw new Error("Job has not been started");
+        try {
+            await this._group.wait();
+        }
+        catch (e) {
+            if (e instanceof JobGroupError) {
+                throw new JobError(e.message, { cause: e });
+            }
+            throw e;
+        }
+    }
+    /**
+     * Run `fn` inside the context, as `async with` does: enter, run the block,
+     * then exit. An error thrown by the block cancels the job and is re-thrown.
+     */
+    async run(fn) {
+        await this.enter();
+        let result;
+        try {
+            result = await fn(this);
+        }
+        catch (e) {
+            await this.exit(e ?? new Error("context exited with error"));
+            throw e;
+        }
+        await this.exit();
+        return result;
+    }
+}
+//# sourceMappingURL=job_context.js.map

package/dist/pipeline/job_decorator.d.ts

@@ -0,0 +1,54 @@
+/** Decorator for marking worker methods as job handlers. */
+type AnyFn = (...args: any[]) => any;
+/** A function marked by `job()`. */
+export type JobHandler<F extends AnyFn = AnyFn> = F & {
+    isJobHandler: true;
+    jobName: string;
+    jobSequential: boolean;
+};
+/**
+ * Mark a worker method as a job handler.
+ *
+ * Decorated methods are automatically collected by `BaseWorker` at
+ * initialization and dispatched when matching job requests arrive. Each
+ * request runs in its own task so the bus message loop is never blocked.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyWorker extends BaseWorker {
+ *   async onResearch(message: BusJobRequestMessage): Promise<void> { ... }
+ *   async onWrite(message: BusJobRequestMessage): Promise<void> { ... }
+ *   static {
+ *     job({ name: "research" })(this.prototype.onResearch);
+ *     job({ name: "write", sequential: true })(this.prototype.onWrite);
+ *   }
+ * }
+ *
+ * @param options.name Job name to match. The handler only receives requests
+ *   with a matching name.
+ * @param options.sequential When true, requests with this name run one at a
+ *   time in FIFO order. Concurrent requests wait for the previous one to
+ *   finish before running. When false (the default), multiple requests run
+ *   concurrently. The wait time counts against the requester's timeout, so a
+ *   slow predecessor can cause queued requests to time out before they start.
+ */
+export declare function job(options: {
+    name: string;
+    sequential?: boolean;
+}): <F extends AnyFn>(fn: F, _context?: unknown) => F;
+/**
+ * Collect all `job` decorated bound methods from an object.
+ *
+ * Walks the prototype chain from the object's own class up, so an override in
+ * a subclass shadows the parent's method of the same name.
+ *
+ * @returns A map from job name to the bound method. Each bound method keeps
+ *   the `jobSequential` flag of the decorated function.
+ * @throws Error If two handlers handle the same job name.
+ */
+export declare function _collectJobHandlers(obj: object): Map<string, AnyFn>;
+export {};
+//# sourceMappingURL=job_decorator.d.ts.map

package/dist/pipeline/job_decorator.js

@@ -0,0 +1,92 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/pipeline/job_decorator.py
+/**
+ * Mark a worker method as a job handler.
+ *
+ * Decorated methods are automatically collected by `BaseWorker` at
+ * initialization and dispatched when matching job requests arrive. Each
+ * request runs in its own task so the bus message loop is never blocked.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyWorker extends BaseWorker {
+ *   async onResearch(message: BusJobRequestMessage): Promise<void> { ... }
+ *   async onWrite(message: BusJobRequestMessage): Promise<void> { ... }
+ *   static {
+ *     job({ name: "research" })(this.prototype.onResearch);
+ *     job({ name: "write", sequential: true })(this.prototype.onWrite);
+ *   }
+ * }
+ *
+ * @param options.name Job name to match. The handler only receives requests
+ *   with a matching name.
+ * @param options.sequential When true, requests with this name run one at a
+ *   time in FIFO order. Concurrent requests wait for the previous one to
+ *   finish before running. When false (the default), multiple requests run
+ *   concurrently. The wait time counts against the requester's timeout, so a
+ *   slow predecessor can cause queued requests to time out before they start.
+ */
+export function job(options) {
+    const name = options.name;
+    const sequential = options.sequential ?? false;
+    return function decorator(fn, _context) {
+        const handler = fn;
+        handler.isJobHandler = true;
+        handler.jobName = name;
+        handler.jobSequential = sequential;
+        return fn;
+    };
+}
+/**
+ * Collect all `job` decorated bound methods from an object.
+ *
+ * Walks the prototype chain from the object's own class up, so an override in
+ * a subclass shadows the parent's method of the same name.
+ *
+ * @returns A map from job name to the bound method. Each bound method keeps
+ *   the `jobSequential` flag of the decorated function.
+ * @throws Error If two handlers handle the same job name.
+ */
+export function _collectJobHandlers(obj) {
+    const seen = new Set();
+    const handlers = new Map();
+    const handlerNames = new Map();
+    let proto = Object.getPrototypeOf(obj);
+    while (proto !== null && proto !== Object.prototype) {
+        for (const attrName of Object.getOwnPropertyNames(proto)) {
+            if (seen.has(attrName)) {
+                continue;
+            }
+            seen.add(attrName);
+            const descriptor = Object.getOwnPropertyDescriptor(proto, attrName);
+            // Skip accessors so collecting never runs a getter.
+            const val = descriptor && "value" in descriptor ? descriptor.value : undefined;
+            if (typeof val === "function" && val.isJobHandler === true) {
+                const jobName = val.jobName;
+                if (handlers.has(jobName)) {
+                    const existing = handlerNames.get(jobName);
+                    throw new Error(`Duplicate @job handler for '${jobName}': ` +
+                        `'${attrName}' conflicts with '${existing}'`);
+                }
+                const method = obj[attrName];
+                // Python's bound method still exposes the function's attributes
+                // (`handler.job_sequential`); copy them onto the bound function.
+                const bound = method.bind(obj);
+                bound.isJobHandler = true;
+                bound.jobName = jobName;
+                bound.jobSequential = val.jobSequential;
+                handlers.set(jobName, bound);
+                handlerNames.set(jobName, attrName);
+            }
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    return handlers;
+}
+//# sourceMappingURL=job_decorator.js.map

package/dist/pipeline/llm_switcher.d.ts

@@ -0,0 +1,84 @@
+/** LLM switcher for switching between different LLMs at runtime, with different switching strategies. */
+import { type Frame } from "../frames/frames.ts";
+import type { LLMContext } from "../processors/aggregators/llm_context.ts";
+import type { FrameDirection } from "../processors/frame_processor.ts";
+import type { FunctionCallHandler, LLMService } from "../services/llm_service.ts";
+import { ServiceSwitcher, type ServiceSwitcherOptions, type ServiceSwitcherStrategy, type ServiceSwitcherStrategyManual } from "./service_switcher.ts";
+type AnyLLMService = LLMService<any>;
+/** Options forwarded to the active LLM's `runInference()`. */
+export type LLMSwitcherRunInferenceOptions = Parameters<AnyLLMService["runInference"]>[1];
+/**
+ * A pipeline that switches between different LLMs at runtime.
+ *
+ * @example
+ * const llmSwitcher = new LLMSwitcher([openaiLlm, anthropicLlm]);
+ */
+export declare class LLMSwitcher<S extends ServiceSwitcherStrategy = ServiceSwitcherStrategyManual> extends ServiceSwitcher<S> {
+    /**
+     * Initialize the service switcher with a list of LLMs and a switching strategy.
+     *
+     * @param llms List of LLM services to switch between.
+     * @param options.strategyType The strategy class to use for switching
+     *   between LLMs. Defaults to `ServiceSwitcherStrategyManual`.
+     */
+    constructor(llms: AnyLLMService[], options?: ServiceSwitcherOptions<S>);
+    /**
+     * Process a frame, syncing context tool handlers on all member LLMs.
+     *
+     * On an `LLMContextFrame`, the handlers advertised in the context are synced
+     * on every member LLM — active or not — so that tools listed via
+     * `new LLMContext({ tools: [...] })` keep working across service switches.
+     *
+     * This is needed because member LLMs sit behind per-branch filters: only the
+     * active LLM receives the context frame and would otherwise sync its
+     * handlers, leaving inactive LLMs out of step with the advertised tools.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame flow.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Sync the context's tool handlers on every member LLM.
+     *
+     * @param tools The advertised tools whose handlers should be synced on all
+     *   member LLMs.
+     */
+    protected _syncRegisteredToolHandlers(tools: unknown): void;
+    /** The list of LLMs managed by this switcher. */
+    get llms(): AnyLLMService[];
+    /** The currently active LLM. */
+    get activeLlm(): AnyLLMService;
+    /**
+     * Run a one-shot, out-of-band (i.e. out-of-pipeline) inference with the
+     * given LLM context, using the currently active LLM.
+     *
+     * @param context The LLM context containing conversation history.
+     * @param options Additional options forwarded to the active LLM's
+     *   `runInference` (e.g. maxTokens, systemInstruction).
+     * @returns The LLM's response as a string, or null if no response is generated.
+     */
+    runInference(context: LLMContext, options?: LLMSwitcherRunInferenceOptions): Promise<string | null>;
+    /**
+     * Register a function handler for LLM function calls, on all LLMs, active or not.
+     *
+     * @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. Defaults to null (fall back to the
+     *   `toolOptions()` value on the handler, then to true).
+     * @param options.timeoutSecs Optional timeout in seconds for the function call.
+     * @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`. 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;
+}
+export {};
+//# sourceMappingURL=llm_switcher.d.ts.map