@pipedog/core 0.0.0 → 0.2.0

package/dist/observers/loggers/llm_log_observer.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/loggers/llm_log_observer.py
+/** LLM logging observer for Pipecat. */
+import { FunctionCallInProgressFrame, FunctionCallResultFrame, LLMContextFrame, LLMFullResponseEndFrame, LLMFullResponseStartFrame, LLMTextFrame, } from "../../frames/frames.js";
+import { FrameDirection } from "../../processors/frame_processor.js";
+import { LLMService } from "../../services/llm_service.js";
+import { logger } from "../../utils/logger.js";
+import { BaseObserver } from "../base_observer.js";
+/** 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}`;
+}
+/** Approximation of Python's `repr()` for log lines. */
+function repr(value) {
+    if (typeof value === "string")
+        return reprStr(value);
+    return String(value);
+}
+/** Approximation of Python's `str()` on containers for log lines. */
+function str(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+/**
+ * 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 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.
+     */
+    async onPushFrame(data) {
+        const src = data.source;
+        const dst = data.destination;
+        const frame = data.frame;
+        const direction = data.direction;
+        const timestamp = data.timestamp;
+        if (!(src instanceof LLMService) && !(dst instanceof LLMService)) {
+            return;
+        }
+        const timeSec = (timestamp / 1_000_000_000).toFixed(2);
+        const arrow = "→";
+        // Log LLM start/end frames (output)
+        if (frame instanceof LLMFullResponseStartFrame || frame instanceof LLMFullResponseEndFrame) {
+            const event = frame instanceof LLMFullResponseStartFrame ? "START" : "END";
+            logger.debug(`🧠 ${src} ${arrow} LLM ${event} RESPONSE at ${timeSec}s`);
+        }
+        // Log all LLMTextFrames (output)
+        else if (frame instanceof LLMTextFrame) {
+            logger.debug(`🧠 ${src} ${arrow} LLM GENERATING: ${repr(frame.text)} at ${timeSec}s`);
+        }
+        // Log function calling (output)
+        else if (frame instanceof FunctionCallInProgressFrame &&
+            direction !== FrameDirection.DOWNSTREAM) {
+            logger.debug(`🧠 ${src} ${arrow} LLM FUNCTION CALL (${frame.toolCallId}): ${repr(frame.functionName)}(${str(frame.arguments)}) at ${timeSec}s`);
+        }
+        // Log LLMContextFrame (input)
+        else if (frame instanceof LLMContextFrame) {
+            const messages = frame.context.getMessages();
+            logger.debug(`🧠 ${arrow} ${dst} LLM CONTEXT FRAME: ${str(messages)} at ${timeSec}s`);
+        }
+        // Log function call result (input)
+        else if (frame instanceof FunctionCallResultFrame) {
+            logger.debug(`🧠 ${arrow} ${src} LLM FUNCTION CALL RESULT (${frame.toolCallId}): ${str(frame.result)} at ${timeSec}s`);
+        }
+    }
+}
+//# sourceMappingURL=llm_log_observer.js.map

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

