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

pipecat/transports/tavus/transport.py

@@ -25,11 +25,11 @@ from pipecat.frames.frames import (
     EndFrame,
     Frame,
     InputAudioRawFrame,
+    InterruptionFrame,
     OutputAudioRawFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, FrameProcessorSetup
 from pipecat.transports.base_input import BaseInputTransport
@@ -221,6 +221,7 @@ class TavusTransportClient:
                 ),
                 on_joined=self._on_joined,
                 on_left=self._on_left,
+                on_before_leave=partial(self._on_handle_callback, "on_before_leave"),
                 on_error=partial(self._on_handle_callback, "on_error"),
                 on_app_message=partial(self._on_handle_callback, "on_app_message"),
                 on_call_state_updated=partial(self._on_handle_callback, "on_call_state_updated"),
@@ -344,7 +345,9 @@ class TavusTransportClient:
             participant_id, callback, audio_source, sample_rate, callback_interval_ms
         )
 
-    async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+    async def send_message(
+        self, frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame
+    ):
         """Send a message to participants.
 
         Args:
@@ -372,7 +375,7 @@ class TavusTransportClient:
 
     async def send_interrupt_message(self) -> None:
         """Send an interrupt message to the conversation."""
-        transport_frame = TransportMessageUrgentFrame(
+        transport_frame = OutputTransportMessageUrgentFrame(
             message={
                 "message_type": "conversation",
                 "event_type": "conversation.interrupt",
@@ -395,15 +398,18 @@ class TavusTransportClient:
             participant_settings=participant_settings, profile_settings=profile_settings
         )
 
-    async def write_audio_frame(self, frame: OutputAudioRawFrame):
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         """Write an audio frame to the transport.
 
         Args:
             frame: The audio frame to write.
+
+        Returns:
+            True if the audio frame was written successfully, False otherwise.
         """
         if not self._client:
-            return
-        await self._client.write_audio_frame(frame)
+            return False
+        return await self._client.write_audio_frame(frame)
 
     async def register_audio_destination(self, destination: str):
         """Register an audio destination for output.
@@ -601,7 +607,9 @@ class TavusOutputTransport(BaseOutputTransport):
         await super().cancel(frame)
         await self._client.stop()
 
-    async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+    async def send_message(
+        self, frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame
+    ):
         """Send a message to participants.
 
         Args:
@@ -618,22 +626,25 @@ class TavusOutputTransport(BaseOutputTransport):
             direction: The direction of frame flow in the pipeline.
         """
         await super().process_frame(frame, direction)
-        if isinstance(frame, StartInterruptionFrame):
+        if isinstance(frame, InterruptionFrame):
             await self._handle_interruptions()
 
     async def _handle_interruptions(self):
         """Handle interruption events by sending interrupt message."""
         await self._client.send_interrupt_message()
 
-    async def write_audio_frame(self, frame: OutputAudioRawFrame):
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         """Write an audio frame to the Tavus transport.
 
         Args:
             frame: The audio frame to write.
+
+        Returns:
+            True if the audio frame was written successfully, False otherwise.
         """
         # This is the custom track destination expected by Tavus
         frame.transport_destination = self._transport_destination
-        await self._client.write_audio_frame(frame)
+        return await self._client.write_audio_frame(frame)
 
     async def register_audio_destination(self, destination: str):
         """Register an audio destination.

pipecat/transports/websocket/client.py

@@ -28,9 +28,9 @@ from pipecat.frames.frames import (
     Frame,
     InputAudioRawFrame,
     OutputAudioRawFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.processors.frame_processor import FrameProcessorSetup
 from pipecat.serializers.base_serializer import FrameSerializer
@@ -150,17 +150,39 @@ class WebsocketClientSession:
         await self._websocket.close()
         self._websocket = None
 
-    async def send(self, message: websockets.Data):
+    async def send(self, message: websockets.Data) -> bool:
         """Send a message through the WebSocket connection.
 
         Args:
             message: The message data to send.
         """
+        result = False
         try:
             if self._websocket:
                 await self._websocket.send(message)
+                result = True
         except Exception as e:
             logger.error(f"{self} exception sending data: {e.__class__.__name__} ({e})")
+        finally:
+            return result
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if the WebSocket is currently connected.
+
+        Returns:
+            True if the WebSocket is in connected state.
+        """
+        return self._websocket.state == websockets.State.OPEN if self._websocket else False
+
+    @property
+    def is_closing(self) -> bool:
+        """Check if the WebSocket is currently closing.
+
+        Returns:
+            True if the WebSocket is in the process of closing.
+        """
+        return self._websocket.state == websockets.State.CLOSING if self._websocket else False
 
     async def _client_task_handler(self):
         """Handle incoming messages from the WebSocket connection."""
