dv-pipecat-ai 0.0.85.dev7__py3-none-any.whl → 0.0.85.dev699__py3-none-any.whl

pipecat/frames/frames.py

@@ -672,7 +672,7 @@ class TTSSpeakFrame(DataFrame):
 
 
 @dataclass
-class TransportMessageFrame(DataFrame):
+class OutputTransportMessageFrame(DataFrame):
     """Frame containing transport-specific message data.
 
     Parameters:
@@ -685,6 +685,32 @@ class TransportMessageFrame(DataFrame):
         return f"{self.name}(message: {self.message})"
 
 
+@dataclass
+class TransportMessageFrame(OutputTransportMessageFrame):
+    """Frame containing transport-specific message data.
+
+    .. deprecated:: 0.0.87
+        This frame is deprecated and will be removed in a future version.
+        Instead, use `OutputTransportMessageFrame`.
+
+    Parameters:
+        message: The transport message payload.
+    """
+
+    def __post_init__(self):
+        super().__post_init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "TransportMessageFrame is deprecated and will be removed in a future version. "
+                "Instead, use OutputTransportMessageFrame.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+
 @dataclass
 class DTMFFrame:
     """Base class for DTMF (Dual-Tone Multi-Frequency) keypad frames.
@@ -788,43 +814,6 @@ class FatalErrorFrame(ErrorFrame):
     fatal: bool = field(default=True, init=False)
 
 
-@dataclass
-class EndTaskFrame(SystemFrame):
-    """Frame to request graceful pipeline task closure.
-
-    This is used to notify the pipeline task that the pipeline should be
-    closed nicely (flushing all the queued frames) by pushing an EndFrame
-    downstream. This frame should be pushed upstream.
-    """
-
-    pass
-
-
-@dataclass
-class CancelTaskFrame(SystemFrame):
-    """Frame to request immediate pipeline task cancellation.
-
-    This is used to notify the pipeline task that the pipeline should be
-    stopped immediately by pushing a CancelFrame downstream. This frame
-    should be pushed upstream.
-    """
-
-    pass
-
-
-@dataclass
-class StopTaskFrame(SystemFrame):
-    """Frame to request pipeline task stop while keeping processors running.
-
-    This is used to notify the pipeline task that it should be stopped as
-    soon as possible (flushing all the queued frames) but that the pipeline
-    processors should be kept in a running state. This frame should be pushed
-    upstream.
-    """
-
-    pass
-
-
 @dataclass
 class FrameProcessorPauseUrgentFrame(SystemFrame):
     """Frame to pause frame processing immediately.
@@ -857,7 +846,7 @@ class FrameProcessorResumeUrgentFrame(SystemFrame):
 
 
 @dataclass
-class StartInterruptionFrame(SystemFrame):
+class InterruptionFrame(SystemFrame):
     """Frame indicating user started speaking (interruption detected).
 
     Emitted by the BaseInputTransport to indicate that a user has started
@@ -869,6 +858,34 @@ class StartInterruptionFrame(SystemFrame):
     pass
 
 
+@dataclass
+class StartInterruptionFrame(InterruptionFrame):
+    """Frame indicating user started speaking (interruption detected).
+
+    .. deprecated:: 0.0.85
+        This frame is deprecated and will be removed in a future version.
+        Instead, use `InterruptionFrame`.
+
+    Emitted by the BaseInputTransport to indicate that a user has started
+    speaking (i.e. is interrupting). This is similar to
+    UserStartedSpeakingFrame except that it should be pushed concurrently
+    with other frames (so the order is not guaranteed).
+    """
+
+    def __post_init__(self):
+        super().__post_init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "StartInterruptionFrame is deprecated and will be removed in a future version. "
+                "Instead, use InterruptionFrame.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+
 @dataclass
 class UserStartedSpeakingFrame(SystemFrame):
     """Frame indicating user has started speaking.
@@ -944,20 +961,6 @@ class VADUserStoppedSpeakingFrame(SystemFrame):
     pass
 
 
-@dataclass
-class BotInterruptionFrame(SystemFrame):
-    """Frame indicating the bot should be interrupted.
-
-    Emitted when the bot should be interrupted. This will mainly cause the
-    same actions as if the user interrupted except that the
-    UserStartedSpeakingFrame and UserStoppedSpeakingFrame won't be generated.
-    This frame should be pushed upstreams. It results in the BaseInputTransport
-    starting an interruption by pushing a StartInterruptionFrame downstream.
-    """
-
-    pass
-
-
 @dataclass
 class BotStartedSpeakingFrame(SystemFrame):
     """Frame indicating the bot started speaking.
@@ -1115,8 +1118,8 @@ class STTMuteFrame(SystemFrame):
 
 
 @dataclass
