@pipedog/core 0.0.0 → 0.1.0

package/dist/observers/service_metrics_observer.js

@@ -0,0 +1,236 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/service_metrics_observer.py
+/**
+ * Observer reporting what each service spent and consumed.
+ *
+ * Services report metrics as they finish a piece of work, and this observer
+ * turns each one into a record: what was measured, which processor and model
+ * reported it, and when. Nothing is summed, so a consumer groups the records
+ * by turn, session or model as it needs, and a session that ends abruptly
+ * still leaves behind everything that happened before it did.
+ */
+import { time } from "@pipedog/asyncio";
+import { MetricsFrame } from "../frames/frames.js";
+import { LLMUsageMetricsData, STTUsageMetricsData, TTFAMetricsData, TTFATMetricsData, TTFBMetricsData, TTSUsageMetricsData, } from "../metrics/metrics.js";
+import { BaseObserver } from "./base_observer.js";
+/** Which measurement of a service's own time a record carries. */
+export const ServiceLatencyKind = {
+    TTFB: "ttfb",
+    TTFA: "ttfa",
+    TTFAT: "ttfat",
+};
+/** Which kind of service consumed something. */
+export const ServiceUsageKind = {
+    STT: "stt",
+    LLM: "llm",
+    TTS: "tts",
+};
+/** One measurement of how long a service took. */
+export class ServiceLatencyRecord {
+    kind;
+    processor;
+    model;
+    timestamp;
+    seconds;
+    ttfbSecs;
+    leadingSilenceSecs;
+    thinkingTimeSecs;
+    constructor(options) {
+        this.kind = options.kind;
+        this.processor = options.processor;
+        this.model = options.model ?? null;
+        this.timestamp = options.timestamp;
+        this.seconds = options.seconds;
+        this.ttfbSecs = options.ttfbSecs ?? null;
+        this.leadingSilenceSecs = options.leadingSilenceSecs ?? null;
+        this.thinkingTimeSecs = options.thinkingTimeSecs ?? null;
+    }
+}
+/**
+ * What one service consumed doing a piece of work.
+ *
+ * A field is set only where the kind of service reports it, so an LLM record
+ * carries token counts and a text-to-speech record carries characters.
+ */
+export class ServiceUsageRecord {
+    kind;
+    processor;
+    model;
+    timestamp;
+    audioSeconds;
+    characters;
+    promptTokens;
+    completionTokens;
+    totalTokens;
+    cacheReadInputTokens;
+    cacheCreationInputTokens;
+    reasoningTokens;
+    inputAudioTokens;
+    outputAudioTokens;
+    cacheReadInputAudioTokens;
+    constructor(options) {
+        this.kind = options.kind;
+        this.processor = options.processor;
+        this.model = options.model ?? null;
+        this.timestamp = options.timestamp;
+        this.audioSeconds = options.audioSeconds ?? null;
+        this.characters = options.characters ?? null;
+        this.promptTokens = options.promptTokens ?? null;
+        this.completionTokens = options.completionTokens ?? null;
+        this.totalTokens = options.totalTokens ?? null;
+        this.cacheReadInputTokens = options.cacheReadInputTokens ?? null;
+        this.cacheCreationInputTokens = options.cacheCreationInputTokens ?? null;
+        this.reasoningTokens = options.reasoningTokens ?? null;
+        this.inputAudioTokens = options.inputAudioTokens ?? null;
+        this.outputAudioTokens = options.outputAudioTokens ?? null;
+        this.cacheReadInputAudioTokens = options.cacheReadInputAudioTokens ?? null;
+    }
+}
+/**
+ * Reports each metric a service publishes as its own record.
+ *
+ * A record arrives per piece of work rather than per turn or per session: a
+ * turn that runs two inferences reports two, and a consumer that wants a
+ * total groups them itself. Summing here would lose the grain, and a total
+ * held in memory is lost with the process holding it.
+ *
+ * What a service made someone wait for is here; what it did with its own
+ * time is not. Processing time, text aggregation and smart-turn predictions
+ * are all deliberately absent: aggregation already appears as a span in
+ * `LatencyBreakdown` (see `user_bot_latency_observer`), and the other two
+ * describe how work was done rather than what it cost the person waiting.
+ *
+ * Events:
+ *
+ * - on_service_latency(observer, record): Emitted for each measurement of a
+ *   service's own time, as a `ServiceLatencyRecord`.
+ * - on_service_usage(observer, record): Emitted for each report of what a
+ *   service consumed, as a `ServiceUsageRecord`.
+ *
+ * @example
+ * const observer = new ServiceMetricsObserver();
+ *
+ * observer.eventHandler("on_service_usage", async (observer, record: ServiceUsageRecord) => {
+ *   logger.info(JSON.stringify(record));
+ * });
+ */
+export class ServiceMetricsObserver extends BaseObserver {
+    _now;
+    constructor(options = {}) {
+        super({ ...options, observeEveryPush: false });
+        this._now = options.timeSource ?? time;
+        this._registerEventHandler("on_service_latency");
+        this._registerEventHandler("on_service_usage");
+    }
+    /**
+     * Report the metrics carried by a frame.
+     *
+     * Metrics travel in one direction. A frame broadcast both ways would arrive
+     * as two frames, and would be reported twice.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    async onPushFrame(data) {
+        if (!(data.frame instanceof MetricsFrame)) {
+            return;
+        }
+        for (const metrics of data.frame.data) {
+            const latency = this._asLatency(metrics);
+            if (latency) {
+                await this._callEventHandler("on_service_latency", latency);
+                continue;
+            }
+            const usage = this._asUsage(metrics);
+            if (usage) {
+                await this._callEventHandler("on_service_usage", usage);
+            }
+        }
+    }
+    /**
+     * Build a latency record, for the metrics that measure time spent.
+     *
+     * @param metrics One metric a processor reported.
+     * @returns The record, or null if this metric measures something else.
+     */
+    _asLatency(metrics) {
+        const common = {
+            processor: metrics.processor,
+            model: metrics.model,
+            timestamp: this._now(),
+        };
+        if (metrics instanceof TTFAMetricsData) {
+            return new ServiceLatencyRecord({
+                kind: ServiceLatencyKind.TTFA,
+                seconds: metrics.ttfa,
+                ttfbSecs: metrics.ttfb,
+                leadingSilenceSecs: metrics.leadingSilence,
+                ...common,
+            });
+        }
+        else if (metrics instanceof TTFATMetricsData) {
+            return new ServiceLatencyRecord({
+                kind: ServiceLatencyKind.TTFAT,
+                seconds: metrics.ttfat,
+                ttfbSecs: metrics.ttfb,
+                thinkingTimeSecs: metrics.thinkingTime,
+                ...common,
+            });
+        }
+        else if (metrics instanceof TTFBMetricsData) {
+            return new ServiceLatencyRecord({
+                kind: ServiceLatencyKind.TTFB,
+                seconds: metrics.value,
+                ...common,
+            });
+        }
+        return null;
+    }
+    /**
+     * Build a usage record, for the metrics that measure what was consumed.
+     *
+     * @param metrics One metric a processor reported.
+     * @returns The record, or null if this metric measures something else.
+     */
+    _asUsage(metrics) {
+        const common = {
+            processor: metrics.processor,
+            model: metrics.model,
+            timestamp: this._now(),
+        };
+        if (metrics instanceof LLMUsageMetricsData) {
+            const tokens = metrics.value;
+            return new ServiceUsageRecord({
+                kind: ServiceUsageKind.LLM,
+                promptTokens: tokens.promptTokens,
+                completionTokens: tokens.completionTokens,
+                totalTokens: tokens.totalTokens,
+                cacheReadInputTokens: tokens.cacheReadInputTokens,
+                cacheCreationInputTokens: tokens.cacheCreationInputTokens,
+                reasoningTokens: tokens.reasoningTokens,
+                inputAudioTokens: tokens.inputAudioTokens,
+                outputAudioTokens: tokens.outputAudioTokens,
+                cacheReadInputAudioTokens: tokens.cacheReadInputAudioTokens,
+                ...common,
+            });
+        }
+        else if (metrics instanceof STTUsageMetricsData) {
+            return new ServiceUsageRecord({
+                kind: ServiceUsageKind.STT,
+                audioSeconds: metrics.value.audioSeconds,
+                ...common,
+            });
+        }
+        else if (metrics instanceof TTSUsageMetricsData) {
+            return new ServiceUsageRecord({
+                kind: ServiceUsageKind.TTS,
+                characters: metrics.value,
+                ...common,
+            });
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=service_metrics_observer.js.map

package/dist/observers/speaking_observer.d.ts

@@ -0,0 +1,104 @@
+import { type Frame } from "../frames/frames.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "./base_observer.ts";
+/**
+ * What happened, to whom, and at which layer.
+ *
+ * The user appears at two layers, and they answer different questions.
+ * `user_speech_*` is the speech itself, as the voice activity detector heard
+ * it: speech that never becomes a turn — a cough, a false start, a pause
+ * mid-sentence — appears only here. `user_turn_*` is the turn strategy's
+ * ruling on that speech, which is what the rest of the pipeline acts on, and
+ * follows the speech by however long the ruling took.
+ */
+export declare const SpeechEventKind: {
+    readonly USER_SPEECH_STARTED: "user_speech_started";
+    readonly USER_SPEECH_STOPPED: "user_speech_stopped";
+    readonly USER_TURN_STARTED: "user_turn_started";
+    readonly USER_TURN_STOPPED: "user_turn_stopped";
+    readonly BOT_SPEECH_STARTED: "bot_speech_started";
+    readonly BOT_SPEECH_STOPPED: "bot_speech_stopped";
+    readonly INTERRUPTION: "interruption";
+};
+export type SpeechEventKind = (typeof SpeechEventKind)[keyof typeof SpeechEventKind];
+export interface SpeechEventOptions {
+    /** What happened, to whom, and at which layer. */
+    kind: SpeechEventKind;
+    /**
+     * Unix timestamp of the moment itself. Speech is timed to when it began and
+     * ended, not to when the detector confirmed it, so an interval drawn from
+     * these matches what was said.
+     */
+    timestamp: number;
+    /**
+     * When the matching stretch of speech began, on the moments that end one,
+     * so a stretch reads as an interval without pairing it with the moment that
+     * opened it.
+     */
+    startedAt?: number | null;
+}
+/** One moment in the conversation's speaking lifecycle. */
+export declare class SpeechEvent {
+    kind: SpeechEventKind;
+    timestamp: number;
+    startedAt: number | null;
+    constructor(options: SpeechEventOptions);
+}
+export interface SpeakingObserverOptions extends Omit<BaseObserverOptions, "observeEveryPush"> {
+    /**
+     * Reads the current time in seconds. Supplying one lets a test place
+     * moments without waiting. Defaults to `time()`.
+     */
+    timeSource?: () => number;
+}
+/**
+ * Reports the speaking lifecycle of a conversation.
+ *
+ * Every moment is reported as it happens, and the moments that close a
+ * stretch of speech name where it began, so an interval reads whole from one
+ * record: a stretch whose closing moment never arrives stays open rather than
+ * quietly joining itself to the next one. What a turn is stays with the
+ * reader: a turn built here would freeze one definition into every record,
+ * where the moments themselves can be grouped again later, differently, over
+ * the same history.
+ *
+ * Events:
+ *
+ * - on_speech_event(observer, event): Emitted for each moment, as a
+ *   `SpeechEvent`.
+ *
+ * @example
+ * const observer = new SpeakingObserver();
+ *
+ * observer.eventHandler("on_speech_event", async (observer, event: SpeechEvent) => {
+ *   logger.info(JSON.stringify(event));
+ * });
+ */
+export declare class SpeakingObserver extends BaseObserver {
+    protected _now: () => number;
+    protected _open: Map<SpeechEventKind, number>;
+    constructor(options?: SpeakingObserverOptions);
+    /**
+     * Report the moment a frame represents.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * Build the moment a frame represents.
+     *
+     * @param frame The frame being pushed.
+     * @returns The moment, or null if this frame is not part of the speaking
+     *   lifecycle.
+     */
+    protected _asEvent(frame: Frame): SpeechEvent | null;
+    /** Record the start of a stretch of speech. */
+    protected _opens(kind: SpeechEventKind, at: number): SpeechEvent;
+    /**
+     * Record the end of a stretch, naming its start where one is known.
+     *
+     * A stretch that began before the observer was watching closes without a
+     * start rather than borrowing one from another stretch.
+     */
+    protected _closes(kind: SpeechEventKind, openedBy: SpeechEventKind, at: number): SpeechEvent;
+}
+//# sourceMappingURL=speaking_observer.d.ts.map

package/dist/observers/speaking_observer.js

@@ -0,0 +1,150 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/speaking_observer.py
+/**
+ * Observer reporting who was speaking, and when.
+ *
+ * A conversation is a sequence of people taking the floor and occasionally
+ * taking it from each other. This observer reports each of those moments as
+ * it happens, leaving what counts as a turn to whoever reads them: a turn
+ * boundary is a policy, and a policy that ships inside a record can never be
+ * revised.
+ */
+import { time } from "@pipedog/asyncio";
+import { BotStartedSpeakingFrame, BotStoppedSpeakingFrame, InterruptionFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, VADUserStartedSpeakingFrame, VADUserStoppedSpeakingFrame, } from "../frames/frames.js";
+import { FrameDirection } from "../processors/frame_processor.js";
+import { BaseObserver } from "./base_observer.js";
+/**
+ * What happened, to whom, and at which layer.
+ *
+ * The user appears at two layers, and they answer different questions.
+ * `user_speech_*` is the speech itself, as the voice activity detector heard
+ * it: speech that never becomes a turn — a cough, a false start, a pause
+ * mid-sentence — appears only here. `user_turn_*` is the turn strategy's
+ * ruling on that speech, which is what the rest of the pipeline acts on, and
+ * follows the speech by however long the ruling took.
+ */
+export const SpeechEventKind = {
+    USER_SPEECH_STARTED: "user_speech_started",
+    USER_SPEECH_STOPPED: "user_speech_stopped",
+    USER_TURN_STARTED: "user_turn_started",
+    USER_TURN_STOPPED: "user_turn_stopped",
+    BOT_SPEECH_STARTED: "bot_speech_started",
+    BOT_SPEECH_STOPPED: "bot_speech_stopped",
+    INTERRUPTION: "interruption",
+};
+/** One moment in the conversation's speaking lifecycle. */
+export class SpeechEvent {
+    kind;
+    timestamp;
+    startedAt;
+    constructor(options) {
+        this.kind = options.kind;
+        this.timestamp = options.timestamp;
+        this.startedAt = options.startedAt ?? null;
+    }
+}
+/**
+ * Reports the speaking lifecycle of a conversation.
+ *
+ * Every moment is reported as it happens, and the moments that close a
+ * stretch of speech name where it began, so an interval reads whole from one
+ * record: a stretch whose closing moment never arrives stays open rather than
+ * quietly joining itself to the next one. What a turn is stays with the
+ * reader: a turn built here would freeze one definition into every record,
+ * where the moments themselves can be grouped again later, differently, over
+ * the same history.
+ *
+ * Events:
+ *
+ * - on_speech_event(observer, event): Emitted for each moment, as a
+ *   `SpeechEvent`.
+ *
+ * @example
+ * const observer = new SpeakingObserver();
+ *
+ * observer.eventHandler("on_speech_event", async (observer, event: SpeechEvent) => {
+ *   logger.info(JSON.stringify(event));
+ * });
+ */
+export class SpeakingObserver extends BaseObserver {
+    _now;
+    // When each open stretch of speech began, so the moment that closes one can
+    // carry it.
+    _open = new Map();
+    constructor(options = {}) {
+        super({ ...options, observeEveryPush: false });
+        this._now = options.timeSource ?? time;
+        this._registerEventHandler("on_speech_event");
+    }
+    /**
+     * Report the moment a frame represents.
+     *
+     * @param data Frame push event containing the frame and direction.
+     */
+    async onPushFrame(data) {
+        const frame = data.frame;
+        // An interruption is 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 event = this._asEvent(frame);
+        if (!event) {
+            return;
+        }
+        await this._callEventHandler("on_speech_event", event);
+    }
+    /**
+     * Build the moment a frame represents.
+     *
+     * @param frame The frame being pushed.
+     * @returns The moment, or null if this frame is not part of the speaking
+     *   lifecycle.
+     */
+    _asEvent(frame) {
+        if (frame instanceof VADUserStartedSpeakingFrame) {
+            // The detector's account of when speech began, which precedes its
+            // confirmation by the time it needed to be sure.
+            return this._opens(SpeechEventKind.USER_SPEECH_STARTED, frame.timestamp - frame.startSecs);
+        }
+        else if (frame instanceof VADUserStoppedSpeakingFrame) {
+            return this._closes(SpeechEventKind.USER_SPEECH_STOPPED, SpeechEventKind.USER_SPEECH_STARTED, frame.timestamp - frame.stopSecs);
+        }
+        else if (frame instanceof UserStartedSpeakingFrame) {
+            return this._opens(SpeechEventKind.USER_TURN_STARTED, this._now());
+        }
+        else if (frame instanceof UserStoppedSpeakingFrame) {
+            return this._closes(SpeechEventKind.USER_TURN_STOPPED, SpeechEventKind.USER_TURN_STARTED, this._now());
+        }
+        else if (frame instanceof BotStartedSpeakingFrame) {
+            return this._opens(SpeechEventKind.BOT_SPEECH_STARTED, this._now());
+        }
+        else if (frame instanceof BotStoppedSpeakingFrame) {
+            return this._closes(SpeechEventKind.BOT_SPEECH_STOPPED, SpeechEventKind.BOT_SPEECH_STARTED, this._now());
+        }
+        else if (frame instanceof InterruptionFrame) {
+            return new SpeechEvent({ kind: SpeechEventKind.INTERRUPTION, timestamp: this._now() });
+        }
+        return null;
+    }
+    /** Record the start of a stretch of speech. */
+    _opens(kind, at) {
+        this._open.set(kind, at);
+        return new SpeechEvent({ kind, timestamp: at });
+    }
+    /**
+     * Record the end of a stretch, naming its start where one is known.
+     *
+     * A stretch that began before the observer was watching closes without a
+     * start rather than borrowing one from another stretch.
+     */
+    _closes(kind, openedBy, at) {
+        const startedAt = this._open.get(openedBy) ?? null;
+        this._open.delete(openedBy);
+        return new SpeechEvent({ kind, timestamp: at, startedAt });
+    }
+}
+//# sourceMappingURL=speaking_observer.js.map