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

pipecat/pipeline/base_task.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base pipeline task implementation for managing pipeline execution.
+
+This module provides the abstract base class and configuration for pipeline
+tasks that manage the lifecycle and execution of frame processing pipelines.
+"""
+
 import asyncio
 from abc import abstractmethod
 from dataclasses import dataclass
@@ -15,44 +21,81 @@ from pipecat.utils.base_object import BaseObject
 
 @dataclass
 class PipelineTaskParams:
-    """Specific configuration for the pipeline task."""
+    """Configuration parameters for pipeline task execution.
+
+    Parameters:
+        loop: The asyncio event loop to use for task execution.
+    """
 
     loop: asyncio.AbstractEventLoop
 
 
 class BasePipelineTask(BaseObject):
+    """Abstract base class for pipeline task implementations.
+
+    Defines the interface for managing pipeline execution lifecycle,
+    including starting, stopping, and frame queuing operations.
+    """
+
     @abstractmethod
     def has_finished(self) -> bool:
-        """Indicates whether the tasks has finished. That is, all processors
-        have stopped.
+        """Check if the pipeline task has finished execution.
 
+        Returns:
+            True if all processors have stopped and the task is complete.
         """
         pass
 
     @abstractmethod
     async def stop_when_done(self):
-        """This is a helper function that sends an EndFrame to the pipeline in
-        order to stop the task after everything in it has been processed.
+        """Schedule the pipeline to stop after processing all queued frames.
 
+        Implementing classes should send an EndFrame or equivalent signal to
+        gracefully terminate the pipeline once all current processing is complete.
         """
         pass
 
     @abstractmethod
     async def cancel(self):
-        """Stops the running pipeline immediately."""
+        """Immediately stop the running pipeline.
+
+        Implementing classes should cancel all running tasks and stop frame
+        processing without waiting for completion.
+        """
         pass
 
     @abstractmethod
     async def run(self, params: PipelineTaskParams):
-        """Starts running the given pipeline."""
+        """Start and run the pipeline with the given parameters.
+
+        Implementing classes should initialize and execute the pipeline using
+        the provided configuration parameters.
+
+        Args:
+            params: Configuration parameters for pipeline execution.
+        """
         pass
 
     @abstractmethod
     async def queue_frame(self, frame: Frame):
-        """Queue a frame to be pushed down the pipeline."""
+        """Queue a single frame for processing by the pipeline.
+
+        Implementing classes should add the frame to their processing queue
+        for downstream handling.
+
+        Args:
+            frame: The frame to be processed.
+        """
         pass
 
     @abstractmethod
     async def queue_frames(self, frames: Iterable[Frame] | AsyncIterable[Frame]):
-        """Queues multiple frames to be pushed down the pipeline."""
+        """Queue multiple frames for processing by the pipeline.
+
+        Implementing classes should process the iterable/async iterable and
+        add all frames to their processing queue.
+
+        Args:
+            frames: An iterable or async iterable of frames to be processed.
+        """
         pass

pipecat/pipeline/parallel_pipeline.py

@@ -4,227 +4,171 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-import asyncio
+"""Parallel pipeline implementation for concurrent frame processing.
+
+This module provides a parallel pipeline that processes frames through multiple
+sub-pipelines concurrently, with coordination for system frames and proper
+handling of pipeline lifecycle events.
+"""
+
 from itertools import chain
-from typing import Awaitable, Callable, Dict, List
+from typing import Dict, List
 
 from loguru import logger
 
-from pipecat.frames.frames import (
-    CancelFrame,
-    EndFrame,
-    Frame,
-    StartFrame,
-    StartInterruptionFrame,
-    SystemFrame,
-)
+from pipecat.frames.frames import EndFrame, Frame, StartFrame
 from pipecat.pipeline.base_pipeline import BasePipeline
-from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.pipeline import Pipeline, PipelineSink, PipelineSource
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, FrameProcessorSetup
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 
-class ParallelPipelineSource(FrameProcessor):
-    def __init__(
-        self,
-        upstream_queue: asyncio.Queue,
-        push_frame_func: Callable[[Frame, FrameDirection], Awaitable[None]],
-    ):
-        super().__init__()
-        self._up_queue = upstream_queue
-        self._push_frame_func = push_frame_func
-
-    async def process_frame(self, frame: Frame, direction: FrameDirection):
-        await super().process_frame(frame, direction)
-
-        match direction:
-            case FrameDirection.UPSTREAM:
-                if isinstance(frame, SystemFrame):
-                    await self._push_frame_func(frame, direction)
-                else:
-                    await self._up_queue.put(frame)
-            case FrameDirection.DOWNSTREAM:
-                await self.push_frame(frame, direction)
-
-
-class ParallelPipelineSink(FrameProcessor):
-    def __init__(
-        self,
-        downstream_queue: asyncio.Queue,
-        push_frame_func: Callable[[Frame, FrameDirection], Awaitable[None]],
-    ):
-        super().__init__()
-        self._down_queue = downstream_queue
-        self._push_frame_func = push_frame_func
+class ParallelPipeline(BasePipeline):
+    """Pipeline that processes frames through multiple sub-pipelines concurrently.
 
