dv-pipecat-ai 0.0.82.dev815__py3-none-any.whl → 0.0.82.dev857__py3-none-any.whl

pipecat/frames/frames.py

@@ -12,7 +12,6 @@ and LLM processing.
 """
 
 from dataclasses import dataclass, field
-from enum import Enum
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -27,6 +26,8 @@ from typing import (
     Tuple,
 )
 
+from pipecat.adapters.schemas.tools_schema import ToolsSchema
+from pipecat.audio.dtmf.types import KeypadEntry as NewKeypadEntry
 from pipecat.audio.interruptions.base_interruption_strategy import BaseInterruptionStrategy
 from pipecat.audio.turn.smart_turn.base_smart_turn import SmartTurnParams
 from pipecat.audio.vad.vad_analyzer import VADParams
@@ -36,12 +37,17 @@ from pipecat.utils.time import nanoseconds_to_str
 from pipecat.utils.utils import obj_count, obj_id
 
 if TYPE_CHECKING:
+    from pipecat.processors.aggregators.llm_context import LLMContext, NotGiven
     from pipecat.processors.frame_processor import FrameProcessor
 
 
-class KeypadEntry(str, Enum):
+class DeprecatedKeypadEntry:
     """DTMF keypad entries for phone system integration.
 
+    .. deprecated:: 0.0.82
+        This class is deprecated and will be removed in a future version.
+        Instead, use `audio.dtmf.types.KeypadEntry`.
+
     Parameters:
         ONE: Number key 1.
         TWO: Number key 2.
@@ -57,18 +63,38 @@ class KeypadEntry(str, Enum):
         STAR: Star/asterisk key (*).
     """
 
-    ONE = "1"
-    TWO = "2"
-    THREE = "3"
-    FOUR = "4"
-    FIVE = "5"
-    SIX = "6"
-    SEVEN = "7"
-    EIGHT = "8"
-    NINE = "9"
-    ZERO = "0"
-    POUND = "#"
-    STAR = "*"
+    _enum = NewKeypadEntry
+
+    @classmethod
+    def _warn(cls):
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "`pipecat.frames.frames.KeypadEntry` is deprecated and will be removed in a future version. "
+                "Use `pipecat.audio.dtmf.types.KeypadEntry` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Allow the instance to be called as a function."""
+        self._warn()
+        return self._enum(*args, **kwargs)
+
+    def __getattr__(self, name):
+        """Retrieve an attribute from the underlying enum."""
+        self._warn()
+        return getattr(self._enum, name)
+
+    def __getitem__(self, name):
+        """Retrieve an item from the underlying enum."""
+        self._warn()
+        return self._enum[name]
+
+
+KeypadEntry = DeprecatedKeypadEntry()
 
 
 def format_pts(pts: Optional[int]):
@@ -303,6 +329,11 @@ class TextFrame(DataFrame):
     """
 
     text: str
+    skip_tts: bool = field(init=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.skip_tts = False
 
     def __str__(self):
         pts = format_pts(self.pts)
@@ -403,6 +434,11 @@ class OpenAILLMContextAssistantTimestampFrame(DataFrame):
     timestamp: str
 
 
+# A more universal (LLM-agnostic) name for
+# OpenAILLMContextAssistantTimestampFrame, matching LLMContext
+LLMContextAssistantTimestampFrame = OpenAILLMContextAssistantTimestampFrame
+
+
 @dataclass
 class TranscriptionMessage:
     """A message in a conversation transcript.
@@ -474,6 +510,20 @@ class TranscriptionUpdateFrame(DataFrame):
         return f"{self.name}(pts: {pts}, messages: {len(self.messages)})"
 
 
