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

pipecat/pipeline/task_observer.py

@@ -4,22 +4,34 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Task observer for managing pipeline frame observers.
+
+This module provides a proxy observer system that manages multiple observers
+for pipeline frame events, ensuring that observer processing doesn't block
+the main pipeline execution.
+"""
+
 import asyncio
 import inspect
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 from attr import dataclass
 
-from pipecat.observers.base_observer import BaseObserver, FramePushed
+from pipecat.observers.base_observer import BaseObserver, FrameProcessed, FramePushed
 from pipecat.utils.asyncio.task_manager import BaseTaskManager
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 
 @dataclass
 class Proxy:
-    """This is the data we receive from the main observer and that we put into
-    a queue for later processing.
+    """Proxy data for managing observer tasks and queues.
+
+    This represents is the data received from the main observer that
+    is queued for later processing.
 
+    Parameters:
+        queue: Queue for frame data awaiting observer processing.
+        task: Asyncio task running the observer's frame processing loop.
+        observer: The actual observer instance being proxied.
     """
 
     queue: asyncio.Queue
@@ -28,7 +40,9 @@ class Proxy:
 
 
 class TaskObserver(BaseObserver):
-    """This is a pipeline frame observer that is meant to be used as a proxy to
+    """Proxy observer that manages multiple observers without blocking the pipeline.
+
+    This is a pipeline frame observer that is meant to be used as a proxy to
     the user provided observers. That is, this is the observer that should be
     passed to the frame processors. Then, every time a frame is pushed this
     observer will call all the observers registered to the pipeline task.
@@ -37,7 +51,6 @@ class TaskObserver(BaseObserver):
     pipeline by creating a queue and a task for each user observer. When a frame
     is received, it will be put in a queue for efficiency and later processed by
     each task.
-
     """
 
     def __init__(
@@ -47,6 +60,13 @@ class TaskObserver(BaseObserver):
         task_manager: BaseTaskManager,
         **kwargs,
     ):
+        """Initialize the TaskObserver.
+
+        Args:
+            observers: List of observers to manage. Defaults to empty list.
+            task_manager: Task manager for creating and managing observer tasks.
+            **kwargs: Additional arguments passed to the base observer.
+        """
         super().__init__(**kwargs)
         self._observers = observers or []
         self._task_manager = task_manager
@@ -55,18 +75,28 @@ class TaskObserver(BaseObserver):
         )
 
     def add_observer(self, observer: BaseObserver):
+        """Add a new observer to the managed list.
+
+        Args:
+            observer: The observer to add.
+        """
         # Add the observer to the list.
         self._observers.append(observer)
 
         # If we already started, create a new proxy for the observer.
         # Otherwise, it will be created in start().
-        if self._started():
+        if self._proxies:
             proxy = self._create_proxy(observer)
             self._proxies[observer] = proxy
 
     async def remove_observer(self, observer: BaseObserver):
+        """Remove an observer and clean up its resources.
+
+        Args:
+            observer: The observer to remove.
+        """
         # If the observer has a proxy, remove it.
-        if observer in self._proxies:
+        if self._proxies and observer in self._proxies:
             proxy = self._proxies[observer]
             # Remove the proxy so it doesn't get called anymore.
             del self._proxies[observer]
@@ -78,26 +108,36 @@ class TaskObserver(BaseObserver):
             self._observers.remove(observer)
 
     async def start(self):
-        """Starts all proxy observer tasks."""
+        """Start all proxy observer tasks."""
         self._proxies = self._create_proxies(self._observers)
 
     async def stop(self):
-        """Stops all proxy observer tasks."""
+        """Stop all proxy observer tasks."""
         if not self._proxies:
             return
 
         for proxy in self._proxies.values():
             await self._task_manager.cancel_task(proxy.task)
 
+    async def on_process_frame(self, data: FramePushed):
+        """Queue frame data for all managed observers.
+
+        Args:
+            data: The frame push event data to distribute to observers.
+        """
+        await self._send_to_proxy(data)
+
     async def on_push_frame(self, data: FramePushed):
-        for proxy in self._proxies.values():
-            await proxy.queue.put(data)
+        """Queue frame data for all managed observers.
 
