dv-pipecat-ai 0.0.74.dev770__py3-none-any.whl → 0.0.82.dev776__py3-none-any.whl

pipecat/metrics/metrics.py

@@ -1,39 +1,102 @@
+#
+# Copyright (c) 2024–2025, 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 typing import Optional
 
 from pydantic import BaseModel
 
 
 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: Optional[str] = None
 
 
 class TTFBMetricsData(MetricsData):
+    """Time To First Byte (TTFB) metrics data.
+
+    Parameters:
+        value: TTFB measurement in seconds.
+    """
+
     value: float
 
 
 class ProcessingMetricsData(MetricsData):
+    """General processing time metrics data.
+
+    Parameters:
+        value: Processing time measurement in seconds.
+    """
+
     value: float
 
 
 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.
+    """
+
     prompt_tokens: int
     completion_tokens: int
     total_tokens: int
     cache_read_input_tokens: Optional[int] = None
     cache_creation_input_tokens: Optional[int] = None
+    reasoning_tokens: Optional[int] = None
 
 
 class LLMUsageMetricsData(MetricsData):
+    """LLM token usage metrics data.
+
+    Parameters:
+        value: Token usage statistics for the LLM operation.
+    """
+
     value: LLMTokenUsage
 
 
 class TTSUsageMetricsData(MetricsData):
+    """Text-to-Speech usage metrics data.
+
+    Parameters:
+        value: Number of characters processed by TTS.
+    """
+
     value: int
 
 
 class SmartTurnMetricsData(MetricsData):
-    """Metrics data for smart turn predictions."""
+    """Metrics data for smart turn predictions.
+
+    Parameters:
+        is_complete: Whether the turn is predicted to be complete.
+        probability: Confidence probability of the turn completion prediction.
+        inference_time_ms: Time taken for inference in milliseconds.
+        server_total_time_ms: Total server processing time in milliseconds.
+        e2e_processing_time_ms: End-to-end processing time in milliseconds.
+    """
 
     is_complete: bool
     probability: float

pipecat/observers/base_observer.py

@@ -4,7 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-from abc import abstractmethod
+"""Base observer classes for monitoring frame flow in the Pipecat pipeline.
+
+This module 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.
+"""
+
 from dataclasses import dataclass
 
 from typing_extensions import TYPE_CHECKING
@@ -17,22 +23,44 @@ if TYPE_CHECKING:
 
 
 @dataclass
-class FramePushed:
-    """Represents an event where a frame is pushed from one processor to another
-    within the pipeline.
+class FrameProcessed:
+    """Event data for frame processing in 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.
+    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.
 
-    Attributes:
-        source (FrameProcessor): The processor sending the frame.
-        destination (FrameProcessor): The processor receiving the frame.
-        frame (Frame): The frame being transferred.
-        direction (FrameDirection): The direction of the transfer (e.g., downstream or upstream).
-        timestamp (int): The time when the frame was pushed, based on the pipeline clock.
+    Parameters:
+        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.
 
     """
 
+    processor: "FrameProcessor"
+    frame: Frame
+    direction: "FrameDirection"
+    timestamp: int
+
+
+@dataclass
+class FramePushed:
+    """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.
+
+    Parameters:
+        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.
+    """
+
     source: "FrameProcessor"
     destination: "FrameProcessor"
     frame: Frame
@@ -41,14 +69,26 @@ class FramePushed:
 
 
 class BaseObserver(BaseObject):
-    """This is the base class for pipeline frame observers. Observers can view
-    all the frames that go through the pipeline without the need to inject
-    processors in the pipeline. This can be useful, for example, to implement
-    frame loggers or debuggers among other things.
+    """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.
     """
 
-    @abstractmethod
+    async def on_process_frame(self, data: FrameProcessed):
+        """Handle the event when a frame is being processed by a processor.
+
+        This method should be implemented by subclasses to define specific
+        behavior (e.g., logging, monitoring, debugging) when a frame is
+        being processed by a processor.
+
+        Args:
+            data: The event data containing details about the frame processing.
+        """
+        pass
+
     async def on_push_frame(self, data: FramePushed):
         """Handle the event when a frame is pushed from one processor to another.
 