-    async def process_frame(self, frame: Frame, direction: FrameDirection):
-        await super().process_frame(frame, direction)
+    Creates multiple parallel processing branches from the provided processor lists,
+    coordinating frame flow and ensuring proper synchronization of lifecycle events
+    like EndFrames. Each branch runs independently while system frames are handled
+    specially to maintain pipeline coordination.
+    """
 
-        match direction:
-            case FrameDirection.UPSTREAM:
-                await self.push_frame(frame, direction)
-            case FrameDirection.DOWNSTREAM:
-                if isinstance(frame, SystemFrame):
-                    await self._push_frame_func(frame, direction)
-                else:
-                    await self._down_queue.put(frame)
+    def __init__(self, *args):
+        """Initialize the parallel pipeline with processor lists.
 
+        Args:
+            *args: Variable number of processor lists, each becoming a parallel branch.
 
-class ParallelPipeline(BasePipeline):
-    def __init__(self, *args):
+        Raises:
+            Exception: If no processor lists are provided.
+            TypeError: If any argument is not a list of processors.
+        """
+        # We don't set it to direct mode because we use frame pausing and that
+        # requires queues.
         super().__init__()
 
         if len(args) == 0:
             raise Exception(f"ParallelPipeline needs at least one argument")
 
-        self._args = args
-        self._sources = []
-        self._sinks = []
         self._pipelines = []
 
         self._seen_ids = set()
-        self._endframe_counter: Dict[int, int] = {}
+        self._frame_counter: Dict[int, int] = {}
 
-        self._up_task = None
-        self._down_task = None
+        logger.debug(f"Creating {self} pipelines")
 
-    #
-    # BasePipeline
-    #
+        for processors in args:
+            if not isinstance(processors, list):
+                raise TypeError(f"ParallelPipeline argument {processors} is not a list")
 
-    def processors_with_metrics(self) -> List[FrameProcessor]:
-        return list(chain.from_iterable(p.processors_with_metrics() for p in self._pipelines))
+            num_pipelines = len(self._pipelines)
+
+            # We add a source before the pipeline and a sink after so we control
+            # the frames that are pushed upstream and downstream.
+            source = PipelineSource(
+                self._parallel_push_frame, name=f"{self}::Source{num_pipelines}"
+            )
+            sink = PipelineSink(self._pipeline_sink_push_frame, name=f"{self}::Sink{num_pipelines}")
+
+            # Create pipeline
+            pipeline = Pipeline(processors, source=source, sink=sink)
+            self._pipelines.append(pipeline)
+
+        logger.debug(f"Finished creating {self} pipelines")
 
     #
     # Frame processor
     #
 
-    async def setup(self, setup: FrameProcessorSetup):
-        await super().setup(setup)
+    @property
+    def processors(self):
+        """Return the list of sub-processors contained within this processor.
 
-        self._up_queue = WatchdogQueue(setup.task_manager)
-        self._down_queue = WatchdogQueue(setup.task_manager)
+        Only compound processors (e.g. pipelines and parallel pipelines) have
+        sub-processors. Non-compound processors will return an empty list.
 
