@pipedog/core 0.0.0 → 0.1.0

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

@@ -0,0 +1,68 @@
+/**
+ * Decorator for marking methods as LLM tools.
+ *
+ * Porting notes:
+ * - The deprecated `timeout` alias of `timeoutSecs` is not ported.
+ * - `_collectTools` returns the (unbound) methods found on the prototype
+ *   chain, not bound methods: direct-function metadata is read from a
+ *   function's source, which a bound function does not expose. `LLMWorker`
+ *   binds each one to the worker when it registers it on the LLM.
+ */
+import { type ToolOptionsMetadata } from "../../adapters/schemas/direct_function.ts";
+type AnyFn = (...args: any[]) => any;
+/** Options accepted by `tool()`. */
+export interface ToolDecoratorOptions {
+    /**
+     * Whether to cancel this tool call when an interruption occurs. Defaults to
+     * true. Only applies to `LLMWorker` tools.
+     */
+    cancelOnInterruption?: boolean;
+    /**
+     * Optional timeout in seconds for this tool call. A call that runs past it
+     * is cancelled. Defaults to null (uses the LLM service default). Only
+     * applies to `LLMWorker` tools.
+     */
+    timeoutSecs?: number | null;
+}
+/** A function marked by `tool()`. */
+export type LLMTool<F extends AnyFn = AnyFn> = F & ToolOptionsMetadata & {
+    _pipecatIsLlmTool: true;
+};
+/**
+ * Mark a method as a tool.
+ *
+ * On `LLMWorker` subclasses, decorated methods are automatically registered
+ * with the LLM and included in `buildTools()`.
+ *
+ * This is the worker-flavored variant of `toolOptions`: it attaches the same
+ * `cancelOnInterruption` / `timeoutSecs` call options and additionally marks
+ * the method (with `_pipecatIsLlmTool`) so the worker collects it from the
+ * prototype chain.
+ *
+ * Can be used with or without options, as a standard (TC39) method decorator
+ * or as a plain function (runtimes that strip types do not run decorator
+ * syntax):
+ *
+ * @example
+ * class MyWorker extends LLMWorker {
+ *   async my_tool(params: FunctionCallParams, arg: string) { ... }
+ *   async my_other_tool(params: FunctionCallParams, arg: string) { ... }
+ *   static {
+ *     tool(this.prototype.my_tool);
+ *     tool({ cancelOnInterruption: false, timeoutSecs: 60 })(this.prototype.my_other_tool);
+ *   }
+ * }
+ */
+export declare function tool<F extends AnyFn>(fn: F, context?: unknown): LLMTool<F>;
+export declare function tool(options?: ToolDecoratorOptions): <F extends AnyFn>(fn: F, context?: unknown) => LLMTool<F>;
+/**
+ * Collect all `tool` decorated methods from an object.
+ *
+ * Walks the prototype chain so that overridden methods in subclasses take
+ * precedence over base-class definitions.
+ *
+ * DIVERGENCE: returns the unbound methods (see the module notes).
+ */
+export declare function _collectTools(obj: object): LLMTool[];
+export {};
+//# sourceMappingURL=tool_decorator.d.ts.map

package/dist/workers/llm/tool_decorator.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/llm/tool_decorator.py
+/**
+ * Decorator for marking methods as LLM tools.
+ *
+ * Porting notes:
+ * - The deprecated `timeout` alias of `timeoutSecs` is not ported.
+ * - `_collectTools` returns the (unbound) methods found on the prototype
+ *   chain, not bound methods: direct-function metadata is read from a
+ *   function's source, which a bound function does not expose. `LLMWorker`
+ *   binds each one to the worker when it registers it on the LLM.
+ */
+import { toolOptions } from "../../adapters/schemas/direct_function.js";
+export function tool(fnOrOptions, _context) {
+    const options = typeof fnOrOptions === "function" ? {} : (fnOrOptions ?? {});
+    const cancelOnInterruption = options.cancelOnInterruption ?? true;
+    const timeoutSecs = options.timeoutSecs ?? null;
+    const decorator = (fn, _ctx) => {
+        const decorated = toolOptions(fn, { cancelOnInterruption, timeoutSecs });
+        decorated._pipecatIsLlmTool = true;
+        return decorated;
+    };
+    if (typeof fnOrOptions === "function") {
+        return decorator(fnOrOptions);
+    }
+    return decorator;
+}
+/**
+ * Collect all `tool` decorated methods from an object.
+ *
+ * Walks the prototype chain so that overridden methods in subclasses take
+ * precedence over base-class definitions.
+ *
+ * DIVERGENCE: returns the unbound methods (see the module notes).
+ */
+export function _collectTools(obj) {
+    const seen = new Set();
+    const tools = [];
+    let proto = Object.getPrototypeOf(obj);
+    while (proto !== null && proto !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(proto)) {
+            if (seen.has(name)) {
+                continue;
+            }
+            seen.add(name);
+            const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+            // Skip accessors so collecting never runs a getter.
+            const val = descriptor && "value" in descriptor ? descriptor.value : undefined;
+            if (typeof val === "function" && val._pipecatIsLlmTool === true) {
+                tools.push(val);
+            }
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    return tools;
+}
+//# sourceMappingURL=tool_decorator.js.map

package/dist/workers/runner.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Worker runner for managing worker execution and orchestration.
+ *
+ * This module provides the `WorkerRunner` class. It runs `BaseWorker`
+ * instances (including `PipelineWorker`) to completion, owning the shared
+ * `WorkerBus`, the worker registry, and the worker manager that backs the
+ * entire session.
+ *
+ * For a typical single-pipeline bot, register the worker with
+ * `WorkerRunner.addWorkers` and then call `WorkerRunner.run`:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(worker);
+ * await runner.run();
+ * ```
+ *
+ * For multi-worker setups, register every worker the same way:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(new CodeWorker("code-worker", ...), worker);
+ * await runner.run();
+ * ```
+ *
+ * By default, `run()` ends once every root worker has finished — so a
+ * single-pipeline bot naturally ends when its pipeline does. Multi-worker
+ * bots whose helpers run forever (e.g. waiting for bus messages) end by
+ * calling `WorkerRunner.end` / `WorkerRunner.cancel` from an event handler
+ * (typically on transport disconnect). For long-lived hosts that add and
+ * remove workers over many sessions (e.g. an HTTP server), pass
+ * `autoEnd: false` to `run()` so the runner does not exit when no workers
+ * are left.
+ */
+import { Event, type Task } from "@pipedog/asyncio";
+import { BusCancelWorkerMessage, BusEndWorkerMessage, type BusMessage, BusWorkerRegistryMessage, type WorkerBus } from "../bus/index.ts";
+import { WorkerRegistry } from "../registry/index.ts";
+import { WorkerReadyData } from "../registry/types.ts";
+import { type BaseTaskManager } from "../utils/asyncio/task_manager.ts";
+import { BaseObject } from "../utils/base_object.ts";
+import { type BaseWorker } from "./base_worker.ts";
+/** A worker registered on the runner and its background task. */
+declare class _WorkerEntry {
+    worker: BaseWorker;
+    runnerTask: Task<unknown> | null;
+    constructor(options: {
+        worker: BaseWorker;
+        runnerTask?: Task<unknown> | null;
+    });
+}
+export interface WorkerRunnerOptions {
+    /**
+     * Optional name for the runner instance. Defaults to a UUID-based name.
+     * Must be unique across runners in a distributed setup.
+     */
+    name?: string | null;
+    /** Optional `WorkerBus`. Defaults to a new in-process `AsyncQueueBus`. */
+    bus?: WorkerBus | null;
+    /** Whether to automatically handle SIGINT signals. */
+    handleSigint?: boolean;
+    /** Whether to automatically handle SIGTERM signals. */
+    handleSigterm?: boolean;
+    /** Whether to force garbage collection once every worker has been torn down. */
+    forceGc?: boolean;
+    /**
+     * Whether to warn about tasks left running on the shared task manager once
+     * every worker has finished.
+     */
+    checkDanglingTasks?: boolean;
+    /** Optional task manager for handling tasks. */
+    taskManager?: BaseTaskManager | null;
+}
+export interface WorkerRunnerRunOptions {
+    /**
+     * When true (the default), the runner ends once every root worker has
+     * finished. When false, the runner blocks until `end()` or `cancel()` is
+     * called.
+     */
+    autoEnd?: boolean;
+}
+declare const WorkerRunner_base: typeof BaseObject & import("../utils/mixin.ts").Ctor<import("../bus/subscriber.ts").BusSubscriberMethods>;
+/**
+ * Manages worker execution.
+ *
+ * Provides a high-level interface for running workers with automatic signal
+ * handling (SIGINT/SIGTERM), optional garbage collection, proper cleanup of
+ * resources, and a worker bus + registry for multi-worker orchestration.
+ *
+ * Two entry points:
+ *
+ * - `addWorkers(...workers)` — register one or more workers on the runner's
+ *   bus and start them in the background. Workers run concurrently and
+ *   remaining workers are cancelled when the runner ends.
+ * - `run()` — block until the runner ends. By default (`autoEnd: true`) the
+ *   runner ends once every root worker has finished; pass `autoEnd: false`
+ *   to keep the runner up until `end()` / `cancel()` is called.
+ *
+ * Event handlers available:
+ *
+ * - `on_ready` — fired after the runner has finished its initialization and
+ *   any added workers have been started.
+ * - `on_error` — fired when starting an added worker fails.
+ */
+export declare class WorkerRunner extends WorkerRunner_base {
+    protected _bus: WorkerBus;
+    protected _registry: WorkerRegistry;
+    protected _checkDanglingTasks: boolean;
+    protected _entries: Map<string, _WorkerEntry>;
+    protected _knownRunners: Set<string>;
+    protected _running: boolean;
+    protected _autoEnd: boolean;
+    protected _cancelReason: string | null;
+    protected _shutdownEvent: Event;
+    protected _sigTask: Task<void> | null;
+    protected _handleSigint: boolean;
+    protected _handleSigterm: boolean;
+    protected _forceGc: boolean;
+    /**
+     * Initialize the worker runner.
+     *
+     * @param options Runner options (see `WorkerRunnerOptions`).
+     */
+    constructor(options?: WorkerRunnerOptions);
+    /** The bus this runner hosts; shared across launched workers. */
+    get bus(): WorkerBus;
+    /** The worker registry this runner owns. */
+    get registry(): WorkerRegistry;
+    /**
+     * Look up a worker running on this runner by name.
+     *
+     * Only workers added to this runner have a local instance to return. A
+     * worker on another runner is addressable over the bus by name but has no
+     * object here, so it looks the same as an unknown name.
+     *
+     * @param name The name the worker was created with.
+     * @returns The worker, or null if this runner has no worker by that name.
+     */
+    getWorker(name: string): BaseWorker | null;
+    /**
+     * Add one or more workers to the runner.
+     *
+     * Adding a worker attaches it to the runner's bus and registry, and starts
+     * it in the background. If the runner is not yet running (`addWorkers` was
+     * called before `run()`), workers are queued and started during run setup;
+     * if the runner is already running, each worker starts immediately.
+     *
+     * Every added worker is a peer: the runner privileges none of them. They
+     * run concurrently, and whichever are still running when the runner ends
+     * are cancelled. With `autoEnd: true` the runner ends once every root
+     * worker has finished, so a worker that never finishes on its own, such as
+     * a bus-only one waiting for messages, keeps it up until `end()` or
+     * `cancel()` is called.
+     *
+     * @param workers One or more workers to add.
+     */
+    addWorkers(...workers: BaseWorker[]): Promise<void>;
+    /**
+     * Run all added workers until the runner is stopped.
+     *
+     * By default (`autoEnd: true`), the runner ends once every root worker has
+     * finished — so a single-pipeline bot naturally ends when its pipeline
+     * does. Multi-worker bots whose helpers run forever (e.g. waiting for bus
+     * messages) end by calling `end()` / `cancel()` from an event handler
+     * (typically on transport disconnect). For long-lived hosts that add and
+     * remove workers over many sessions (e.g. an HTTP server), pass
+     * `autoEnd: false` so the runner does not exit when no workers are left.
+     *
+     * @param options.autoEnd When true (the default), the runner ends once
+     *   every root worker has finished. When false, the runner blocks until
+     *   `end()` or `cancel()` is called.
+     */
+    run(options?: WorkerRunnerRunOptions): Promise<void>;
+    /** Schedule all root pipeline workers to stop when their current processing is complete. */
+    stopWhenDone(): Promise<void>;
+    /**
+     * Gracefully end all running workers.
+     *
+     * Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for ending.
+     */
+    end(reason?: string | null): Promise<void>;
+    /**
+     * Immediately cancel all running workers.
+     *
+     * Signals shutdown, which `run()` answers by cancelling every worker still
+     * going and waiting for it. Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for cancelling. Reaches each
+     *   worker on the cancel message sent as the runner exits.
+     */
+    cancel(reason?: string | null): Promise<void>;
+    /** Process incoming bus messages for runner-level concerns. */
+    onBusMessage(message: BusMessage): Promise<void>;
+    /** One-time per-run setup: worker manager, bus, signal handlers, launched workers. */
+    protected _setupSession(): Promise<void>;
+    /**
+     * Cancel every worker still going and wait for it to finish.
+     *
+     * The one place the runner cancels its workers, reached on every way out:
+     * an ended session, a cancelled one, or the last root worker finishing. A
+     * worker whose task has already finished is left alone.
+     */
+    protected _cancelSpawnedWorkers(): Promise<void>;
+    /**
+     * Ask each root worker that has not finished to wind down.
+     *
+     * Both messages this takes end a worker, gracefully or not. A worker whose
+     * task has already finished is skipped; one that has not started yet has
+     * not finished either, so it is still told.
+     *
+     * Sending is all this does. The worker finishes in its own time, which is
+     * what the returned entries are for.
+     *
+     * @param messageClass The per-worker message to send.
+     * @param reason Optional human-readable reason, carried on each message.
+     * @returns The entries that were messaged, root or otherwise.
+     */
+    protected _finishRunningWorkers(messageClass: typeof BusEndWorkerMessage | typeof BusCancelWorkerMessage, reason: string | null): Promise<_WorkerEntry[]>;
+    /**
+     * Run `setup_worker_runner` from each file in `PIPECAT_SETUP_FILES`.
+     *
+     * A setup file may define `setup_worker_runner(runner)` (or `setupWorkerRunner`) to add workers,
+     * attach event handlers, or wire other runner-level configuration.
+     */
+    protected _loadSetupFiles(): Promise<void>;
+    /** Run a registered worker as a background task. */
+    protected _startWorker(entry: _WorkerEntry): Promise<void>;
+    /** Drive a registered worker to completion. */
+    protected _runWorker(worker: BaseWorker): Promise<void>;
+    /** Called when a local added worker registers as ready. */
+    protected _onLocalWorkerReady(data: WorkerReadyData): Promise<void>;
+    /** Broadcast this runner's workers to the bus. */
+    protected _sendRegistry(): Promise<void>;
+    /** Handle a registry message from a remote runner. */
+    protected _handleWorkerRegistry(message: BusWorkerRegistryMessage): Promise<void>;
+    /**
+     * Set up SIGINT handler for graceful shutdown.
+     *
+     * DIVERGENCE: installed through the host's `process.on` when there is one
+     * (Bun, Node, Deno); a no-op on runtimes without process signals (Workers).
+     */
+    protected _setupSigint(): void;
+    /**
+     * Set up SIGTERM handler for graceful shutdown.
+     *
+     * DIVERGENCE: see `_setupSigint`.
+     */
+    protected _setupSigterm(): void;
+    /** Handle interrupt signals by cancelling the runner. */
+    protected _sigHandler(): void;
+    /** Cancel the runner due to signal interruption. */
+    protected _sigCancel(): Promise<void>;
+    /**
+     * Force garbage collection and log results.
+     *
+     * DIVERGENCE: JS has no `gc.collect()` count or `gc.garbage`; this calls
+     * the global `gc()` when the runtime exposes one (e.g. Node/Deno with
+     * `--expose-gc`).
+     */
+    protected _gcCollect(): Promise<void>;
+    /** Warn about tasks left running on the task manager this runner owns. */
+    protected _printDanglingTasks(): void;
+}
+export {};
+//# sourceMappingURL=runner.d.ts.map