-class TransportMessageUrgentFrame(SystemFrame):
-    """Frame for urgent transport messages that need immediate processing.
+class InputTransportMessageFrame(SystemFrame):
+    """Frame for transport messages received from external sources.
 
     Parameters:
         message: The urgent transport message payload.
@@ -1129,20 +1132,69 @@ class TransportMessageUrgentFrame(SystemFrame):
 
 
 @dataclass
-class InputTransportMessageUrgentFrame(TransportMessageUrgentFrame):
+class InputTransportMessageUrgentFrame(InputTransportMessageFrame):
     """Frame for transport messages received from external sources.
 
-    This frame wraps incoming transport messages to distinguish them from outgoing
-    urgent transport messages (TransportMessageUrgentFrame), preventing infinite
-    message loops in the transport layer. It inherits the message payload from
-    TransportMessageFrame while marking the message as having been received
-    rather than generated locally.
+    .. deprecated:: 0.0.87
+        This frame is deprecated and will be removed in a future version.
+        Instead, use `InputTransportMessageFrame`.
 
-    Used by transport implementations to properly handle bidirectional message
-    flow without creating feedback loops.
+    Parameters:
+        message: The urgent transport message payload.
     """
 
-    pass
+    def __post_init__(self):
+        super().__post_init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "InputTransportMessageUrgentFrame is deprecated and will be removed in a future version. "
+                "Instead, use InputTransportMessageFrame.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+
+@dataclass
+class OutputTransportMessageUrgentFrame(SystemFrame):
+    """Frame for urgent transport messages that need to be sent immediately.
+
+    Parameters:
+        message: The urgent transport message payload.
+    """
+
+    message: Any
+
+    def __str__(self):
+        return f"{self.name}(message: {self.message})"
+
+
+@dataclass
+class TransportMessageUrgentFrame(OutputTransportMessageUrgentFrame):
+    """Frame for urgent transport messages that need to be sent immediately.
+
+    .. deprecated:: 0.0.87
+        This frame is deprecated and will be removed in a future version.
+        Instead, use `OutputTransportMessageUrgentFrame`.
+
+    Parameters:
+        message: The urgent transport message payload.
+    """
+
+    def __post_init__(self):
+        super().__post_init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "TransportMessageUrgentFrame is deprecated and will be removed in a future version. "
+                "Instead, use OutputTransportMessageFrame.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
 
 @dataclass
@@ -1253,23 +1305,6 @@ class UserImageRawFrame(InputImageRawFrame):
         return f"{self.name}(pts: {pts}, user: {self.user_id}, source: {self.transport_source}, size: {self.size}, format: {self.format}, request: {self.request})"
 
 
-@dataclass
-class VisionImageRawFrame(InputImageRawFrame):
-    """Image frame for vision/image analysis with associated text prompt.
-
-    An image with an associated text to ask for a description of it.
-
-    Parameters:
-        text: Optional text prompt describing what to analyze in the image.
-    """
-
-    text: Optional[str] = None
-
-    def __str__(self):
-        pts = format_pts(self.pts)
-        return f"{self.name}(pts: {pts}, text: [{self.text}], size: {self.size}, format: {self.format})"
-
-
 @dataclass
 class InputDTMFFrame(DTMFFrame, SystemFrame):
     """DTMF keypress input frame from transport."""
@@ -1571,15 +1606,13 @@ class MixerEnableFrame(MixerControlFrame):
 
 
 @dataclass
-class StartUserIdleProcessorFrame(SystemFrame):
-    """Frame to start the UserIdleProcessor monitoring."""
+class ServiceSwitcherFrame(ControlFrame):
+    """A base class for frames that affect ServiceSwitcher behavior."""
 
 
 @dataclass
-class ServiceSwitcherFrame(ControlFrame):
-    """A base class for frames that control ServiceSwitcher behavior."""
-
-    pass
+class StartUserIdleProcessorFrame(SystemFrame):
+    """Frame to start the UserIdleProcessor monitoring."""
 
 
 @dataclass

pipecat/observers/loggers/debug_log_observer.py

@@ -54,7 +54,7 @@ class DebugLogObserver(BaseObserver):
 
         Log frames with specific source/destination filters::
 
