@pipedog/core 0.0.0 → 0.1.0

package/dist/observers/function_call_observer.js

@@ -0,0 +1,222 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/function_call_observer.py
+/**
+ * Observer reporting the function calls a conversation makes.
+ *
+ * A function call is the one thing a bot does rather than says, and the part
+ * of a turn whose duration belongs to the application's own code. This
+ * observer reports a call when it starts, when it goes in progress, and when
+ * it settles, so a call that stops short of any of those reads as one still
+ * waiting rather than one that quietly stopped mattering.
+ */
+import { time } from "@pipedog/asyncio";
+import { FunctionCallCancelFrame, FunctionCallInProgressFrame, FunctionCallResultFrame, FunctionCallsStartedFrame, } from "../frames/frames.js";
+import { FrameDirection } from "../processors/frame_processor.js";
+import { BaseObserver } from "./base_observer.js";
+/**
+ * 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 const FunctionCallEventKind = {
+    STARTED: "function_call_started",
+    IN_PROGRESS: "function_call_in_progress",
+    COMPLETED: "function_call_completed",
+    FAILED: "function_call_failed",
+    TIMED_OUT: "function_call_timed_out",
+    CANCELLED: "function_call_cancelled",
+};
+/**
+ * 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 class FunctionCallEvent {
+    kind;
+    functionName;
+    toolCallId;
+    timestamp;
+    groupId;
+    blocking;
+    arguments;
+    startedAt;
+    inProgressAt;
+    result;
+    error;
+    constructor(options) {
+        this.kind = options.kind;
+        this.functionName = options.functionName;
+        this.toolCallId = options.toolCallId;
+        this.timestamp = options.timestamp;
+        this.groupId = options.groupId ?? null;
+        this.blocking = options.blocking ?? null;
+        this.arguments = options.arguments ?? null;
+        this.startedAt = options.startedAt ?? null;
+        this.inProgressAt = options.inProgressAt ?? null;
+        this.result = options.result ?? null;
+        this.error = options.error ?? null;
+    }
+}
+/** Remove `key` from `map` and return its value, or null (Python's `dict.pop(key, None)`). */
+function pop(map, key) {
+    const value = map.get(key);
+    map.delete(key);
+    return value ?? null;
+}
+/**
+ * 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 class FunctionCallObserver extends BaseObserver {
+    _includeArguments;
+    _includeResults;
+    _now;
+    // When each call started and when it went in progress, so the moment that
+    // follows either can carry it.
+    _startedAt = new Map();
+    _inProgressAt = new Map();
+    constructor(options = {}) {
+        super({ ...options, observeEveryPush: false });
+        this._includeArguments = options.includeArguments ?? true;
+        this._includeResults = options.includeResults ?? false;
+        this._now = options.timeSource ?? time;
+        this._registerEventHandler("on_function_call_event");
+    }
+    /**
+     * Report the moment a frame represents.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    async onPushFrame(data) {
+        const frame = data.frame;
+        // These frames are broadcast, arriving as two frames, each pushed for the
+        // first time once. Read the downstream one.
+        if (frame.broadcastSiblingId !== null && data.direction !== FrameDirection.DOWNSTREAM) {
+            return;
+        }
+        const events = this._asEvents(frame);
+        if (events.length === 0) {
+            return;
+        }
+        for (const event of events) {
+            await this._callEventHandler("on_function_call_event", event);
+        }
+    }
+    /**
+     * 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.
+     */
+    _asEvents(frame) {
+        if (frame instanceof FunctionCallsStartedFrame) {
+            const at = this._now();
+            const events = [];
+            for (const call of frame.functionCalls) {
+                this._startedAt.set(call.toolCallId, at);
+                events.push(new FunctionCallEvent({
+                    kind: FunctionCallEventKind.STARTED,
+                    functionName: call.functionName,
+                    toolCallId: call.toolCallId,
+                    timestamp: at,
+                    arguments: this._includeArguments ? call.arguments : null,
+                }));
+            }
+            return events;
+        }
+        else if (frame instanceof FunctionCallInProgressFrame) {
+            const at = this._now();
+            this._inProgressAt.set(frame.toolCallId, at);
+            return [
+                new FunctionCallEvent({
+                    kind: FunctionCallEventKind.IN_PROGRESS,
+                    functionName: frame.functionName,
+                    toolCallId: frame.toolCallId,
+                    timestamp: at,
+                    groupId: frame.groupId,
+                    // A call that survives an interruption is one the conversation was
+                    // never waiting on.
+                    blocking: frame.cancelOnInterruption,
+                    arguments: this._includeArguments ? frame.arguments : null,
+                    startedAt: pop(this._startedAt, frame.toolCallId),
+                }),
+            ];
+        }
+        else if (frame instanceof FunctionCallResultFrame) {
+            // A call that doesn't block may report progress before it is done, and
+            // only its final result settles it.
+            if (frame.properties && !frame.properties.isFinal) {
+                return [];
+            }
+            return this._settles(frame.error ? FunctionCallEventKind.FAILED : FunctionCallEventKind.COMPLETED, frame.functionName, frame.toolCallId, {
+                result: this._includeResults && !frame.error ? frame.result : null,
+                error: frame.error,
+            });
+        }
+        else if (frame instanceof FunctionCallCancelFrame) {
+            // Inference is asked for by the deadline that settled the call, and by
+            // nothing else that cancels one.
+            const kind = frame.runLlm ? FunctionCallEventKind.TIMED_OUT : FunctionCallEventKind.CANCELLED;
+            return this._settles(kind, frame.functionName, frame.toolCallId);
+        }
+        return [];
+    }
+    /**
+     * 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.
+     */
+    _settles(kind, functionName, toolCallId, options = {}) {
+        this._startedAt.delete(toolCallId);
+        return [
+            new FunctionCallEvent({
+                kind,
+                functionName,
+                toolCallId,
+                timestamp: this._now(),
+                inProgressAt: pop(this._inProgressAt, toolCallId),
+                result: options.result ?? null,
+                error: options.error ?? null,
+            }),
+        ];
+    }
+}
+//# sourceMappingURL=function_call_observer.js.map