-    def _started(self) -> bool:
-        return self._proxies is not None
+        Args:
+            data: The frame push event data to distribute to observers.
+        """
+        await self._send_to_proxy(data)
 
     def _create_proxy(self, observer: BaseObserver) -> Proxy:
-        queue = WatchdogQueue(self._task_manager)
+        """Create a proxy for a single observer."""
+        queue = asyncio.Queue()
         task = self._task_manager.create_task(
             self._proxy_task_handler(queue, observer),
             f"TaskObserver::{observer}::_proxy_task_handler",
@@ -106,33 +146,44 @@ class TaskObserver(BaseObserver):
         return proxy
 
     def _create_proxies(self, observers: List[BaseObserver]) -> Dict[BaseObserver, Proxy]:
+        """Create proxies for all observers."""
         proxies = {}
         for observer in observers:
             proxy = self._create_proxy(observer)
             proxies[observer] = proxy
         return proxies
 
+    async def _send_to_proxy(self, data: Any):
+        for proxy in self._proxies.values():
+            await proxy.queue.put(data)
+
     async def _proxy_task_handler(self, queue: asyncio.Queue, observer: BaseObserver):
-        warning_reported = False
+        """Handle frame processing for a single observer."""
+        on_push_frame_deprecated = False
+        signature = inspect.signature(observer.on_push_frame)
+        if len(signature.parameters) > 1:
+            import warnings
+
+            with warnings.catch_warnings():
+                warnings.simplefilter("always")
+                warnings.warn(
+                    "Observer `on_push_frame(source, destination, frame, direction, timestamp)` is deprecated, us `on_push_frame(data: FramePushed)` instead.",
+                    DeprecationWarning,
+                )
+
+            on_push_frame_deprecated = True
+
         while True:
             data = await queue.get()
 
-            signature = inspect.signature(observer.on_push_frame)
-            if len(signature.parameters) > 1:
-                if not warning_reported:
-                    import warnings
-
-                    with warnings.catch_warnings():
-                        warnings.simplefilter("always")
-                        warnings.warn(
-                            "Observer `on_push_frame(source, destination, frame, direction, timestamp)` is deprecated, us `on_push_frame(data: FramePushed)` instead.",
-                            DeprecationWarning,
-                        )
-                    warning_reported = True
-                await observer.on_push_frame(
-                    data.src, data.dst, data.frame, data.direction, data.timestamp
-                )
-            else:
-                await observer.on_push_frame(data)
+            if isinstance(data, FramePushed):
+                if on_push_frame_deprecated:
+                    await observer.on_push_frame(
+                        data.src, data.dst, data.frame, data.direction, data.timestamp
+                    )
+                else:
+                    await observer.on_push_frame(data)
+            elif isinstance(data, FrameProcessed):
+                await observer.on_process_frame(data)
 
             queue.task_done()

pipecat/pipeline/to_be_updated/merge_pipeline.py

@@ -1,3 +1,16 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Sequential pipeline merging for Pipecat.
+
+This module provides a pipeline implementation that sequentially merges
+the output from multiple pipelines, processing them one after another
+in a specified order.
+"""
+
 from typing import List
 
 from pipecat.frames.frames import EndFrame, EndPipeFrame
@@ -5,14 +18,31 @@ from pipecat.pipeline.pipeline import Pipeline
 
 
 class SequentialMergePipeline(Pipeline):
-    """This class merges the sink queues from a list of pipelines. Frames from
-    each pipeline's sink are merged in the order of pipelines in the list."""
+    """Pipeline that sequentially merges output from multiple pipelines.
+
+    This pipeline merges the sink queues from a list of pipelines by processing
+    frames from each pipeline's sink sequentially in the order specified. Each
+    pipeline runs to completion before the next one begins processing.
+    """
 
     def __init__(self, pipelines: List[Pipeline]):
+        """Initialize the sequential merge pipeline.
+
+        Args:
+            pipelines: List of pipelines to merge sequentially. Pipelines will
+                      be processed in the order they appear in this list.
+        """
         super().__init__([])
         self.pipelines = pipelines
 
     async def run_pipeline(self):
+        """Run all pipelines sequentially and merge their output.
+
+        Processes each pipeline in order, consuming all frames from each
+        pipeline's sink until an EndFrame or EndPipeFrame is encountered,
+        then moves to the next pipeline. After all pipelines complete,
+        sends a final EndFrame to signal completion.
+        """
         for idx, pipeline in enumerate(self.pipelines):
             while True:
                 frame = await pipeline.sink.get()