@@ -363,7 +385,9 @@ class WebsocketClientOutputTransport(BaseOutputTransport):
         await super().cleanup()
         await self._transport.cleanup()
 
-    async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+    async def send_message(
+        self, frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame
+    ):
         """Send a transport message through the WebSocket.
 
         Args:
@@ -371,12 +395,18 @@ class WebsocketClientOutputTransport(BaseOutputTransport):
         """
         await self._write_frame(frame)
 
-    async def write_audio_frame(self, frame: OutputAudioRawFrame):
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         """Write an audio frame to the WebSocket with optional WAV header.
 
         Args:
             frame: The output audio frame to write.
+
+        Returns:
+            True if the audio frame was written successfully, False otherwise.
         """
+        if self._session.is_closing or not self._session.is_connected:
+            return False
+
         frame = OutputAudioRawFrame(
             audio=frame.audio,
             sample_rate=self.sample_rate,
@@ -402,10 +432,16 @@ class WebsocketClientOutputTransport(BaseOutputTransport):
         # Simulate audio playback with a sleep.
         await self._write_audio_sleep()
 
+        return True
+
     async def _write_frame(self, frame: Frame):
         """Write a frame to the WebSocket after serialization."""
+        if self._session.is_closing or not self._session.is_connected:
+            return
+
         if not self._params.serializer:
             return
+
         payload = await self._params.serializer.serialize(frame)
         if payload:
             await self._session.send(payload)

pipecat/transports/websocket/fastapi.py

@@ -26,11 +26,11 @@ from pipecat.frames.frames import (
     EndFrame,
     Frame,
     InputAudioRawFrame,
+    InterruptionFrame,
     OutputAudioRawFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.processors.frame_processor import FrameDirection
 from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
@@ -150,7 +150,6 @@ class FastAPIWebsocketClient:
                     "Closing already disconnected websocket!", call_id=self._conversation_id
                 )
                 self._closing = True
-                await self.trigger_client_disconnected()
 
     async def disconnect(self):
         """Disconnect the WebSocket client."""
@@ -164,8 +163,6 @@ class FastAPIWebsocketClient:
                 await self._websocket.close()
             except Exception as e:
                 logger.error(f"{self} exception while closing the websocket: {e}")
-            finally:
-                await self.trigger_client_disconnected()
 
     async def trigger_client_disconnected(self):
         """Trigger the client disconnected callback."""
@@ -310,7 +307,10 @@ class FastAPIWebsocketInputTransport(BaseInputTransport):
         except Exception as e:
             logger.error(f"{self} exception receiving data: {e.__class__.__name__} ({e})")
 
-        await self._client.trigger_client_disconnected()
+        # Trigger `on_client_disconnected` if the client actually disconnects,
+        # that is, we are not the ones disconnecting.
+        if not self._client.is_closing:
+            await self._client.trigger_client_disconnected()
 
     async def _monitor_websocket(self):
         """Wait for self._params.session_timeout seconds, if the websocket is still open, trigger timeout event."""
@@ -410,11 +410,13 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport):
         """
         await super().process_frame(frame, direction)
 
-        if isinstance(frame, StartInterruptionFrame):
+        if isinstance(frame, InterruptionFrame):
             await self._write_frame(frame)
             self._next_send_time = 0
 
-    async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+    async def send_message(
+        self, frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame
+    ):
         """Send a transport message frame.
 
         Args:
@@ -422,14 +424,17 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport):
         """
         await self._write_frame(frame)
 
-    async def write_audio_frame(self, frame: OutputAudioRawFrame):
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         """Write an audio frame to the WebSocket with timing simulation.
 
         Args:
             frame: The output audio frame to write.
