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

pipecat/services/gladia/config.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Configuration for the Gladia STT service."""
+
 from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel
@@ -14,7 +16,7 @@ from pipecat.transcriptions.language import Language
 class LanguageConfig(BaseModel):
     """Configuration for language detection and handling.
 
-    Attributes:
+    Parameters:
         languages: List of language codes to use for transcription
         code_switching: Whether to auto-detect language changes during transcription
     """
@@ -26,7 +28,7 @@ class LanguageConfig(BaseModel):
 class PreProcessingConfig(BaseModel):
     """Configuration for audio pre-processing options.
 
-    Attributes:
+    Parameters:
         speech_threshold: Sensitivity for speech detection (0-1)
     """
 
@@ -36,7 +38,7 @@ class PreProcessingConfig(BaseModel):
 class CustomVocabularyItem(BaseModel):
     """Represents a custom vocabulary item with an intensity value.
 
-    Attributes:
+    Parameters:
         value: The vocabulary word or phrase
         intensity: The bias intensity for this vocabulary item (0-1)
     """
@@ -48,7 +50,7 @@ class CustomVocabularyItem(BaseModel):
 class CustomVocabularyConfig(BaseModel):
     """Configuration for custom vocabulary.
 
-    Attributes:
+    Parameters:
         vocabulary: List of words/phrases or CustomVocabularyItem objects
         default_intensity: Default intensity for simple string vocabulary items
     """
@@ -60,7 +62,7 @@ class CustomVocabularyConfig(BaseModel):
 class CustomSpellingConfig(BaseModel):
     """Configuration for custom spelling rules.
 
-    Attributes:
+    Parameters:
         spelling_dictionary: Mapping of correct spellings to phonetic variations
     """
 
@@ -70,7 +72,7 @@ class CustomSpellingConfig(BaseModel):
 class TranslationConfig(BaseModel):
     """Configuration for real-time translation.
 
-    Attributes:
+    Parameters:
         target_languages: List of target language codes for translation
         model: Translation model to use ("base" or "enhanced")
         match_original_utterances: Whether to align translations with original utterances
@@ -92,7 +94,7 @@ class TranslationConfig(BaseModel):
 class RealtimeProcessingConfig(BaseModel):
     """Configuration for real-time processing features.
 
-    Attributes:
+    Parameters:
         words_accurate_timestamps: Whether to provide per-word timestamps
         custom_vocabulary: Whether to enable custom vocabulary
         custom_vocabulary_config: Custom vocabulary configuration
@@ -118,7 +120,7 @@ class RealtimeProcessingConfig(BaseModel):
 class MessagesConfig(BaseModel):
     """Configuration for controlling which message types are sent via WebSocket.
 
-    Attributes:
+    Parameters:
         receive_partial_transcripts: Whether to receive intermediate transcription results
         receive_final_transcripts: Whether to receive final transcription results
         receive_speech_events: Whether to receive speech begin/end events
@@ -144,14 +146,19 @@ class MessagesConfig(BaseModel):
 class GladiaInputParams(BaseModel):
     """Configuration parameters for the Gladia STT service.
 
-    Attributes:
+    Parameters:
         encoding: Audio encoding format
         bit_depth: Audio bit depth
         channels: Number of audio channels
         custom_metadata: Additional metadata to include with requests
         endpointing: Silence duration in seconds to mark end of speech
         maximum_duration_without_endpointing: Maximum utterance duration without silence
-        language: DEPRECATED - Use language_config instead
+        language: Language code for transcription
+
+            .. deprecated:: 0.0.62
+                The 'language' parameter is deprecated and will be removed in a future version.
+                Use 'language_config' instead.
+
         language_config: Detailed language configuration
         pre_processing: Audio pre-processing options
         realtime_processing: Real-time processing features

pipecat/services/gladia/stt.py

@@ -4,11 +4,17 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Gladia Speech-to-Text (STT) service implementation.
+
+This module provides a Speech-to-Text service using Gladia's real-time WebSocket API,
+supporting multiple languages, custom vocabulary, and various audio processing options.
+"""
+
 import asyncio
 import base64
 import json
 import warnings