@@ -0,0 +1,85 @@
+import { LLMUsageMetricsData, type MetricsData, TurnMetricsData } from "../../metrics/metrics.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "../base_observer.ts";
+export type MetricsDataClass = abstract new (...args: any[]) => MetricsData;
+export interface MetricsLogObserverOptions extends Omit<BaseObserverOptions, "observeEveryPush"> {
+    /**
+     * Set of metrics types to include. If specified, only these metrics types
+     * will be logged. If null, all metrics are logged.
+     */
+    includeMetrics?: ReadonlySet<MetricsDataClass> | null;
+}
+/**
+ * Observer to log metrics activity to the console.
+ *
+ * Monitors and logs all MetricsFrame instances, including:
+ *
+ * - TTFBMetricsData (Time To First Byte)
+ * - TTFAMetricsData (Time To First Audio)
+ * - TTFATMetricsData (Time To First Answer Token)
+ * - ProcessingMetricsData (General processing time)
+ * - LLMUsageMetricsData (Token usage statistics)
+ * - STTUsageMetricsData (Speech-to-Text audio seconds)
+ * - TTSUsageMetricsData (Text-to-Speech character counts)
+ * - TurnMetricsData (Turn prediction metrics)
+ *
+ * This allows developers to track performance metrics, token usage, and other
+ * statistics throughout the pipeline.
+ *
+ * @example
+ * // Log all metrics types
+ * const observers = [new MetricsLogObserver()];
+ *
+ * // Log only LLM and TTS metrics
+ * const observers = [
+ *   new MetricsLogObserver({
+ *     includeMetrics: new Set([LLMUsageMetricsData, TTSUsageMetricsData]),
+ *   }),
+ * ];
+ */
+export declare class MetricsLogObserver extends BaseObserver {
+    protected _includeMetrics: ReadonlySet<MetricsDataClass> | null;
+    /** Initialize the metrics log observer. */
+    constructor(options?: MetricsLogObserverOptions);
+    /**
+     * Handle frame push events and log metrics frames.
+     *
+     * Logs MetricsFrame instances with detailed information about the metrics
+     * data, formatted appropriately for each metrics type.
+     *
+     * @param data Frame push event data containing source, frame, and timestamp.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * Determine if a metrics data item should be logged based on filters.
+     *
+     * @param metricsData The metrics data to check.
+     * @returns True if the metrics should be logged, false otherwise.
+     */
+    protected _shouldLogMetrics(metricsData: MetricsData): boolean;
+    /**
+     * Log a single metrics data item.
+     *
+     * @param metricsData The metrics data to log.
+     * @param timeSec Timestamp in seconds.
+     */
+    protected _logMetricsData(metricsData: MetricsData, timeSec: number): void;
+    /**
+     * Log LLM token usage metrics.
+     *
+     * @param metricsData The LLM usage metrics data.
+     * @param processorInfo Formatted processor name string.
+     * @param modelInfo Formatted model name string.
+     * @param timeSec Timestamp in seconds.
+     */
+    protected _logLlmUsage(metricsData: LLMUsageMetricsData, processorInfo: string, modelInfo: string, timeSec: number): void;
+    /**
+     * Log turn prediction metrics.
+     *
+     * @param metricsData The turn metrics data.
+     * @param processorInfo Formatted processor name string.
+     * @param modelInfo Formatted model name string.
+     * @param timeSec Timestamp in seconds.
+     */
+    protected _logTurn(metricsData: TurnMetricsData, processorInfo: string, modelInfo: string, timeSec: number): void;
+}
+//# sourceMappingURL=metrics_log_observer.d.ts.map

package/dist/observers/loggers/metrics_log_observer.js