+@dataclass
+class LLMContextFrame(Frame):
+    """Frame containing a universal LLM context.
+
+    Used as a signal to LLM services to ingest the provided context and
+    generate a response based on it.
+
+    Parameters:
+        context: The LLM context containing messages, tools, and configuration.
+    """
+
+    context: "LLMContext"
+
+
 @dataclass
 class LLMMessagesFrame(DataFrame):
     """Frame containing LLM messages for chat completion.
@@ -500,15 +550,27 @@ class LLMMessagesFrame(DataFrame):
         super().__post_init__()
         import warnings
 
-        warnings.simplefilter("always")
-        warnings.warn(
-            "LLMMessagesFrame is deprecated and will be removed in a future version. "
-            "Instead, use either "
-            "`LLMMessagesUpdateFrame` with `run_llm=True`, or "
-            "`OpenAILLMContextFrame` with desired messages in a new context",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "LLMMessagesFrame is deprecated and will be removed in a future version. "
+                "Instead, use either "
+                "`LLMMessagesUpdateFrame` with `run_llm=True`, or "
+                "`OpenAILLMContextFrame` with desired messages in a new context",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+
+@dataclass
+class LLMRunFrame(DataFrame):
+    """Frame to trigger LLM processing with current context.
+
+    A frame that instructs the LLM service to process the current context and
+    generate a response.
+    """
+
+    pass
 
 
 @dataclass
@@ -531,9 +593,8 @@ class LLMMessagesAppendFrame(DataFrame):
 class LLMMessagesUpdateFrame(DataFrame):
     """Frame containing LLM messages to replace current context.
 
-    A frame containing a list of new LLM messages. These messages will
-    replace the current context LLM messages and should generate a new
-    LLMMessagesFrame.
+    A frame containing a list of new LLM messages to replace the current
+    context LLM messages.
 
     Parameters:
         messages: List of message dictionaries to replace current context.
@@ -556,7 +617,7 @@ class LLMSetToolsFrame(DataFrame):
         tools: List of tool/function definitions for the LLM.
     """
 
-    tools: List[dict]
+    tools: List[dict] | ToolsSchema | "NotGiven"
 
 
 @dataclass
@@ -581,6 +642,21 @@ class LLMEnablePromptCachingFrame(DataFrame):
     enable: bool
 
 
+@dataclass
+class LLMConfigureOutputFrame(DataFrame):
+    """Frame to configure LLM output.
+
+    This frame is used to configure how the LLM produces output. For example, it
+    can tell the LLM to generate tokens that should be added to the context but
+    not spoken by the TTS service (if one is present in the pipeline).
+
+    Parameters:
+        skip_tts: Whether LLM tokens should skip the TTS service (if any).
+    """
+
+    skip_tts: bool
+
+
 @dataclass
 class TTSSpeakFrame(DataFrame):
     """Frame containing text that should be spoken by TTS.
@@ -617,7 +693,7 @@ class DTMFFrame:
         button: The DTMF keypad entry that was pressed.
     """
 
-    button: KeypadEntry
+    button: NewKeypadEntry
 
 
 @dataclass
@@ -793,19 +869,6 @@ class StartInterruptionFrame(SystemFrame):
     pass
 
 
-@dataclass
-class StopInterruptionFrame(SystemFrame):
-    """Frame indicating user stopped speaking (interruption ended).
-
-    Emitted by the BaseInputTransport to indicate that a user has stopped
-    speaking (i.e. no more interruptions). This is similar to
-    UserStoppedSpeakingFrame except that it should be pushed concurrently
-    with other frames (so the order is not guaranteed).
-    """
-
-    pass
-
-
 @dataclass
 class UserStartedSpeakingFrame(SystemFrame):
     """Frame indicating user has started speaking.
@@ -835,6 +898,16 @@ class UserStoppedSpeakingFrame(SystemFrame):
     emulated: bool = False
 
 
+@dataclass
+class UserSpeakingFrame(SystemFrame):
+    """Frame indicating the user is speaking.
+
+    Emitted by VAD to indicate the user is speaking.
+    """
+
+    pass
+
+
 @dataclass
 class EmulateUserStartedSpeakingFrame(SystemFrame):
     """Frame to emulate user started speaking behavior.
@@ -1055,6 +1128,23 @@ class TransportMessageUrgentFrame(SystemFrame):
         return f"{self.name}(message: {self.message})"
 
 
+@dataclass
+class InputTransportMessageUrgentFrame(TransportMessageUrgentFrame):
+    """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.
+
+    Used by transport implementations to properly handle bidirectional message
+    flow without creating feedback loops.
+    """
+
+    pass
+
+
 @dataclass
 class UserImageRequestFrame(SystemFrame):
     """Frame requesting an image from a specific user.