-            from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame
+            from pipecat.frames.frames import InterruptionFrame, 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
@@ -62,8 +62,8 @@ class DebugLogObserver(BaseObserver):
             observers=[
                 DebugLogObserver(
                     frame_types={
-                        # Only log StartInterruptionFrame when source is BaseOutputTransport
-                        StartInterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE),
+                        # Only log InterruptionFrame when source is BaseOutputTransport
+                        InterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE),
                         # Only log UserStartedSpeakingFrame when destination is STTService
                         UserStartedSpeakingFrame: (STTService, FrameEndpoint.DESTINATION),
                         # Log LLMTextFrame regardless of source or destination type

pipecat/observers/loggers/llm_log_observer.py

@@ -11,6 +11,7 @@ from loguru import logger
 from pipecat.frames.frames import (
     FunctionCallInProgressFrame,
     FunctionCallResultFrame,
+    LLMContextFrame,
     LLMFullResponseEndFrame,
     LLMFullResponseStartFrame,
     LLMMessagesFrame,
@@ -79,10 +80,13 @@ class LLMLogObserver(BaseObserver):
                 f"🧠 {arrow} {dst} LLM MESSAGES FRAME: {frame.messages} at {time_sec:.2f}s"
             )
         # Log OpenAILLMContextFrame (input)
-        elif isinstance(frame, OpenAILLMContextFrame):
-            logger.debug(
-                f"🧠 {arrow} {dst} LLM CONTEXT FRAME: {frame.context.messages} at {time_sec:.2f}s"
+        elif isinstance(frame, (LLMContextFrame, OpenAILLMContextFrame)):
+            messages = (
+                frame.context.messages
+                if isinstance(frame, OpenAILLMContextFrame)
+                else frame.context.get_messages()
             )
+            logger.debug(f"🧠 {arrow} {dst} LLM CONTEXT FRAME: {messages} at {time_sec:.2f}s")
         # Log function call result (input)
         elif isinstance(frame, FunctionCallResultFrame):
             logger.debug(

pipecat/observers/loggers/user_bot_latency_log_observer.py

@@ -61,17 +61,29 @@ class UserBotLatencyLogObserver(BaseObserver):
         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"
-                )
+            self._log_summary()
         elif isinstance(data.frame, BotStartedSpeakingFrame) and self._user_stopped_time:
             latency = time.time() - self._user_stopped_time
             self._user_stopped_time = 0
             self._latencies.append(latency)
-            logger.debug(
-                f"⏱️ LATENCY FROM USER STOPPED SPEAKING TO BOT STARTED SPEAKING: {latency:.3f}s"
-            )
+            self._log_latency(latency)
+
+    def _log_summary(self):
+        if not self._latencies:
+            return
+        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"
+        )
+
+    def _log_latency(self, latency: float):
+        """Log the latency.
+
+        Args:
+            latency: The latency to log.
+        """
+        logger.debug(
+            f"⏱️ LATENCY FROM USER STOPPED SPEAKING TO BOT STARTED SPEAKING: {latency:.3f}s"
+        )

pipecat/pipeline/runner.py

@@ -106,13 +106,21 @@ class PipelineRunner(BaseObject):
 
     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())
+        try:
+            loop = asyncio.get_running_loop()
+            loop.add_signal_handler(signal.SIGINT, lambda *args: self._sig_handler())
+        except NotImplementedError:
+            # Windows fallback
+            signal.signal(signal.SIGINT, lambda s, f: 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())
+        try:
+            loop = asyncio.get_running_loop()
+            loop.add_signal_handler(signal.SIGTERM, lambda *args: self._sig_handler())
+        except NotImplementedError:
+            # Windows fallback
+            signal.signal(signal.SIGTERM, lambda s, f: self._sig_handler())
 
     def _sig_handler(self):
         """Handle interrupt signals by cancelling all tasks."""

pipecat/pipeline/service_switcher.py

@@ -6,9 +6,15 @@
 
 """Service switcher for switching between different services at runtime, with different switching strategies."""
 
+from dataclasses import dataclass
 from typing import Any, Generic, List, Optional, Type, TypeVar
 
-from pipecat.frames.frames import Frame, ManuallySwitchServiceFrame, ServiceSwitcherFrame
+from pipecat.frames.frames import (
+    ControlFrame,
+    Frame,
+    ManuallySwitchServiceFrame,
+    ServiceSwitcherFrame,
+)
 from pipecat.pipeline.parallel_pipeline import ParallelPipeline
 from pipecat.processors.filters.function_filter import FunctionFilter
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
@@ -22,19 +28,6 @@ class ServiceSwitcherStrategy:
         self.services = services
         self.active_service: Optional[FrameProcessor] = None
 