-from typing import Any, AsyncGenerator, Dict, List, Optional  # Add List
+from typing import Any, AsyncGenerator, Dict, Literal, List, Optional
 
 import aiohttp
 from loguru import logger
@@ -31,12 +37,13 @@ from pipecat.services.gladia.config import (
 )
 from pipecat.services.stt_service import STTService
 from pipecat.transcriptions.language import Language
-from pipecat.utils.asyncio.watchdog_async_iterator import WatchdogAsyncIterator
 from pipecat.utils.time import time_now_iso8601
 from pipecat.utils.tracing.service_decorators import traced_stt
 
 try:
     import websockets
+    from websockets.asyncio.client import connect as websocket_connect
+    from websockets.protocol import State
 except ModuleNotFoundError as e:
     logger.error(f"Exception: {e}")
     logger.error("In order to use Gladia, you need to `pip install pipecat-ai[gladia]`.")
@@ -47,10 +54,10 @@ def language_to_gladia_language(language: Language) -> Optional[str]:
     """Convert a Language enum to Gladia's language code format.
 
     Args:
-        language: The Language enum value to convert
+        language: The Language enum value to convert.
 
     Returns:
-        The Gladia language code string or None if not supported
+        The Gladia language code string or None if not supported.
     """
     BASE_LANGUAGES = {
         Language.AF: "af",
@@ -186,8 +193,12 @@ class GladiaSTTService(STTService):
 
     This service connects to Gladia's WebSocket API for real-time transcription
     with support for multiple languages, custom vocabulary, and various processing options.
+    Provides automatic reconnection, audio buffering, and comprehensive error handling.
 
     For complete API documentation, see: https://docs.gladia.io/api-reference/v2/live/init
+
+    .. deprecated:: 0.0.62
+        Use :class:`~pipecat.services.gladia.config.GladiaInputParams` directly instead.
     """
 
     # Maintain backward compatibility
@@ -197,6 +208,7 @@ class GladiaSTTService(STTService):
         self,
         *,
         api_key: str,
+        region: Literal["us-west", "eu-west"] | None = None,
         url: str = "https://api.gladia.io/v2/live",
         confidence: float = 0.5,
         sample_rate: Optional[int] = None,
@@ -210,16 +222,17 @@ class GladiaSTTService(STTService):
         """Initialize the Gladia STT service.
 
         Args:
-            api_key: Gladia API key
-            url: Gladia API URL
-            confidence: Minimum confidence threshold for transcriptions
-            sample_rate: Audio sample rate in Hz
-            model: Model to use ("solaria-1")
-            params: Additional configuration parameters
-            max_reconnection_attempts: Maximum number of reconnection attempts
-            reconnection_delay: Initial delay between reconnection attempts (exponential backoff)
-            max_buffer_size: Maximum size of audio buffer in bytes
-            **kwargs: Additional arguments passed to the STTService
+            api_key: Gladia API key for authentication.
+            region: Region used to process audio. eu-west or us-west. Defaults to eu-west.
+            url: Gladia API URL. Defaults to "https://api.gladia.io/v2/live".
+            confidence: Minimum confidence threshold for transcriptions (0.0-1.0).
+            sample_rate: Audio sample rate in Hz. If None, uses service default.
+            model: Model to use for transcription. Defaults to "solaria-1".
+            params: Additional configuration parameters for Gladia service.
+            max_reconnection_attempts: Maximum number of reconnection attempts. Defaults to 5.
+            reconnection_delay: Initial delay between reconnection attempts in seconds.
+            max_buffer_size: Maximum size of audio buffer in bytes. Defaults to 20MB.
+            **kwargs: Additional arguments passed to the STTService parent class.
         """
         super().__init__(sample_rate=sample_rate, **kwargs)
         vocab: Optional[List[str]] = kwargs.pop("vocab", None)  # Get vocab from kwargs
@@ -236,6 +249,7 @@ class GladiaSTTService(STTService):
             )
 
         self._api_key = api_key
+        self._region = region
         self._url = url
         self.set_model_name(model)
         self._confidence = confidence
@@ -280,10 +294,22 @@ class GladiaSTTService(STTService):
         self._should_reconnect = True
 
     def can_generate_metrics(self) -> bool:
+        """Check if the service can generate performance metrics.
+
+        Returns:
+            True, indicating this service supports metrics generation.
+        """
         return True
 
     def language_to_service_language(self, language: Language) -> Optional[str]:
-        """Convert pipecat Language enum to Gladia's language code."""
+        """Convert pipecat Language enum to Gladia's language code.
+
+        Args:
+            language: The Language enum value to convert.
+
+        Returns:
+            The Gladia language code string or None if not supported.
+        """
         return language_to_gladia_language(language)
 
     def _prepare_settings(self) -> Dict[str, Any]:
@@ -338,7 +364,11 @@ class GladiaSTTService(STTService):
         return settings
 
     async def start(self, frame: StartFrame):
-        """Start the Gladia STT websocket connection."""
+        """Start the Gladia STT websocket connection.
+
+        Args:
+            frame: The start frame triggering service startup.
+        """
         await super().start(frame)
         if self._connection_task:
             return
@@ -347,7 +377,11 @@ class GladiaSTTService(STTService):
         self._connection_task = self.create_task(self._connection_handler())
 
     async def stop(self, frame: EndFrame):
-        """Stop the Gladia STT websocket connection."""
+        """Stop the Gladia STT websocket connection.
+
+        Args:
+            frame: The end frame triggering service shutdown.
+        """
         await super().stop(frame)
         self._should_reconnect = False
         await self._send_stop_recording()
@@ -359,7 +393,11 @@ class GladiaSTTService(STTService):
         await self._cleanup_connection()
 
     async def cancel(self, frame: CancelFrame):
-        """Cancel the Gladia STT websocket connection."""
+        """Cancel the Gladia STT websocket connection.
+
+        Args:
+            frame: The cancel frame triggering service cancellation.
+        """
         await super().cancel(frame)
         self._should_reconnect = False
 
@@ -370,7 +408,14 @@ class GladiaSTTService(STTService):
         await self._cleanup_connection()
 
     async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
-        """Run speech-to-text on audio data."""
+        """Run speech-to-text on audio data.
+
+        Args:
+            audio: Raw audio bytes to transcribe.
+
+        Yields:
+            None (processing is handled asynchronously via WebSocket).
+        """
         await self.start_ttfb_metrics()
         await self.start_processing_metrics()
 
@@ -385,7 +430,7 @@ class GladiaSTTService(STTService):
                 logger.warning(f"Audio buffer exceeded max size, trimmed {trim_size} bytes")
 
         # Send audio if connected
-        if self._connection_active and self._websocket and not self._websocket.closed:
+        if self._connection_active and self._websocket and self._websocket.state is State.OPEN:
             try:
                 await self._send_audio(audio)
             except websockets.exceptions.ConnectionClosed as e:
@@ -406,11 +451,11 @@ class GladiaSTTService(STTService):
                     self._reconnection_attempts = 0
 
                 # Connect with automatic reconnection
-                async with websockets.connect(self._session_url) as websocket:
+                async with websocket_connect(self._session_url) as websocket:
                     try:
                         self._websocket = websocket
                         self._connection_active = True
-                        logger.info("Connected to Gladia WebSocket")
+                        logger.debug(f"{self} Connected to Gladia WebSocket")
 
                         # Send buffered audio if any
                         await self._send_buffered_audio()
@@ -465,10 +510,14 @@ class GladiaSTTService(STTService):
 
     async def _setup_gladia(self, settings: Dict[str, Any]):
         async with aiohttp.ClientSession() as session:
+            params = {}
+            if self._region:
+                params["region"] = self._region
             async with session.post(
                 self._url,
-                headers={"X-Gladia-Key": self._api_key, "Content-Type": "application/json"},
+                headers={"X-Gladia-Key": self._api_key},
                 json=settings,
+                params=params,
             ) as response:
                 if response.ok:
                     return await response.json()
@@ -490,7 +539,7 @@ class GladiaSTTService(STTService):
 
     async def _send_audio(self, audio: bytes):
         """Send audio chunk with proper message format."""
-        if self._websocket and not self._websocket.closed:
+        if self._websocket and self._websocket.state is State.OPEN:
             data = base64.b64encode(audio).decode("utf-8")
             message = {"type": "audio_chunk", "data": {"chunk": data}}
             await self._websocket.send(json.dumps(message))
@@ -499,22 +548,21 @@ class GladiaSTTService(STTService):
         """Send any buffered audio after reconnection."""
         async with self._buffer_lock:
             if self._audio_buffer:
-                logger.info(f"Sending {len(self._audio_buffer)} bytes of buffered audio")
+                logger.debug(f"{self} Sending {len(self._audio_buffer)} bytes of buffered audio")
                 await self._send_audio(bytes(self._audio_buffer))
 
     async def _send_stop_recording(self):
-        if self._websocket and not self._websocket.closed:
+        if self._websocket and self._websocket.state is State.OPEN:
             await self._websocket.send(json.dumps({"type": "stop_recording"}))
 
     async def _keepalive_task_handler(self):
         """Send periodic empty audio chunks to keep the connection alive."""
         try:
-            KEEPALIVE_SLEEP = 20 if self.task_manager.task_watchdog_enabled else 3
+            KEEPALIVE_SLEEP = 20
             while self._connection_active:
-                self.reset_watchdog()
                 # Send keepalive (Gladia times out after 30 seconds)
                 await asyncio.sleep(KEEPALIVE_SLEEP)
-                if self._websocket and not self._websocket.closed:
+                if self._websocket and self._websocket.state is State.OPEN:
                     # Send an empty audio chunk as keepalive
                     empty_audio = b""
                     await self._send_audio(empty_audio)
@@ -528,7 +576,7 @@ class GladiaSTTService(STTService):
 
     async def _receive_task_handler(self):
         try:
-            async for message in WatchdogAsyncIterator(self._websocket, manager=self.task_manager):
+            async for message in self._websocket:
                 content = json.loads(message)
 
                 # Handle audio chunk acknowledgments
@@ -553,7 +601,7 @@ class GladiaSTTService(STTService):
                             await self.push_frame(
                                 TranscriptionFrame(
                                     transcript,
-                                    "",
+                                    self._user_id,
                                     time_now_iso8601(),
                                     language,
                                     result=content,
@@ -568,7 +616,7 @@ class GladiaSTTService(STTService):
                             await self.push_frame(
                                 InterimTranscriptionFrame(
                                     transcript,
-                                    "",
+                                    self._user_id,
                                     time_now_iso8601(),
                                     language,
                                     result=content,
@@ -586,8 +634,6 @@ class GladiaSTTService(STTService):
                                 translation, "", time_now_iso8601(), translated_language
                             )
                         )
-
-                self.reset_watchdog()
         except websockets.exceptions.ConnectionClosed:
             # Expected when closing the connection
             pass
@@ -604,8 +650,8 @@ class GladiaSTTService(STTService):
             self._should_reconnect = False
             return False
         delay = self._reconnection_delay * (2 ** (self._reconnection_attempts - 1))
-        logger.info(
-            f"Reconnecting in {delay} seconds (attempt {self._reconnection_attempts}/{self._max_reconnection_attempts})"
+        logger.debug(
+            f"{self} Reconnecting in {delay} seconds (attempt {self._reconnection_attempts}/{self._max_reconnection_attempts})"
         )
         await asyncio.sleep(delay)
         return True

pipecat/services/google/frames.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google AI service frames for search and grounding functionality.
+
+This module defines specialized frame types for handling search results
+and grounding metadata from Google AI models, particularly for Gemini
+models that support web search and fact grounding capabilities.
+"""
+
 from dataclasses import dataclass, field
 from typing import List, Optional
 
@@ -12,12 +19,27 @@ from pipecat.frames.frames import DataFrame
 
 @dataclass
 class LLMSearchResult:
+    """Represents a single search result with confidence scores.
+
+    Parameters:
+        text: The search result text content.
+        confidence: List of confidence scores associated with the result.
+    """
+
     text: str
     confidence: List[float] = field(default_factory=list)
 
 
 @dataclass
 class LLMSearchOrigin:
+    """Represents the origin source of search results.
+
+    Parameters:
+        site_uri: URI of the source website.
+        site_title: Title of the source website.
+        results: List of search results from this origin.
+    """
+
     site_uri: Optional[str] = None
     site_title: Optional[str] = None
     results: List[LLMSearchResult] = field(default_factory=list)
@@ -25,9 +47,27 @@ class LLMSearchOrigin:
 
 @dataclass
 class LLMSearchResponseFrame(DataFrame):
+    """Frame containing search results and grounding information from Google AI models.
+
+    This frame is used to convey search results and grounding metadata
+    from Google AI models that support web search capabilities. It includes
+    the search result text, rendered content, and detailed origin information
+    with confidence scores.
+
+    Parameters:
+        search_result: The main search result text.
+        rendered_content: Rendered content from the search entry point.
+        origins: List of search result origins with detailed information.
+    """
+
     search_result: Optional[str] = None
     rendered_content: Optional[str] = None
     origins: List[LLMSearchOrigin] = field(default_factory=list)
 
     def __str__(self):
+        """Return string representation of the search response frame.
+
+        Returns:
+            String representation showing search result and origins.
+        """
         return f"LLMSearchResponseFrame(search_result={self.search_result}, origins={self.origins})"

pipecat/services/google/google.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google services module for Pipecat."""
+
 import sys
 
 from pipecat.services import DeprecatedModuleProxy

pipecat/services/google/image.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google AI image generation service implementation.
+
+This module provides integration with Google's Imagen model for generating
+images from text prompts using the Google AI API.
+"""
+
 import io
 import os
 
@@ -29,7 +35,22 @@ except ModuleNotFoundError as e:
 
 
 class GoogleImageGenService(ImageGenService):
+    """Google AI image generation service using Imagen models.
+
+    Provides text-to-image generation capabilities using Google's Imagen models
+    through the Google AI API. Supports multiple image generation and negative
+    prompting for enhanced control over generated content.
+    """
+
     class InputParams(BaseModel):
+        """Configuration parameters for Google image generation.
+
+        Parameters:
+            number_of_images: Number of images to generate (1-8). Defaults to 1.
+            model: Google Imagen model to use. Defaults to "imagen-3.0-generate-002".
+            negative_prompt: Optional negative prompt to guide what not to include.
+        """
+
         number_of_images: int = Field(default=1, ge=1, le=8)
         model: str = Field(default="imagen-3.0-generate-002")
         negative_prompt: Optional[str] = Field(default=None)
@@ -41,22 +62,38 @@ class GoogleImageGenService(ImageGenService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the GoogleImageGenService with API key and parameters.
+
+        Args:
+            api_key: Google AI API key for authentication.
+            params: Configuration parameters for image generation. Defaults to InputParams().
+            **kwargs: Additional arguments passed to the parent ImageGenService.
+        """
         super().__init__(**kwargs)
         self._params = params or GoogleImageGenService.InputParams()
         self._client = genai.Client(api_key=api_key)
         self.set_model_name(self._params.model)
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as Google image generation service supports metrics.
+        """
         return True
 
     async def run_image_gen(self, prompt: str) -> AsyncGenerator[Frame, None]:
         """Generate images from a text prompt using Google's Imagen model.
 
         Args:
-            prompt (str): The text description to generate images from.
+            prompt: The text description to generate images from.
 
         Yields:
-            Frame: Generated image frames or error frames.
+            Frame: Generated URLImageRawFrame objects containing the generated
+                images, or ErrorFrame objects if generation fails.
+
+        Raises:
+            Exception: If there are issues with the Google AI API or image processing.
         """
         logger.debug(f"Generating image from prompt: {prompt}")
         await self.start_ttfb_metrics()