@@ -1310,14 +1400,22 @@ class LLMFullResponseStartFrame(ControlFrame):
     more TextFrames and a final LLMFullResponseEndFrame.
     """
 
-    pass
+    skip_tts: bool = field(init=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.skip_tts = False
 
 
 @dataclass
 class LLMFullResponseEndFrame(ControlFrame):
     """Frame indicating the end of an LLM response."""
 
-    pass
+    skip_tts: bool = field(init=False)
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.skip_tts = False
 
 
 @dataclass
@@ -1451,6 +1549,11 @@ class MixerEnableFrame(MixerControlFrame):
 class StartUserIdleProcessorFrame(SystemFrame):
     """Frame to start the UserIdleProcessor monitoring."""
 
+
+@dataclass
+class ServiceSwitcherFrame(ControlFrame):
+    """A base class for frames that control ServiceSwitcher behavior."""
+
     pass
 
 
@@ -1466,3 +1569,13 @@ class WaitForDTMFFrame(ControlFrame):
     """Frame to stop the UserIdleProcessor monitoring."""
 
     pass
+
+
+@dataclass
+class ManuallySwitchServiceFrame(ServiceSwitcherFrame):
+    """A frame to request a manual switch in the active service in a ServiceSwitcher.
+
+    Handled by ServiceSwitcherStrategyManual to switch the active service.
+    """
+
+    service: "FrameProcessor"

pipecat/pipeline/llm_switcher.py

@@ -0,0 +1,76 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""LLM switcher for switching between different LLMs at runtime, with different switching strategies."""
+
+from typing import Any, List, Optional, Type
+
+from pipecat.pipeline.service_switcher import ServiceSwitcher, StrategyType
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.services.llm_service import LLMService
+
+
+class LLMSwitcher(ServiceSwitcher[StrategyType]):
+    """A pipeline that switches between different LLMs at runtime."""
+
+    def __init__(self, llms: List[LLMService], strategy_type: Type[StrategyType]):
+        """Initialize the service switcher with a list of LLMs and a switching strategy."""
+        super().__init__(llms, strategy_type)
+
+    @property
+    def llms(self) -> List[LLMService]:
+        """Get the list of LLMs managed by this switcher."""
+        return self.services
+
+    @property
+    def active_llm(self) -> Optional[LLMService]:
+        """Get the currently active LLM, if any."""
+        return self.strategy.active_service
+
+    async def run_inference(self, context: LLMContext) -> Optional[str]:
+        """Run a one-shot, out-of-band (i.e. out-of-pipeline) inference with the given LLM context, using the currently active LLM.
+
+        Args:
+            context: The LLM context containing conversation history.
+
+        Returns:
+            The LLM's response as a string, or None if no response is generated.
+        """
+        if self.active_llm:
+            return await self.active_llm.run_inference(context=context)
+        return None
+
+    def register_function(
+        self,
+        function_name: Optional[str],
+        handler: Any,
+        start_callback=None,
+        *,
+        cancel_on_interruption: bool = True,
+    ):
+        """Register a function handler for LLM function calls, on all LLMs, active or not.
+
+        Args:
+            function_name: The name of the function to handle. Use None to handle
+                all function calls with a catch-all handler.
+            handler: The function handler. Should accept a single FunctionCallParams
+                parameter.
+            start_callback: Legacy callback function (deprecated). Put initialization
+                code at the top of your handler instead.
+
+                .. deprecated:: 0.0.59
+                    The `start_callback` parameter is deprecated and will be removed in a future version.
+
+            cancel_on_interruption: Whether to cancel this function call when an
+                interruption occurs. Defaults to True.
+        """
+        for llm in self.llms:
+            llm.register_function(
+                function_name=function_name,
+                handler=handler,
+                start_callback=start_callback,
+                cancel_on_interruption=cancel_on_interruption,
+            )