package/dist/observers/index.d.ts

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

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

package/dist/observers/loggers/debug_log_observer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Debug logging observer for frame activity monitoring.
+ *
+ * This module provides a debug observer that logs detailed frame activity to
+ * the console, making it useful for debugging pipeline behavior and
+ * understanding frame flow between processors.
+ */
+import type { Frame } from "../../frames/frames.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "../base_observer.ts";
+/**
+ * Specifies which endpoint (source or destination) to filter on.
+ *
+ * - SOURCE: filter on the source component that is pushing the frame.
+ * - DESTINATION: filter on the destination component receiving the frame.
+ */
+export declare const FrameEndpoint: {
+    readonly SOURCE: 1;
+    readonly DESTINATION: 2;
+};
+export type FrameEndpoint = (typeof FrameEndpoint)[keyof typeof FrameEndpoint];
+type AnyClass = abstract new (...args: any[]) => unknown;
+export type FrameType = abstract new (...args: any[]) => Frame;
+/** A filter configuration: null logs every instance, or `[serviceType, endpoint]`. */
+export type FrameFilterConfig = readonly [AnyClass, FrameEndpoint] | null;
+export interface DebugLogObserverOptions extends BaseObserverOptions {
+    /**
+     * Frame types to log. Can be:
+     *
+     * - An array of frame types to log all instances
+     * - A Map from frame types to filter configurations
+     * - null to log all frames
+     *
+     * Filter configurations can be null (log all instances) or a tuple of
+     * `[serviceType, endpoint]` to filter on specific services.
+     */
+    frameTypes?: readonly FrameType[] | ReadonlyMap<FrameType, FrameFilterConfig> | null;
+    /**
+     * Field names to exclude from logging. Defaults to excluding binary data
+     * fields like 'audio', 'image', 'images'.
+     */
+    excludeFields?: ReadonlySet<string> | null;
+}
+/**
+ * Observer that logs frame activity with detailed content to the console.
+ *
+ * Automatically extracts and formats data from any frame type, making it
+ * useful for debugging pipeline behavior without needing frame-specific
+ * observers.
+ *
+ * @example
+ * // Log all frames from all services
+ * const observers = [new DebugLogObserver()];
+ *
+ * // Log specific frame types from any source/destination
+ * const observers = [new DebugLogObserver({ frameTypes: [LLMTextFrame, TranscriptionFrame] })];
+ *
+ * // Log frames with specific source/destination filters
+ * const observers = [
+ *   new DebugLogObserver({
+ *     frameTypes: new Map([
+ *       // Only log InterruptionFrame when source is BaseOutputTransport
+ *       [InterruptionFrame, [BaseOutputTransport, FrameEndpoint.SOURCE]],
+ *       // Only log UserStartedSpeakingFrame when destination is STTService
+ *       [UserStartedSpeakingFrame, [STTService, FrameEndpoint.DESTINATION]],
+ *       // Log LLMTextFrame regardless of source or destination type
+ *       [LLMTextFrame, null],
+ *     ]),
+ *   }),
+ * ];
+ */
+export declare class DebugLogObserver extends BaseObserver {
+    frameFilters: Map<FrameType, FrameFilterConfig>;
+    excludeFields: ReadonlySet<string>;
+    /** Initialize the debug log observer. */
+    constructor(options?: DebugLogObserverOptions);
+    /** Format a value for logging. */
+    protected _formatValue(value: unknown): string;
+    /** Determine if a frame should be logged based on filters. */
+    protected _shouldLogFrame(frame: Frame, src: unknown, dst: unknown): boolean;
+    /**
+     * Process a frame being pushed into the pipeline.
+     *
+     * Logs frame details to the console with all relevant fields and values.
+     *
+     * @param data Event data containing the frame, source, destination,
+     *   direction, and timestamp.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+}
+export {};
+//# sourceMappingURL=debug_log_observer.d.ts.map

package/dist/observers/loggers/debug_log_observer.js

@@ -0,0 +1,228 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/loggers/debug_log_observer.py
+import { FrameDirection } from "../../processors/frame_processor.js";
+import { logger } from "../../utils/logger.js";
+import { BaseObserver } from "../base_observer.js";
+/**
+ * Specifies which endpoint (source or destination) to filter on.
+ *
+ * - SOURCE: filter on the source component that is pushing the frame.
+ * - DESTINATION: filter on the destination component receiving the frame.
+ */
+export const FrameEndpoint = {
+    SOURCE: 1,
+    DESTINATION: 2,
+};
+/**
+ * Observer that logs frame activity with detailed content to the console.
+ *
+ * Automatically extracts and formats data from any frame type, making it
+ * useful for debugging pipeline behavior without needing frame-specific
+ * observers.
+ *
+ * @example
+ * // Log all frames from all services
+ * const observers = [new DebugLogObserver()];
+ *
+ * // Log specific frame types from any source/destination
+ * const observers = [new DebugLogObserver({ frameTypes: [LLMTextFrame, TranscriptionFrame] })];
+ *
+ * // Log frames with specific source/destination filters
+ * const observers = [
+ *   new DebugLogObserver({
+ *     frameTypes: new Map([
+ *       // Only log InterruptionFrame when source is BaseOutputTransport
+ *       [InterruptionFrame, [BaseOutputTransport, FrameEndpoint.SOURCE]],
+ *       // Only log UserStartedSpeakingFrame when destination is STTService
+ *       [UserStartedSpeakingFrame, [STTService, FrameEndpoint.DESTINATION]],
+ *       // Log LLMTextFrame regardless of source or destination type
+ *       [LLMTextFrame, null],
+ *     ]),
+ *   }),
+ * ];
+ */
+export class DebugLogObserver extends BaseObserver {
+    frameFilters = new Map();
+    excludeFields;
+    /** Initialize the debug log observer. */
+    constructor(options = {}) {
+        super(options);
+        // Process frame filters
+        const frameTypes = options.frameTypes ?? null;
+        if (frameTypes !== null) {
+            if (Array.isArray(frameTypes)) {
+                // Array of frame types - log all instances
+                this.frameFilters = new Map(frameTypes.map((frameType) => [frameType, null]));
+            }
+            else {
+                // Map of frame types with filters
+                this.frameFilters = new Map(frameTypes);
+            }
+        }
+        // By default, exclude binary data fields that would clutter logs
+        this.excludeFields =
+            options.excludeFields ??
+                new Set([
+                    "audio", // Skip binary audio data
+                    "image", // Skip binary image data
+                    "images", // Skip lists of images
+                ]);
+    }
+    /** Format a value for logging. */
+    _formatValue(value) {
+        if (value === null || value === undefined) {
+            return "None";
+        }
+        else if (typeof value === "string") {
+            return reprStr(value);
+        }
+        else if (Array.isArray(value)) {
+            if (value.length === 0) {
+                return "[]";
+            }
+            if (isPlainObject(value[0]) && value.length > 3) {
+                // For message lists, just show count
+                return `${value.length} items`;
+            }
+            return formatList(value);
+        }
+        else if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+            return `${value.byteLength} bytes`;
+        }
+        else if (typeof value === "object" &&
+            typeof value.getMessagesForLogging === "function") {
+            // Special case for OpenAI context
+            const messages = value.getMessagesForLogging();
+            return `${value.constructor.name} with messages: ${formatAny(messages)}`;
+        }
+        else {
+            return formatAny(value);
+        }
+    }
+    /** Determine if a frame should be logged based on filters. */
+    _shouldLogFrame(frame, src, dst) {
+        // If no filters, log all frames
+        if (this.frameFilters.size === 0) {
+            return true;
+        }
+        // Check if this frame type is in our filters
+        for (const [frameType, filterConfig] of this.frameFilters) {
+            if (frame instanceof frameType) {
+                // If filter is null, log all instances of this frame type
+                if (filterConfig === null) {
+                    return true;
+                }
+                // Otherwise, check the specific filter
+                const [serviceType, endpoint] = filterConfig;
+                if (endpoint === FrameEndpoint.SOURCE) {
+                    return src instanceof serviceType;
+                }
+                else if (endpoint === FrameEndpoint.DESTINATION) {
+                    return dst instanceof serviceType;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Process a frame being pushed into the pipeline.
+     *
+     * Logs frame details to the console with all relevant fields and values.
+     *
+     * @param data Event data containing the frame, source, destination,
+     *   direction, and timestamp.
+     */
+    async onPushFrame(data) {
+        const src = data.source;
+        const dst = data.destination;
+        const frame = data.frame;
+        const direction = data.direction;
+        const timestamp = data.timestamp;
+        // Check if we should log this frame
+        if (!this._shouldLogFrame(frame, src, dst)) {
+            return;
+        }
+        // Format direction arrow
+        const arrow = direction === FrameDirection.DOWNSTREAM ? "→" : "←";
+        const timeSec = (timestamp / 1_000_000_000).toFixed(2);
+        const className = frame.constructor.name;
+        // Build frame representation
+        const frameDetails = [];
+        // Extract the frame's fields (its own enumerable properties, the
+        // equivalent of a dataclass's fields).
+        for (const [fieldName, value] of Object.entries(frame)) {
+            if (this.excludeFields.has(fieldName)) {
+                continue;
+            }
+            if (value === null || value === undefined) {
+                continue;
+            }
+            const formattedValue = this._formatValue(value);
+            frameDetails.push(`${fieldName}: ${formattedValue}`);
+        }
+        // Format the message
+        let message;
+        if (frameDetails.length > 0) {
+            const details = frameDetails.join(", ");
+            message = `${className} ${details} at ${timeSec}s`;
+        }
+        else {
+            message = `${className} at ${timeSec}s`;
+        }
+        // Log the message
+        logger.debug(`${src} ${arrow} ${dst}: ${message}`);
+    }
+}
+/** Python's `repr()` of a string: single-quoted unless it holds only single quotes. */
+function reprStr(s) {
+    const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+    let out = "";
+    for (const ch of s) {
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === quote)
+            out += `\\${ch}`;
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (ch < " " || ch === "\x7f")
+            out += `\\x${ch.charCodeAt(0).toString(16).padStart(2, "0")}`;
+        else
+            out += ch;
+    }
+    return `${quote}${out}${quote}`;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Roughly Python's `str()`: plain data as JSON, objects through `toString()`. */
+function formatAny(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return formatList(value);
+    if (isPlainObject(value)) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+function formatList(values) {
+    return `[${values.map((v) => (typeof v === "string" ? reprStr(v) : formatAny(v))).join(", ")}]`;
+}
+//# sourceMappingURL=debug_log_observer.js.map

package/dist/observers/loggers/index.d.ts

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

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

package/dist/observers/loggers/llm_log_observer.d.ts

@@ -0,0 +1,24 @@
+import { BaseObserver, type FramePushed } from "../base_observer.ts";
+/**
+ * Observer to log LLM activity to the console.
+ *
+ * Logs all frame instances (only from/to LLM service) of:
+ *
+ * - LLMFullResponseStartFrame
+ * - LLMFullResponseEndFrame
+ * - LLMTextFrame
+ * - FunctionCallInProgressFrame
+ *
+ * This allows you to track when the LLM starts responding, what it generates,
+ * and when it finishes.
+ */
+export declare class LLMLogObserver extends BaseObserver {
+    /**
+     * Handle frame push events and log LLM-related activities.
+     *
+     * @param data The frame push event data containing source, destination,
+     *   frame, direction, and timestamp information.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+}
+//# sourceMappingURL=llm_log_observer.d.ts.map