@pipedog/core 0.0.0 → 0.2.0

package/dist/processors/filters/wake_notifier_filter.d.ts

@@ -0,0 +1,48 @@
+/** Wake notifier filter for conditional frame-based notifications. */
+import type { Frame } from "../../frames/frames.ts";
+import type { FrameClass } from "../../utils/frame_queue.ts";
+import type { BaseNotifier } from "../../utils/sync/base_notifier.ts";
+import { type FrameDirection, FrameProcessor, type FrameProcessorOptions } from "../frame_processor.ts";
+export interface WakeNotifierFilterOptions extends FrameProcessorOptions {
+    /** The notifier to trigger when conditions are met. */
+    notifier: BaseNotifier;
+    /** Frame types to monitor for potential notifications. */
+    types: readonly FrameClass[];
+    /**
+     * Async callback that determines whether to trigger notification. Should
+     * return true to trigger notification, false otherwise.
+     */
+    filter: (frame: Frame) => Promise<boolean>;
+}
+/**
+ * Frame processor that conditionally triggers notifications based on frame
+ * types and filters.
+ *
+ * This processor monitors frames of specified types and executes a callback
+ * predicate when such frames are processed. If the callback returns true, the
+ * associated notifier is triggered, allowing for conditional wake-up or
+ * notification scenarios.
+ */
+export declare class WakeNotifierFilter extends FrameProcessor {
+    protected _notifier: BaseNotifier;
+    protected _types: readonly FrameClass[];
+    protected _filter: (frame: Frame) => Promise<boolean>;
+    /**
+     * Initialize the wake notifier filter.
+     *
+     * @param options.notifier The notifier to trigger when conditions are met.
+     * @param options.types Frame types to monitor for potential notifications.
+     * @param options.filter Async callback that determines whether to trigger
+     *   notification. Should return true to trigger notification, false
+     *   otherwise. Other options are passed to the parent FrameProcessor.
+     */
+    constructor(options: WakeNotifierFilterOptions);
+    /**
+     * Process frames and conditionally trigger notifications.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame flow in the pipeline.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+}
+//# sourceMappingURL=wake_notifier_filter.d.ts.map

package/dist/processors/filters/wake_notifier_filter.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/processors/filters/wake_notifier_filter.py
+import { FrameProcessor, } from "../frame_processor.js";
+/**
+ * Frame processor that conditionally triggers notifications based on frame
+ * types and filters.
+ *
+ * This processor monitors frames of specified types and executes a callback
+ * predicate when such frames are processed. If the callback returns true, the
+ * associated notifier is triggered, allowing for conditional wake-up or
+ * notification scenarios.
+ */
+export class WakeNotifierFilter extends FrameProcessor {
+    _notifier;
+    _types;
+    _filter;
+    /**
+     * Initialize the wake notifier filter.
+     *
+     * @param options.notifier The notifier to trigger when conditions are met.
+     * @param options.types Frame types to monitor for potential notifications.
+     * @param options.filter Async callback that determines whether to trigger
+     *   notification. Should return true to trigger notification, false
+     *   otherwise. Other options are passed to the parent FrameProcessor.
+     */
+    constructor(options) {
+        super(options);
+        this._notifier = options.notifier;
+        this._types = options.types;
+        this._filter = options.filter;
+    }
+    /**
+     * Process frames and conditionally trigger notifications.
+     *
+     * @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 (this._types.some((t) => frame instanceof t) && (await this._filter(frame))) {
+            await this._notifier.notify();
+        }
+        await this.pushFrame(frame, direction);
+    }
+}
+//# sourceMappingURL=wake_notifier_filter.js.map

package/dist/processors/frame_processor.d.ts

@@ -0,0 +1,360 @@
+import type { BaseClock } from "../clocks/base_clock.ts";
+import { ErrorFrame, type Frame, type TTSAudioRawFrame } from "../frames/frames.ts";
+import type { LLMTokenUsage, MetricsData, STTUsage } from "../metrics/metrics.ts";
+import { type BaseObserver } from "../observers/base_observer.ts";
+import type { PipelineWorker } from "../pipeline/worker.ts";
+import type { BaseTaskManager, EventLoop } from "../utils/asyncio/task_manager.ts";
+import { BaseObject, type BaseObjectOptions } from "../utils/base_object.ts";
+import { ErrorCategory } from "../utils/errors.ts";
+import { type FrameClass } from "../utils/frame_queue.ts";
+import type { TracingContext } from "../utils/tracing/tracing_context.ts";
+import type { WorkerRunner } from "../workers/runner.ts";
+import { FrameProcessorMetrics } from "./metrics/frame_processor_metrics.ts";
+/**
+ * Direction of frame flow in the processing pipeline.
+ *
+ * - DOWNSTREAM: frames flowing from input to output.
+ * - UPSTREAM: frames flowing back from output to input.
+ */
+export declare const FrameDirection: {
+    readonly DOWNSTREAM: 1;
+    readonly UPSTREAM: 2;
+};
+export type FrameDirection = (typeof FrameDirection)[keyof typeof FrameDirection];
+export type FrameCallback = (processor: FrameProcessor, frame: Frame, direction: FrameDirection) => Promise<void>;
+export interface FrameProcessorSetupOptions {
+    clock: BaseClock;
+    taskManager: BaseTaskManager;
+    pipelineWorker: PipelineWorker | null;
+    audioInSampleRate?: number;
+    audioOutSampleRate?: number;
+    enableMetrics?: boolean;
+    enableTracing?: boolean;
+    enableUsageMetrics?: boolean;
+    observer?: BaseObserver | null;
+    reportOnlyInitialTtfb?: boolean;
+    tracingContext?: TracingContext | null;
+}
+/**
+ * Configuration parameters for frame processor initialization.
+ *
+ * - `audioInSampleRate` / `audioOutSampleRate`: audio sample rates in Hz.
+ * - `clock`: the clock instance for timing operations.
+ * - `enableMetrics` / `enableTracing` / `enableUsageMetrics`: feature switches.
+ * - `pipelineWorker`: the PipelineWorker running this pipeline, so processors
+ *   can reach worker-scoped state (e.g. `this.pipelineWorker.appResources`).
+ * - `observer`: optional observer for monitoring frame processing events.
+ * - `taskManager`: the task manager for handling async operations.
+ * - `tracingContext`: pipeline-scoped tracing context for span hierarchy.
+ */
+export declare class FrameProcessorSetup {
+    clock: BaseClock;
+    taskManager: BaseTaskManager;
+    pipelineWorker: PipelineWorker | null;
+    audioInSampleRate: number;
+    audioOutSampleRate: number;
+    enableMetrics: boolean;
+    enableTracing: boolean;
+    enableUsageMetrics: boolean;
+    observer: BaseObserver | null;
+    reportOnlyInitialTtfb: boolean;
+    tracingContext: TracingContext | null;
+    constructor(options: FrameProcessorSetupOptions);
+}
+type QueueItem = [Frame, FrameDirection, FrameCallback | null];
+/**
+ * A priority queue for the frames arriving at a frame processor.
+ *
+ * Frames are dequeued in three tiers: the StartFrame first, then
+ * SystemFrame, then data and control frames. Frames of the same tier keep
+ * their arrival order.
+ */
+export declare class FrameProcessorQueue {
+    #private;
+    static readonly START_PRIORITY = 1;
+    static readonly SYSTEM_PRIORITY = 10;
+    static readonly DEFAULT_PRIORITY = 20;
+    /**
+     * Put an item into the priority queue. The StartFrame outranks every other
+     * frame and SystemFrame frames outrank data and control frames.
+     */
+    put(item: QueueItem): Promise<void>;
+    /** Retrieve the next item from the queue, waiting until one is available. */
+    get(): Promise<QueueItem>;
+    taskDone(): void;
+    empty(): boolean;
+    qsize(): number;
+}
+/**
+ * How long (seconds) a processor holds frames waiting for a readiness
+ * condition before giving up and resuming. See `pauseProcessingAllFramesUntil()`.
+ */
+export declare const PAUSE_UNTIL_READY_TIMEOUT_SECS = 5;
+/**
+ * Timeout in seconds for cancelling the input frame processing task. Prevents
+ * hanging if some code swallows cancellation.
+ */
+export declare const INPUT_TASK_CANCEL_TIMEOUT_SECS = 3;
+export interface FrameProcessorOptions extends BaseObjectOptions {
+    /** Process frames immediately instead of using internal queues. */
+    enableDirectMode?: boolean;
+    /** Optional metrics collector for this processor. */
+    metrics?: FrameProcessorMetrics | null;
+}
+/**
+ * Base class for all frame processors in the pipeline.
+ *
+ * Frame processors are the building blocks of Pipecat pipelines. They
+ * receive frames, process them, and pass them to the next or previous
+ * processor in the chain. Each processor guarantees frame ordering and
+ * processes frames in its own task. System frames are processed in a
+ * separate task which guarantees frame priority.
+ *
+ * Event handlers available:
+ *
+ * - on_before_process_frame: called before a frame is processed
+ * - on_after_process_frame: called after a frame is processed
+ * - on_before_push_frame: called before a frame is pushed
+ * - on_after_push_frame: called after a frame is pushed
+ * - on_error: called when an error is raised in the frame processing
+ * - on_usable_changed: called with the new value of `isUsable` when the
+ *   processor stops or starts being able to do its job
+ *
+ * @example
+ * processor.eventHandler("on_usable_changed", async (processor, isUsable) => { ... });
+ */
+export declare class FrameProcessor extends BaseObject {
+    #private;
+    protected _prev: FrameProcessor | null;
+    protected _next: FrameProcessor | null;
+    protected _enableDirectMode: boolean;
+    protected _setup: FrameProcessorSetup | null;
+    protected _cancelling: boolean;
+    protected _metrics: FrameProcessorMetrics;
+    protected _isUsable: boolean;
+    constructor(options?: FrameProcessorOptions);
+    /**
+     * Whether this processor can still do its job.
+     *
+     * A processor stays usable through failures it might recover from, and
+     * becomes unusable once its work can no longer succeed: a provider has
+     * rejected its API key, model or voice, or it has failed enough times to
+     * stop trying. Services stop accepting work and stop reconnecting once this
+     * is false.
+     *
+     * Errors set this as they are reported, so an error handler reading
+     * `frame.processor.isUsable` sees the verdict that came with the error.
+     */
+    get isUsable(): boolean;
+    /**
+     * Set whether this processor can be given work. Call this to bring back a
+     * processor that became unusable, once whatever stopped it working has been
+     * dealt with.
+     */
+    setUsable(isUsable: boolean): Promise<void>;
+    /**
+     * The sub-processors contained within this processor. Only compound
+     * processors (e.g. pipelines and parallel pipelines) have sub-processors.
+     */
+    get processors(): FrameProcessor[];
+    /**
+     * The entry processors for this processor: the first processors in a
+     * compound processor. Non-compound processors return an empty list.
+     */
+    get entryProcessors(): FrameProcessor[];
+    /** The next processor, or null. */
+    get next(): FrameProcessor | null;
+    /** The previous processor, or null. */
+    get previous(): FrameProcessor | null;
+    /** The configuration this processor was set up with. */
+    get processorSetup(): FrameProcessorSetup;
+    /** Whether metrics collection is enabled. */
+    get metricsEnabled(): boolean;
+    /** Whether usage metrics collection is enabled. */
+    get usageMetricsEnabled(): boolean;
+    /** Whether only the initial TTFB should be reported. */
+    get reportOnlyInitialTtfb(): boolean;
+    /**
+     * The PipelineWorker this processor is running in. Gives access to
+     * worker-scoped state, e.g. `this.pipelineWorker.appResources`.
+     */
+    get pipelineWorker(): PipelineWorker;
+    /**
+     * The WorkerRunner hosting this processor's worker. Use it to reach another
+     * worker by name, e.g. `this.workerRunner.getWorker("ui-jobs")`.
+     */
+    get workerRunner(): WorkerRunner;
+    /** Processors that can generate metrics, including nested ones. */
+    processorsWithMetrics(): FrameProcessor[];
+    /** Whether this processor can generate metrics. */
+    canGenerateMetrics(): boolean;
+    /** Set core metrics data for this processor. */
+    setCoreMetricsData(data: MetricsData): void;
+    /** Start time-to-first-byte metrics collection. */
+    startTtfbMetrics(options?: {
+        startTime?: number | null;
+    }): Promise<void>;
+    /** Abandon the current time-to-first-byte measurement without reporting it. */
+    cancelTtfbMetrics(): Promise<void>;
+    /** Stop time-to-first-byte metrics collection and push results. */
+    stopTtfbMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<void>;
+    /**
+     * Scan a TTS audio frame for the first audible sample and push TTFA.
+     * Call for every audio frame until a measurement is produced.
+     */
+    processTtfaMetrics(frame: TTSAudioRawFrame): Promise<void>;
+    /** Stop time-to-first-answer-token metrics collection and push results. */
+    stopTtfatMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<void>;
+    /** Start processing metrics collection. */
+    startProcessingMetrics(options?: {
+        startTime?: number | null;
+    }): Promise<void>;
+    /** Stop processing metrics collection and push results. */
+    stopProcessingMetrics(options?: {
+        endTime?: number | null;
+    }): Promise<void>;
+    /** Start LLM usage metrics collection. */
+    startLlmUsageMetrics(tokens: LLMTokenUsage): Promise<void>;
+    /** Start STT usage metrics collection. */
+    startSttUsageMetrics(usage: STTUsage): Promise<void>;
+    /** Start TTS usage metrics collection. */
+    startTtsUsageMetrics(text: string): Promise<void>;
+    /** Start text aggregation time metrics collection. */
+    startTextAggregationMetrics(): Promise<void>;
+    /** Stop text aggregation time metrics collection and push results. */
+    stopTextAggregationMetrics(): Promise<void>;
+    /** Stop all active metrics collection. */
+    stopAllMetrics(): Promise<void>;
+    /**
+     * Set up the processor with required components.
+     *
+     * This is where a processor connects and does its other slow start-up
+     * work. A pipeline sets its processors up concurrently, so a resource
+     * shared with another processor needs guarding (see `utils/shared`).
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Hold the StartFrame until `_setupFinished` is called. Called by the pipeline before setup. */
+    _setupStarted(): void;
+    /** Let this processor start, once its own setup() has returned. */
+    _setupFinished(): void;
+    /**
+     * Release this processor's resources at teardown.
+     *
+     * This base implementation cancels only the processor's internal
+     * input/process tasks; tasks created via `createTask` are released by an
+     * override. Runs concurrently with every other processor's cleanup.
+     */
+    cleanup(): Promise<void>;
+    /** Link this processor to the next processor in the pipeline. */
+    link(processor: FrameProcessor): void;
+    /** The clock used by this processor. */
+    getClock(): BaseClock;
+    /** The event loop used by this processor. */
+    getEventLoop(): EventLoop;
+    /** Queue a frame for processing. */
+    queueFrame(frame: Frame, direction?: FrameDirection, callback?: FrameCallback | null): Promise<void>;
+    /** Pause processing of queued frames. */
+    pauseProcessingFrames(): Promise<void>;
+    /** Pause processing of queued system frames. */
+    pauseProcessingSystemFrames(): Promise<void>;
+    /** Resume processing of queued frames. */
+    resumeProcessingFrames(): Promise<void>;
+    /** Resume processing of queued system frames. */
+    resumeProcessingSystemFrames(): Promise<void>;
+    /**
+     * Hold frames arriving at this processor until `ready` resolves.
+     *
+     * Useful for a processor that cannot act on frames until some condition
+     * holds, such as one that establishes a connection in the background.
+     * Frames wait in the processor's queues and are delivered in order once
+     * the condition resolves, so nothing is lost.
+     *
+     * The frame being processed when this is called is unaffected: the pause
+     * takes hold from the next frame onwards.
+     *
+     * Both queues are held, so the pause is always lifted: when `ready`
+     * resolves, when `timeout` (seconds) elapses, or at teardown.
+     *
+     * @param ready Awaited to learn when frames can be acted on, e.g. `() => someEvent.wait()`.
+     */
+    pauseProcessingAllFramesUntil(ready: () => Promise<unknown>, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Process a frame. Subclasses override this and call
+     * `await super.processFrame(frame, direction)` first.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Classify an exception this processor knows the shape of. Override for
+     * providers that signal failures through SDK-specific errors rather than an
+     * HTTP status code. Return null to fall back to `classifyHttpException`.
+     */
+    protected _classifyError(_exception: unknown): ErrorCategory | null;
+    /**
+     * Create and push an ErrorFrame upstream, with context about which
+     * processor generated the error.
+     *
+     * @param errorMsg Descriptive message explaining the error condition.
+     * @param options.exception The error that caused it, if available.
+     * @param options.category Why the error occurred, when the caller knows.
+     *   Leave unset to work it out from the exception, or pass
+     *   `ErrorCategory.UNKNOWN` for an error whose cause can't be attributed.
+     * @param options.forceTreatAsPermanent Treat this error as one that will
+     *   keep recurring, leaving the processor unable to do any more work. The
+     *   pipeline worker then applies its ProcessorUnusablePolicy.
+     *
+     * @example
+     * // An error this processor can recover from
+     * await this.pushError("Failed to process audio chunk, skipping");
+     *
+     * // An error that leaves this processor unable to do any more work
+     * try {
+     *   someCriticalOperation();
+     * } catch (e) {
+     *   await this.pushError("Critical operation failed", { exception: e, forceTreatAsPermanent: true });
+     * }
+     */
+    pushError(errorMsg: string, options?: {
+        exception?: unknown;
+        category?: ErrorCategory | null;
+        forceTreatAsPermanent?: boolean;
+    }): Promise<void>;
+    /**
+     * Push an error frame upstream.
+     *
+     * @param options.forceTreatAsPermanent See `pushError`.
+     */
+    pushErrorFrame(error: ErrorFrame, options?: {
+        forceTreatAsPermanent?: boolean;
+    }): Promise<void>;
+    /** Push a frame to the next (downstream) or previous (upstream) processor. */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /** Broadcast an InterruptionFrame both upstream and downstream. */
+    broadcastInterruption(): Promise<void>;
+    /**
+     * Broadcast a frame of the specified class upstream and downstream.
+     *
+     * Creates two instances of the given frame class from the provided options
+     * (without deep-copying them) and pushes them upstream and downstream.
+     */
+    broadcastFrame<O>(frameCls: new (options: O) => Frame, options?: O): Promise<void>;
+    /**
+     * Broadcast a frame instance upstream and downstream.
+     *
+     * Creates two new frames shallow-copying all fields from the original
+     * frame except `id` and `name`, which get fresh values. Prefer
+     * `broadcastFrame()` when you are the creator of the frame.
+     */
+    broadcastFrameInstance(frame: Frame): Promise<void>;
+    /** Start handling an interruption by cancelling current tasks. */
+    protected _startInterruption(): Promise<void>;
+    /** Whether a frame of the given type is waiting in the processing queue. */
+    hasQueuedFrame(frameType: FrameClass): boolean;
+}
+export {};
+//# sourceMappingURL=frame_processor.d.ts.map