@@ -0,0 +1,186 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/loggers/metrics_log_observer.py
+/**
+ * Metrics logging observer for Pipecat.
+ *
+ * This module provides an observer that logs metrics frames to the console,
+ * allowing developers to monitor performance metrics, token usage, and other
+ * statistics in real-time.
+ */
+import { MetricsFrame } from "../../frames/frames.js";
+import { LLMUsageMetricsData, ProcessingMetricsData, STTUsageMetricsData, TTFAMetricsData, TTFATMetricsData, TTFBMetricsData, TTSUsageMetricsData, TurnMetricsData, } from "../../metrics/metrics.js";
+import { logger } from "../../utils/logger.js";
+import { BaseObserver } from "../base_observer.js";
+/**
+ * Observer to log metrics activity to the console.
+ *
+ * Monitors and logs all MetricsFrame instances, including:
+ *
+ * - TTFBMetricsData (Time To First Byte)
+ * - TTFAMetricsData (Time To First Audio)
+ * - TTFATMetricsData (Time To First Answer Token)
+ * - ProcessingMetricsData (General processing time)
+ * - LLMUsageMetricsData (Token usage statistics)
+ * - STTUsageMetricsData (Speech-to-Text audio seconds)
+ * - TTSUsageMetricsData (Text-to-Speech character counts)
+ * - TurnMetricsData (Turn prediction metrics)
+ *
+ * This allows developers to track performance metrics, token usage, and other
+ * statistics throughout the pipeline.
+ *
+ * @example
+ * // Log all metrics types
+ * const observers = [new MetricsLogObserver()];
+ *
+ * // Log only LLM and TTS metrics
+ * const observers = [
+ *   new MetricsLogObserver({
+ *     includeMetrics: new Set([LLMUsageMetricsData, TTSUsageMetricsData]),
+ *   }),
+ * ];
+ */
+export class MetricsLogObserver extends BaseObserver {
+    _includeMetrics;
+    /** Initialize the metrics log observer. */
+    constructor(options = {}) {
+        super({ ...options, observeEveryPush: false });
+        this._includeMetrics = options.includeMetrics ?? null;
+    }
+    /**
+     * Handle frame push events and log metrics frames.
+     *
+     * Logs MetricsFrame instances with detailed information about the metrics
+     * data, formatted appropriately for each metrics type.
+     *
+     * @param data Frame push event data containing source, frame, and timestamp.
+     */
+    async onPushFrame(data) {
+        const frame = data.frame;
+        const timestamp = data.timestamp;
+        if (!(frame instanceof MetricsFrame)) {
+            return;
+        }
+        const timeSec = timestamp / 1_000_000_000;
+        // Process each metrics data item in the frame
+        for (const metricsData of frame.data) {
+            // Check if this metrics type should be logged
+            if (!this._shouldLogMetrics(metricsData)) {
+                continue;
+            }
+            this._logMetricsData(metricsData, timeSec);
+        }
+    }
+    /**
+     * Determine if a metrics data item should be logged based on filters.
+     *
+     * @param metricsData The metrics data to check.
+     * @returns True if the metrics should be logged, false otherwise.
+     */
+    _shouldLogMetrics(metricsData) {
+        // If includeMetrics is specified, only log those types
+        if (this._includeMetrics !== null) {
+            return this._includeMetrics.has(metricsData.constructor);
+        }
+        // Otherwise, log all metrics
+        return true;
+    }
+    /**
+     * Log a single metrics data item.
+     *
+     * @param metricsData The metrics data to log.
+     * @param timeSec Timestamp in seconds.
+     */
+    _logMetricsData(metricsData, timeSec) {
+        const processorInfo = `[${metricsData.processor}]`;
+        const modelInfo = metricsData.model ? ` (${metricsData.model})` : "";
+        const t = timeSec.toFixed(3);
+        if (metricsData instanceof TTFBMetricsData) {
+            logger.debug(`📊 ${processorInfo} TTFB${modelInfo}: ${metricsData.value}s at ${t}s`);
+        }
+        else if (metricsData instanceof TTFAMetricsData) {
+            logger.debug(`📊 ${processorInfo} TTFA${modelInfo}: ${metricsData.ttfa}s ` +
+                `(${metricsData.leadingSilence}s leading silence) at ${t}s`);
+        }
+        else if (metricsData instanceof TTFATMetricsData) {
+            logger.debug(`📊 ${processorInfo} TTFAT${modelInfo}: ${metricsData.ttfat}s ` +
+                `(${metricsData.thinkingTime}s thinking) at ${t}s`);
+        }
+        else if (metricsData instanceof ProcessingMetricsData) {
+            logger.debug(`📊 ${processorInfo} PROCESSING TIME${modelInfo}: ${metricsData.value}s at ${t}s`);
+        }
+        else if (metricsData instanceof LLMUsageMetricsData) {
+            this._logLlmUsage(metricsData, processorInfo, modelInfo, timeSec);
+        }
+        else if (metricsData instanceof STTUsageMetricsData) {
+            logger.debug(`📊 ${processorInfo} STT USAGE${modelInfo}: ` +
+                `${metricsData.value.audioSeconds.toFixed(3)}s audio at ${t}s`);
+        }
+        else if (metricsData instanceof TTSUsageMetricsData) {
+            logger.debug(`📊 ${processorInfo} TTS USAGE${modelInfo}: ${metricsData.value} characters at ${t}s`);
+        }
+        else if (metricsData instanceof TurnMetricsData) {
+            this._logTurn(metricsData, processorInfo, modelInfo, timeSec);
+        }
+        else {
+            // Generic fallback for unknown metrics types
+            logger.debug(`📊 ${processorInfo} METRICS${modelInfo}: ${metricsData} at ${t}s`);
+        }
+    }
+    /**
+     * Log LLM token usage metrics.
+     *
+     * @param metricsData The LLM usage metrics data.
+     * @param processorInfo Formatted processor name string.
+     * @param modelInfo Formatted model name string.
+     * @param timeSec Timestamp in seconds.
+     */
+    _logLlmUsage(metricsData, processorInfo, modelInfo, timeSec) {
+        const usage = metricsData.value;
+        // Build usage details
+        const details = [
+            `prompt: ${usage.promptTokens}`,
+            `completion: ${usage.completionTokens}`,
+            `total: ${usage.totalTokens}`,
+        ];
+        if (usage.cacheReadInputTokens !== null && usage.cacheReadInputTokens !== undefined) {
+            details.push(`cache_read: ${usage.cacheReadInputTokens}`);
+        }
+        if (usage.cacheCreationInputTokens !== null && usage.cacheCreationInputTokens !== undefined) {
+            details.push(`cache_creation: ${usage.cacheCreationInputTokens}`);
+        }
+        if (usage.reasoningTokens !== null && usage.reasoningTokens !== undefined) {
+            details.push(`reasoning: ${usage.reasoningTokens}`);
+        }
+        if (usage.inputAudioTokens !== null && usage.inputAudioTokens !== undefined) {
+            details.push(`input_audio: ${usage.inputAudioTokens}`);
+        }
+        if (usage.outputAudioTokens !== null && usage.outputAudioTokens !== undefined) {
+            details.push(`output_audio: ${usage.outputAudioTokens}`);
+        }
+        if (usage.cacheReadInputAudioTokens !== null && usage.cacheReadInputAudioTokens !== undefined) {
+            details.push(`cache_read_audio: ${usage.cacheReadInputAudioTokens}`);
+        }
+        const usageStr = details.join(", ");
+        logger.debug(`📊 ${processorInfo} LLM TOKEN USAGE${modelInfo}: ${usageStr} at ${timeSec.toFixed(2)}s`);
+    }
+    /**
+     * Log turn prediction metrics.
+     *
+     * @param metricsData The turn metrics data.
+     * @param processorInfo Formatted processor name string.
+     * @param modelInfo Formatted model name string.
+     * @param timeSec Timestamp in seconds.
+     */
+    _logTurn(metricsData, processorInfo, modelInfo, timeSec) {
+        const completeStr = metricsData.isComplete ? "COMPLETE" : "INCOMPLETE";
+        const e2eStr = `${metricsData.e2eProcessingTimeMs.toFixed(1)}ms`;
+        logger.debug(`📊 ${processorInfo} TURN${modelInfo}: ${completeStr} ` +
+            `(probability: ${(metricsData.probability * 100).toFixed(2)}%, ` +
+            `e2e: ${e2eStr}) ` +
+            `at ${timeSec.toFixed(2)}s`);
+    }
+}
+//# sourceMappingURL=metrics_log_observer.js.map

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

