@pipedog/core 0.0.0 → 0.1.0

package/dist/observers/base_observer.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Base observer classes for monitoring frame flow in the Pipecat pipeline.
+ *
+ * Provides the foundation for observing frame transfers between processors
+ * without modifying the pipeline structure. Observers can be used for logging,
+ * debugging, analytics, and monitoring pipeline behavior.
+ */
+import type { Frame } from "../frames/frames.ts";
+import type { FrameDirection, FrameProcessor } from "../processors/frame_processor.ts";
+import { BaseObject, type BaseObjectOptions } from "../utils/base_object.ts";
+export interface FrameProcessedOptions {
+    /** The processor processing the frame. */
+    processor: FrameProcessor;
+    /** The frame being processed. */
+    frame: Frame;
+    /** The direction of the frame (e.g., downstream or upstream). */
+    direction: FrameDirection;
+    /** The time when the frame was pushed, based on the pipeline clock. */
+    timestamp: number;
+}
+/**
+ * Event data for frame processing in the pipeline.
+ *
+ * Represents an event where a frame is being processed by a processor. This
+ * data structure is typically used by observers to track the flow of frames
+ * through the pipeline for logging, debugging, or analytics purposes.
+ *
+ * - `processor`: the processor processing the frame.
+ * - `frame`: the frame being processed.
+ * - `direction`: the direction of the frame (e.g., downstream or upstream).
+ * - `timestamp`: the time when the frame was pushed, based on the pipeline clock.
+ */
+export declare class FrameProcessed {
+    processor: FrameProcessor;
+    frame: Frame;
+    direction: FrameDirection;
+    timestamp: number;
+    constructor(options: FrameProcessedOptions);
+}
+export interface FramePushedOptions {
+    /** The processor sending the frame. */
+    source: FrameProcessor;
+    /** The processor receiving the frame. */
+    destination: FrameProcessor;
+    /** The frame being transferred. */
+    frame: Frame;
+    /** The direction of the transfer (e.g., downstream or upstream). */
+    direction: FrameDirection;
+    /** The time when the frame was pushed, based on the pipeline clock. */
+    timestamp: number;
+    /** Whether this is the first time the frame is pushed. Defaults to true. */
+    firstPush?: boolean;
+}
+/**
+ * Event data for frame transfers between processors in the pipeline.
+ *
+ * Represents an event where a frame is pushed from one processor to another
+ * within the pipeline. This data structure is typically used by observers
+ * to track the flow of frames through the pipeline for logging, debugging,
+ * or analytics purposes.
+ *
+ * - `source`: the processor sending the frame.
+ * - `destination`: the processor receiving the frame.
+ * - `frame`: the frame being transferred.
+ * - `direction`: the direction of the transfer (e.g., downstream or upstream).
+ * - `timestamp`: the time when the frame was pushed, based on the pipeline clock.
+ * - `firstPush`: whether this is the first time the frame is pushed. A frame
+ *   is pushed again by every processor that passes it along.
+ */
+export declare class FramePushed {
+    source: FrameProcessor;
+    destination: FrameProcessor;
+    frame: Frame;
+    direction: FrameDirection;
+    timestamp: number;
+    firstPush: boolean;
+    constructor(options: FramePushedOptions);
+}
+export interface ProcessorSetUpOptions {
+    /** The processor that was set up. */
+    processor: FrameProcessor;
+    /** When the processor's `setup()` began. */
+    startedAtNs: number;
+    /** When the processor's `setup()` returned. */
+    finishedAtNs: number;
+}
+/**
+ * Event data for a processor having been set up.
+ *
+ * Processors are set up concurrently and before any frame flows, so this is
+ * what a timing observer measures the work a processor does to get ready by.
+ * The times come from `monotonicNs()`, since the pipeline clock only starts
+ * once the pipeline does.
+ *
+ * - `processor`: the processor that was set up.
+ * - `startedAtNs`: when the processor's `setup()` began.
+ * - `finishedAtNs`: when the processor's `setup()` returned.
+ */
+export declare class ProcessorSetUp {
+    processor: FrameProcessor;
+    startedAtNs: number;
+    finishedAtNs: number;
+    constructor(options: ProcessorSetUpOptions);
+}
+export interface BaseObserverOptions extends BaseObjectOptions {
+    /**
+     * Whether to observe every push of a frame, rather than only its first.
+     * Defaults to true.
+     */
+    observeEveryPush?: boolean;
+}
+/**
+ * Base class for pipeline frame observers.
+ *
+ * Observers can view all frames that flow through the pipeline without
+ * needing to inject processors into the pipeline structure. This enables
+ * non-intrusive monitoring capabilities such as frame logging, debugging,
+ * performance analysis, and analytics collection.
+ *
+ * A frame is pushed again by every processor that passes it along, and by
+ * default an observer observes every push. An observer that handles a frame
+ * once, such as one that reports the moment a frame represents, is created
+ * with `observeEveryPush: false` and is told about a frame only when it
+ * is first pushed.
+ */
+export declare class BaseObserver extends BaseObject {
+    protected _observeEveryPush: boolean;
+    constructor(options?: BaseObserverOptions);
+    /** Whether the observer observes every push of a frame, not only the first. */
+    get observeEveryPush(): boolean;
+    /**
+     * Handle the event when a frame is being processed by a processor.
+     *
+     * Subclasses implement this to define specific behavior (e.g., logging,
+     * monitoring, debugging) when a frame is being processed by a processor.
+     *
+     * @param data The event data containing details about the frame processing.
+     */
+    onProcessFrame(_data: FrameProcessed): Promise<void>;
+    /**
+     * Handle the event when a frame is pushed from one processor to another.
+     *
+     * Subclasses implement this to define specific behavior (e.g., logging,
+     * monitoring, debugging) when a frame is transferred through the pipeline.
+     *
+     * A frame is pushed again by every processor that passes it along, so
+     * this is called once per hop, with `data.firstPush` set on the first
+     * one. An observer created with `observeEveryPush: false` is only
+     * called for that first push.
+     *
+     * @param data The event data containing details about the frame transfer.
+     */
+    onPushFrame(_data: FramePushed): Promise<void>;
+    /**
+     * Handle the event when a processor has been set up.
+     *
+     * A processor connects and does its other slow start-up work here, so
+     * this is where that cost can be measured. Processors are set up
+     * concurrently, so these arrive in the order they finish rather than in
+     * pipeline order.
+     *
+     * @param data The event data containing details about the processor setup.
+     */
+    onProcessorSetup(_data: ProcessorSetUp): Promise<void>;
+    /**
+     * Called when the pipeline has fully started.
+     *
+     * Fired after the `StartFrame` has been processed by all processors in the
+     * pipeline, including nested `ParallelPipeline` branches.
+     */
+    onPipelineStarted(): Promise<void>;
+}
+//# sourceMappingURL=base_observer.d.ts.map