+
+        Returns:
+            True if the audio frame was written successfully, False otherwise.
         """
         if self._client.is_closing or not self._client.is_connected:
-            return
+            return False
 
         frame = OutputAudioRawFrame(
             audio=frame.audio,
@@ -456,8 +461,13 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport):
         # Simulate audio playback with a sleep.
         await self._write_audio_sleep()
 
+        return True
+
     async def _write_frame(self, frame: Frame):
         """Serialize and send a frame through the WebSocket."""
+        if self._client.is_closing or not self._client.is_connected:
+            return
+
         if not self._params.serializer:
             return
 

pipecat/transports/websocket/server.py

@@ -25,11 +25,11 @@ from pipecat.frames.frames import (
     EndFrame,
     Frame,
     InputAudioRawFrame,
+    InterruptionFrame,
     OutputAudioRawFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.processors.frame_processor import FrameDirection
 from pipecat.serializers.base_serializer import FrameSerializer
@@ -334,11 +334,13 @@ class WebsocketServerOutputTransport(BaseOutputTransport):
         """
         await super().process_frame(frame, direction)
 
-        if isinstance(frame, StartInterruptionFrame):
+        if isinstance(frame, InterruptionFrame):
             await self._write_frame(frame)
             self._next_send_time = 0
 
-    async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+    async def send_message(
+        self, frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame
+    ):
         """Send a transport message frame to the client.
 
         Args:
@@ -346,14 +348,17 @@ class WebsocketServerOutputTransport(BaseOutputTransport):
         """
         await self._write_frame(frame)
 
-    async def write_audio_frame(self, frame: OutputAudioRawFrame):
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         """Write an audio frame to the WebSocket client with timing control.
 
         Args:
             frame: The output audio frame to write.
+
+        Returns:
+            True if the audio frame was written successfully, False otherwise.
         """
         if not self._websocket:
-            return
+            return False
 
         frame = OutputAudioRawFrame(
             audio=frame.audio,
@@ -380,6 +385,8 @@ class WebsocketServerOutputTransport(BaseOutputTransport):
         # Simulate audio playback with a sleep.
         await self._write_audio_sleep()
 
+        return True
+
     async def _write_frame(self, frame: Frame):
         """Serialize and send a frame to the WebSocket client."""
         if not self._params.serializer:

pipecat/transports/whatsapp/api.py

@@ -241,6 +241,14 @@ class WhatsAppApi:
         self._whatsapp_url = f"{self.BASE_URL}{phone_number_id}/calls"
         self._whatsapp_token = whatsapp_token
 
+    def update_whatsapp_token(self, whatsapp_token: str):
+        """Update the WhatsApp access token for authentication."""
+        self._whatsapp_token = whatsapp_token
+
+    def update_whatsapp_phone_number_id(self, phone_number_id: str):
+        """Update the WhatsApp phone number ID for authentication."""
+        self._phone_number_id = phone_number_id
+
     async def answer_call_to_whatsapp(self, call_id: str, action: str, sdp: str, from_: str):
         """Answer an incoming WhatsApp call.
 

pipecat/transports/whatsapp/client.py

@@ -12,6 +12,8 @@ WhatsApp call events.
 """
 
 import asyncio
+import hashlib
+import hmac
 from typing import Awaitable, Callable, Dict, List, Optional
 
 import aiohttp
@@ -47,6 +49,7 @@ class WhatsAppClient:
         phone_number_id: str,
         session: aiohttp.ClientSession,
         ice_servers: Optional[List[IceServer]] = None,
+        whatsapp_secret: Optional[str] = None,
     ) -> None:
         """Initialize the WhatsApp client.
 
@@ -56,10 +59,12 @@ class WhatsAppClient:
             session: aiohttp session for making HTTP requests
             ice_servers: List of ICE servers for WebRTC connections. If None,
                         defaults to Google's public STUN server
+            whatsapp_secret: WhatsApp APP secret for validating that the webhook request came from WhatsApp.
         """
         self._whatsapp_api = WhatsAppApi(
             whatsapp_token=whatsapp_token, phone_number_id=phone_number_id, session=session
         )
+        self._whatsapp_secret = whatsapp_secret
         self._ongoing_calls_map: Dict[str, SmallWebRTCConnection] = {}
 
         # Set default ICE servers if none provided
@@ -68,6 +73,22 @@ class WhatsAppClient:
         else:
             self._ice_servers = ice_servers
 