@@ -0,0 +1,23 @@
+import { BaseObserver, type FramePushed } from "../base_observer.ts";
+/**
+ * Observer to log transcription activity to the console.
+ *
+ * Monitors and logs all transcription frames from STT services, including both
+ * final transcriptions and interim results. This allows developers to track
+ * speech recognition activity and debug transcription issues.
+ *
+ * Only processes frames from STTService instances to avoid logging unrelated
+ * transcription frames from other sources.
+ */
+export declare class TranscriptionLogObserver extends BaseObserver {
+    /**
+     * Handle frame push events and log transcription frames.
+     *
+     * Logs TranscriptionFrame and InterimTranscriptionFrame instances with
+     * timestamps and user information for debugging purposes.
+     *
+     * @param data Frame push event data containing source, frame, and timestamp.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+}
+//# sourceMappingURL=transcription_log_observer.d.ts.map

package/dist/observers/loggers/transcription_log_observer.js

@@ -0,0 +1,74 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/observers/loggers/transcription_log_observer.py
+/**
+ * Transcription logging observer for Pipecat.
+ *
+ * This module provides an observer that logs transcription frames to the
+ * console, allowing developers to monitor speech-to-text activity in real-time.
+ */
+import { InterimTranscriptionFrame, TranscriptionFrame } from "../../frames/frames.js";
+import { STTService } from "../../services/stt_service.js";
+import { logger } from "../../utils/logger.js";
+import { BaseObserver } from "../base_observer.js";
+/** 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}`;
+}
+/**
+ * Observer to log transcription activity to the console.
+ *
+ * Monitors and logs all transcription frames from STT services, including both
+ * final transcriptions and interim results. This allows developers to track
+ * speech recognition activity and debug transcription issues.
+ *
+ * Only processes frames from STTService instances to avoid logging unrelated
+ * transcription frames from other sources.
+ */
+export class TranscriptionLogObserver extends BaseObserver {
+    /**
+     * Handle frame push events and log transcription frames.
+     *
+     * Logs TranscriptionFrame and InterimTranscriptionFrame instances with
+     * timestamps and user information for debugging purposes.
+     *
+     * @param data Frame push event data containing source, frame, and timestamp.
+     */
+    async onPushFrame(data) {
+        const src = data.source;
+        const frame = data.frame;
+        const timestamp = data.timestamp;
+        if (!(src instanceof STTService)) {
+            return;
+        }
+        const timeSec = (timestamp / 1_000_000_000).toFixed(2);
+        const arrow = "→";
+        if (frame instanceof TranscriptionFrame) {
+            logger.debug(`💬 ${src} ${arrow} TRANSCRIPTION: ${reprStr(frame.text)} from ${reprStr(frame.userId)} at ${timeSec}s`);
+        }
+        else if (frame instanceof InterimTranscriptionFrame) {
+            logger.debug(`💬 ${src} ${arrow} INTERIM TRANSCRIPTION: ${reprStr(frame.text)} from ${reprStr(frame.userId)} at ${timeSec}s`);
+        }
+    }
+}
+//# sourceMappingURL=transcription_log_observer.js.map

package/dist/observers/service_metrics_observer.d.ts

@@ -0,0 +1,168 @@
+import { type MetricsData } from "../metrics/metrics.ts";
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "./base_observer.ts";
+/** Which measurement of a service's own time a record carries. */
+export declare const ServiceLatencyKind: {
+    readonly TTFB: "ttfb";
+    readonly TTFA: "ttfa";
+    readonly TTFAT: "ttfat";
+};
+export type ServiceLatencyKind = (typeof ServiceLatencyKind)[keyof typeof ServiceLatencyKind];
+/** Which kind of service consumed something. */
+export declare const ServiceUsageKind: {
+    readonly STT: "stt";
+    readonly LLM: "llm";
+    readonly TTS: "tts";
+};
+export type ServiceUsageKind = (typeof ServiceUsageKind)[keyof typeof ServiceUsageKind];
+export interface ServiceLatencyRecordOptions {
+    /** Which wait was measured. */
+    kind: ServiceLatencyKind;
+    /** Name of the processor that reported it. */
+    processor: string;
+    /** Model the processor was using, where it names one. */
+    model?: string | null;
+    /** Unix timestamp when the measurement was observed. */
+    timestamp: number;
+    /** The measurement itself. */
+    seconds: number;
+    /** The time to first byte the measurement builds on, for the kinds that report one. */
+    ttfbSecs?: number | null;
+    /** Silence at the head of the first audio, for time to first audio. */
+    leadingSilenceSecs?: number | null;
+    /**
+     * Time between a model's first output and its first answer token, for time
+     * to first answer token.
+     */
+    thinkingTimeSecs?: number | null;
+}
+/** One measurement of how long a service took. */
+export declare class ServiceLatencyRecord {
+    kind: ServiceLatencyKind;
+    processor: string;
+    model: string | null;
+    timestamp: number;
+    seconds: number;
+    ttfbSecs: number | null;
+    leadingSilenceSecs: number | null;
+    thinkingTimeSecs: number | null;
+    constructor(options: ServiceLatencyRecordOptions);
+}
+export interface ServiceUsageRecordOptions {
+    /** Which kind of service reported. */
+    kind: ServiceUsageKind;
+    /** Name of the processor that reported it. */
+    processor: string;
+    /** Model the processor was using, where it names one. */
+    model?: string | null;
+    /** Unix timestamp when the usage was observed. */
+    timestamp: number;
+    /** Audio transcribed, for speech-to-text. */
+    audioSeconds?: number | null;
+    /** Characters synthesised, for text-to-speech. */
+    characters?: number | null;
+    /** Tokens in the prompt, for an LLM. */
+    promptTokens?: number | null;
+    /** Tokens generated, for an LLM. */
+    completionTokens?: number | null;
+    /** Tokens in the prompt and the completion together. */
+    totalTokens?: number | null;
+    /** Prompt tokens served from cache. */
+    cacheReadInputTokens?: number | null;
+    /** Prompt tokens written to cache. */
+    cacheCreationInputTokens?: number | null;
+    /** Tokens spent reasoning before answering. */
+    reasoningTokens?: number | null;
+    /** Audio tokens in the prompt. */
+    inputAudioTokens?: number | null;
+    /** Audio tokens generated. */
+    outputAudioTokens?: number | null;
+    /** Audio prompt tokens served from cache. */
+    cacheReadInputAudioTokens?: number | 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 declare class ServiceUsageRecord {
+    kind: ServiceUsageKind;
+    processor: string;
+    model: string | null;
+    timestamp: number;
+    audioSeconds: number | null;
+    characters: number | null;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    totalTokens: number | null;
+    cacheReadInputTokens: number | null;
+    cacheCreationInputTokens: number | null;
+    reasoningTokens: number | null;
+    inputAudioTokens: number | null;
+    outputAudioTokens: number | null;
+    cacheReadInputAudioTokens: number | null;
+    constructor(options: ServiceUsageRecordOptions);
+}
+export interface ServiceMetricsObserverOptions extends Omit<BaseObserverOptions, "observeEveryPush"> {
+    /**
+     * Reads the current time in seconds. Supplying one lets a test place
+     * records without waiting. Defaults to `time()`.
+     */
+    timeSource?: () => number;
+}
+/**
+ * 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 declare class ServiceMetricsObserver extends BaseObserver {
+    protected _now: () => number;
+    constructor(options?: ServiceMetricsObserverOptions);
+    /**
+     * 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.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _asLatency(metrics: MetricsData): ServiceLatencyRecord | 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.
+     */
+    protected _asUsage(metrics: MetricsData): ServiceUsageRecord | null;
+}
+//# sourceMappingURL=service_metrics_observer.d.ts.map