@pipedog/core 0.0.0 → 0.1.0

package/dist/registry/registry.d.ts

@@ -0,0 +1,69 @@
+import type { WorkerReadyData } from "./types.ts";
+export type WatchHandler = (data: WorkerReadyData) => Promise<unknown>;
+/**
+ * Tracks all known workers across local and remote runners.
+ *
+ * Owned by a runner and shared with its workers. Organizes workers into
+ * local (this runner) and remote (other runners) so they are easy to
+ * distinguish. Deduplication is built in: each worker name is
+ * registered at most once.
+ *
+ * Notifications use a targeted watch mechanism: call
+ * `watch(workerName, handler)` to be notified when a specific worker
+ * registers.
+ */
+export declare class WorkerRegistry {
+    protected _runnerName: string;
+    protected _localWorkers: Map<string, WorkerReadyData>;
+    protected _remoteWorkers: Map<string, Map<string, WorkerReadyData>>;
+    protected _watches: Map<string, WatchHandler[]>;
+    /**
+     * Initialize the WorkerRegistry.
+     *
+     * @param runnerName Name of the runner that owns this registry.
+     */
+    constructor(runnerName: string);
+    /** The name of the runner that owns this registry. */
+    get runnerName(): string;
+    /** Names of workers registered under this runner. */
+    get localWorkers(): string[];
+    /** Names of workers registered under remote runners. */
+    get remoteWorkers(): string[];
+    /**
+     * Look up a registered worker by name.
+     *
+     * @param workerName The worker name to look up.
+     * @returns The worker's `WorkerReadyData`, or null if not found.
+     */
+    get(workerName: string): WorkerReadyData | null;
+    /** Whether a worker with this name is registered (Python's `in`). */
+    has(workerName: string): boolean;
+    /**
+     * Watch for a specific worker's registration.
+     *
+     * Idempotent: registering the same `(workerName, handler)` pair more than
+     * once is a no-op (otherwise the handler would fire multiple times when the
+     * worker registers — e.g. when a parent both calls `addWorkers(child)`
+     * (which auto-watches) and declares a `workerReady({ name: child.name })`
+     * handler that the framework also installs).
+     *
+     * If the worker is already registered, the handler fires immediately.
+     *
+     * @param workerName The worker name to watch for.
+     * @param handler Async callable invoked with the worker's data.
+     */
+    watch(workerName: string, handler: WatchHandler): Promise<void>;
+    /**
+     * Register a worker. Returns true if the worker was new.
+     *
+     * If the worker is already registered, this is a no-op and returns false.
+     * Otherwise the worker is added and watchers are notified.
+     *
+     * @param workerData Information about the worker to register.
+     * @returns True if the worker was newly registered, false if already known.
+     */
+    register(workerData: WorkerReadyData): Promise<boolean>;
+    /** Notify watchers of a new registration. */
+    protected _notify(workerData: WorkerReadyData): Promise<void>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/registry.js

@@ -0,0 +1,149 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/registry/registry.py
+/** Shared registry for tracking known workers across runners. */
+import { logger } from "../utils/logger.js";
+/**
+ * Tracks all known workers across local and remote runners.
+ *
+ * Owned by a runner and shared with its workers. Organizes workers into
+ * local (this runner) and remote (other runners) so they are easy to
+ * distinguish. Deduplication is built in: each worker name is
+ * registered at most once.
+ *
+ * Notifications use a targeted watch mechanism: call
+ * `watch(workerName, handler)` to be notified when a specific worker
+ * registers.
+ */
+export class WorkerRegistry {
+    _runnerName;
+    _localWorkers = new Map();
+    _remoteWorkers = new Map();
+    _watches = new Map();
+    /**
+     * Initialize the WorkerRegistry.
+     *
+     * @param runnerName Name of the runner that owns this registry.
+     */
+    constructor(runnerName) {
+        this._runnerName = runnerName;
+    }
+    /** The name of the runner that owns this registry. */
+    get runnerName() {
+        return this._runnerName;
+    }
+    /** Names of workers registered under this runner. */
+    get localWorkers() {
+        return [...this._localWorkers.keys()];
+    }
+    /** Names of workers registered under remote runners. */
+    get remoteWorkers() {
+        const result = [];
+        for (const workers of this._remoteWorkers.values()) {
+            result.push(...workers.keys());
+        }
+        return result;
+    }
+    /**
+     * Look up a registered worker by name.
+     *
+     * @param workerName The worker name to look up.
+     * @returns The worker's `WorkerReadyData`, or null if not found.
+     */
+    get(workerName) {
+        const local = this._localWorkers.get(workerName);
+        if (local) {
+            return local;
+        }
+        for (const workers of this._remoteWorkers.values()) {
+            const remote = workers.get(workerName);
+            if (remote) {
+                return remote;
+            }
+        }
+        return null;
+    }
+    /** Whether a worker with this name is registered (Python's `in`). */
+    has(workerName) {
+        return this.get(workerName) !== null;
+    }
+    /**
+     * Watch for a specific worker's registration.
+     *
+     * Idempotent: registering the same `(workerName, handler)` pair more than
+     * once is a no-op (otherwise the handler would fire multiple times when the
+     * worker registers — e.g. when a parent both calls `addWorkers(child)`
+     * (which auto-watches) and declares a `workerReady({ name: child.name })`
+     * handler that the framework also installs).
+     *
+     * If the worker is already registered, the handler fires immediately.
+     *
+     * @param workerName The worker name to watch for.
+     * @param handler Async callable invoked with the worker's data.
+     */
+    async watch(workerName, handler) {
+        let handlers = this._watches.get(workerName);
+        if (!handlers) {
+            handlers = [];
+            this._watches.set(workerName, handlers);
+        }
+        if (handlers.includes(handler)) {
+            return;
+        }
+        handlers.push(handler);
+        const existing = this.get(workerName);
+        if (existing) {
+            await handler(existing);
+        }
+    }
+    /**
+     * Register a worker. Returns true if the worker was new.
+     *
+     * If the worker is already registered, this is a no-op and returns false.
+     * Otherwise the worker is added and watchers are notified.
+     *
+     * @param workerData Information about the worker to register.
+     * @returns True if the worker was newly registered, false if already known.
+     */
+    async register(workerData) {
+        const isLocal = workerData.runner === this._runnerName;
+        let target;
+        if (isLocal) {
+            target = this._localWorkers;
+        }
+        else {
+            let remote = this._remoteWorkers.get(workerData.runner);
+            if (!remote) {
+                remote = new Map();
+                this._remoteWorkers.set(workerData.runner, remote);
+            }
+            target = remote;
+        }
+        if (target.has(workerData.workerName)) {
+            return false;
+        }
+        // Warn if the same name exists on a different runner
+        const existing = this.get(workerData.workerName);
+        if (existing && existing.runner !== workerData.runner) {
+            logger.warning(`Worker '${workerData.workerName}' registered on both ` +
+                `'${existing.runner}' and '${workerData.runner}'`);
+        }
+        target.set(workerData.workerName, workerData);
+        const locality = isLocal ? "local" : workerData.runner;
+        logger.debug(`Worker '${workerData.workerName}' ready (${locality})`);
+        await this._notify(workerData);
+        return true;
+    }
+    /** Notify watchers of a new registration. */
+    async _notify(workerData) {
+        // Iterate the live list by index, as Python does: handlers appended
+        // during notification are visited too.
+        const handlers = this._watches.get(workerData.workerName) ?? [];
+        for (let i = 0; i < handlers.length; i++) {
+            await handlers[i](workerData);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry/types.d.ts

@@ -0,0 +1,47 @@
+/** Shared types for the worker registry. */
+export interface WorkerRegistryEntryOptions {
+    /** The worker's name. */
+    name: string;
+    /** Name of the parent worker, or null for root tasks. */
+    parent?: string | null;
+    /** Whether the worker is currently active. */
+    active?: boolean;
+    /** Whether the worker is bridged. */
+    bridged?: boolean;
+    /** Unix timestamp when the worker became ready. */
+    startedAt?: number | null;
+}
+/** Information about a worker in a registry snapshot. */
+export declare class WorkerRegistryEntry {
+    name: string;
+    parent: string | null;
+    active: boolean;
+    bridged: boolean;
+    startedAt: number | null;
+    constructor(options: WorkerRegistryEntryOptions);
+}
+export interface WorkerReadyDataOptions {
+    /** The name of the worker. */
+    workerName: string;
+    /** The name of the runner managing this worker. */
+    runner: string;
+}
+/** Information about a registered worker. */
+export declare class WorkerReadyData {
+    workerName: string;
+    runner: string;
+    constructor(options: WorkerReadyDataOptions);
+}
+export interface WorkerErrorDataOptions {
+    /** The name of the worker that errored. */
+    workerName: string;
+    /** Description of the error. */
+    error: string;
+}
+/** Information about a worker error. */
+export declare class WorkerErrorData {
+    workerName: string;
+    error: string;
+    constructor(options: WorkerErrorDataOptions);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.js

@@ -0,0 +1,39 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/registry/types.py
+/** Information about a worker in a registry snapshot. */
+export class WorkerRegistryEntry {
+    name;
+    parent;
+    active;
+    bridged;
+    startedAt;
+    constructor(options) {
+        this.name = options.name;
+        this.parent = options.parent ?? null;
+        this.active = options.active ?? false;
+        this.bridged = options.bridged ?? false;
+        this.startedAt = options.startedAt ?? null;
+    }
+}
+/** Information about a registered worker. */
+export class WorkerReadyData {
+    workerName;
+    runner;
+    constructor(options) {
+        this.workerName = options.workerName;
+        this.runner = options.runner;
+    }
+}
+/** Information about a worker error. */
+export class WorkerErrorData {
+    workerName;
+    error;
+    constructor(options) {
+        this.workerName = options.workerName;
+        this.error = options.error;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/serializers/base_serializer.d.ts

@@ -0,0 +1,94 @@
+/** Frame serialization interfaces for Pipecat. */
+import { type Frame } from "../frames/frames.ts";
+import type { FrameProcessorSetup } from "../processors/frame_processor.ts";
+import { BaseObject, type BaseObjectOptions } from "../utils/base_object.ts";
+export interface FrameSerializerInputParamsOptions {
+    /**
+     * Whether to ignore RTVI protocol messages during serialization. Defaults
+     * to true to prevent RTVI messages from being sent to external transports.
+     */
+    ignoreRtviMessages?: boolean;
+    /**
+     * Seconds of inactivity after which the stream resampler clears its
+     * internal history to avoid audio artefacts from stale state. Set to `null`
+     * to never clear — recommended for telephony providers (e.g. Genesys) that
+     * have irregular gaps between audio chunks. Defaults to `0.2`.
+     */
+    resamplerClearAfterSecs?: number | null;
+}
+/**
+ * Base configuration parameters for FrameSerializer.
+ *
+ * - `ignoreRtviMessages`: whether to ignore RTVI protocol messages during
+ *   serialization. Defaults to true to prevent RTVI messages from being sent
+ *   to external transports.
+ * - `resamplerClearAfterSecs`: seconds of inactivity after which the stream
+ *   resampler clears its internal history to avoid audio artefacts from stale
+ *   state. Set to `null` to never clear — recommended for telephony providers
+ *   (e.g. Genesys) that have irregular gaps between audio chunks. Defaults to
+ *   `0.2`.
+ */
+export declare class FrameSerializerInputParams {
+    ignoreRtviMessages: boolean;
+    resamplerClearAfterSecs: number | null;
+    constructor(options?: FrameSerializerInputParamsOptions);
+}
+export interface FrameSerializerOptions extends BaseObjectOptions {
+    /** Configuration parameters. */
+    params?: FrameSerializerInputParams | null;
+}
+/** Serialized frame data: a string or bytes. */
+export type SerializedData = string | Uint8Array;
+/**
+ * Abstract base class for frame serialization implementations.
+ *
+ * Defines the interface for converting frames to/from serialized formats
+ * for transmission or storage. Subclasses must implement the core
+ * serialize/deserialize methods.
+ */
+export declare abstract class FrameSerializer extends BaseObject {
+    /** Upstream's nested `FrameSerializer.InputParams`. */
+    static InputParams: typeof FrameSerializerInputParams;
+    protected _params: FrameSerializerInputParams;
+    /**
+     * Initialize the FrameSerializer.
+     *
+     * @param options.params Configuration parameters. Other options (e.g.
+     *   `name`) are passed to BaseObject.
+     */
+    constructor(options?: FrameSerializerOptions);
+    /**
+     * Check if a frame should be ignored during serialization.
+     *
+     * This method filters out RTVI protocol messages when `ignoreRtviMessages`
+     * is enabled. Subclasses can override this to add additional filtering
+     * logic.
+     *
+     * @param frame The frame to check.
+     * @returns True if the frame should be ignored, false otherwise.
+     */
+    shouldIgnoreFrame(frame: Frame): boolean;
+    /**
+     * Initialize the serializer with pipeline configuration.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(_setup: FrameProcessorSetup | unknown): Promise<void>;
+    /**
+     * Convert a frame to its serialized representation.
+     *
+     * @param frame The frame to serialize.
+     * @returns Serialized frame data as string or bytes, or null when there is
+     *   nothing to send for this frame: it isn't handled, or the serializer is
+     *   buffering it and will emit it on a later call.
+     */
+    abstract serialize(frame: Frame): Promise<SerializedData | null>;
+    /**
+     * Convert serialized data back to a frame object.
+     *
+     * @param data Serialized frame data as string or bytes.
+     * @returns Reconstructed Frame object, or null if deserialization fails.
+     */
+    abstract deserialize(data: SerializedData): Promise<Frame | null>;
+}
+//# sourceMappingURL=base_serializer.d.ts.map

package/dist/serializers/base_serializer.js

@@ -0,0 +1,82 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/serializers/base_serializer.py
+/** Frame serialization interfaces for Pipecat. */
+import { OutputTransportMessageFrame, OutputTransportMessageUrgentFrame, } from "../frames/frames.js";
+import * as RTVI from "../processors/frameworks/rtvi/models.js";
+import { BaseObject } from "../utils/base_object.js";
+/**
+ * Base configuration parameters for FrameSerializer.
+ *
+ * - `ignoreRtviMessages`: whether to ignore RTVI protocol messages during
+ *   serialization. Defaults to true to prevent RTVI messages from being sent
+ *   to external transports.
+ * - `resamplerClearAfterSecs`: seconds of inactivity after which the stream
+ *   resampler clears its internal history to avoid audio artefacts from stale
+ *   state. Set to `null` to never clear — recommended for telephony providers
+ *   (e.g. Genesys) that have irregular gaps between audio chunks. Defaults to
+ *   `0.2`.
+ */
+export class FrameSerializerInputParams {
+    ignoreRtviMessages;
+    resamplerClearAfterSecs;
+    constructor(options = {}) {
+        this.ignoreRtviMessages = options.ignoreRtviMessages ?? true;
+        this.resamplerClearAfterSecs =
+            options.resamplerClearAfterSecs === undefined ? 0.2 : options.resamplerClearAfterSecs;
+    }
+}
+/**
+ * Abstract base class for frame serialization implementations.
+ *
+ * Defines the interface for converting frames to/from serialized formats
+ * for transmission or storage. Subclasses must implement the core
+ * serialize/deserialize methods.
+ */
+export class FrameSerializer extends BaseObject {
+    /** Upstream's nested `FrameSerializer.InputParams`. */
+    static InputParams = FrameSerializerInputParams;
+    _params;
+    /**
+     * Initialize the FrameSerializer.
+     *
+     * @param options.params Configuration parameters. Other options (e.g.
+     *   `name`) are passed to BaseObject.
+     */
+    constructor(options = {}) {
+        super(options);
+        this._params = options.params || new FrameSerializerInputParams();
+    }
+    /**
+     * Check if a frame should be ignored during serialization.
+     *
+     * This method filters out RTVI protocol messages when `ignoreRtviMessages`
+     * is enabled. Subclasses can override this to add additional filtering
+     * logic.
+     *
+     * @param frame The frame to check.
+     * @returns True if the frame should be ignored, false otherwise.
+     */
+    shouldIgnoreFrame(frame) {
+        if (this._params.ignoreRtviMessages &&
+            (frame instanceof OutputTransportMessageFrame ||
+                frame instanceof OutputTransportMessageUrgentFrame) &&
+            typeof frame.message === "object" &&
+            frame.message !== null &&
+            frame.message.label === RTVI.MESSAGE_LABEL) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Initialize the serializer with pipeline configuration.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    // Typed `unknown` to keep BaseObject.setup's signature; callers pass a
+    // FrameProcessorSetup, as upstream does.
+    async setup(_setup) { }
+}
+//# sourceMappingURL=base_serializer.js.map

package/dist/serializers/index.d.ts

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

package/dist/serializers/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/serializers/__init__.py
+// Upstream's `__init__.py` is empty: import the package's modules directly.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/services/ai_service.d.ts

@@ -0,0 +1,145 @@
+import { CancelFrame, EndFrame, type Frame, type ServiceMetadataFrame, StartFrame } from "../frames/frames.ts";
+import { FrameDirection, FrameProcessor, type FrameProcessorOptions, type FrameProcessorSetup } from "../processors/frame_processor.ts";
+import type { TracingContext } from "../utils/tracing/tracing_context.ts";
+import { ServiceSettings } from "./settings.ts";
+export interface AIServiceOptions extends FrameProcessorOptions {
+    /** The runtime-updatable settings for the AI service. */
+    settings?: ServiceSettings | null;
+}
+/**
+ * Base class for all AI services.
+ *
+ * Provides common functionality for AI services including model management,
+ * settings handling, session properties, and frame processing lifecycle.
+ * Subclasses should implement specific AI functionality while leveraging
+ * this base infrastructure.
+ */
+export declare class AIService extends FrameProcessor {
+    protected _settings: ServiceSettings;
+    protected _sessionProperties: Record<string, unknown>;
+    protected _tracingEnabled: boolean;
+    protected _tracingContext: TracingContext | null;
+    /**
+     * Initialize the AI service.
+     *
+     * @param options.settings The runtime-updatable settings for the AI service.
+     *   Other options are passed to the parent FrameProcessor.
+     */
+    constructor(options?: AIServiceOptions);
+    /**
+     * The service's current settings, for reading.
+     *
+     * Change them with a `ServiceUpdateSettingsFrame`, so the service applies
+     * the change and its metrics keep the model in sync.
+     */
+    get settings(): ServiceSettings;
+    /**
+     * Sync the current AI model name (in `this._settings.model`) for usage in
+     * metrics.
+     *
+     * We don't store model name here because there's already a single source
+     * of truth for it in `this._settings.model`. This method is just for
+     * syncing the model name to the metrics data.
+     */
+    protected _syncModelNameToMetrics(): void;
+    /**
+     * The metadata frame this service broadcasts at start, or null.
+     *
+     * Override to return a populated `ServiceMetadataFrame` (or a subtype such
+     * as `STTMetadataFrame`) describing this service for downstream processors,
+     * for example the `userTurnStrategies` an STT with server-side end-of-turn
+     * detection recommends. Return null to broadcast nothing.
+     *
+     * @returns The metadata frame to broadcast, or null.
+     */
+    serviceMetadataFrame(): ServiceMetadataFrame | null;
+    /** Broadcast this service's metadata frame, if any. */
+    broadcastServiceMetadata(): Promise<void>;
+    /**
+     * Set up the service.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /**
+     * Start the AI service.
+     *
+     * Called when the service should begin processing. Subclasses should
+     * override this method to perform service-specific initialization.
+     *
+     * @param _frame The start frame containing initialization parameters.
+     */
+    start(_frame: StartFrame): Promise<void>;
+    /**
+     * Stop the AI service on a graceful end (`EndFrame`).
+     *
+     * Runs in frame order, after pending frames drain. Override for graceful
+     * shutdown behavior, such as flushing in-flight work before stopping.
+     *
+     * @param _frame The end frame.
+     */
+    stop(_frame: EndFrame): Promise<void>;
+    /**
+     * Cancel the AI service immediately (`CancelFrame`).
+     *
+     * Runs at once, ahead of any queued frames, to abort active work fast (for
+     * example, stop producing audio now). Override only for that time-sensitive
+     * subset.
+     *
+     * @param _frame The cancel frame.
+     */
+    cancel(_frame: CancelFrame): Promise<void>;
+    /**
+     * Apply a settings delta and return the changed fields.
+     *
+     * The delta is applied to `_settings` and a record mapping each changed
+     * field name to its **pre-update** value is returned. The `model` field is
+     * handled specially: when it changes, the model name is synced to metrics.
+     *
+     * Concrete services should override this method (calling `super`) to react
+     * to specific changed fields (e.g. reconnect on voice change).
+     *
+     * @param delta A delta-mode settings object.
+     * @returns Record mapping changed field names to their previous values.
+     */
+    protected _updateSettings(delta: ServiceSettings): Promise<Record<string, unknown>>;
+    /**
+     * Log a warning for settings changes that won't take effect at runtime.
+     *
+     * Convenience helper for `_updateSettings` overrides. Accepts any iterable
+     * of field names (an array, a set, a record's keys, etc.) or a record.
+     *
+     * @param unhandled Field names that changed but are not applied.
+     */
+    protected _warnUnhandledUpdatedSettings(unhandled: Iterable<string> | Record<string, unknown>): void;
+    /**
+     * Push a frame and broadcast service metadata once the service starts.
+     *
+     * @param frame The frame to push.
+     * @param direction The direction to push the frame.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Process frames and handle service lifecycle.
+     *
+     * Automatically handles StartFrame, EndFrame, and CancelFrame by calling
+     * the appropriate lifecycle methods.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Process frames from an async generator.
+     *
+     * Takes an async generator that yields frames and processes each one,
+     * handling error frames specially by pushing them as errors.
+     *
+     * @param generator An async generator that yields Frame objects or null.
+     */
+    processGenerator(generator: AsyncIterable<Frame | null | undefined>): Promise<void>;
+    protected _start(frame: StartFrame): Promise<void>;
+    protected _stop(frame: EndFrame): Promise<void>;
+    protected _cancel(frame: CancelFrame): Promise<void>;
+}
+//# sourceMappingURL=ai_service.d.ts.map