-        logger.debug(f"Creating {self} pipelines")
-        for processors in self._args:
-            if not isinstance(processors, list):
-                raise TypeError(f"ParallelPipeline argument {processors} is not a list")
+        Returns:
+            The list of sub-processors if this is a compound processor.
+        """
+        return self._pipelines
 
-            # We will add a source before the pipeline and a sink after.
-            source = ParallelPipelineSource(self._up_queue, self._parallel_push_frame)
-            sink = ParallelPipelineSink(self._down_queue, self._parallel_push_frame)
-            self._sources.append(source)
-            self._sinks.append(sink)
+    @property
+    def entry_processors(self) -> List["FrameProcessor"]:
+        """Return the list of entry processors for this processor.
 
-            # Create pipeline
-            pipeline = Pipeline(processors)
-            source.link(pipeline)
-            pipeline.link(sink)
-            self._pipelines.append(pipeline)
+        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.
 
-        logger.debug(f"Finished creating {self} pipelines")
+        Returns:
+            The list of entry processors.
+        """
+        return self._pipelines
+
+    def processors_with_metrics(self) -> List[FrameProcessor]:
+        """Collect processors that can generate metrics from all parallel branches.
 
-        await asyncio.gather(*[s.setup(setup) for s in self._sources])
-        await asyncio.gather(*[p.setup(setup) for p in self._pipelines])
-        await asyncio.gather(*[s.setup(setup) for s in self._sinks])
+        Returns:
+            List of frame processors that support metrics collection from all branches.
+        """
+        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 its branches.
+
+        Args:
+            setup: Configuration for frame processor setup.
+
+        Raises:
+            TypeError: If any processor list argument is not actually a list.
+        """
+        await super().setup(setup)
+        for p in self._pipelines:
+            await p.setup(setup)
 
     async def cleanup(self):
+        """Clean up the parallel pipeline and all its branches."""
         await super().cleanup()
-        await asyncio.gather(*[s.cleanup() for s in self._sources])
-        await asyncio.gather(*[p.cleanup() for p in self._pipelines])
-        await asyncio.gather(*[s.cleanup() for s in self._sinks])
+        for p in self._pipelines:
+            await p.cleanup()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames through all parallel branches with lifecycle coordination.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
         await super().process_frame(frame, direction)
 
-        if isinstance(frame, StartFrame):
-            await self._start(frame)
-        elif isinstance(frame, EndFrame):
-            self._endframe_counter[frame.id] = len(self._pipelines)
-        elif isinstance(frame, CancelFrame):
-            await self._cancel()
-
-        if direction == FrameDirection.UPSTREAM:
-            # If we get an upstream frame we process it in each sink.
-            await asyncio.gather(*[s.queue_frame(frame, direction) for s in self._sinks])
-        elif direction == FrameDirection.DOWNSTREAM:
-            # If we get a downstream frame we process it in each source.
-            await asyncio.gather(*[s.queue_frame(frame, direction) for s in self._sources])
-
-        # Handle interruptions after everything has been cancelled.
-        if isinstance(frame, StartInterruptionFrame):
-            await self._handle_interruption()
-        # Wait for tasks to finish.
-        elif isinstance(frame, EndFrame):
-            await self._stop()
-
-    async def _start(self, frame: StartFrame):
-        await self._create_tasks()
-
-    async def _stop(self):
-        if self._up_task:
-            # The up task doesn't receive an EndFrame, so we just cancel it.
-            await self.cancel_task(self._up_task)
-            self._up_task = None
-
-        if self._down_task:
-            # The down tasks waits for the last EndFrame sent by the internal
-            # pipelines.
-            await self._down_task
-            self._down_task = None
-
-    async def _cancel(self):
-        if self._up_task:
-            await self.cancel_task(self._up_task)
-            self._up_task = None
-        if self._down_task:
-            await self.cancel_task(self._down_task)
-            self._down_task = None
-
-    async def _create_tasks(self):
-        if not self._up_task:
-            self._up_task = self.create_task(self._process_up_queue())
-        if not self._down_task:
-            self._down_task = self.create_task(self._process_down_queue())
-
-    async def _drain_queues(self):
-        while not self._up_queue.empty:
-            await self._up_queue.get()
-        while not self._down_queue.empty:
-            await self._down_queue.get()
-
-    async def _handle_interruption(self):
-        await self._cancel()
-        await self._drain_queues()
-        await self._create_tasks()
+        # Parallel pipeline synchronized frames.
+        if isinstance(frame, (StartFrame, EndFrame)):
+            self._frame_counter[frame.id] = len(self._pipelines)
+            await self.pause_processing_system_frames()
+            await self.pause_processing_frames()
+
+        # Process frames in each of the sub-pipelines.
+        for p in self._pipelines:
+            await p.queue_frame(frame, direction)
 
     async def _parallel_push_frame(self, frame: Frame, direction: FrameDirection):
