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

pipecat/pipeline/runner.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Pipeline runner for managing pipeline task execution.
+
+This module provides the PipelineRunner class that handles the execution
+of pipeline tasks with signal handling, garbage collection, and lifecycle
+management.
+"""
+
 import asyncio
 import gc
 import signal
@@ -17,14 +24,31 @@ from pipecat.utils.base_object import BaseObject
 
 
 class PipelineRunner(BaseObject):
+    """Manages the execution of pipeline tasks with lifecycle and signal handling.
+
+    Provides a high-level interface for running pipeline tasks with automatic
+    signal handling (SIGINT/SIGTERM), optional garbage collection, and proper
+    cleanup of resources.
+    """
+
     def __init__(
         self,
         *,
         name: Optional[str] = None,
         handle_sigint: bool = True,
+        handle_sigterm: bool = False,
         force_gc: bool = False,
         loop: Optional[asyncio.AbstractEventLoop] = None,
     ):
+        """Initialize the pipeline runner.
+
+        Args:
+            name: Optional name for the runner instance.
+            handle_sigint: Whether to automatically handle SIGINT signals.
+            handle_sigterm: Whether to automatically handle SIGTERM signals.
+            force_gc: Whether to force garbage collection after task completion.
+            loop: Event loop to use. If None, uses the current running loop.
+        """
         super().__init__(name=name)
 
         self._tasks = {}
@@ -35,11 +59,22 @@ class PipelineRunner(BaseObject):
         if handle_sigint:
             self._setup_sigint()
 
+        if handle_sigterm:
+            self._setup_sigterm()
+
     async def run(self, task: PipelineTask):
+        """Run a pipeline task to completion.
+
+        Args:
+            task: The pipeline task to execute.
+        """
         logger.debug(f"Runner {self} started running {task}", call_id=task._conversation_id)
         self._tasks[task.name] = task
         params = PipelineTaskParams(loop=self._loop)
-        await task.run(params)
+        try:
+            await task.run(params)
+        except asyncio.CancelledError:
+            await self._cancel()
         del self._tasks[task.name]
 
         # Cleanup base object.
@@ -56,27 +91,41 @@ class PipelineRunner(BaseObject):
         logger.debug(f"Runner {self} finished running {task}", call_id=task._conversation_id)
 
     async def stop_when_done(self):
+        """Schedule all running tasks to stop when their current processing is complete."""
         logger.debug(f"Runner {self} scheduled to stop when all tasks are done")
         await asyncio.gather(*[t.stop_when_done() for t in self._tasks.values()])
 
     async def cancel(self):
+        """Cancel all running tasks immediately."""
         logger.debug(f"Cancelling runner {self}")
+        await self._cancel()
+
+    async def _cancel(self):
+        """Cancel all running tasks immediately."""
         await asyncio.gather(*[t.cancel() for t in self._tasks.values()])
 
     def _setup_sigint(self):
+        """Set up signal handlers for graceful shutdown."""
         loop = asyncio.get_running_loop()
         loop.add_signal_handler(signal.SIGINT, lambda *args: self._sig_handler())
+
+    def _setup_sigterm(self):
+        """Set up signal handlers for graceful shutdown."""
+        loop = asyncio.get_running_loop()
         loop.add_signal_handler(signal.SIGTERM, lambda *args: self._sig_handler())
 
     def _sig_handler(self):
+        """Handle interrupt signals by cancelling all tasks."""
         if not self._sig_task:
             self._sig_task = asyncio.create_task(self._sig_cancel())
 
     async def _sig_cancel(self):
+        """Cancel all running tasks due to signal interruption."""
         logger.warning(f"Interruption detected. Cancelling runner {self}")
         await self.cancel()
 
     def _gc_collect(self):
+        """Force garbage collection and log results."""
         collected = gc.collect()
         logger.debug(f"Garbage collector: collected {collected} objects.")
         logger.debug(f"Garbage collector: uncollectable objects {gc.garbage}")

pipecat/pipeline/sync_parallel_pipeline.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Synchronous parallel pipeline implementation for concurrent frame processing.
+
+This module provides a pipeline that processes frames through multiple parallel
+pipelines simultaneously, synchronizing their output to maintain frame ordering
+and prevent duplicate processing.
+"""
+
 import asyncio
 from dataclasses import dataclass
 from itertools import chain
@@ -15,22 +22,42 @@ from pipecat.frames.frames import ControlFrame, EndFrame, Frame, SystemFrame
 from pipecat.pipeline.base_pipeline import BasePipeline
 from pipecat.pipeline.pipeline import Pipeline
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, FrameProcessorSetup
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 
 @dataclass
 class SyncFrame(ControlFrame):
-    """This frame is used to know when the internal pipelines have finished."""
+    """Control frame used to synchronize parallel pipeline processing.
+
+    This frame is sent through parallel pipelines to determine when the
+    internal pipelines have finished processing a batch of frames.
+    """
 
     pass
 
 
 class SyncParallelPipelineSource(FrameProcessor):
+    """Source processor for synchronous parallel pipeline processing.
+
+    Routes frames to parallel pipelines and collects upstream responses
+    for synchronization purposes.
+    """
+
     def __init__(self, upstream_queue: asyncio.Queue):
-        super().__init__()
+        """Initialize the sync parallel pipeline source.
+
+        Args:
+            upstream_queue: Queue for collecting upstream frames from the pipeline.
+        """
+        super().__init__(enable_direct_mode=True)
         self._up_queue = upstream_queue
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames and route them based on direction.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
         await super().process_frame(frame, direction)
 
         match direction:
@@ -41,11 +68,28 @@ class SyncParallelPipelineSource(FrameProcessor):
 
 
 class SyncParallelPipelineSink(FrameProcessor):
