dv-pipecat-ai 0.0.82.dev857__py3-none-any.whl → 0.0.85.dev837__py3-none-any.whl

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/redis.py

@@ -0,0 +1,58 @@
+"""Async Redis helper utilities."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+from urllib.parse import urlparse
+
+try:
+    import redis.asyncio as redis
+except ImportError:  # pragma: no cover - Redis is optional
+    redis = None
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing aid
+    from redis.asyncio import Redis
+
+
+def create_async_redis_client(
+    url: Optional[str],
+    *,
+    decode_responses: bool = True,
+    encoding: str = "utf-8",
+    logger: Optional[Any] = None,
+    **kwargs,
+) -> Optional["Redis"]:
+    """Return a configured async Redis client or None if unavailable.
+
+    Args:
+        url: Redis connection URL.
+        decode_responses: Whether to decode responses to str.
+        encoding: Character encoding to use with decoded responses.
+        logger: Optional logger supporting .warning() for diagnostics.
+        **kwargs: Additional keyword arguments forwarded to Redis.from_url.
+    """
+    if redis is None:
+        return None
+
+    if not url or url in {"redis_url", "REDIS_URL"}:
+        return None
+
+    parsed = urlparse(url)
+    connection_kwargs = {
+        "decode_responses": decode_responses,
+        "encoding": encoding,
+    }
+    connection_kwargs.update(kwargs)
+
+    if parsed.scheme == "rediss":
+        connection_kwargs.setdefault("ssl_cert_reqs", "none")
+        connection_kwargs.setdefault("ssl_check_hostname", False)
+
+    try:
+        return redis.Redis.from_url(url, **connection_kwargs)
+    except Exception as exc:  # pragma: no cover - best effort logging
+        if logger is not None:
+            logger.warning(f"Failed to create Redis client: {exc}")
+        return None

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(
     {
@@ -36,6 +47,7 @@ SENTENCE_ENDING_PUNCTUATION: FrozenSet[str] = frozenset(
         "!",
         "?",
         ";",
+        "…",
         # East Asian punctuation (Chinese (Traditional & Simplified), Japanese, Korean)
         "。",  # Ideographic full stop
         "？",  # Full-width question mark

pipecat/utils/tracing/service_decorators.py

@@ -651,9 +651,9 @@ def traced_gemini_live(operation: str) -> Callable:
 
                         elif operation == "llm_tool_call" and args:
                             # Extract tool call information
-                            evt = args[0] if args else None
-                            if evt and hasattr(evt, "toolCall") and evt.toolCall.functionCalls:
-                                function_calls = evt.toolCall.functionCalls
+                            msg = args[0] if args else None
+                            if msg and hasattr(msg, "tool_call") and msg.tool_call.function_calls:
+                                function_calls = msg.tool_call.function_calls
                                 if function_calls:
                                     # Add information about the first function call
                                     call = function_calls[0]
@@ -722,19 +722,19 @@ def traced_gemini_live(operation: str) -> Callable:
 
                         elif operation == "llm_response" and args:
                             # Extract usage and response metadata from turn complete event
-                            evt = args[0] if args else None
-                            if evt and hasattr(evt, "usageMetadata") and evt.usageMetadata:
-                                usage = evt.usageMetadata
+                            msg = args[0] if args else None
+                            if msg and hasattr(msg, "usage_metadata") and msg.usage_metadata:
+                                usage = msg.usage_metadata
 
                                 # Token usage - basic attributes for span visibility
-                                if hasattr(usage, "promptTokenCount"):
-                                    operation_attrs["tokens.prompt"] = usage.promptTokenCount or 0
-                                if hasattr(usage, "responseTokenCount"):
+                                if hasattr(usage, "prompt_token_count"):
+                                    operation_attrs["tokens.prompt"] = usage.prompt_token_count or 0
+                                if hasattr(usage, "response_token_count"):
                                     operation_attrs["tokens.completion"] = (
-                                        usage.responseTokenCount or 0
+                                        usage.response_token_count or 0
                                     )
-                                if hasattr(usage, "totalTokenCount"):
-                                    operation_attrs["tokens.total"] = usage.totalTokenCount or 0
+                                if hasattr(usage, "total_token_count"):
+                                    operation_attrs["tokens.total"] = usage.total_token_count or 0
 
                             # Get output text and modality from service state
                             text = getattr(self, "_bot_text_buffer", "")
@@ -751,9 +751,9 @@ def traced_gemini_live(operation: str) -> Callable:
 
                             # Add turn completion status
                             if (
-                                evt
-                                and hasattr(evt, "serverContent")
-                                and evt.serverContent.turnComplete
+                                msg
+                                and hasattr(msg, "server_content")
+                                and msg.server_content.turn_complete
                             ):
                                 operation_attrs["turn_complete"] = True
 
@@ -772,16 +772,16 @@ def traced_gemini_live(operation: str) -> Callable:
 
                         # For llm_response operation, also handle token usage metrics
                         if operation == "llm_response" and hasattr(self, "start_llm_usage_metrics"):
-                            evt = args[0] if args else None
-                            if evt and hasattr(evt, "usageMetadata") and evt.usageMetadata:
-                                usage = evt.usageMetadata
+                            msg = args[0] if args else None
+                            if msg and hasattr(msg, "usage_metadata") and msg.usage_metadata:
+                                usage = msg.usage_metadata
                                 # Create LLMTokenUsage object
                                 from pipecat.metrics.metrics import LLMTokenUsage
 
                                 tokens = LLMTokenUsage(
-                                    prompt_tokens=usage.promptTokenCount or 0,
-                                    completion_tokens=usage.responseTokenCount or 0,
-                                    total_tokens=usage.totalTokenCount or 0,
+                                    prompt_tokens=usage.prompt_token_count or 0,
+                                    completion_tokens=usage.response_token_count or 0,
+                                    total_tokens=usage.total_token_count or 0,
                                 )
                                 _add_token_usage_to_span(current_span, tokens)
 

pipecat/serializers/genesys.py

@@ -1,95 +0,0 @@
-import base64
-import json
-from typing import Optional
-
-from pydantic import BaseModel
-
-from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm
-from pipecat.frames.frames import (
-    AudioRawFrame,
-    Frame,
-    InputAudioRawFrame,
-    InputDTMFFrame,
-    KeypadEntry,
-    StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
-)
-from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
-
-
-class GenesysFrameSerializer(FrameSerializer):
-    class InputParams(BaseModel):
-        genesys_sample_rate: int = 8000  # Default Genesys rate (8kHz)
-        sample_rate: Optional[int] = None  # Pipeline input rate
-
-    def __init__(self, session_id: str, params: InputParams = InputParams()):
-        self._session_id = session_id
-        self._params = params
-        self._genesys_sample_rate = self._params.genesys_sample_rate
-        self._sample_rate = 0  # Pipeline input rate
-        self._resampler = create_default_resampler()
-        self._seq = 1  # Sequence number for outgoing messages
-
-    @property
-    def type(self) -> FrameSerializerType:
-        return FrameSerializerType.TEXT
-
-    async def setup(self, frame: StartFrame):
-        self._sample_rate = self._params.sample_rate or frame.audio_in_sample_rate
-
-    async def serialize(self, frame: Frame) -> str | bytes | None:
-        if isinstance(frame, StartInterruptionFrame):
-            answer = {
-                "version": "2",
-                "type": "clearAudio",  # Or appropriate event for interruption
-                "seq": self._seq,
-                "id": self._session_id,
-            }
-            self._seq += 1
-            return json.dumps(answer)
-        elif isinstance(frame, AudioRawFrame):
-            data = frame.audio
-            # Convert PCM to 8kHz μ-law for Genesys
-            serialized_data = await pcm_to_ulaw(
-                data, frame.sample_rate, self._genesys_sample_rate, self._resampler
-            )
-            payload = base64.b64encode(serialized_data).decode("utf-8")
-            answer = {
-                "version": "2",
-                "type": "audio",
-                "seq": self._seq,
-                "id": self._session_id,
-                "media": {
-                    "payload": payload,
-                    "format": "PCMU",
-                    "rate": self._genesys_sample_rate,
-                },
-            }
-            self._seq += 1
-            return json.dumps(answer)
-        elif isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
-            return json.dumps(frame.message)
-
-    async def deserialize(self, data: str | bytes) -> Frame | None:
-        message = json.loads(data)
-        if message.get("type") == "audio":
-            payload_base64 = message["media"]["payload"]
-            payload = base64.b64decode(payload_base64)
-            # Convert Genesys 8kHz μ-law to PCM at pipeline input rate
-            deserialized_data = await ulaw_to_pcm(
-                payload, self._genesys_sample_rate, self._sample_rate, self._resampler
-            )
-            audio_frame = InputAudioRawFrame(
-                audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate
-            )
-            return audio_frame
-        elif message.get("type") == "dtmf":
-            digit = message.get("dtmf", {}).get("digit")
-            try:
-                return InputDTMFFrame(KeypadEntry(digit))
-            except ValueError:
-                return None
-        else:
-            return None

pipecat/services/google/test-google-chirp.py

@@ -1,45 +0,0 @@
-import asyncio
-import os
-
-from pipecat.frames.frames import TTSAudioRawFrame
-from pipecat.services.google.tts import GoogleTTSService
-
-
-async def test_chirp_tts():
-    # Get credentials from environment variable
-    credentials_path = (
-        "/Users/kalicharanvemuru/Documents/Code/pipecat/examples/ringg-chatbot/creds.json"
-    )
-
-    if not credentials_path or not os.path.exists(credentials_path):
-        raise ValueError(
-            "Please set GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account key file"
-        )
-
-    # Initialize the TTS service with Chirp voice
-    tts = GoogleTTSService(
-        credentials_path=credentials_path,
-        voice_id="en-US-Chirp3-HD-Charon",  # Using Chirp3 HD Charon voice
-        sample_rate=24000,
-    )
-
-    # Test text
-    test_text = "Hello, this is a test of the Google TTS service with Chirp voice."
-
-    print(f"Testing TTS with text: {test_text}")
-
-    # Generate speech
-    try:
-        async for frame in tts.run_tts(test_text):
-            if isinstance(frame, TTSAudioRawFrame):
-                print(f"Received audio chunk of size: {len(frame.audio)} bytes")
-            else:
-                print(f"Received frame: {frame.__class__.__name__}")
-
-        print("TTS generation completed successfully!")
-    except Exception as e:
-        print(f"Error during TTS generation: {str(e)}")
-
-
-if __name__ == "__main__":
-    asyncio.run(test_chirp_tts())