+        """Push frames while avoiding duplicates using frame ID tracking."""
         if frame.id not in self._seen_ids:
             self._seen_ids.add(frame.id)
             await self.push_frame(frame, direction)
 
-    async def _process_up_queue(self):
-        while True:
-            frame = await self._up_queue.get()
-            await self._parallel_push_frame(frame, FrameDirection.UPSTREAM)
-            self._up_queue.task_done()
-
-    async def _process_down_queue(self):
-        running = True
-        while running:
-            frame = await self._down_queue.get()
-
-            endframe_counter = self._endframe_counter.get(frame.id, 0)
-
-            # If we have a counter, decrement it.
-            if endframe_counter > 0:
-                self._endframe_counter[frame.id] -= 1
-                endframe_counter = self._endframe_counter[frame.id]
-
-            # If we don't have a counter or we reached 0, push the frame.
-            if endframe_counter == 0:
-                await self._parallel_push_frame(frame, FrameDirection.DOWNSTREAM)
-
-            running = not (endframe_counter == 0 and isinstance(frame, EndFrame))
-
-            self._down_queue.task_done()
+    async def _pipeline_sink_push_frame(self, frame: Frame, direction: FrameDirection):
+        # Parallel pipeline synchronized frames.
+        if isinstance(frame, (StartFrame, EndFrame)):
+            # Decrement counter.
+            frame_counter = self._frame_counter.get(frame.id, 0)
+            if frame_counter > 0:
+                self._frame_counter[frame.id] -= 1
+                frame_counter = self._frame_counter[frame.id]
+
+            # Only push the frame when all pipelines have processed it.
+            if frame_counter == 0:
+                await self._parallel_push_frame(frame, direction)
+                await self.resume_processing_system_frames()
+                await self.resume_processing_frames()
+        else:
+            await self._parallel_push_frame(frame, direction)

pipecat/pipeline/pipeline.py

@@ -4,7 +4,14 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-from typing import Callable, Coroutine, List
+"""Pipeline implementation for connecting and managing frame processors.
+
+This module provides the main Pipeline class that connects frame processors
+in sequence and manages frame flow between them, along with helper classes
+for pipeline source and sink operations.
+"""
+
+from typing import Callable, Coroutine, List, Optional
 
 from pipecat.frames.frames import Frame
 from pipecat.pipeline.base_pipeline import BasePipeline
@@ -12,11 +19,30 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, F
 
 
 class PipelineSource(FrameProcessor):
-    def __init__(self, upstream_push_frame: Callable[[Frame, FrameDirection], Coroutine]):
-        super().__init__()
+    """Source processor that forwards frames to an upstream handler.
+
+    This processor acts as the entry point for a pipeline, forwarding
+    downstream frames to the next processor and upstream frames to a
+    provided upstream handler function.
+    """
+
+    def __init__(self, upstream_push_frame: Callable[[Frame, FrameDirection], Coroutine], **kwargs):
+        """Initialize the pipeline source.
+
+        Args:
+            upstream_push_frame: Coroutine function to handle upstream frames.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        super().__init__(enable_direct_mode=True, **kwargs)
         self._upstream_push_frame = upstream_push_frame
 
     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:
@@ -27,11 +53,32 @@ class PipelineSource(FrameProcessor):
 
 
 class PipelineSink(FrameProcessor):
-    def __init__(self, downstream_push_frame: Callable[[Frame, FrameDirection], Coroutine]):
-        super().__init__()
+    """Sink processor that forwards frames to a downstream handler.
+
+    This processor acts as the exit point for a pipeline, forwarding
+    upstream frames to the previous processor and downstream frames to a
+    provided downstream handler function.
+    """
+
+    def __init__(
+        self, downstream_push_frame: Callable[[Frame, FrameDirection], Coroutine], **kwargs
+    ):
+        """Initialize the pipeline sink.
+
+        Args:
+            downstream_push_frame: Coroutine function to handle downstream frames.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        super().__init__(enable_direct_mode=True, **kwargs)
         self._downstream_push_frame = downstream_push_frame
 
     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:
@@ -42,43 +89,104 @@ class PipelineSink(FrameProcessor):
 
 
 class Pipeline(BasePipeline):
-    def __init__(self, processors: List[FrameProcessor]):
-        super().__init__()
+    """Main pipeline implementation that connects frame processors in sequence.
+
+    Creates a linear chain of frame processors with automatic source and sink
+    processors for external frame handling. Manages processor lifecycle and
+    provides metrics collection from contained processors.
+    """
+
+    def __init__(
+        self,
+        processors: List[FrameProcessor],
+        *,
+        source: Optional[FrameProcessor] = None,
+        sink: Optional[FrameProcessor] = None,
+    ):
+        """Initialize the pipeline with a list of processors.
+
+        Args:
+            processors: List of frame processors to connect in sequence.
+            source: An optional pipeline source processor.
+            sink: An optional pipeline sink processor.
+        """
+        super().__init__(enable_direct_mode=True)
 
         # Add a source and a sink queue so we can forward frames upstream and
         # downstream outside of the pipeline.
-        self._source = PipelineSource(self.push_frame)
-        self._sink = PipelineSink(self.push_frame)
+        self._source = source or PipelineSource(self.push_frame, name=f"{self}::Source")
+        self._sink = sink or PipelineSink(self.push_frame, name=f"{self}::Sink")
         self._processors: List[FrameProcessor] = [self._source] + processors + [self._sink]
 
         self._link_processors()
 
     #
-    # BasePipeline
+    # 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._processors
+
+    @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._source]
+
     def processors_with_metrics(self):
+        """Return processors that can generate metrics.
+
+        Recursively collects all processors that support metrics generation,
+        including those from nested pipelines.
+
+        Returns:
+            List of frame processors that can generate metrics.
+        """
         services = []
-        for p in self._processors:
-            if isinstance(p, BasePipeline):
-                services.extend(p.processors_with_metrics())
-            elif p.can_generate_metrics():
+        for p in self.processors:
+            if p.can_generate_metrics():
                 services.append(p)
+            services.extend(p.processors_with_metrics())
         return services
 
-    #
-    # Frame processor
-    #
-
     async def setup(self, setup: FrameProcessorSetup):
+        """Set up the pipeline and all contained processors.
+
+        Args:
+            setup: Configuration for frame processor setup.
+        """
         await super().setup(setup)
         await self._setup_processors(setup)
 
     async def cleanup(self):
+        """Clean up the pipeline and all contained processors."""
         await super().cleanup()
         await self._cleanup_processors()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames by routing them through the pipeline.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
         await super().process_frame(frame, direction)
 
         if direction == FrameDirection.DOWNSTREAM:
@@ -87,17 +195,18 @@ class Pipeline(BasePipeline):
             await self._sink.queue_frame(frame, FrameDirection.UPSTREAM)
 
     async def _setup_processors(self, setup: FrameProcessorSetup):
+        """Set up all processors in the pipeline."""
         for p in self._processors:
             await p.setup(setup)
 
     async def _cleanup_processors(self):
+        """Clean up all processors in the pipeline."""
         for p in self._processors:
             await p.cleanup()
 
     def _link_processors(self):
+        """Link all processors in sequence and set their parent."""
         prev = self._processors[0]
         for curr in self._processors[1:]:
-            prev.set_parent(self)
             prev.link(curr)
             prev = curr
-        prev.set_parent(self)