pipecat/processors/aggregators/dtmf_aggregator.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""DTMF aggregation processor for converting keypad input to transcription.
+
+This module provides a frame processor that aggregates DTMF (Dual-Tone Multi-Frequency)
+keypad inputs into meaningful sequences and converts them to transcription frames
+for downstream processing by LLM context aggregators.
+"""
+
 import asyncio
 from typing import Optional
 
@@ -17,7 +24,7 @@ from pipecat.frames.frames import (
     StartFrame,
     TranscriptionFrame,
 )
-from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, FrameProcessorSetup
 from pipecat.utils.time import time_now_iso8601
 
 
@@ -26,16 +33,12 @@ class DTMFAggregator(FrameProcessor):
 
     The aggregator accumulates digits from InputDTMFFrame instances and flushes
     when:
+
     - Timeout occurs (configurable idle period)
     - Termination digit is received (default: '#')
     - EndFrame or CancelFrame is received
 
     Emits TranscriptionFrame for compatibility with existing LLM context aggregators.
-
-    Args:
-        timeout: Idle timeout in seconds before flushing
-        termination_digit: Digit that triggers immediate flush
-        prefix: Prefix added to DTMF sequence in transcription
     """
 
     def __init__(
@@ -45,6 +48,14 @@ class DTMFAggregator(FrameProcessor):
         prefix: str = "DTMF: ",
         **kwargs,
     ):
+        """Initialize the DTMF aggregator.
+
+        Args:
+            timeout: Idle timeout in seconds before flushing
+            termination_digit: Digit that triggers immediate flush
+            prefix: Prefix added to DTMF sequence in transcription
+            **kwargs: Additional arguments passed to FrameProcessor
+        """
         super().__init__(**kwargs)
         self._aggregation = ""
         self._idle_timeout = timeout
@@ -54,7 +65,18 @@ class DTMFAggregator(FrameProcessor):
         self._digit_event = asyncio.Event()
         self._aggregation_task: Optional[asyncio.Task] = None
 
+    async def cleanup(self) -> None:
+        """Clean up resources."""
+        await super().cleanup()
+        await self._stop_aggregation_task()
+
     async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
+        """Process incoming frames and handle DTMF aggregation.
+
+        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):
@@ -83,7 +105,7 @@ class DTMFAggregator(FrameProcessor):
 
         # For first digit, schedule interruption in separate task
         if is_first_digit:
-            asyncio.create_task(self._send_interruption_task())
+            await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM)
 
         # Check for immediate flush conditions
         if frame.button == self._termination_digit:
@@ -92,15 +114,6 @@ class DTMFAggregator(FrameProcessor):
             # Signal digit received for timeout handling
             self._digit_event.set()
 
-    async def _send_interruption_task(self):
-        """Send interruption frame safely in a separate task."""
-        try:
-            # Send the interruption frame
-            await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM)
-        except Exception as e:
-            # Log error but don't propagate
-            print(f"Error sending interruption: {e}")
-
     def _create_aggregation_task(self) -> None:
         """Creates the aggregation task if it hasn't been created yet."""
         if not self._aggregation_task:
@@ -119,7 +132,6 @@ class DTMFAggregator(FrameProcessor):
                 await asyncio.wait_for(self._digit_event.wait(), timeout=self._idle_timeout)
                 self._digit_event.clear()
             except asyncio.TimeoutError:
-                self.reset_watchdog()
                 if self._aggregation:
                     await self._flush_aggregation()
 
@@ -137,8 +149,3 @@ class DTMFAggregator(FrameProcessor):
         await self.push_frame(transcription_frame)
 
         self._aggregation = ""
-
-    async def cleanup(self) -> None:
-        """Clean up resources."""
-        await super().cleanup()
-        await self._stop_aggregation_task()

pipecat/processors/aggregators/gated.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Gated frame aggregator for conditional frame accumulation.
+
+This module provides a gated aggregator that accumulates frames based on
+custom gate open/close functions, allowing for conditional frame buffering
+and release in frame processing pipelines.
+"""
+
 from typing import List, Tuple
 
 from loguru import logger
@@ -14,31 +21,11 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 class GatedAggregator(FrameProcessor):
     """Accumulate frames, with custom functions to start and stop accumulation.
+
     Yields gate-opening frame before any accumulated frames, then ensuing frames