+    """Sink processor for synchronous parallel pipeline processing.
+
+    Collects downstream frames from parallel pipelines and routes
+    upstream frames back through the pipeline.
+    """
+
     def __init__(self, downstream_queue: asyncio.Queue):
-        super().__init__()
+        """Initialize the sync parallel pipeline sink.
+
+        Args:
+            downstream_queue: Queue for collecting downstream frames from the pipeline.
+        """
+        super().__init__(enable_direct_mode=True)
         self._down_queue = downstream_queue
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames and route them based on direction.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
         await super().process_frame(frame, direction)
 
         match direction:
@@ -56,36 +100,42 @@ class SyncParallelPipelineSink(FrameProcessor):
 
 
 class SyncParallelPipeline(BasePipeline):
+    """Pipeline that processes frames through multiple parallel pipelines synchronously.
+
+    Creates multiple parallel processing paths that all receive the same input frames
+    and produces synchronized output. Each parallel path is a separate pipeline that
+    processes frames independently, with synchronization points to ensure consistent
+    ordering and prevent duplicate frame processing.
+
+    The pipeline uses SyncFrame control frames to coordinate between parallel paths
+    and ensure all paths have completed processing before moving to the next frame.
+    """
+
     def __init__(self, *args):
+        """Initialize the synchronous parallel pipeline.
+
+        Args:
+            *args: Variable number of processor lists, each representing a parallel pipeline path.
+                   Each argument should be a list of FrameProcessor instances.
+
+        Raises:
+            Exception: If no arguments are provided.
+            TypeError: If any argument is not a list of processors.
+        """
         super().__init__()
 
         if len(args) == 0:
             raise Exception(f"SyncParallelPipeline needs at least one argument")
 
-        self._args = args
         self._sinks = []
         self._sources = []
         self._pipelines = []
 
-    #
-    # BasePipeline
-    #
-
-    def processors_with_metrics(self) -> List[FrameProcessor]:
-        return list(chain.from_iterable(p.processors_with_metrics() for p in self._pipelines))
-
-    #
-    # Frame processor
-    #
-
-    async def setup(self, setup: FrameProcessorSetup):
-        await super().setup(setup)
-
-        self._up_queue = WatchdogQueue(setup.task_manager)
-        self._down_queue = WatchdogQueue(setup.task_manager)
+        self._up_queue = asyncio.Queue()
+        self._down_queue = asyncio.Queue()
 
         logger.debug(f"Creating {self} pipelines")
-        for processors in self._args:
+        for processors in args:
             if not isinstance(processors, list):
                 raise TypeError(f"SyncParallelPipeline argument {processors} is not a list")
 
@@ -95,30 +145,80 @@ class SyncParallelPipeline(BasePipeline):
             source = SyncParallelPipelineSource(up_queue)
             sink = SyncParallelPipelineSink(down_queue)
 
-            # Create pipeline
-            pipeline = Pipeline(processors)
-            source.link(pipeline)
-            pipeline.link(sink)
-            self._pipelines.append(pipeline)
-
             # Keep track of sources and sinks. We also keep the output queue of
             # the source and the sinks so we can use it later.
             self._sources.append({"processor": source, "queue": down_queue})
             self._sinks.append({"processor": sink, "queue": up_queue})
 
+            # Create pipeline
+            pipeline = Pipeline(processors, source=source, sink=sink)
+            self._pipelines.append(pipeline)
+
         logger.debug(f"Finished creating {self} pipelines")
 
-        await asyncio.gather(*[s["processor"].setup(setup) for s in self._sources])
+    #
+    # Frame processor
+    #
+
+    @property
+    def processors(self):
+        """Return the list of sub-processors contained within this processor.
+
+        Only compound processors (e.g. pipelines and parallel pipelines) have
+        sub-processors. Non-compound processors will return an empty list.
+
+        Returns:
+            The list of sub-processors if this is a compound processor.
+        """
+        return self._pipelines
+
+    @property
+    def entry_processors(self) -> List["FrameProcessor"]:
+        """Return the list of entry processors for this processor.
+
+        Entry processors are the first processors in a compound processor
+        (e.g. pipelines, parallel pipelines). Note that pipelines can also be an
+        entry processor as pipelines are processors themselves. Non-compound
+        processors will simply return an empty list.
+
+        Returns:
+            The list of entry processors.
+        """
+        return self._sources
+
+    def processors_with_metrics(self) -> List[FrameProcessor]:
+        """Collect processors that can generate metrics from all parallel pipelines.
+
+        Returns:
+            List of frame processors that support metrics collection from all parallel paths.
+        """
+        return list(chain.from_iterable(p.processors_with_metrics() for p in self._pipelines))
+
+    async def setup(self, setup: FrameProcessorSetup):
+        """Set up the parallel pipeline and all contained processors.
+
+        Args:
+            setup: Configuration for frame processor setup.
+        """
+        await super().setup(setup)
         await asyncio.gather(*[p.setup(setup) for p in self._pipelines])
-        await asyncio.gather(*[s["processor"].setup(setup) for s in self._sinks])
 
     async def cleanup(self):
+        """Clean up the parallel pipeline and all contained processors."""
         await super().cleanup()
-        await asyncio.gather(*[s["processor"].cleanup() for s in self._sources])
         await asyncio.gather(*[p.cleanup() for p in self._pipelines])
-        await asyncio.gather(*[s["processor"].cleanup() for s in self._sinks])
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames through all parallel pipelines with synchronization.
+
+        Distributes frames to all parallel pipelines and synchronizes their output
+        to maintain proper ordering and prevent duplicate processing. Uses SyncFrame
+        control frames to coordinate between parallel paths.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
         await super().process_frame(frame, direction)
 
         # The last processor of each pipeline needs to be synchronous otherwise