+    def update_ice_servers(self, ice_servers: Optional[List[IceServer]] = None):
+        """Update the list of ICE servers used for WebRTC connections."""
+        self._ice_servers = ice_servers
+
+    def update_whatsapp_secret(self, whatsapp_secret: Optional[str] = None):
+        """Update the WhatsApp APP secret for validating that the webhook request came from WhatsApp."""
+        self._whatsapp_secret = whatsapp_secret
+
+    def update_whatsapp_token(self, whatsapp_token: str):
+        """Update the WhatsApp API access token."""
+        self._whatsapp_api.update_whatsapp_token(whatsapp_token)
+
+    def update_whatsapp_phone_number_id(self, phone_number_id: str):
+        """Update the WhatsApp phone number ID for authentication."""
+        self._whatsapp_api.update_whatsapp_phone_number_id(phone_number_id)
+
     async def terminate_all_calls(self) -> None:
         """Terminate all ongoing WhatsApp calls.
 
@@ -133,10 +154,32 @@ class WhatsAppClient:
 
         return int(challenge)
 
+    async def _validate_whatsapp_webhook_request(self, raw_body: bytes, sha256_signature: str):
+        """Common handler for both /start and /connect endpoints."""
+        # Compute HMAC SHA256 using your App Secret
+        expected_signature = hmac.new(
+            key=self._whatsapp_secret.encode("utf-8"),
+            msg=raw_body,
+            digestmod=hashlib.sha256,
+        ).hexdigest()
+
+        # Extract signature from header (strip 'sha256=' prefix)
+        if not sha256_signature:
+            raise Exception("Missing X-Hub-Signature-256 header")
+        received_signature = sha256_signature.split("sha256=")[-1]
+
+        # Compare signatures securely
+        if not hmac.compare_digest(expected_signature, received_signature):
+            raise Exception("Invalid webhook signature")
+
+        logger.debug(f"Webhook signature verified!")
+
     async def handle_webhook_request(
         self,
         request: WhatsAppWebhookRequest,
         connection_callback: Optional[Callable[[SmallWebRTCConnection], Awaitable[None]]] = None,
+        raw_body: Optional[bytes] = None,
+        sha256_signature: Optional[str] = None,
     ) -> bool:
         """Handle a webhook request from WhatsApp.
 
@@ -150,6 +193,8 @@ class WhatsAppClient:
             connection_callback: Optional callback function to invoke when a new
                                WebRTC connection is established. The callback
                                receives the SmallWebRTCConnection instance.
+            raw_body: Optional bytes containing the raw request body.
+            sha256_signature: Optional X-Hub-Signature-256 header value from the request.
 
         Returns:
             bool: True if the webhook request was handled successfully, False otherwise
@@ -159,6 +204,8 @@ class WhatsAppClient:
             Exception: If connection establishment or API calls fail
         """
         try:
+            if self._whatsapp_secret:
+                await self._validate_whatsapp_webhook_request(raw_body, sha256_signature)
             for entry in request.entry:
                 for change in entry.changes:
                     # Handle connect events

pipecat/utils/base_object.py

@@ -14,13 +14,33 @@ and async cleanup for all Pipecat components.
 import asyncio
 import inspect
 from abc import ABC
-from typing import Optional
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
 
 from loguru import logger
 
 from pipecat.utils.utils import obj_count, obj_id
 
 
+@dataclass
+class EventHandler:
+    """Data class to store event handlers information.
+
+    This data class stores the event name, a list of handlers to run for this
+    event, and whether these handlers will be executed in a task.
+
+    Parameters:
+        name (str): The name of the event handler.
+        handlers (List[Any]): A list of functions to be called when this event is triggered.
+        is_sync (bool): Indicates whether the functions are executed in a task.
+
+    """
+
+    name: str
+    handlers: List[Any]
+    is_sync: bool
+
+
 class BaseObject(ABC):
     """Abstract base class providing common functionality for Pipecat objects.
 
@@ -41,7 +61,7 @@ class BaseObject(ABC):
         self._name = name or f"{self.__class__.__name__}#{obj_count(self)}"
 
         # Registered event handlers.
-        self._event_handlers: dict = {}
+        self._event_handlers: Dict[str, EventHandler] = {}
 
         # Set of tasks being executed. When a task finishes running it gets
         # automatically removed from the set. When we cleanup we wait for all