@@ -57,7 +97,6 @@ class BaseObserver(BaseObject):
         transferred through the pipeline.
 
         Args:
-            data (FramePushed): The event data containing details about the frame transfer.
-
+            data: The event data containing details about the frame transfer.
         """
         pass

pipecat/observers/loggers/debug_log_observer.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""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.
+"""
+
 from dataclasses import fields, is_dataclass
 from enum import Enum, auto
 from typing import Dict, Optional, Set, Tuple, Type, Union
@@ -16,7 +23,12 @@ from pipecat.processors.frame_processor import FrameDirection
 
 
 class FrameEndpoint(Enum):
-    """Specifies which endpoint (source or destination) to filter on."""
+    """Specifies which endpoint (source or destination) to filter on.
+
+    Parameters:
+        SOURCE: Filter on the source component that is pushing the frame.
+        DESTINATION: Filter on the destination component receiving the frame.
+    """
 
     SOURCE = auto()
     DESTINATION = auto()
@@ -28,44 +40,37 @@ class DebugLogObserver(BaseObserver):
     Automatically extracts and formats data from any frame type, making it useful
     for debugging pipeline behavior without needing frame-specific observers.
 
-    Args:
-        frame_types: Optional tuple of frame types to log, or a dict with frame type
-            filters. If None, logs all frame types.
-        exclude_fields: Optional set of field names to exclude from logging.
-
     Examples:
-        Log all frames from all services:
-        ```python
-        observers = DebugLogObserver()
-        ```
-
-        Log specific frame types from any source/destination:
-        ```python
-        from pipecat.frames.frames import TranscriptionFrame, InterimTranscriptionFrame
-        observers=[
-            DebugLogObserver(frame_types=(LLMTextFrame,TranscriptionFrame,)),
-        ],
-        ```
-
-        Log frames with specific source/destination filters:
-        ```python
-        from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame
-        from pipecat.transports.base_output_transport import BaseOutputTransport
-        from pipecat.services.stt_service import STTService
-
-        observers=[
-            DebugLogObserver(
-                frame_types={
-                    # Only log StartInterruptionFrame when source is BaseOutputTransport
-                    StartInterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE),
-                    # Only log UserStartedSpeakingFrame when destination is STTService
-                    UserStartedSpeakingFrame: (STTService, FrameEndpoint.DESTINATION),
-                    # Log LLMTextFrame regardless of source or destination type
-                    LLMTextFrame: None,
-                }
-            ),
-        ],
-        ```
+        Log all frames from all services::
+
+            observers = DebugLogObserver()
+
+        Log specific frame types from any source/destination::
+
+            from pipecat.frames.frames import LLMTextFrame, TranscriptionFrame
+            observers=[
+                DebugLogObserver(frame_types=(LLMTextFrame,TranscriptionFrame,)),
+            ]
+
+        Log frames with specific source/destination filters::
+
+            from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame
+            from pipecat.observers.loggers.debug_log_observer import DebugLogObserver, FrameEndpoint
+            from pipecat.transports.base_output import BaseOutputTransport
+            from pipecat.services.stt_service import STTService
+
+            observers=[
+                DebugLogObserver(
+                    frame_types={
+                        # Only log StartInterruptionFrame when source is BaseOutputTransport
+                        StartInterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE),
+                        # Only log UserStartedSpeakingFrame when destination is STTService
+                        UserStartedSpeakingFrame: (STTService, FrameEndpoint.DESTINATION),
+                        # Log LLMTextFrame regardless of source or destination type
+                        LLMTextFrame: None,
+                    }
+                ),
+            ]
     """
 
     def __init__(
@@ -79,14 +84,17 @@ class DebugLogObserver(BaseObserver):
         """Initialize the debug log observer.
 
         Args:
-            frame_types: Tuple of frame types to log, or a dict mapping frame types to
-                filter configurations. Filter configs can be:
-                - None to log all instances of the frame type
-                - A tuple of (service_type, endpoint) to filter on a specific service
-                  and endpoint (SOURCE or DESTINATION)
-                If None is provided instead of a tuple/dict, log all frames.
-            exclude_fields: Set of field names to exclude from logging. If None, only binary
-                data fields are excluded.
+            frame_types: Frame types to log. Can be:
+
+                - Tuple of frame types to log all instances
+                - Dict mapping frame types to filter configurations
+                - None to log all frames
+
+                Filter configurations can be None (log all instances) or a tuple
+                of (service_type, endpoint) to filter on specific services.
+            exclude_fields: Field names to exclude from logging. Defaults to
+                excluding binary data fields like 'audio', 'image', 'images'.
+            **kwargs: Additional arguments passed to parent class.
         """
         super().__init__(**kwargs)
 
@@ -113,14 +121,7 @@ class DebugLogObserver(BaseObserver):
         )
 
     def _format_value(self, value):
-        """Format a value for logging.
-
-        Args:
-            value: The value to format.
-
-        Returns:
-            str: A string representation of the value suitable for logging.
-        """
+        """Format a value for logging."""
         if value is None:
             return "None"
         elif isinstance(value, str):
@@ -143,16 +144,7 @@ class DebugLogObserver(BaseObserver):
             return str(value)
 
     def _should_log_frame(self, frame, src, dst):
-        """Determine if a frame should be logged based on filters.
-
-        Args:
-            frame: The frame being processed
-            src: The source component
-            dst: The destination component
-
-        Returns:
-            bool: True if the frame should be logged, False otherwise
-        """
+        """Determine if a frame should be logged based on filters."""
         # If no filters, log all frames
         if not self.frame_filters:
             return True

pipecat/observers/loggers/llm_log_observer.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""LLM logging observer for Pipecat."""
+
 from loguru import logger
 
 from pipecat.frames.frames import (
@@ -34,10 +36,15 @@ class LLMLogObserver(BaseObserver):
 
     This allows you to track when the LLM starts responding, what it generates,
     and when it finishes.
-
     """
 
     async def on_push_frame(self, data: FramePushed):
+        """Handle frame push events and log LLM-related activities.
+
+        Args:
+            data: The frame push event data containing source, destination,
+                  frame, direction, and timestamp information.
+        """
         src = data.source
         dst = data.destination
         frame = data.frame

pipecat/observers/loggers/transcription_log_observer.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""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.
+"""
+
 from loguru import logger
 
 from pipecat.frames.frames import (
@@ -17,17 +23,23 @@ from pipecat.services.stt_service import STTService
 class TranscriptionLogObserver(BaseObserver):
     """Observer to log transcription activity to the console.
 
-    Logs all frame instances (only from STT service) of:
-
-    - TranscriptionFrame
-    - InterimTranscriptionFrame
-
-    This allows you to track when the LLM starts responding, what it generates,
-    and when it finishes.
+    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.
     """
 
     async def on_push_frame(self, data: FramePushed):
+        """Handle frame push events and log transcription frames.
+
+        Logs TranscriptionFrame and InterimTranscriptionFrame instances
+        with timestamps and user information for debugging purposes.
+
+        Args:
+            data: Frame push event data containing source, frame, and timestamp.
+        """
         src = data.source
         frame = data.frame
         timestamp = data.timestamp

pipecat/observers/loggers/user_bot_latency_log_observer.py

@@ -4,12 +4,17 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Observer for measuring user-to-bot response latency."""
+
 import time
+from statistics import mean
 
 from loguru import logger
 
 from pipecat.frames.frames import (
     BotStartedSpeakingFrame,
+    CancelFrame,
+    EndFrame,
     UserStartedSpeakingFrame,
     UserStoppedSpeakingFrame,
 )
@@ -18,19 +23,29 @@ from pipecat.processors.frame_processor import FrameDirection
 
 
 class UserBotLatencyLogObserver(BaseObserver):
-    """Observer that logs the latency between when the user stops speaking and
-    when the bot starts speaking.
-
-    This helps measure how quickly the AI services respond.
+    """Observer that measures time between user stopping speech and bot starting speech.
 
+    This helps measure how quickly the AI services respond by tracking
+    conversation turn timing and logging latency metrics.
     """
 
     def __init__(self):
+        """Initialize the latency observer.
+
+        Sets up tracking for processed frames and user speech timing
+        to calculate response latencies.
+        """
         super().__init__()
         self._processed_frames = set()
         self._user_stopped_time = 0
+        self._latencies = []
 
     async def on_push_frame(self, data: FramePushed):
+        """Process frames to track speech timing and calculate latency.
+
+        Args:
+            data: Frame push event containing the frame and direction information.
+        """
         # Only process downstream frames
         if data.direction != FrameDirection.DOWNSTREAM:
             return
@@ -45,6 +60,18 @@ class UserBotLatencyLogObserver(BaseObserver):
             self._user_stopped_time = 0
         elif isinstance(data.frame, UserStoppedSpeakingFrame):
             self._user_stopped_time = time.time()
+        elif isinstance(data.frame, (EndFrame, CancelFrame)):
+            if self._latencies:
+                avg_latency = mean(self._latencies)
+                min_latency = min(self._latencies)
+                max_latency = max(self._latencies)
+                logger.info(
+                    f"⏱️ LATENCY FROM USER STOPPED SPEAKING TO BOT STARTED SPEAKING - Avg: {avg_latency:.3f}s, Min: {min_latency:.3f}s, Max: {max_latency:.3f}s"
+                )
         elif isinstance(data.frame, BotStartedSpeakingFrame) and self._user_stopped_time:
             latency = time.time() - self._user_stopped_time
-            logger.debug(f"⏱️ LATENCY FROM USER STOPPED SPEAKING TO BOT STARTED SPEAKING: {latency}")
+            self._user_stopped_time = 0
+            self._latencies.append(latency)
+            logger.debug(
+                f"⏱️ LATENCY FROM USER STOPPED SPEAKING TO BOT STARTED SPEAKING: {latency:.3f}s"
+            )

pipecat/observers/turn_tracking_observer.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Turn tracking observer for conversation flow monitoring.
+
+This module provides an observer that monitors conversation turns in a pipeline,
+tracking when turns start and end based on user and bot speech patterns.
+"""
+
 import asyncio
 from collections import deque
 
@@ -23,15 +29,30 @@ from pipecat.observers.base_observer import BaseObserver, FramePushed
 class TurnTrackingObserver(BaseObserver):
     """Observer that tracks conversation turns in a pipeline.
 
+    This observer monitors the flow of conversation by tracking when turns
+    start and end based on user and bot speaking patterns. It handles
+    interruptions, timeouts, and maintains turn state throughout the pipeline.
+
     Turn tracking logic:
+
     - The first turn starts immediately when the pipeline starts (StartFrame)
     - Subsequent turns start when the user starts speaking
     - A turn ends when the bot stops speaking and either:
+
       - The user starts speaking again
       - A timeout period elapses with no more bot speech
     """
 
     def __init__(self, max_frames=100, turn_end_timeout_secs=2.5, **kwargs):
+        """Initialize the turn tracking observer.
+
+        Args:
+            max_frames: Maximum number of frame IDs to keep in history for
+                duplicate detection. Defaults to 100.
+            turn_end_timeout_secs: Timeout in seconds after bot stops speaking
+                before automatically ending the turn. Defaults to 2.5.
+            **kwargs: Additional arguments passed to the parent observer.
+        """
         super().__init__(**kwargs)
         self._turn_count = 0
         self._is_turn_active = False
@@ -49,7 +70,11 @@ class TurnTrackingObserver(BaseObserver):
         self._register_event_handler("on_turn_ended")
 
     async def on_push_frame(self, data: FramePushed):
-        """Process frame events for turn tracking."""
+        """Process frame events for turn tracking.
+
+        Args:
+            data: Frame push event data containing the frame and metadata.
+        """
         # Skip already processed frames
         if data.frame.id in self._processed_frames:
             return

pipecat/pipeline/base_pipeline.py

@@ -4,16 +4,14 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-from abc import abstractmethod
-from typing import List
+"""Base pipeline implementation for frame processing."""
 
 from pipecat.processors.frame_processor import FrameProcessor
 
 
 class BasePipeline(FrameProcessor):
-    def __init__(self):
-        super().__init__()
+    """Base class for all pipeline implementations."""
 
-    @abstractmethod
-    def processors_with_metrics(self) -> List[FrameProcessor]:
-        pass
+    def __init__(self, **kwargs):
+        """Initialize the base pipeline."""
+        super().__init__(**kwargs)