@pipedog/core 0.0.0 → 0.1.0

package/dist/processors/idle_frame_processor.d.ts

@@ -0,0 +1,44 @@
+/** Idle frame processor for timeout-based callback execution. */
+import { Event, type Task } from "@pipedog/asyncio";
+import { type Frame } from "../frames/frames.ts";
+import { type FrameDirection, FrameProcessor, type FrameProcessorOptions } from "./frame_processor.ts";
+type AnyClass = abstract new (...args: any[]) => unknown;
+export interface IdleFrameProcessorOptions extends FrameProcessorOptions {
+    /** Async callback to execute on timeout. Receives this processor instance. */
+    callback: (processor: IdleFrameProcessor) => Promise<void>;
+    /** Timeout duration in seconds before triggering the callback. */
+    timeout: number;
+    /** Optional list of frame types to monitor. If null, monitors all frames. */
+    types?: AnyClass[] | null;
+}
+/**
+ * Monitors frame activity and triggers callbacks on timeout.
+ *
+ * This processor waits to receive any frame or specific frame types within a
+ * given timeout period. If the timeout is reached before receiving the
+ * expected frames, the provided callback will be executed.
+ */
+export declare class IdleFrameProcessor extends FrameProcessor {
+    protected _callback: (processor: IdleFrameProcessor) => Promise<void>;
+    protected _timeout: number;
+    protected _types: AnyClass[];
+    protected _idleTask: Task<unknown> | null;
+    protected _idleEvent: Event;
+    /** Initialize the idle frame processor. */
+    constructor(options: IdleFrameProcessorOptions);
+    /**
+     * Process incoming frames and manage idle timeout monitoring.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame flow in the pipeline.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /** Clean up resources and cancel pending tasks. */
+    cleanup(): Promise<void>;
+    /** Create and start the idle monitoring task. */
+    protected _createIdleTask(): void;
+    /** Handle idle timeout monitoring and callback execution. */
+    protected _idleTaskHandler(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=idle_frame_processor.d.ts.map

package/dist/processors/idle_frame_processor.js

@@ -0,0 +1,86 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/processors/idle_frame_processor.py
+/** Idle frame processor for timeout-based callback execution. */
+import { Event, TimeoutError, waitFor } from "@pipedog/asyncio";
+import { StartFrame } from "../frames/frames.js";
+import { FrameProcessor, } from "./frame_processor.js";
+/**
+ * Monitors frame activity and triggers callbacks on timeout.
+ *
+ * This processor waits to receive any frame or specific frame types within a
+ * given timeout period. If the timeout is reached before receiving the
+ * expected frames, the provided callback will be executed.
+ */
+export class IdleFrameProcessor extends FrameProcessor {
+    _callback;
+    _timeout;
+    _types;
+    _idleTask = null;
+    _idleEvent = new Event();
+    /** Initialize the idle frame processor. */
+    constructor(options) {
+        super(options);
+        this._callback = options.callback;
+        this._timeout = options.timeout;
+        this._types = options.types ?? [];
+    }
+    /**
+     * Process incoming frames and manage idle timeout monitoring.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame flow in the pipeline.
+     */
+    async processFrame(frame, direction) {
+        await super.processFrame(frame, direction);
+        if (frame instanceof StartFrame) {
+            this._createIdleTask();
+        }
+        await this.pushFrame(frame, direction);
+        // If we are not waiting for any specific frame set the event, otherwise
+        // check if we have received one of the desired frames.
+        if (this._types.length === 0) {
+            this._idleEvent.set();
+        }
+        else {
+            for (const t of this._types) {
+                if (frame instanceof t) {
+                    this._idleEvent.set();
+                }
+            }
+        }
+    }
+    /** Clean up resources and cancel pending tasks. */
+    async cleanup() {
+        // Upstream doesn't call super().cleanup() here; we do, so the base
+        // processor's input/process tasks are released too.
+        await super.cleanup();
+        if (this._idleTask) {
+            await this.cancelTask(this._idleTask);
+        }
+    }
+    /** Create and start the idle monitoring task. */
+    _createIdleTask() {
+        if (!this._idleTask) {
+            this._idleEvent = new Event();
+            this._idleTask = this.createTask(() => this._idleTaskHandler());
+        }
+    }
+    /** Handle idle timeout monitoring and callback execution. */
+    async _idleTaskHandler() {
+        for (;;) {
+            try {
+                await waitFor(() => this._idleEvent.wait(), this._timeout);
+                this._idleEvent.clear();
+            }
+            catch (e) {
+                if (!(e instanceof TimeoutError))
+                    throw e;
+                await this._callback(this);
+            }
+        }
+    }
+}
+//# sourceMappingURL=idle_frame_processor.js.map

package/dist/processors/index.d.ts

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

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

package/dist/processors/logger.d.ts

@@ -0,0 +1,42 @@
+/** Frame logging utilities for debugging and monitoring frame flow in Pipecat pipelines. */
+import { type Frame } from "../frames/frames.ts";
+import { FrameDirection, FrameProcessor } from "./frame_processor.ts";
+type FrameType = abstract new (...args: any[]) => Frame;
+export interface FrameLoggerOptions {
+    /** Color name for log message formatting (e.g. "red"). If null, no coloring is applied. */
+    color?: string | null;
+    /**
+     * Frame types to exclude from logging. Defaults to common high-frequency
+     * frames like audio and speaking frames.
+     */
+    ignoredFrameTypes?: readonly FrameType[];
+}
+/**
+ * A frame processor that logs frame information for debugging purposes.
+ *
+ * This processor intercepts frames passing through the pipeline and logs their
+ * details with configurable formatting and filtering. Useful for debugging
+ * frame flow and understanding pipeline behavior.
+ */
+export declare class FrameLogger extends FrameProcessor {
+    protected _prefix: string;
+    protected _color: string | null;
+    protected _ignoredFrameTypes: readonly FrameType[];
+    /**
+     * Initialize the frame logger.
+     *
+     * @param prefix Text prefix to add to log messages. Defaults to "Frame".
+     * @param options.color Color for log message formatting. If null, no coloring is applied.
+     * @param options.ignoredFrameTypes Frame types to exclude from logging.
+     */
+    constructor(prefix?: string, options?: FrameLoggerOptions);
+    /**
+     * Process and log frame information.
+     *
+     * @param frame The frame to process and potentially log.
+     * @param direction The direction of frame flow in the pipeline.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+}
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/processors/logger.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/processors/logger.py
+/** Frame logging utilities for debugging and monitoring frame flow in Pipecat pipelines. */
+import { BotSpeakingFrame, InputAudioRawFrame, OutputAudioRawFrame, UserSpeakingFrame, } from "../frames/frames.js";
+import { logger } from "../utils/logger.js";
+import { FrameDirection, FrameProcessor } from "./frame_processor.js";
+// loguru renders `<color>...</>` markup as ANSI escapes (`logger.opt(ansi=True)`).
+// Our logger has no markup, so the common loguru color names are mapped here.
+const ANSI_COLORS = {
+    black: "30",
+    red: "31",
+    green: "32",
+    yellow: "33",
+    blue: "34",
+    magenta: "35",
+    cyan: "36",
+    white: "37",
+    "light-black": "90",
+    "light-red": "91",
+    "light-green": "92",
+    "light-yellow": "93",
+    "light-blue": "94",
+    "light-magenta": "95",
+    "light-cyan": "96",
+    "light-white": "97",
+    bold: "1",
+    dim: "2",
+    italic: "3",
+    underline: "4",
+};
+function colorize(color, msg) {
+    const code = ANSI_COLORS[color.toLowerCase()];
+    return code ? `\u001b[${code}m${msg}\u001b[0m` : msg;
+}
+/**
+ * A frame processor that logs frame information for debugging purposes.
+ *
+ * This processor intercepts frames passing through the pipeline and logs their
+ * details with configurable formatting and filtering. Useful for debugging
+ * frame flow and understanding pipeline behavior.
+ */
+export class FrameLogger extends FrameProcessor {
+    _prefix;
+    _color;
+    _ignoredFrameTypes;
+    /**
+     * Initialize the frame logger.
+     *
+     * @param prefix Text prefix to add to log messages. Defaults to "Frame".
+     * @param options.color Color for log message formatting. If null, no coloring is applied.
+     * @param options.ignoredFrameTypes Frame types to exclude from logging.
+     */
+    constructor(prefix = "Frame", options = {}) {
+        super();
+        this._prefix = prefix;
+        this._color = options.color ?? null;
+        this._ignoredFrameTypes = options.ignoredFrameTypes ?? [
+            BotSpeakingFrame,
+            UserSpeakingFrame,
+            InputAudioRawFrame,
+            OutputAudioRawFrame,
+        ];
+    }
+    /**
+     * Process and log frame information.
+     *
+     * @param frame The frame to process and potentially log.
+     * @param direction The direction of frame flow in the pipeline.
+     */
+    async processFrame(frame, direction) {
+        await super.processFrame(frame, direction);
+        if (this._ignoredFrameTypes.length > 0 &&
+            !this._ignoredFrameTypes.some((t) => frame instanceof t)) {
+            const dir = direction === FrameDirection.UPSTREAM ? "<" : ">";
+            let msg = `${dir} ${this._prefix}: ${frame}`;
+            if (this._color) {
+                msg = colorize(this._color, msg);
+            }
+            logger.debug(msg);
+        }
+        await this.pushFrame(frame, direction);
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/processors/metrics/frame_processor_metrics.d.ts

@@ -0,0 +1,172 @@
+import { MetricsFrame } from "../../frames/frames.ts";
+import { type LLMTokenUsage, MetricsData, type STTUsage } from "../../metrics/metrics.ts";
+import { BaseObject } from "../../utils/base_object.ts";
+/**
+ * Metrics collection and reporting for frame processors.
+ *
+ * Provides comprehensive metrics tracking for frame processing operations,
+ * including timing measurements, resource usage, and performance analytics.
+ * Supports TTFB tracking, TTFA tracking, processing duration metrics, and
+ * usage statistics for LLM, STT, and TTS operations.
+ */
+export declare class FrameProcessorMetrics extends BaseObject {
+    protected static readonly _TTFA_MAX_BUFFER_SECONDS = 3;
+    protected _startTtfbTime: number;
+    protected _startProcessingTime: number;
+    protected _startTextAggregationTime: number;
+    protected _lastTtfbTime: number;
+    protected _shouldReportTtfb: boolean;
+    protected _ttfaActive: boolean;
+    protected _ttfaBuffer: Uint8Array;
+    protected _ttfatActive: boolean;
+    protected _startTtfatTime: number;
+    protected _coreMetricsData: MetricsData;
+    /**
+     * The current TTFB value in seconds, or null if not measured.
+     */
+    get ttfb(): number | null;
+    /** Get the processor name from core metrics data. */
+    protected _processorName(): string;
+    /** Get the model name from core metrics data. */
+    protected _modelName(): string | null;
+    /**
+     * Set the core metrics data for this collector.
+     *
+     * @param data The core metrics data containing processor and model information.
+     */
+    setCoreMetricsData(data: MetricsData): void;
+    /**
+     * Set the processor name for metrics reporting.
+     *
+     * @param name The name of the processor to use in metrics.
+     */
+    setProcessorName(name: string): void;
+    /**
+     * Start measuring time-to-first-byte (TTFB).
+     *
+     * @param options.startTime Optional timestamp to use as the start time. If
+     *   null, uses the current time.
+     * @param options.reportOnlyInitialTtfb Whether to report only the first TTFB measurement.
+     */
+    startTtfbMetrics(options: {
+        startTime?: number | null;
+        reportOnlyInitialTtfb: boolean;
+    }): Promise<void>;
+    /**
+     * Abandon the current TTFB measurement without reporting it.
+     *
+     * For a request whose response never came: there is no interval to
+     * report, and leaving the measurement open would let the next unrelated
+     * output be measured against it.
+     */
+    cancelTtfbMetrics(): Promise<void>;
+    /**
+     * Stop TTFB measurement and generate metrics frame.
+     *
+     * TTFB ends at the first output the service produces, of any kind —
+     * including content a caller never sees, such as an LLM's reasoning. Events
+     * that merely acknowledge the request (an HTTP response head, a stream-open
+     * or keepalive event) carry no output and must not stop it, or TTFB
+     * measures connection setup rather than the service's response.
+     *
+     * Only the first call per measurement takes effect, so services can call
+     * this from every branch that handles output rather than tracking which
+     * arrived first.
+     *
+     * @param options.endTime Optional timestamp to use as the end time. If null,
+     *   uses the current time.
+     * @returns MetricsFrame containing TTFB data, or null if not measuring.
+     */
+    stopTtfbMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<MetricsFrame | null>;
+    /**
+     * Scan buffered audio for speech onset and report TTFA.
+     *
+     * TTFA extends TTFB: once `stopTtfbMetrics` records the first byte, audio
+     * is buffered across chunks (the leading silence may span several, and
+     * onset confirmation needs a little audio past it) and scanned for a
+     * sustained speech onset. When found, TTFB plus the leading-silence
+     * duration is emitted and measuring stops until the next response.
+     *
+     * @param options.audio Raw PCM audio bytes (16-bit signed integers).
+     * @param options.sampleRate Sample rate of the audio in Hz.
+     * @param options.numChannels Number of interleaved audio channels.
+     * @returns MetricsFrame containing TTFA data once onset is confirmed,
+     *   otherwise null.
+     */
+    processTtfaMetrics(options: {
+        audio: Uint8Array;
+        sampleRate: number;
+        numChannels: number;
+    }): Promise<MetricsFrame | null>;
+    /**
+     * Stop TTFAT measurement and generate metrics frame.
+     *
+     * TTFAT extends TTFB: it runs from the same request start but ends at the
+     * first token of the answer the caller sees, so anything the model streams
+     * first — reasoning, most often — falls between the two. Measuring it at
+     * the point a service produces the token, rather than where the pipeline
+     * releases it, keeps buffering downstream of the service out of the number.
+     *
+     * Only the first call per measurement takes effect, so services can call
+     * this from every branch that produces an answer — streamed text, and the
+     * start of a tool call on a turn that answers with one instead of text.
+     *
+     * @param options.endTime Optional timestamp to use as the end time. If null,
+     *   uses the current time.
+     * @returns MetricsFrame containing TTFAT data, or null if not measuring.
+     */
+    stopTtfatMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<MetricsFrame | null>;
+    /**
+     * Start measuring processing time.
+     *
+     * @param options.startTime Optional timestamp to use as the start time. If
+     *   null, uses the current time.
+     */
+    startProcessingMetrics(options?: {
+        startTime?: number | null;
+    }): Promise<void>;
+    /**
+     * Stop processing time measurement and generate metrics frame.
+     *
+     * @param options.endTime Optional timestamp to use as the end time. If null,
+     *   uses the current time.
+     * @returns MetricsFrame containing processing duration data, or null if not measuring.
+     */
+    stopProcessingMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<MetricsFrame | null>;
+    /**
+     * Record LLM token usage metrics.
+     *
+     * @param tokens Token usage information including prompt and completion tokens.
+     * @returns MetricsFrame containing LLM usage data.
+     */
+    startLlmUsageMetrics(tokens: LLMTokenUsage): Promise<MetricsFrame>;
+    /**
+     * Record STT usage metrics.
+     *
+     * @param usage Usage information for the STT operation.
+     * @returns MetricsFrame containing STT usage data.
+     */
+    startSttUsageMetrics(usage: STTUsage): Promise<MetricsFrame>;
+    /**
+     * Record TTS character usage metrics.
+     *
+     * @param text The text being processed by TTS.
+     * @returns MetricsFrame containing TTS usage data.
+     */
+    startTtsUsageMetrics(text: string): Promise<MetricsFrame>;
+    /** Start measuring text aggregation time (first token to first sentence). */
+    startTextAggregationMetrics(): Promise<void>;
+    /**
+     * Stop text aggregation measurement and generate metrics frame.
+     *
+     * @returns MetricsFrame containing text aggregation time, or null if not measuring.
+     */
+    stopTextAggregationMetrics(): Promise<MetricsFrame | null>;
+}
+//# sourceMappingURL=frame_processor_metrics.d.ts.map