@@ -103,20 +123,23 @@ class BaseObject(ABC):
                 Can be sync or async.
         """
         if event_name in self._event_handlers:
-            self._event_handlers[event_name].append(handler)
+            self._event_handlers[event_name].handlers.append(handler)
         else:
             logger.warning(f"Event handler {event_name} not registered")
 
-    def _register_event_handler(self, event_name: str):
+    def _register_event_handler(self, event_name: str, sync: bool = False):
         """Register an event handler type.
 
         Args:
             event_name: The name of the event type to register.
+            sync: Whether this event handler will be executed in a task.
         """
         if event_name not in self._event_handlers:
-            self._event_handlers[event_name] = []
+            self._event_handlers[event_name] = EventHandler(
+                name=event_name, handlers=[], is_sync=sync
+            )
         else:
-            logger.warning(f"Event handler {event_name} not registered")
+            logger.warning(f"Event handler {event_name} already registered")
 
     async def _call_event_handler(self, event_name: str, *args, **kwargs):
         """Call all registered handlers for the specified event.
@@ -126,34 +149,43 @@ class BaseObject(ABC):
             *args: Positional arguments to pass to event handlers.
             **kwargs: Keyword arguments to pass to event handlers.
         """
-        # If we haven't registered an event handler, we don't need to do
-        # anything.
-        if not self._event_handlers.get(event_name):
+        if event_name not in self._event_handlers:
             return
 
-        # Create the task.
-        task = asyncio.create_task(self._run_task(event_name, *args, **kwargs))
+        event_handler = self._event_handlers[event_name]
+
+        for handler in event_handler.handlers:
+            if event_handler.is_sync:
+                # Just run the handler.
+                await self._run_handler(event_handler.name, handler, *args, **kwargs)
+            else:
+                # Create the task. Note that this is a task per each function
+                # handler. Users can register to an event handler multiple
+                # times.
+                task = asyncio.create_task(
+                    self._run_handler(event_handler.name, handler, *args, **kwargs)
+                )
 
-        # Add it to our list of event tasks.
-        self._event_tasks.add((event_name, task))
+                # Add it to our list of event tasks.
+                self._event_tasks.add((event_name, task))
 
-        # Remove the task from the event tasks list when the task completes.
-        task.add_done_callback(self._event_task_finished)
+                # Remove the task from the event tasks list when the task completes.
+                task.add_done_callback(self._event_task_finished)
 
-    async def _run_task(self, event_name: str, *args, **kwargs):
+    async def _run_handler(self, event_name: str, handler, *args, **kwargs):
         """Execute all handlers for an event.
 
         Args:
-            event_name: The name of the event being handled.
+            event_name: The event name for this handler.
+            handler: The handler function to run.
             *args: Positional arguments to pass to handlers.
             **kwargs: Keyword arguments to pass to handlers.
         """
         try:
-            for handler in self._event_handlers[event_name]:
-                if inspect.iscoroutinefunction(handler):
-                    await handler(self, *args, **kwargs)
-                else:
-                    handler(self, *args, **kwargs)
+            if inspect.iscoroutinefunction(handler):
+                await handler(self, *args, **kwargs)
+            else:
+                handler(self, *args, **kwargs)
         except Exception as e:
             logger.exception(f"Exception in event handler {event_name}: {e}")
 

pipecat/utils/string.py

@@ -21,13 +21,24 @@ import re
 from typing import FrozenSet, Optional, Sequence, Tuple
 
 import nltk
+from loguru import logger
 from nltk.tokenize import sent_tokenize
 
 # Ensure punkt_tab tokenizer data is available
 try:
     nltk.data.find("tokenizers/punkt_tab")
 except LookupError:
-    nltk.download("punkt_tab", quiet=True)
+    try:
+        nltk.download("punkt_tab", quiet=True)
+    except (OSError, PermissionError) as e:
+        logger.error(
+            f"Failed to download NLTK 'punkt_tab' tokenizer data: {e}. "
+            "This data is required for sentence tokenization features. "
+            "The download failed due to filesystem permissions. "
+            "To resolve: pre-install the data in a location with appropriate read permissions, "
+            "or set the NLTK_DATA environment variable to point to a writable directory. "
+            "See https://www.nltk.org/data.html for more information."
+        )
 
 SENTENCE_ENDING_PUNCTUATION: FrozenSet[str] = frozenset(
     {