pipecat/pipeline/parallel_pipeline.py

@@ -16,7 +16,7 @@ from typing import Dict, List
 
 from loguru import logger
 
-from pipecat.frames.frames import EndFrame, Frame, StartFrame
+from pipecat.frames.frames import CancelFrame, EndFrame, Frame, StartFrame
 from pipecat.pipeline.base_pipeline import BasePipeline
 from pipecat.pipeline.pipeline import Pipeline, PipelineSink, PipelineSource
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, FrameProcessorSetup
@@ -141,7 +141,7 @@ class ParallelPipeline(BasePipeline):
         await super().process_frame(frame, direction)
 
         # Parallel pipeline synchronized frames.
-        if isinstance(frame, (StartFrame, EndFrame)):
+        if isinstance(frame, (StartFrame, EndFrame, CancelFrame)):
             self._frame_counter[frame.id] = len(self._pipelines)
             await self.pause_processing_system_frames()
             await self.pause_processing_frames()
@@ -158,7 +158,7 @@ class ParallelPipeline(BasePipeline):
 
     async def _pipeline_sink_push_frame(self, frame: Frame, direction: FrameDirection):
         # Parallel pipeline synchronized frames.
-        if isinstance(frame, (StartFrame, EndFrame)):
+        if isinstance(frame, (StartFrame, EndFrame, CancelFrame)):
             # Decrement counter.
             frame_counter = self._frame_counter.get(frame.id, 0)
             if frame_counter > 0:

pipecat/pipeline/service_switcher.py

@@ -0,0 +1,144 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Service switcher for switching between different services at runtime, with different switching strategies."""
+
+from typing import Any, Generic, List, Optional, Type, TypeVar
+
+from pipecat.frames.frames import 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
+
+
+class ServiceSwitcherStrategy:
+    """Base class for service switching strategies."""
+
+    def __init__(self, services: List[FrameProcessor]):
+        """Initialize the service switcher strategy with a list of services."""
+        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.
+
+        This method can be overridden by subclasses to implement specific logic
+        for handling frames that control service switching.
+
+        Args:
+            frame: The frame to handle.
+            direction: The direction of the frame (upstream or downstream).
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+
+class ServiceSwitcherStrategyManual(ServiceSwitcherStrategy):
+    """A strategy for switching between services manually.
+
+    This strategy allows the user to manually select which service is active.
+    The initial active service is the first one in the list.
+    """
+
+    def __init__(self, services: List[FrameProcessor]):
+        """Initialize the manual service switcher strategy with a list of services."""
+        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.
+
+        Args:
+            frame: The frame to handle.
+            direction: The direction of the frame (upstream or downstream).
+        """
+        if isinstance(frame, ManuallySwitchServiceFrame):
+            self._set_active(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.
+
+        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)
+
+
+class ServiceSwitcher(ParallelPipeline, Generic[StrategyType]):
+    """A pipeline that switches between different services at runtime."""
+
+    def __init__(self, services: List[FrameProcessor], strategy_type: Type[StrategyType]):
+        """Initialize the service switcher with a list of services and a switching strategy."""
+        strategy = strategy_type(services)
+        super().__init__(*self._make_pipeline_definitions(services, strategy))
+        self.services = services
+        self.strategy = strategy
+
+    @staticmethod
+    def _make_pipeline_definitions(
+        services: List[FrameProcessor], strategy: ServiceSwitcherStrategy
+    ) -> List[Any]:
+        pipelines = []
+        for service in services:
+            pipelines.append(ServiceSwitcher._make_pipeline_definition(service, strategy))
+        return pipelines
+
+    @staticmethod
+    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),
+            service,
+            FunctionFilter(filter, direction=FrameDirection.UPSTREAM),
+        ]
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process a frame, handling frames which affect service switching.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of the frame (upstream or downstream).
+        """
+        await super().process_frame(frame, direction)
+
+        if isinstance(frame, ServiceSwitcherFrame):
+            self.strategy.handle_frame(frame, direction)