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

pipecat/processors/gstreamer/pipeline_source.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""GStreamer pipeline source integration for Pipecat."""
+
 import asyncio
 from typing import Optional
 
@@ -36,7 +38,24 @@ except ModuleNotFoundError as e:
 
 
 class GStreamerPipelineSource(FrameProcessor):
+    """A frame processor that uses GStreamer pipelines as media sources.
+
+    This processor creates and manages GStreamer pipelines to generate audio and video
+    output frames. It handles pipeline lifecycle, decoding, format conversion, and
+    frame generation with configurable output parameters.
+    """
+
     class OutputParams(BaseModel):
+        """Output configuration parameters for GStreamer pipeline.
+
+        Parameters:
+            video_width: Width of output video frames in pixels.
+            video_height: Height of output video frames in pixels.
+            audio_sample_rate: Sample rate for audio output. If None, uses frame sample rate.
+            audio_channels: Number of audio channels for output.
+            clock_sync: Whether to synchronize output with pipeline clock.
+        """
+
         video_width: int = 1280
         video_height: int = 720
         audio_sample_rate: Optional[int] = None
@@ -44,6 +63,13 @@ class GStreamerPipelineSource(FrameProcessor):
         clock_sync: bool = True
 
     def __init__(self, *, pipeline: str, out_params: Optional[OutputParams] = None, **kwargs):
+        """Initialize the GStreamer pipeline source.
+
+        Args:
+            pipeline: GStreamer pipeline description string for the source.
+            out_params: Output configuration parameters. If None, uses defaults.
+            **kwargs: Additional arguments passed to parent FrameProcessor.
+        """
         super().__init__(**kwargs)
 
         self._out_params = out_params or GStreamerPipelineSource.OutputParams()
@@ -67,6 +93,12 @@ class GStreamerPipelineSource(FrameProcessor):
         bus.connect("message", self._on_gstreamer_message)
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and manage GStreamer pipeline lifecycle.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame processing.
+        """
         await super().process_frame(frame, direction)
 
         # Specific system frames
@@ -92,13 +124,16 @@ class GStreamerPipelineSource(FrameProcessor):
             await self.push_frame(frame, direction)
 
     async def _start(self, frame: StartFrame):
+        """Start the GStreamer pipeline."""
         self._sample_rate = self._out_params.audio_sample_rate or frame.audio_out_sample_rate
         self._player.set_state(Gst.State.PLAYING)
 
     async def _stop(self, frame: EndFrame):
+        """Stop the GStreamer pipeline."""
         self._player.set_state(Gst.State.NULL)
 
     async def _cancel(self, frame: CancelFrame):
+        """Cancel the GStreamer pipeline."""
         self._player.set_state(Gst.State.NULL)
 
     #
@@ -106,6 +141,7 @@ class GStreamerPipelineSource(FrameProcessor):
     #
 
     def _on_gstreamer_message(self, bus: Gst.Bus, message: Gst.Message):
+        """Handle GStreamer bus messages."""
         t = message.type
         if t == Gst.MessageType.ERROR:
             err, debug = message.parse_error()
@@ -113,6 +149,7 @@ class GStreamerPipelineSource(FrameProcessor):
         return True
 
     def _decodebin_callback(self, decodebin: Gst.Element, pad: Gst.Pad):
+        """Handle new pads from decodebin element."""
         caps_string = pad.get_current_caps().to_string()
         if caps_string.startswith("audio"):
             self._decodebin_audio(pad)
@@ -120,6 +157,7 @@ class GStreamerPipelineSource(FrameProcessor):
             self._decodebin_video(pad)
 
     def _decodebin_audio(self, pad: Gst.Pad):
+        """Set up audio processing pipeline from decoded audio pad."""
         queue_audio = Gst.ElementFactory.make("queue", None)
         audioconvert = Gst.ElementFactory.make("audioconvert", None)
         audioresample = Gst.ElementFactory.make("audioresample", None)
@@ -153,6 +191,7 @@ class GStreamerPipelineSource(FrameProcessor):
         pad.link(queue_pad)
 
     def _decodebin_video(self, pad: Gst.Pad):
+        """Set up video processing pipeline from decoded video pad."""
         queue_video = Gst.ElementFactory.make("queue", None)
         videoconvert = Gst.ElementFactory.make("videoconvert", None)
         videoscale = Gst.ElementFactory.make("videoscale", None)
@@ -187,6 +226,7 @@ class GStreamerPipelineSource(FrameProcessor):
         pad.link(queue_pad)
 
     def _appsink_audio_new_sample(self, appsink: GstApp.AppSink):
