#
# Copyright (c) 2024-2026, Daily
#
# SPDX-License-Identifier: BSD 2-Clause License
#
"""Metrics data models for Pipecat framework.
This module defines Pydantic models for various types of metrics data
collected throughout the pipeline, including timing, token usage, and
processing statistics.
"""
from pydantic import BaseModel
from pipecat.utils.deprecation import deprecated
[docs]
class MetricsData(BaseModel):
"""Base class for all metrics data.
Parameters:
processor: Name of the processor generating the metrics.
model: Optional model name associated with the metrics.
"""
processor: str
model: str | None = None
[docs]
class TTFBMetricsData(MetricsData):
"""Time To First Byte (TTFB) metrics data.
Parameters:
value: TTFB measurement in seconds.
"""
value: float
[docs]
class TTFAMetricsData(MetricsData):
"""Time To First Audio (TTFA) metrics data.
Measures the time from a TTS request to the first audible audio sample,
i.e. time-to-first-byte plus any leading silence the service pads onto the
start of its response. ``ttfa`` is reported with its breakdown so consumers
can see how much of the perceived latency is silence padding rather than
service response time, without correlating a separate ``TTFBMetricsData``.
Parameters:
ttfa: TTFA measurement in seconds (``ttfb`` plus ``leading_silence``).
ttfb: Time-to-first-byte that TTFA builds on, in seconds. This mirrors
the standalone ``TTFBMetricsData`` (emitted earlier) for convenience;
it is not a separate measurement, so don't aggregate both.
leading_silence: Silence padding before the first audible sample, in
seconds (``ttfa`` minus ``ttfb``).
"""
ttfa: float
ttfb: float
leading_silence: float
[docs]
class ProcessingMetricsData(MetricsData):
"""General processing time metrics data.
Parameters:
value: Processing time measurement in seconds.
"""
value: float
[docs]
class LLMTokenUsage(BaseModel):
"""Token usage statistics for LLM operations.
Parameters:
prompt_tokens: Number of tokens in the input prompt.
completion_tokens: Number of tokens in the generated completion.
total_tokens: Total number of tokens used (prompt + completion).
cache_read_input_tokens: Number of tokens read from cache, if applicable.
cache_creation_input_tokens: Number of tokens used to create cache entries, if applicable.
reasoning_tokens: Number of completion tokens used for reasoning, if applicable.
input_audio_tokens: Number of prompt tokens that were audio, if applicable.
output_audio_tokens: Number of completion tokens that were audio, if applicable.
cache_read_input_audio_tokens: Number of cache-read tokens that were audio, if applicable.
"""
prompt_tokens: int
completion_tokens: int
total_tokens: int
cache_read_input_tokens: int | None = None
cache_creation_input_tokens: int | None = None
reasoning_tokens: int | None = None
input_audio_tokens: int | None = None
output_audio_tokens: int | None = None
cache_read_input_audio_tokens: int | None = None
[docs]
class LLMUsageMetricsData(MetricsData):
"""LLM token usage metrics data.
Parameters:
value: Token usage statistics for the LLM operation.
"""
value: LLMTokenUsage
[docs]
class TTSUsageMetricsData(MetricsData):
"""Text-to-Speech usage metrics data.
Parameters:
value: Number of characters processed by TTS.
"""
value: int
[docs]
class TextAggregationMetricsData(MetricsData):
"""Text aggregation time metrics data.
Measures the time from the first LLM token to the first complete sentence,
representing the latency cost of sentence aggregation in the TTS pipeline.
Parameters:
value: Aggregation time in seconds.
"""
value: float
[docs]
class TurnMetricsData(MetricsData):
"""Metrics data for turn detection predictions.
Parameters:
is_complete: Whether the turn is predicted to be complete.
probability: Confidence probability of the turn completion prediction.
e2e_processing_time_ms: End-to-end processing time in milliseconds,
measured from VAD speech-to-silence transition to turn completion.
"""
is_complete: bool
probability: float
e2e_processing_time_ms: float
[docs]
@deprecated(
"`SmartTurnMetricsData` is deprecated since 0.0.104 and will be removed in 2.0.0. "
"Use `TurnMetricsData` instead."
)
class SmartTurnMetricsData(TurnMetricsData):
"""Metrics data for smart turn predictions.
.. deprecated:: 0.0.104
Use :class:`TurnMetricsData` instead. Will be removed in 2.0.0.
Parameters:
inference_time_ms: Time taken for inference in milliseconds.
server_total_time_ms: Total server processing time in milliseconds.
"""
inference_time_ms: float = 0.0
server_total_time_ms: float = 0.0