-    def is_active(self, service: FrameProcessor) -> bool:
-        """Determine if the given service is the currently active one.
-
-        This method should be overridden by subclasses to implement specific logic.
-
-        Args:
-            service: The service to check.
-
-        Returns:
-            True if the given service is the active one, False otherwise.
-        """
-        raise NotImplementedError("Subclasses must implement this method.")
-
     def handle_frame(self, frame: ServiceSwitcherFrame, direction: FrameDirection):
         """Handle a frame that controls service switching.
 
@@ -60,17 +53,6 @@ class ServiceSwitcherStrategyManual(ServiceSwitcherStrategy):
         super().__init__(services)
         self.active_service = services[0] if services else None
 
-    def is_active(self, service: FrameProcessor) -> bool:
-        """Check if the given service is the currently active one.
-
-        Args:
-            service: The service to check.
-
-        Returns:
-            True if the given service is the active one, False otherwise.
-        """
-        return service == self.active_service
-
     def handle_frame(self, frame: ServiceSwitcherFrame, direction: FrameDirection):
         """Handle a frame that controls service switching.
 
@@ -79,20 +61,21 @@ class ServiceSwitcherStrategyManual(ServiceSwitcherStrategy):
             direction: The direction of the frame (upstream or downstream).
         """
         if isinstance(frame, ManuallySwitchServiceFrame):
-            self._set_active(frame.service)
+            self._set_active_if_available(frame.service)
         else:
             raise ValueError(f"Unsupported frame type: {type(frame)}")
 
-    def _set_active(self, service: FrameProcessor):
-        """Set the active service to the given one.
+    def _set_active_if_available(self, service: FrameProcessor):
+        """Set the active service to the given one, if it is in the list of available services.
+
+        If it's not in the list, the request is ignored, as it may have been
+        intended for another ServiceSwitcher in the pipeline.
 
         Args:
             service: The service to set as active.
         """
         if service in self.services:
             self.active_service = service
-        else:
-            raise ValueError(f"Service {service} is not in the list of available services.")
 
 
 StrategyType = TypeVar("StrategyType", bound=ServiceSwitcherStrategy)
@@ -108,6 +91,43 @@ class ServiceSwitcher(ParallelPipeline, Generic[StrategyType]):
         self.services = services
         self.strategy = strategy
 
+    class ServiceSwitcherFilter(FunctionFilter):
+        """An internal filter that allows frames to pass through to the wrapped service only if it's the active service."""
+
+        def __init__(
+            self,
+            wrapped_service: FrameProcessor,
+            active_service: FrameProcessor,
+            direction: FrameDirection,
+        ):
+            """Initialize the service switcher filter with a strategy and direction."""
+
+            async def filter(_: Frame) -> bool:
+                return self._wrapped_service == self._active_service
+
+            super().__init__(filter, direction)
+            self._wrapped_service = wrapped_service
+            self._active_service = active_service
+
+        async def process_frame(self, frame, direction):
+            """Process a frame through the filter, handling special internal filter-updating frames."""
+            if isinstance(frame, ServiceSwitcher.ServiceSwitcherFilterFrame):
+                self._active_service = frame.active_service
+                # Two ServiceSwitcherFilters "sandwich" a service. Push the
+                # frame only to update the other side of the sandwich, but
+                # otherwise don't let it leave the sandwich.
+                if direction == self._direction:
+                    await self.push_frame(frame, direction)
+                return
+
+            await super().process_frame(frame, direction)
+
+    @dataclass
+    class ServiceSwitcherFilterFrame(ControlFrame):
+        """An internal frame used by ServiceSwitcher to filter frames based on active service."""
+
+        active_service: FrameProcessor
+
     @staticmethod
     def _make_pipeline_definitions(
         services: List[FrameProcessor], strategy: ServiceSwitcherStrategy
@@ -121,14 +141,18 @@ class ServiceSwitcher(ParallelPipeline, Generic[StrategyType]):
     def _make_pipeline_definition(
         service: FrameProcessor, strategy: ServiceSwitcherStrategy
     ) -> Any:
-        async def filter(frame) -> bool:
-            _ = frame
-            return strategy.is_active(service)
-
         return [
-            FunctionFilter(filter, direction=FrameDirection.DOWNSTREAM),
+            ServiceSwitcher.ServiceSwitcherFilter(
+                wrapped_service=service,
+                active_service=strategy.active_service,
+                direction=FrameDirection.DOWNSTREAM,
+            ),
             service,
-            FunctionFilter(filter, direction=FrameDirection.UPSTREAM),
+            ServiceSwitcher.ServiceSwitcherFilter(
+                wrapped_service=service,
+                active_service=strategy.active_service,
+                direction=FrameDirection.UPSTREAM,
+            ),
         ]
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
@@ -142,3 +166,7 @@ class ServiceSwitcher(ParallelPipeline, Generic[StrategyType]):
 
         if isinstance(frame, ServiceSwitcherFrame):
             self.strategy.handle_frame(frame, direction)
+            service_switcher_filter_frame = ServiceSwitcher.ServiceSwitcherFilterFrame(
+                active_service=self.strategy.active_service
+            )
+            await super().process_frame(service_switcher_filter_frame, direction)