+        """Handle new audio samples from GStreamer appsink."""
         buffer = appsink.pull_sample().get_buffer()
         (_, info) = buffer.map(Gst.MapFlags.READ)
         frame = OutputAudioRawFrame(
@@ -199,6 +239,7 @@ class GStreamerPipelineSource(FrameProcessor):
         return Gst.FlowReturn.OK
 
     def _appsink_video_new_sample(self, appsink: GstApp.AppSink):
+        """Handle new video samples from GStreamer appsink."""
         buffer = appsink.pull_sample().get_buffer()
         (_, info) = buffer.map(Gst.MapFlags.READ)
         frame = OutputImageRawFrame(

pipecat/processors/idle_frame_processor.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Idle frame processor for timeout-based callback execution."""
+
 import asyncio
 from typing import Awaitable, Callable, List, Optional
 
@@ -12,9 +14,11 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class IdleFrameProcessor(FrameProcessor):
-    """This class waits to receive any frame or list of desired frames within a
-    given timeout. If the timeout is reached before receiving any of those
-    frames the provided callback will be called.
+    """Monitors frame activity and triggers callbacks on timeout.
+
+    This processor waits to receive any frame or specific frame types within a
+    given timeout period. If the timeout is reached before receiving the expected
+    frames, the provided callback will be executed.
     """
 
     def __init__(
@@ -25,6 +29,16 @@ class IdleFrameProcessor(FrameProcessor):
         types: Optional[List[type]] = None,
         **kwargs,
     ):
+        """Initialize the idle frame processor.
+
+        Args:
+            callback: Async callback function to execute on timeout. Receives
+                this processor instance as an argument.
+            timeout: Timeout duration in seconds before triggering the callback.
+            types: Optional list of frame types to monitor. If None, monitors
+                all frames.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
 
         self._callback = callback
@@ -33,6 +47,12 @@ class IdleFrameProcessor(FrameProcessor):
         self._idle_task = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and manage idle timeout monitoring.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, StartFrame):
@@ -50,15 +70,18 @@ class IdleFrameProcessor(FrameProcessor):
                     self._idle_event.set()
 
     async def cleanup(self):
+        """Clean up resources and cancel pending tasks."""
         if self._idle_task:
             await self.cancel_task(self._idle_task)
 
     def _create_idle_task(self):
+        """Create and start the idle monitoring task."""
         if not self._idle_task:
             self._idle_event = asyncio.Event()
             self._idle_task = self.create_task(self._idle_task_handler())
 
     async def _idle_task_handler(self):
+        """Handle idle timeout monitoring and callback execution."""
         while True:
             try:
                 await asyncio.wait_for(self._idle_event.wait(), timeout=self._timeout)

pipecat/processors/logger.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Frame logging utilities for debugging and monitoring frame flow in Pipecat pipelines."""
+
 from typing import Optional, Tuple, Type
 
 from loguru import logger
@@ -21,6 +23,13 @@ logger = logger.opt(ansi=True)
 
 
 class FrameLogger(FrameProcessor):
+    """A frame processor that logs frame information for debugging purposes.
+
+    This processor intercepts frames passing through the pipeline and logs
+    their details with configurable formatting and filtering. Useful for
+    debugging frame flow and understanding pipeline behavior.
+    """
+
     def __init__(
         self,
         prefix="Frame",
@@ -32,12 +41,26 @@ class FrameLogger(FrameProcessor):
             TransportMessageFrame,
         ),
     ):
+        """Initialize the frame logger.
+
+        Args:
+            prefix: Text prefix to add to log messages. Defaults to "Frame".
+            color: ANSI color code for log message formatting. If None, no coloring is applied.
+            ignored_frame_types: Tuple of frame types to exclude from logging.
+                Defaults to common high-frequency frames like audio and speaking frames.
+        """
         super().__init__()
         self._prefix = prefix
         self._color = color
         self._ignored_frame_types = ignored_frame_types
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process and log frame information.
+
+        Args:
+            frame: The frame to process and potentially log.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if self._ignored_frame_types and not isinstance(frame, self._ignored_frame_types):

pipecat/processors/metrics/frame_processor_metrics.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Frame processor metrics collection and reporting."""
+
 import time
 from typing import Optional
 
@@ -23,7 +25,20 @@ from pipecat.utils.base_object import BaseObject
 
 
 class FrameProcessorMetrics(BaseObject):
+    """Metrics collection and reporting for frame processors.
+
+    Provides comprehensive metrics tracking for frame processing operations,
+    including timing measurements, resource usage, and performance analytics.
+    Supports TTFB tracking, processing duration metrics, and usage statistics
+    for LLM and TTS operations.
+    """
+
     def __init__(self):
+        """Initialize the frame processor metrics collector.
+
+        Sets up internal state for tracking various metrics including TTFB,
+        processing times, and usage statistics.
+        """
         super().__init__()
         self._task_manager = None
         self._start_ttfb_time = 0
@@ -33,13 +48,24 @@ class FrameProcessorMetrics(BaseObject):
         self._logger = logger
 
     async def setup(self, task_manager: BaseTaskManager):
+        """Set up the metrics collector with a task manager.
+
+        Args:
+            task_manager: The task manager for handling async operations.
+        """
         self._task_manager = task_manager
 
     async def cleanup(self):
+        """Clean up metrics collection resources."""
         await super().cleanup()
 
     @property
     def task_manager(self) -> BaseTaskManager:
+        """Get the associated task manager.
+
+        Returns:
+            The task manager instance for async operations.
+        """
         return self._task_manager
 
     @property
@@ -47,7 +73,7 @@ class FrameProcessorMetrics(BaseObject):
         """Get the current TTFB value in seconds.
 
         Returns:
-            Optional[float]: The TTFB value in seconds, or None if not measured
+            The TTFB value in seconds, or None if not measured.
         """
         if self._last_ttfb_time > 0:
             return self._last_ttfb_time
@@ -59,9 +85,11 @@ class FrameProcessorMetrics(BaseObject):
         return None
 
     def _processor_name(self):
+        """Get the processor name from core metrics data."""
         return self._core_metrics_data.processor
 
     def _model_name(self):
+        """Get the model name from core metrics data."""
         return self._core_metrics_data.model
 
     def set_logger(self, logger_instance):
@@ -69,18 +97,38 @@ class FrameProcessorMetrics(BaseObject):
         self._logger = logger_instance
 
     def set_core_metrics_data(self, data: MetricsData):
+        """Set the core metrics data for this collector.
+
+        Args:
+            data: The core metrics data containing processor and model information.
+        """
         self._core_metrics_data = data
 
     def set_processor_name(self, name: str):
+        """Set the processor name for metrics reporting.
+
+        Args:
+            name: The name of the processor to use in metrics.
+        """
         self._core_metrics_data = MetricsData(processor=name)
 
     async def start_ttfb_metrics(self, report_only_initial_ttfb):
+        """Start measuring time-to-first-byte (TTFB).
+
+        Args:
+            report_only_initial_ttfb: Whether to report only the first TTFB measurement.
+        """
         if self._should_report_ttfb:
             self._start_ttfb_time = time.time()
             self._last_ttfb_time = 0
             self._should_report_ttfb = not report_only_initial_ttfb
 
     async def stop_ttfb_metrics(self):
+        """Stop TTFB measurement and generate metrics frame.
+
+        Returns:
+            MetricsFrame containing TTFB data, or None if not measuring.
+        """
         if self._start_ttfb_time == 0:
             return None
 
@@ -93,9 +141,15 @@ class FrameProcessorMetrics(BaseObject):
         return MetricsFrame(data=[ttfb])
 
     async def start_processing_metrics(self):
+        """Start measuring processing time."""
         self._start_processing_time = time.time()
 
     async def stop_processing_metrics(self):
+        """Stop processing time measurement and generate metrics frame.
+
+        Returns:
+            MetricsFrame containing processing duration data, or None if not measuring.
+        """
         if self._start_processing_time == 0:
             return None
 
@@ -108,15 +162,34 @@ class FrameProcessorMetrics(BaseObject):
         return MetricsFrame(data=[processing])
 
     async def start_llm_usage_metrics(self, tokens: LLMTokenUsage):
-        self._logger.debug(
-            f"{self._processor_name()} prompt tokens: {tokens.prompt_tokens}, completion tokens: {tokens.completion_tokens}"
-        )
+        """Record LLM token usage metrics.
+
+        Args:
+            tokens: Token usage information including prompt and completion tokens.
+
+        Returns:
+            MetricsFrame containing LLM usage data.
+        """
+        logstr = f"{self._processor_name()} prompt tokens: {tokens.prompt_tokens}, completion tokens: {tokens.completion_tokens}"
+        if tokens.cache_read_input_tokens:
+            logstr += f", cache read input tokens: {tokens.cache_read_input_tokens}"
+        if tokens.reasoning_tokens:
+            logstr += f", reasoning tokens: {tokens.reasoning_tokens}"
+        self._logger.debug(logstr)
         value = LLMUsageMetricsData(
             processor=self._processor_name(), model=self._model_name(), value=tokens
         )
         return MetricsFrame(data=[value])
 
     async def start_tts_usage_metrics(self, text: str):
+        """Record TTS character usage metrics.
+
+        Args:
+            text: The text being processed by TTS.
+
+        Returns:
+            MetricsFrame containing TTS usage data.
+        """
         characters = TTSUsageMetricsData(
             processor=self._processor_name(), model=self._model_name(), value=len(text)
         )

pipecat/processors/metrics/sentry.py

@@ -4,12 +4,11 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-import asyncio
+"""Sentry integration for frame processor metrics."""
 
 from loguru import logger
 
 from pipecat.utils.asyncio.task_manager import BaseTaskManager
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 try:
     import sentry_sdk
@@ -22,7 +21,19 @@ from pipecat.processors.metrics.frame_processor_metrics import FrameProcessorMet
 
 
 class SentryMetrics(FrameProcessorMetrics):
+    """Frame processor metrics integration with Sentry monitoring.
+
+    Extends FrameProcessorMetrics to send time-to-first-byte (TTFB) and
+    processing metrics as Sentry transactions for performance monitoring
+    and debugging.
+    """
+
     def __init__(self):
+        """Initialize the Sentry metrics collector.
+
+        Sets up internal state for tracking transactions and verifies
+        Sentry SDK initialization status.
+        """
         super().__init__()
         self._ttfb_metrics_tx = None
         self._processing_metrics_tx = None
@@ -32,23 +43,37 @@ class SentryMetrics(FrameProcessorMetrics):
         self._sentry_task = None
 
     async def setup(self, task_manager: BaseTaskManager):
+        """Setup the Sentry metrics system.
+
+        Args:
+            task_manager: The task manager to use for background operations.
+        """
         await super().setup(task_manager)
         if self._sentry_available:
-            self._sentry_queue = WatchdogQueue(task_manager)
+            self._sentry_queue = asyncio.Queue()
             self._sentry_task = self.task_manager.create_task(
                 self._sentry_task_handler(), name=f"{self}::_sentry_task_handler"
             )
 
     async def cleanup(self):
+        """Clean up Sentry resources and flush pending transactions.
+
+        Ensures all pending transactions are sent to Sentry before shutdown.
+        """
         await super().cleanup()
         if self._sentry_task:
             await self._sentry_queue.put(None)
-            await self.task_manager.wait_for_task(self._sentry_task)
+            await self._sentry_task
             self._sentry_task = None
             logger.trace(f"{self} Flushing Sentry metrics")
             sentry_sdk.flush(timeout=5.0)
 
     async def start_ttfb_metrics(self, report_only_initial_ttfb):
+        """Start tracking time-to-first-byte metrics.
+
+        Args:
+            report_only_initial_ttfb: Whether to report only the initial TTFB measurement.
+        """
         await super().start_ttfb_metrics(report_only_initial_ttfb)
 
         if self._should_report_ttfb and self._sentry_available:
@@ -61,6 +86,10 @@ class SentryMetrics(FrameProcessorMetrics):
             )
 
     async def stop_ttfb_metrics(self):
+        """Stop tracking time-to-first-byte metrics.
+
+        Queues the TTFB transaction for completion and transmission to Sentry.
+        """
         await super().stop_ttfb_metrics()
 
         if self._sentry_available and self._ttfb_metrics_tx:
@@ -68,6 +97,10 @@ class SentryMetrics(FrameProcessorMetrics):
             self._ttfb_metrics_tx = None
 
     async def start_processing_metrics(self):
+        """Start tracking frame processing metrics.
+
+        Creates a new Sentry transaction to track processing performance.
+        """
         await super().start_processing_metrics()
 
         if self._sentry_available:
@@ -80,6 +113,10 @@ class SentryMetrics(FrameProcessorMetrics):
             )
 
     async def stop_processing_metrics(self):
+        """Stop tracking frame processing metrics.
+
+        Queues the processing transaction for completion and transmission to Sentry.
+        """
         await super().stop_processing_metrics()
 
         if self._sentry_available and self._processing_metrics_tx:
@@ -87,6 +124,7 @@ class SentryMetrics(FrameProcessorMetrics):
             self._processing_metrics_tx = None
 
     async def _sentry_task_handler(self):
+        """Background task handler for completing Sentry transactions."""
         running = True
         while running:
             tx = await self._sentry_queue.get()

pipecat/processors/producer_processor.py

@@ -4,24 +4,34 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Producer processor for frame filtering and distribution."""
+
 import asyncio
 from typing import Awaitable, Callable, List
 
 from pipecat.frames.frames import Frame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 
 async def identity_transformer(frame: Frame):
+    """Default transformer that returns the frame unchanged.
+
+    Args:
+        frame: The frame to transform.
+
+    Returns:
+        The same frame without modifications.
+    """
     return frame
 
 
 class ProducerProcessor(FrameProcessor):
-    """This class optionally passes-through received frames and decides if those
-    frames should be sent to consumers based on a user-defined filter. The
-    frames can be transformed into a different type of frame before being
-    sending them to the consumers. More than one consumer can be added.
+    """A processor that filters frames and distributes them to multiple consumers.
 
+    This processor receives frames, applies a filter to determine which frames
+    should be sent to consumers (ConsumerProcessor), optionally transforms those
+    frames, and distributes them to registered consumer queues. It can also pass
+    frames through to the next processor in the pipeline.
     """
 
     def __init__(
@@ -31,6 +41,16 @@ class ProducerProcessor(FrameProcessor):
         transformer: Callable[[Frame], Awaitable[Frame]] = identity_transformer,
         passthrough: bool = True,
     ):
+        """Initialize the producer processor.
+
+        Args:
+            filter: Async function that determines if a frame should be produced.
+                   Must return True for frames to be sent to consumers.
+            transformer: Async function to transform frames before sending to consumers.
+                        Defaults to identity_transformer which returns frames unchanged.
+            passthrough: Whether to pass frames through to the next processor.
+                        If True, all frames continue downstream regardless of filter result.
+        """
         super().__init__()
         self._filter = filter
         self._transformer = transformer
@@ -38,26 +58,25 @@ class ProducerProcessor(FrameProcessor):
         self._consumers: List[asyncio.Queue] = []
 
     def add_consumer(self):
-        """
-        Adds a new consumer and returns its associated queue.
+        """Add a new consumer and return its associated queue.
 
         Returns:
             asyncio.Queue: The queue for the newly added consumer.
         """
-        queue = WatchdogQueue(self.task_manager)
+        queue = asyncio.Queue()
         self._consumers.append(queue)
         return queue
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
-        """
-        Processes an incoming frame and determines whether to produce it as a ProducerItem.
+        """Process an incoming frame and determine whether to produce it.
 
-        If the frame meets the produce criteria, it will be added to the consumer queues.
-        If passthrough is enabled, the frame will also be sent to consumers.
+        If the frame meets the filter criteria, it will be transformed and added
+        to all consumer queues. If passthrough is enabled, the original frame
+        will also be sent downstream.
 
         Args:
-            frame (Frame): The frame to process.
-            direction (FrameDirection): The direction of the frame.
+            frame: The frame to process.
+            direction: The direction of the frame flow.
         """
         await super().process_frame(frame, direction)
 
@@ -69,6 +88,7 @@ class ProducerProcessor(FrameProcessor):
             await self.push_frame(frame, direction)
 
     async def _produce(self, frame: Frame):
+        """Produce a frame to all consumers."""
         for consumer in self._consumers:
             new_frame = await self._transformer(frame)
             await consumer.put(new_frame)

pipecat/processors/text_transformer.py

@@ -4,29 +4,41 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-from typing import Coroutine
+"""Stateless text transformation processor for Pipecat."""
+
+from typing import Callable, Coroutine, Union
 
 from pipecat.frames.frames import Frame, TextFrame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class StatelessTextTransformer(FrameProcessor):
-    """This processor calls the given function on any text in a text frame.
-
-    >>> async def print_frames(aggregator, frame):
-    ...     async for frame in aggregator.process_frame(frame):
-    ...         print(frame.text)
+    """Processor that applies transformation functions to text frames.
 
-    >>> aggregator = StatelessTextTransformer(lambda x: x.upper())
-    >>> asyncio.run(print_frames(aggregator, TextFrame("Hello")))
-    HELLO
+    This processor intercepts TextFrame objects and applies a user-provided
+    transformation function to the text content. The function can be either
+    synchronous or asynchronous (coroutine).
     """
 
-    def __init__(self, transform_fn):
+    def __init__(
+        self, transform_fn: Union[Callable[[str], str], Callable[[str], Coroutine[None, None, str]]]
+    ):
+        """Initialize the text transformer.
+
+        Args:
+            transform_fn: Function to apply to text content. Can be synchronous
+                (str -> str) or asynchronous (str -> Coroutine[None, None, str]).
+        """
         super().__init__()
         self._transform_fn = transform_fn
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames, applying transformation to text frames.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, TextFrame):