-    until and not including the gate-closed frame.
-
-    Doctest: FIXME to work with asyncio
-    >>> from pipecat.frames.frames import ImageRawFrame
-
-    >>> async def print_frames(aggregator, frame):
-    ...     async for frame in aggregator.process_frame(frame):
-    ...         if isinstance(frame, TextFrame):
-    ...             print(frame.text)
-    ...         else:
-    ...             print(frame.__class__.__name__)
-
-    >>> aggregator = GatedAggregator(
-    ...     gate_close_fn=lambda x: isinstance(x, LLMResponseStartFrame),
-    ...     gate_open_fn=lambda x: isinstance(x, ImageRawFrame),
-    ...     start_open=False)
-    >>> asyncio.run(print_frames(aggregator, TextFrame("Hello")))
-    >>> asyncio.run(print_frames(aggregator, TextFrame("Hello again.")))
-    >>> asyncio.run(print_frames(aggregator, ImageRawFrame(image=bytes([]), size=(0, 0))))
-    ImageRawFrame
-    Hello
-    Hello again.
-    >>> asyncio.run(print_frames(aggregator, TextFrame("Goodbye.")))
-    Goodbye.
+    until and not including the gate-closed frame. The aggregator maintains an
+    internal gate state that controls whether frames are passed through immediately
+    or accumulated for later release.
     """
 
     def __init__(
@@ -48,6 +35,14 @@ class GatedAggregator(FrameProcessor):
         start_open,
         direction: FrameDirection = FrameDirection.DOWNSTREAM,
     ):
+        """Initialize the gated aggregator.
+
+        Args:
+            gate_open_fn: Function that returns True when a frame should open the gate.
+            gate_close_fn: Function that returns True when a frame should close the gate.
+            start_open: Whether the gate should start in the open state.
+            direction: The frame direction this aggregator operates on.
+        """
         super().__init__()
         self._gate_open_fn = gate_open_fn
         self._gate_close_fn = gate_close_fn
@@ -56,6 +51,12 @@ class GatedAggregator(FrameProcessor):
         self._accumulator: List[Tuple[Frame, FrameDirection]] = []
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames with gated accumulation logic.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of the frame flow.
+        """
         await super().process_frame(frame, direction)
 
         # We must not block system frames.

pipecat/processors/aggregators/gated_openai_llm_context.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Gated OpenAI LLM context aggregator for controlled message flow."""
+
 from pipecat.frames.frames import CancelFrame, EndFrame, Frame, StartFrame
 from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContextFrame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
@@ -11,12 +13,21 @@ from pipecat.sync.base_notifier import BaseNotifier
 
 
 class GatedOpenAILLMContextAggregator(FrameProcessor):
-    """This aggregator keeps the last received OpenAI LLM context frame and it
-    doesn't let it through until the notifier is notified.
+    """Aggregator that gates OpenAI LLM context frames until notified.
 
+    This aggregator captures OpenAI LLM context frames and holds them until
+    a notifier signals that they can be released. This is useful for controlling
+    the flow of context frames based on external conditions or timing.
     """
 
     def __init__(self, *, notifier: BaseNotifier, start_open: bool = False, **kwargs):
+        """Initialize the gated context aggregator.
+
+        Args:
+            notifier: The notifier that controls when frames are released.
+            start_open: If True, the first context frame passes through immediately.
+            **kwargs: Additional arguments passed to the parent FrameProcessor.
+        """
         super().__init__(**kwargs)
         self._notifier = notifier
         self._start_open = start_open
@@ -24,6 +35,12 @@ class GatedOpenAILLMContextAggregator(FrameProcessor):
         self._gate_task = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames, gating OpenAI LLM context 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, StartFrame):
@@ -42,15 +59,18 @@ class GatedOpenAILLMContextAggregator(FrameProcessor):
             await self.push_frame(frame, direction)
 
     async def _start(self):
+        """Start the gate task handler."""
         if not self._gate_task:
             self._gate_task = self.create_task(self._gate_task_handler())
 
     async def _stop(self):
+        """Stop the gate task handler."""
         if self._gate_task:
             await self.cancel_task(self._gate_task)
             self._gate_task = None
 
     async def _gate_task_handler(self):
+        """Handle the gating logic by waiting for notifications and releasing frames."""
         while True:
             await self._notifier.wait()
             if self._last_context_frame: