@pipedog/core 0.0.0 → 0.2.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/proxy/index.d.ts

@@ -0,0 +1,3 @@
+/** Proxy workers for forwarding bus messages over network transports. */
+export { WebSocketProxyClient } from "./websocket/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/workers/proxy/index.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/proxy/__init__.py
+/** Proxy workers for forwarding bus messages over network transports. */
+// WebSocketProxyServer lives in `@pipedog/worker-proxy` (it needs a server framework).
+export { WebSocketProxyClient } from "./websocket/index.js";
+//# sourceMappingURL=index.js.map

package/dist/workers/proxy/websocket/client.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WebSocket client proxy that forwards bus messages to a remote server.
+ *
+ * Porting notes: upstream connects with the `websockets` library; this port
+ * uses `websocketConnect` / `WebsocketClientConnection` from
+ * `services/websocket_service.ts`, the stand-in for its asyncio client.
+ */
+import { type Task } from "@pipedog/asyncio";
+import { type BusMessage } from "../../../bus/messages.ts";
+import type { MessageSerializer } from "../../../bus/serializers/base.ts";
+import { type WebsocketClientConnection } from "../../../services/websocket_service.ts";
+import { BaseWorker, type BaseWorkerOptions } from "../../base_worker.ts";
+type Dict = Record<string, unknown>;
+/** A bus message class, as listed in `forwardMessages`. */
+export type BusMessageType = abstract new (...args: any[]) => BusMessage;
+export interface WebSocketProxyClientOptions extends Omit<BaseWorkerOptions, "name" | "active"> {
+    /** Unique name for this worker. */
+    name: string;
+    /** The WebSocket URL to connect to. */
+    url: string;
+    /**
+     * Name of the worker on the remote server. Only messages targeted at this
+     * worker are forwarded.
+     */
+    remoteWorkerName: string;
+    /**
+     * Name of the local worker that should receive responses. Only inbound
+     * messages targeted at this worker are accepted.
+     */
+    localWorkerName: string;
+    /**
+     * Additional message types to forward from the local worker (e.g.
+     * `[BusFrameMessage]` for frame routing). These are forwarded based on
+     * source worker name only, regardless of target.
+     */
+    forwardMessages?: readonly BusMessageType[];
+    /** Optional HTTP headers sent with the WebSocket handshake (e.g. for authentication). */
+    headers?: Record<string, string> | null;
+    /** Serializer for bus messages. Defaults to `JSONMessageSerializer`. */
+    serializer?: MessageSerializer | null;
+    /**
+     * Whether the worker starts active. Defaults to false because
+     * `onActivated` opens the WebSocket connection, which is almost always a
+     * deliberate action triggered by an upstream event (e.g. the local client
+     * connecting). Pass true to connect as soon as the worker starts.
+     */
+    active?: boolean;
+}
+/**
+ * Forwards bus messages to a remote worker over WebSocket.
+ *
+ * Connects to a WebSocket URL and forwards messages between a local
+ * worker and a remote worker. Only messages targeted at the remote worker
+ * are sent. Only messages targeted at the local worker are accepted.
+ *
+ * Event handlers available:
+ *
+ * - on_connected: Fired when the WebSocket connection is established.
+ * - on_disconnected: Fired when the WebSocket connection is closed.
+ *
+ * @example
+ * ```ts
+ * const proxy = new WebSocketProxyClient({
+ *   name: "proxy",
+ *   url: "ws://remote-server:8765/ws",
+ *   remoteWorkerName: "worker",
+ *   localWorkerName: "voice",
+ * });
+ *
+ * proxy.eventHandler("on_connected", async (worker, websocket) => {
+ *   logger.info("Connected to remote server");
+ * });
+ *
+ * proxy.eventHandler("on_disconnected", async (worker, websocket) => {
+ *   logger.info("Disconnected from remote server");
+ * });
+ *
+ * await runner.addWorkers(proxy);
+ * ```
+ */
+export declare class WebSocketProxyClient extends BaseWorker {
+    protected _url: string;
+    protected _remoteWorkerName: string;
+    protected _localWorkerName: string;
+    protected _forwardMessages: readonly BusMessageType[];
+    protected _headers: Record<string, string>;
+    protected _serializer: MessageSerializer;
+    protected _ws: WebsocketClientConnection | null;
+    protected _receiveTask: Task<void> | null;
+    /** Initialize the WebSocketProxyClient. */
+    constructor(options: WebSocketProxyClientOptions);
+    /** Connect to the remote WebSocket server. */
+    onActivated(args: Dict | null): Promise<void>;
+    /** Cancel the receive loop and close the WebSocket connection. */
+    stop(): Promise<void>;
+    /**
+     * Forward messages targeted at the remote worker.
+     *
+     * @param message The bus message to process.
+     */
+    onBusMessage(message: BusMessage): Promise<void>;
+    /** Whether `message` is one of the `forwardMessages` types. */
+    protected _isForwardMessage(message: BusMessage): boolean;
+    /** Serialize and send a message over the WebSocket. */
+    protected _sendWs(message: BusMessage): Promise<void>;
+    /** Read messages from the WebSocket and put them on the local bus. */
+    protected _receiveLoop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/workers/proxy/websocket/client.js

@@ -0,0 +1,196 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/proxy/websocket/client.py
+/**
+ * WebSocket client proxy that forwards bus messages to a remote server.
+ *
+ * Porting notes: upstream connects with the `websockets` library; this port
+ * uses `websocketConnect` / `WebsocketClientConnection` from
+ * `services/websocket_service.ts`, the stand-in for its asyncio client.
+ */
+import { CancelledError, rethrowIfCancelled, sleep } from "@pipedog/asyncio";
+import { BusLocalMessage, BusWorkerRegistryMessage, } from "../../../bus/messages.js";
+import { JSONMessageSerializer } from "../../../bus/serializers/json.js";
+import { ConnectionClosed, websocketConnect, } from "../../../services/websocket_service.js";
+import { logger } from "../../../utils/logger.js";
+import { BaseWorker } from "../../base_worker.js";
+/**
+ * Forwards bus messages to a remote worker over WebSocket.
+ *
+ * Connects to a WebSocket URL and forwards messages between a local
+ * worker and a remote worker. Only messages targeted at the remote worker
+ * are sent. Only messages targeted at the local worker are accepted.
+ *
+ * Event handlers available:
+ *
+ * - on_connected: Fired when the WebSocket connection is established.
+ * - on_disconnected: Fired when the WebSocket connection is closed.
+ *
+ * @example
+ * ```ts
+ * const proxy = new WebSocketProxyClient({
+ *   name: "proxy",
+ *   url: "ws://remote-server:8765/ws",
+ *   remoteWorkerName: "worker",
+ *   localWorkerName: "voice",
+ * });
+ *
+ * proxy.eventHandler("on_connected", async (worker, websocket) => {
+ *   logger.info("Connected to remote server");
+ * });
+ *
+ * proxy.eventHandler("on_disconnected", async (worker, websocket) => {
+ *   logger.info("Disconnected from remote server");
+ * });
+ *
+ * await runner.addWorkers(proxy);
+ * ```
+ */
+export class WebSocketProxyClient extends BaseWorker {
+    _url;
+    _remoteWorkerName;
+    _localWorkerName;
+    _forwardMessages;
+    _headers;
+    _serializer;
+    _ws = null;
+    _receiveTask = null;
+    /** Initialize the WebSocketProxyClient. */
+    constructor(options) {
+        super({ ...options, name: options.name, active: options.active ?? false });
+        this._url = options.url;
+        this._remoteWorkerName = options.remoteWorkerName;
+        this._localWorkerName = options.localWorkerName;
+        this._forwardMessages = options.forwardMessages ?? [];
+        this._headers = options.headers ?? {};
+        this._serializer = options.serializer ?? new JSONMessageSerializer();
+        this._registerEventHandler("on_connected");
+        this._registerEventHandler("on_disconnected");
+    }
+    /** Connect to the remote WebSocket server. */
+    async onActivated(args) {
+        await super.onActivated(args);
+        logger.debug(`Worker '${this}': connecting to ${this._url}`);
+        this._ws = await websocketConnect(this._url, { additionalHeaders: this._headers });
+        logger.debug(`Worker '${this}': connected to ${this._url}`);
+        await this._callEventHandler("on_connected", this._ws);
+        this._receiveTask = this.createTask(() => this._receiveLoop());
+        // Schedule worker right away.
+        await sleep(0);
+    }
+    /** Cancel the receive loop and close the WebSocket connection. */
+    async stop() {
+        if (this._receiveTask) {
+            await this.cancelTask(this._receiveTask);
+            this._receiveTask = null;
+        }
+        if (this._ws) {
+            await this._ws.close();
+            logger.debug(`Worker '${this}': WebSocket connection closed`);
+            this._ws = null;
+        }
+        await super.stop();
+    }
+    /**
+     * Forward messages targeted at the remote worker.
+     *
+     * @param message The bus message to process.
+     */
+    async onBusMessage(message) {
+        await super.onBusMessage(message);
+        if (!this._ws)
+            return;
+        if (message instanceof BusLocalMessage)
+            return;
+        // Forward targeted messages to the remote worker.
+        if (message.target === this._remoteWorkerName) {
+            await this._sendWs(message);
+        }
+        // Forward additional message types from the local worker.
+        else if (this._isForwardMessage(message)) {
+            if (message.source === this._localWorkerName) {
+                await this._sendWs(message);
+            }
+        }
+    }
+    /** Whether `message` is one of the `forwardMessages` types. */
+    _isForwardMessage(message) {
+        return this._forwardMessages.some((type) => message instanceof type);
+    }
+    /** Serialize and send a message over the WebSocket. */
+    async _sendWs(message) {
+        if (!this._ws)
+            return;
+        try {
+            const data = this._serializer.serialize(message);
+            await this._ws.send(data);
+            logger.trace(`Worker '${this}': sent ${message}`);
+        }
+        catch (e) {
+            if (!(e instanceof ConnectionClosed))
+                throw e;
+            logger.warning(`Worker '${this}': connection closed, stopping forwarding`);
+            const ws = this._ws;
+            this._ws = null;
+            await this._callEventHandler("on_disconnected", ws);
+        }
+    }
+    /** Read messages from the WebSocket and put them on the local bus. */
+    async _receiveLoop() {
+        if (this._ws === null) {
+            throw new Error("onActivated() must run before _receiveLoop");
+        }
+        const encoder = new TextEncoder();
+        try {
+            for await (const data of this._ws) {
+                try {
+                    const payload = typeof data === "string" ? encoder.encode(data) : data;
+                    const message = this._serializer.deserialize(payload);
+                    if (!message)
+                        continue;
+                    // Accept registry messages (target=None) for worker discovery.
+                    if (message instanceof BusWorkerRegistryMessage) {
+                        logger.trace(`Worker '${this}': received registry from remote: ${JSON.stringify(message.workers)}`);
+                        await this.sendBusMessage(message);
+                        continue;
+                    }
+                    // Accept additional message types (e.g. BusFrameMessage).
+                    if (this._forwardMessages.length > 0 && this._isForwardMessage(message)) {
+                        logger.trace(`Worker '${this}': received ${message} from remote`);
+                        await this.sendBusMessage(message);
+                        continue;
+                    }
+                    // Only accept other messages targeted at the local worker.
+                    if (message.target !== this._localWorkerName) {
+                        logger.warning(`Worker '${this}': dropped inbound message with ` +
+                            `unexpected target '${message.target}'`);
+                        continue;
+                    }
+                    logger.trace(`Worker '${this}': received ${message} from remote`);
+                    await this.sendBusMessage(message);
+                }
+                catch (e) {
+                    rethrowIfCancelled(e);
+                    logger.error(`Worker '${this}': failed to deserialize remote message`, e);
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof ConnectionClosed) {
+                logger.warning(`Worker '${this}': WebSocket connection closed`);
+                const ws = this._ws;
+                this._ws = null;
+                await this._callEventHandler("on_disconnected", ws);
+            }
+            else if (e instanceof CancelledError) {
+                // except asyncio.CancelledError: pass (upstream ends the loop quietly).
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/workers/proxy/websocket/index.d.ts

@@ -0,0 +1,3 @@
+/** WebSocket proxy workers for forwarding bus messages. */
+export { WebSocketProxyClient } from "./client.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/workers/proxy/websocket/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/proxy/websocket/__init__.py
+/** WebSocket proxy workers for forwarding bus messages. */
+export { WebSocketProxyClient } from "./client.js";
+// WebSocketProxyServer depends on a server framework (Starlette upstream), so it
+// lives in its own package: import it from `@pipedog/worker-proxy`.
+//# sourceMappingURL=index.js.map