package/dist/observers/base_observer.js

@@ -0,0 +1,151 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/base_observer.py
+import { BaseObject } from "../utils/base_object.js";
+/**
+ * Event data for frame processing in the pipeline.
+ *
+ * Represents an event where a frame is being processed by a processor. This
+ * data structure is typically used by observers to track the flow of frames
+ * through the pipeline for logging, debugging, or analytics purposes.
+ *
+ * - `processor`: the processor processing the frame.
+ * - `frame`: the frame being processed.
+ * - `direction`: the direction of the frame (e.g., downstream or upstream).
+ * - `timestamp`: the time when the frame was pushed, based on the pipeline clock.
+ */
+export class FrameProcessed {
+    processor;
+    frame;
+    direction;
+    timestamp;
+    constructor(options) {
+        this.processor = options.processor;
+        this.frame = options.frame;
+        this.direction = options.direction;
+        this.timestamp = options.timestamp;
+    }
+}
+/**
+ * Event data for frame transfers between processors in the pipeline.
+ *
+ * Represents an event where a frame is pushed from one processor to another
+ * within the pipeline. This data structure is typically used by observers
+ * to track the flow of frames through the pipeline for logging, debugging,
+ * or analytics purposes.
+ *
+ * - `source`: the processor sending the frame.
+ * - `destination`: the processor receiving the frame.
+ * - `frame`: the frame being transferred.
+ * - `direction`: the direction of the transfer (e.g., downstream or upstream).
+ * - `timestamp`: the time when the frame was pushed, based on the pipeline clock.
+ * - `firstPush`: whether this is the first time the frame is pushed. A frame
+ *   is pushed again by every processor that passes it along.
+ */
+export class FramePushed {
+    source;
+    destination;
+    frame;
+    direction;
+    timestamp;
+    firstPush;
+    constructor(options) {
+        this.source = options.source;
+        this.destination = options.destination;
+        this.frame = options.frame;
+        this.direction = options.direction;
+        this.timestamp = options.timestamp;
+        this.firstPush = options.firstPush ?? true;
+    }
+}
+/**
+ * Event data for a processor having been set up.
+ *
+ * Processors are set up concurrently and before any frame flows, so this is
+ * what a timing observer measures the work a processor does to get ready by.
+ * The times come from `monotonicNs()`, since the pipeline clock only starts
+ * once the pipeline does.
+ *
+ * - `processor`: the processor that was set up.
+ * - `startedAtNs`: when the processor's `setup()` began.
+ * - `finishedAtNs`: when the processor's `setup()` returned.
+ */
+export class ProcessorSetUp {
+    processor;
+    startedAtNs;
+    finishedAtNs;
+    constructor(options) {
+        this.processor = options.processor;
+        this.startedAtNs = options.startedAtNs;
+        this.finishedAtNs = options.finishedAtNs;
+    }
+}
+/**
+ * Base class for pipeline frame observers.
+ *
+ * Observers can view all frames that flow through the pipeline without
+ * needing to inject processors into the pipeline structure. This enables
+ * non-intrusive monitoring capabilities such as frame logging, debugging,
+ * performance analysis, and analytics collection.
+ *
+ * A frame is pushed again by every processor that passes it along, and by
+ * default an observer observes every push. An observer that handles a frame
+ * once, such as one that reports the moment a frame represents, is created
+ * with `observeEveryPush: false` and is told about a frame only when it
+ * is first pushed.
+ */
+export class BaseObserver extends BaseObject {
+    _observeEveryPush;
+    constructor(options = {}) {
+        super(options);
+        this._observeEveryPush = options.observeEveryPush ?? true;
+    }
+    /** Whether the observer observes every push of a frame, not only the first. */
+    get observeEveryPush() {
+        return this._observeEveryPush;
+    }
+    /**
+     * Handle the event when a frame is being processed by a processor.
+     *
+     * Subclasses implement this to define specific behavior (e.g., logging,
+     * monitoring, debugging) when a frame is being processed by a processor.
+     *
+     * @param data The event data containing details about the frame processing.
+     */
+    async onProcessFrame(_data) { }
+    /**
+     * Handle the event when a frame is pushed from one processor to another.
+     *
+     * Subclasses implement this to define specific behavior (e.g., logging,
+     * monitoring, debugging) when a frame is transferred through the pipeline.
+     *
+     * A frame is pushed again by every processor that passes it along, so
+     * this is called once per hop, with `data.firstPush` set on the first
+     * one. An observer created with `observeEveryPush: false` is only
+     * called for that first push.
+     *
+     * @param data The event data containing details about the frame transfer.
+     */
+    async onPushFrame(_data) { }
+    /**
+     * Handle the event when a processor has been set up.
+     *
+     * A processor connects and does its other slow start-up work here, so
+     * this is where that cost can be measured. Processors are set up
+     * concurrently, so these arrive in the order they finish rather than in
+     * pipeline order.
+     *
+     * @param data The event data containing details about the processor setup.
+     */
+    async onProcessorSetup(_data) { }
+    /**
+     * Called when the pipeline has fully started.
+     *
+     * Fired after the `StartFrame` has been processed by all processors in the
+     * pipeline, including nested `ParallelPipeline` branches.
+     */
+    async onPipelineStarted() { }
+}
+//# sourceMappingURL=base_observer.js.map

package/dist/observers/error_observer.d.ts

@@ -0,0 +1,75 @@
+import { ErrorCategory } from "../utils/errors.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "./base_observer.ts";
+export interface ErrorEventOptions {
+    /** What went wrong, in the words of the processor that failed. */
+    message: string;
+    /**
+     * Why it failed, drawn from `ErrorCategory` and independent of the provider
+     * that failed: rejected credentials, an unreachable service, a malformed
+     * request and so on.
+     */
+    category: ErrorCategory;
+    /**
+     * The name of the exception behind the failure, where one caused it.
+     * Failures group by this where a message, carrying the particulars of a
+     * single occurrence, is too specific to group by.
+     */
+    exceptionType?: string | null;
+    /** The name of the processor that raised the error. */
+    processor: string;
+    /**
+     * Whether that processor can still do its job. A processor that can't keeps
+     * failing for as long as it is given work, so this separates a bad minute
+     * from the end of a capability.
+     */
+    processorUsable: boolean;
+    /** Unix timestamp of the failure. */
+    timestamp: number;
+}
+/** One failure, as the processor that raised it described it. */
+export declare class ErrorEvent {
+    message: string;
+    category: ErrorCategory;
+    exceptionType: string | null;
+    processor: string;
+    processorUsable: boolean;
+    timestamp: number;
+    constructor(options: ErrorEventOptions);
+}
+export interface ErrorObserverOptions extends Omit<BaseObserverOptions, "observeEveryPush"> {
+    /**
+     * Reads the current time in seconds. Supplying one lets a test place
+     * failures without waiting. Defaults to `time()`.
+     */
+    timeSource?: () => number;
+}
+/**
+ * Reports each error a pipeline raises, once, where it is raised.
+ *
+ * An error is reported at its origin rather than where it ends up, and named
+ * for the processor that raised it rather than the one that passed it along.
+ *
+ * Events:
+ *
+ * - on_error(observer, event): Emitted for each error, as an `ErrorEvent`.
+ *
+ * @example
+ * const observer = new ErrorObserver();
+ *
+ * observer.eventHandler("on_error", async (observer, event: ErrorEvent) => {
+ *   logger.info(JSON.stringify(event));
+ * });
+ */
+export declare class ErrorObserver extends BaseObserver {
+    protected _now: () => number;
+    constructor(options?: ErrorObserverOptions);
+    /**
+     * Report an error frame.
+     *
+     * The first push of an error comes from the processor that failed.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+}
+//# sourceMappingURL=error_observer.d.ts.map

package/dist/observers/error_observer.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/observers/error_observer.py
+/**
+ * Observer reporting the failures a pipeline runs into.
+ *
+ * Errors travel upstream from the processor that raised them, and not all of
+ * them reach the end of that journey: a processor that answers for a failure
+ * itself — a service switcher that fails over to its next service, say —
+ * stops the error there. This observer reads each error where it is raised,
+ * so a session's failure history holds the ones that were recovered from as
+ * well as the ones that surfaced.
+ */
+import { time } from "@pipedog/asyncio";
+import { ErrorFrame } from "../frames/frames.js";
+import { ErrorCategory } from "../utils/errors.js";
+import { BaseObserver } from "./base_observer.js";
+/** One failure, as the processor that raised it described it. */
+export class ErrorEvent {
+    message;
+    category;
+    exceptionType;
+    processor;
+    processorUsable;
+    timestamp;
+    constructor(options) {
+        this.message = options.message;
+        this.category = options.category;
+        this.exceptionType = options.exceptionType ?? null;
+        this.processor = options.processor;
+        this.processorUsable = options.processorUsable;
+        this.timestamp = options.timestamp;
+    }
+}
+/**
+ * Reports each error a pipeline raises, once, where it is raised.
+ *
+ * An error is reported at its origin rather than where it ends up, and named
+ * for the processor that raised it rather than the one that passed it along.
+ *
+ * Events:
+ *
+ * - on_error(observer, event): Emitted for each error, as an `ErrorEvent`.
+ *
+ * @example
+ * const observer = new ErrorObserver();
+ *
+ * observer.eventHandler("on_error", async (observer, event: ErrorEvent) => {
+ *   logger.info(JSON.stringify(event));
+ * });
+ */
+export class ErrorObserver extends BaseObserver {
+    _now;
+    constructor(options = {}) {
+        super({ ...options, observeEveryPush: false });
+        this._now = options.timeSource ?? time;
+        this._registerEventHandler("on_error");
+    }
+    /**
+     * Report an error frame.
+     *
+     * The first push of an error comes from the processor that failed.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    async onPushFrame(data) {
+        const frame = data.frame;
+        if (!(frame instanceof ErrorFrame)) {
+            return;
+        }
+        // An error assembled by hand rather than reported through `pushError`
+        // arrives without the processor and category that method settles, so
+        // attribute it to the processor pushing it and report its cause as unknown.
+        const processor = frame.processor ?? data.source;
+        await this._callEventHandler("on_error", new ErrorEvent({
+            message: frame.error,
+            category: frame.category ?? ErrorCategory.UNKNOWN,
+            exceptionType: frame.exception ? frame.exception.constructor.name : null,
+            processor: processor.name,
+            processorUsable: processor.isUsable,
+            timestamp: this._now(),
+        }));
+    }
+}
+//# sourceMappingURL=error_observer.js.map

package/dist/observers/function_call_observer.d.ts

@@ -0,0 +1,157 @@
+import { type Frame } from "../frames/frames.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "./base_observer.ts";
+/**
+ * Where a function call has got to.
+ *
+ * A call starts when the LLM asks for it and is in progress once it is
+ * running, which are two moments rather than one: calls run one at a time
+ * unless the service was built to run them in parallel, so a call can wait
+ * in between, and a call still waiting when the conversation moves on never
+ * runs at all. A call settles in one of four ways: it returned, its handler
+ * raised, it ran past its deadline, or it was cancelled — by an
+ * interruption, or by the LLM asking for it.
+ */
+export declare const FunctionCallEventKind: {
+    readonly STARTED: "function_call_started";
+    readonly IN_PROGRESS: "function_call_in_progress";
+    readonly COMPLETED: "function_call_completed";
+    readonly FAILED: "function_call_failed";
+    readonly TIMED_OUT: "function_call_timed_out";
+    readonly CANCELLED: "function_call_cancelled";
+};
+export type FunctionCallEventKind = (typeof FunctionCallEventKind)[keyof typeof FunctionCallEventKind];
+export interface FunctionCallEventOptions {
+    /** What happened to the call. */
+    kind: FunctionCallEventKind;
+    /** The name of the function. */
+    functionName: string;
+    /** The LLM's identifier for this call, unique within a conversation. */
+    toolCallId: string;
+    /** Unix timestamp of the moment. */
+    timestamp: number;
+    /**
+     * Identifies the calls the LLM asked for in one response, which run
+     * together. Set when the call goes in progress.
+     */
+    groupId?: string | null;
+    /**
+     * Whether the conversation waited for this call. A call that doesn't block
+     * is answered later through a developer message, while the LLM carries on
+     * talking. Set when the call goes in progress.
+     */
+    blocking?: boolean | null;
+    /**
+     * What the LLM passed to the function, when the observer is reporting
+     * arguments. Set both when the call starts and when it goes in progress,
+     * since a call can be reported at either moment without the other.
+     */
+    arguments?: unknown;
+    /**
+     * When the call started, on the moment it goes in progress, so the wait
+     * between the two reads from one record.
+     */
+    startedAt?: number | null;
+    /**
+     * When the call went in progress, on the moment that settles it, so the
+     * time it ran reads from one record.
+     */
+    inProgressAt?: number | null;
+    /** What the handler returned, when the observer is reporting results. */
+    result?: unknown;
+    /** What went wrong, on a call whose handler raised. */
+    error?: string | null;
+}
+/**
+ * One moment in the life of a function call.
+ *
+ * The moments that open a call describe it; the moment that settles it
+ * describes what became of it. Each names the call, so they read as a
+ * sequence without any of them repeating the others.
+ */
+export declare class FunctionCallEvent {
+    kind: FunctionCallEventKind;
+    functionName: string;
+    toolCallId: string;
+    timestamp: number;
+    groupId: string | null;
+    blocking: boolean | null;
+    arguments: unknown;
+    startedAt: number | null;
+    inProgressAt: number | null;
+    result: unknown;
+    error: string | null;
+    constructor(options: FunctionCallEventOptions);
+}
+export interface FunctionCallObserverOptions extends Omit<BaseObserverOptions, "observeEveryPush"> {
+    /** Whether to report the arguments a call was made with. Defaults to true. */
+    includeArguments?: boolean;
+    /** Whether to report what a call returned. Defaults to false. */
+    includeResults?: boolean;
+    /**
+     * Reads the current time in seconds. Supplying one lets a test place
+     * moments without waiting. Defaults to `time()`.
+     */
+    timeSource?: () => number;
+}
+/**
+ * Reports each function call a conversation makes, from start to outcome.
+ *
+ * A call is reported at each moment it reaches rather than summarized once
+ * it is over, because the moments can be far apart and a call need not reach
+ * all of them: one waiting its turn to run is dropped if the conversation
+ * moves on, and one the conversation doesn't wait for can settle long after
+ * the turn that asked for it.
+ *
+ * Arguments and results are where a call holds whatever the conversation was
+ * about, so each is a choice: arguments travel by default, being small and
+ * the reason a call is worth reading at all, and results do not, being
+ * whatever a provider decided to return.
+ *
+ * Events:
+ *
+ * - on_function_call_event(observer, event): Emitted for each moment, as a
+ *   `FunctionCallEvent`.
+ *
+ * @example
+ * const observer = new FunctionCallObserver();
+ *
+ * observer.eventHandler("on_function_call_event", async (observer, event: FunctionCallEvent) => {
+ *   logger.info(JSON.stringify(event));
+ * });
+ */
+export declare class FunctionCallObserver extends BaseObserver {
+    protected _includeArguments: boolean;
+    protected _includeResults: boolean;
+    protected _now: () => number;
+    protected _startedAt: Map<string, number>;
+    protected _inProgressAt: Map<string, number>;
+    constructor(options?: FunctionCallObserverOptions);
+    /**
+     * Report the moment a frame represents.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * Build the moments a frame represents.
+     *
+     * One frame reports one moment, except the frame starting the calls an LLM
+     * response asked for, which reports one for each of them.
+     *
+     * @param frame The frame being pushed.
+     * @returns The moments, or an empty list if this frame is not part of a
+     *   function call's life.
+     */
+    protected _asEvents(frame: Frame): FunctionCallEvent[];
+    /**
+     * Record the end of a call, naming when it began running if that is known.
+     *
+     * A call that began before the observer was watching settles without that
+     * moment rather than borrowing one from another call.
+     */
+    protected _settles(kind: FunctionCallEventKind, functionName: string, toolCallId: string, options?: {
+        result?: unknown;
+        error?: string | null;
+    }): FunctionCallEvent[];
+}
+//# sourceMappingURL=function_call_observer.d.ts.map