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

pipecat/services/fal/image.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Fal's image generation service implementation.
+
+This module provides integration with Fal's image generation API
+for creating images from text prompts using various AI models.
+"""
+
 import asyncio
 import io
 import os
@@ -26,7 +32,25 @@ except ModuleNotFoundError as e:
 
 
 class FalImageGenService(ImageGenService):
+    """Fal's image generation service.
+
+    Provides text-to-image generation using Fal.ai's API with configurable
+    parameters for image quality, safety, and format options.
+    """
+
     class InputParams(BaseModel):
+        """Input parameters for Fal.ai image generation.
+
+        Parameters:
+            seed: Random seed for reproducible generation. If None, uses random seed.
+            num_inference_steps: Number of inference steps for generation. Defaults to 8.
+            num_images: Number of images to generate. Defaults to 1.
+            image_size: Image dimensions as string preset or dict with width/height. Defaults to "square_hd".
+            expand_prompt: Whether to automatically expand/enhance the prompt. Defaults to False.
+            enable_safety_checker: Whether to enable content safety filtering. Defaults to True.
+            format: Output image format. Defaults to "png".
+        """
+
         seed: Optional[int] = None
         num_inference_steps: int = 8
         num_images: int = 1
@@ -44,6 +68,15 @@ class FalImageGenService(ImageGenService):
         key: Optional[str] = None,
         **kwargs,
     ):
+        """Initialize the FalImageGenService.
+
+        Args:
+            params: Input parameters for image generation configuration.
+            aiohttp_session: HTTP client session for downloading generated images.
+            model: The Fal.ai model to use for generation. Defaults to "fal-ai/fast-sdxl".
+            key: Optional API key for Fal.ai. If provided, sets FAL_KEY environment variable.
+            **kwargs: Additional arguments passed to parent ImageGenService.
+        """
         super().__init__(**kwargs)
         self.set_model_name(model)
         self._params = params
@@ -52,6 +85,16 @@ class FalImageGenService(ImageGenService):
             os.environ["FAL_KEY"] = key
 
     async def run_image_gen(self, prompt: str) -> AsyncGenerator[Frame, None]:
+        """Generate an image from a text prompt.
+
+        Args:
+            prompt: The text prompt to generate an image from.
+
+        Yields:
+            URLImageRawFrame: Frame containing the generated image data and metadata.
+            ErrorFrame: If image generation fails.
+        """
+
         def load_image_bytes(encoded_image: bytes):
             buffer = io.BytesIO(encoded_image)
             image = Image.open(buffer)

pipecat/services/fal/stt.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Fal speech-to-text service implementation.
+
+This module provides integration with Fal's Wizper API for speech-to-text
+transcription using segmented audio processing.
+"""
+
 import os
 from typing import AsyncGenerator, Optional
 
@@ -27,7 +33,14 @@ except ModuleNotFoundError as e:
 
 
 def language_to_fal_language(language: Language) -> Optional[str]:
-    """Language support for Fal's Wizper API."""
+    """Convert a Language enum to Fal's Wizper language code.
+
+    Args:
+        language: The Language enum value to convert.
+
+    Returns:
+        The corresponding Fal Wizper language code, or None if not supported.
+    """
     BASE_LANGUAGES = {
         Language.AF: "af",
         Language.AM: "am",
@@ -145,18 +158,12 @@ class FalSTTService(SegmentedSTTService):
 
     This service uses Fal's Wizper API to perform speech-to-text transcription on audio
     segments. It inherits from SegmentedSTTService to handle audio buffering and speech detection.
-
-    Args:
-        api_key: Fal API key. If not provided, will check FAL_KEY environment variable.
-        sample_rate: Audio sample rate in Hz. If not provided, uses the pipeline's rate.
-        params: Configuration parameters for the Wizper API.
-        **kwargs: Additional arguments passed to SegmentedSTTService.
     """
 
     class InputParams(BaseModel):
         """Configuration parameters for Fal's Wizper API.
 
-        Attributes:
+        Parameters:
             language: Language of the audio input. Defaults to English.
             task: Task to perform ('transcribe' or 'translate'). Defaults to 'transcribe'.
             chunk_level: Level of chunking ('segment'). Defaults to 'segment'.
@@ -176,6 +183,14 @@ class FalSTTService(SegmentedSTTService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the FalSTTService with API key and parameters.
+
+        Args:
+            api_key: Fal API key. If not provided, will check FAL_KEY environment variable.
+            sample_rate: Audio sample rate in Hz. If not provided, uses the pipeline's rate.
+            params: Configuration parameters for the Wizper API.
+            **kwargs: Additional arguments passed to SegmentedSTTService.
+        """
         super().__init__(
             sample_rate=sample_rate,
             **kwargs,
@@ -201,16 +216,39 @@ class FalSTTService(SegmentedSTTService):
         }
 
     def can_generate_metrics(self) -> bool:
+        """Check if the service can generate processing metrics.
+
+        Returns:
+            True, as Fal STT service supports metrics generation.
+        """
         return True
 
     def language_to_service_language(self, language: Language) -> Optional[str]:
+        """Convert a Language enum to Fal's service-specific language code.
+
+        Args:
+            language: The language to convert.
+
+        Returns:
+            The Fal-specific language code, or None if not supported.
+        """
         return language_to_fal_language(language)
 
     async def set_language(self, language: Language):
+        """Set the transcription language.
+
+        Args:
+            language: The language to use for speech-to-text transcription.
+        """
         logger.info(f"Switching STT language to: [{language}]")
         self._settings["language"] = self.language_to_service_language(language)
 
     async def set_model(self, model: str):
+        """Set the STT model.
+
+        Args:
+            model: The model name to use for transcription.
+        """
         await super().set_model(model)
         logger.info(f"Switching STT model to: [{model}]")
 
@@ -229,7 +267,7 @@ class FalSTTService(SegmentedSTTService):
             audio: Raw audio bytes in WAV format (already converted by base class).
 
         Yields:
-            Frame: TranscriptionFrame containing the transcribed text.
+            Frame: TranscriptionFrame containing the transcribed text, or ErrorFrame on failure.
 
         Note:
             The audio is already in WAV format from the SegmentedSTTService.
@@ -253,7 +291,7 @@ class FalSTTService(SegmentedSTTService):
                     logger.debug(f"Transcription: [{text}]")
                     yield TranscriptionFrame(
                         text,
-                        "",
+                        self._user_id,
                         time_now_iso8601(),
                         Language(self._settings["language"]),
                         result=response,

pipecat/services/fireworks/llm.py

@@ -20,12 +20,6 @@ class FireworksLLMService(OpenAILLMService):
 
     This service extends OpenAILLMService to connect to Fireworks' API endpoint while
     maintaining full compatibility with OpenAI's interface and functionality.
-
-    Args:
-        api_key: The API key for accessing Fireworks AI.
-        model: The model identifier to use. Defaults to "accounts/fireworks/models/firefunction-v2".
-        base_url: The base URL for Fireworks API. Defaults to "https://api.fireworks.ai/inference/v1".
-        **kwargs: Additional keyword arguments passed to OpenAILLMService.
     """
 
     def __init__(
@@ -36,6 +30,14 @@ class FireworksLLMService(OpenAILLMService):
         base_url: str = "https://api.fireworks.ai/inference/v1",
         **kwargs,
     ):
+        """Initialize the Fireworks LLM service.
+
+        Args:
+            api_key: The API key for accessing Fireworks AI.
+            model: The model identifier to use. Defaults to "accounts/fireworks/models/firefunction-v2".
+            base_url: The base URL for Fireworks API. Defaults to "https://api.fireworks.ai/inference/v1".
+            **kwargs: Additional keyword arguments passed to OpenAILLMService.
+        """
         super().__init__(api_key=api_key, base_url=base_url, model=model, **kwargs)
 
     def create_client(self, api_key=None, base_url=None, **kwargs):
@@ -52,20 +54,13 @@ class FireworksLLMService(OpenAILLMService):
         logger.debug(f"Creating Fireworks client with api {base_url}")
         return super().create_client(api_key, base_url, **kwargs)
 
-    async def get_chat_completions(
+    def build_chat_completion_params(
         self, context: OpenAILLMContext, messages: List[ChatCompletionMessageParam]
-    ):
-        """Get chat completions from Fireworks API.
+    ) -> dict:
+        """Build parameters for Fireworks chat completion request.
 
-        Removes OpenAI-specific parameters not supported by Fireworks and
-        configures the request with Fireworks-compatible settings.
-
-        Args:
-            context: The OpenAI LLM context containing tools and settings.
-            messages: List of chat completion message parameters.
-
-        Returns:
-            Async generator yielding chat completion chunks from Fireworks API.
+        Fireworks doesn't support some OpenAI parameters like seed, max_completion_tokens,
+        and stream_options.
         """
         params = {
             "model": self.model_name,
@@ -81,6 +76,4 @@ class FireworksLLMService(OpenAILLMService):
         }
 
         params.update(self._settings["extra"])
-
-        chunks = await self._client.chat.completions.create(**params)
-        return chunks
+        return params

pipecat/services/fish/tts.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Fish Audio text-to-speech service implementation.
+
+This module provides integration with Fish Audio's real-time TTS WebSocket API
+for streaming text-to-speech synthesis with customizable voice parameters.
+"""
+
 import uuid
 from typing import AsyncGenerator, Literal, Optional
 
@@ -28,7 +34,8 @@ from pipecat.utils.tracing.service_decorators import traced_tts
 
 try:
     import ormsgpack
-    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 Fish Audio, you need to `pip install pipecat-ai[fish]`.")
@@ -39,9 +46,27 @@ FishAudioOutputFormat = Literal["opus", "mp3", "pcm", "wav"]
 
 
 class FishAudioTTSService(InterruptibleTTSService):
+    """Fish Audio text-to-speech service with WebSocket streaming.
+
+    Provides real-time text-to-speech synthesis using Fish Audio's WebSocket API.
+    Supports various audio formats, customizable prosody controls, and streaming
+    audio generation with interruption handling.
+    """
+
     class InputParams(BaseModel):
+        """Input parameters for Fish Audio TTS configuration.
+
+        Parameters:
+            language: Language for synthesis. Defaults to English.
+            latency: Latency mode ("normal" or "balanced"). Defaults to "normal".
+            normalize: Whether to normalize audio output. Defaults to True.
+            prosody_speed: Speech speed multiplier (0.5-2.0). Defaults to 1.0.
+            prosody_volume: Volume adjustment in dB. Defaults to 0.
+        """
+
         language: Optional[Language] = Language.EN
         latency: Optional[str] = "normal"  # "normal" or "balanced"
+        normalize: Optional[bool] = True
         prosody_speed: Optional[float] = 1.0  # Speech speed (0.5-2.0)
         prosody_volume: Optional[int] = 0  # Volume adjustment in dB
 
@@ -49,12 +74,31 @@ class FishAudioTTSService(InterruptibleTTSService):
         self,
         *,
         api_key: str,
-        model: str,  # This is the reference_id
+        reference_id: Optional[str] = None,  # This is the voice ID
+        model: Optional[str] = None,  # Deprecated
+        model_id: str = "speech-1.5",
         output_format: FishAudioOutputFormat = "pcm",
         sample_rate: Optional[int] = None,
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the Fish Audio TTS service.
+
+        Args:
+            api_key: Fish Audio API key for authentication.
+            reference_id: Reference ID of the voice model to use for synthesis.
+            model: Deprecated. Reference ID of the voice model to use for synthesis.
+
+              .. deprecated:: 0.0.74
+                The `model` parameter is deprecated and will be removed in version 0.1.0.
+                Use `reference_id` instead to specify the voice model.
+
+            model_id: Specify which Fish Audio TTS model to use (e.g. "speech-1.5")
+            output_format: Audio output format. Defaults to "pcm".
+            sample_rate: Audio sample rate. If None, uses default.
+            params: Additional input parameters for voice customization.
+            **kwargs: Additional arguments passed to the parent service.
+        """
         super().__init__(
             push_stop_frames=True,
             pause_frame_processing=True,
@@ -64,6 +108,26 @@ class FishAudioTTSService(InterruptibleTTSService):
 
         params = params or FishAudioTTSService.InputParams()
 
+        # Validation for model and reference_id parameters
+        if model and reference_id:
+            raise ValueError(
+                "Cannot specify both 'model' and 'reference_id'. Use 'reference_id' only."
+            )
+
+        if model is None and reference_id is None:
+            raise ValueError("Must specify 'reference_id' (or deprecated 'model') parameter.")
+
+        if model:
+            import warnings
+
+            warnings.warn(
+                "Parameter 'model' is deprecated and will be removed in a future version. "
+                "Use 'reference_id' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            reference_id = model
+
         self._api_key = api_key
         self._base_url = "wss://api.fish.audio/v1/tts/live"
         self._websocket = None
@@ -75,33 +139,60 @@ class FishAudioTTSService(InterruptibleTTSService):
             "sample_rate": 0,
             "latency": params.latency,
             "format": output_format,
+            "normalize": params.normalize,
             "prosody": {
                 "speed": params.prosody_speed,
                 "volume": params.prosody_volume,
             },
-            "reference_id": model,
+            "reference_id": reference_id,
         }
 
-        self.set_model_name(model)
+        self.set_model_name(model_id)
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as Fish Audio service supports metrics generation.
+        """
         return True
 
     async def set_model(self, model: str):
-        self._settings["reference_id"] = model
+        """Set the TTS model and reconnect.
+
+        Args:
+            model: The model name to use for synthesis.
+        """
         await super().set_model(model)
         logger.info(f"Switching TTS model to: [{model}]")
+        await self._disconnect()
+        await self._connect()
 
     async def start(self, frame: StartFrame):
+        """Start the Fish Audio TTS service.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
         self._settings["sample_rate"] = self.sample_rate
         await self._connect()
 
     async def stop(self, frame: EndFrame):
+        """Stop the Fish Audio TTS service.
+
+        Args:
+            frame: The end frame.
+        """
         await super().stop(frame)
         await self._disconnect()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the Fish Audio TTS service.
+
+        Args:
+            frame: The cancel frame.
+        """
         await super().cancel(frame)
         await self._disconnect()
 
@@ -120,12 +211,13 @@ class FishAudioTTSService(InterruptibleTTSService):
 
     async def _connect_websocket(self):
         try:
-            if self._websocket and self._websocket.open:
+            if self._websocket and self._websocket.state is State.OPEN:
                 return
 
             logger.debug("Connecting to Fish Audio")
             headers = {"Authorization": f"Bearer {self._api_key}"}
-            self._websocket = await websockets.connect(self._base_url, extra_headers=headers)
+            headers["model"] = self.model_name
+            self._websocket = await websocket_connect(self._base_url, additional_headers=headers)
 
             # Send initial start message with ormsgpack
             start_message = {"event": "start", "request": {"text": "", **self._settings}}
@@ -155,7 +247,7 @@ class FishAudioTTSService(InterruptibleTTSService):
     async def flush_audio(self):
         """Flush any buffered audio by sending a flush event to Fish Audio."""
         logger.trace(f"{self}: Flushing audio buffers")
-        if not self._websocket or self._websocket.closed:
+        if not self._websocket or self._websocket.state is State.CLOSED:
             return
         flush_message = {"event": "flush"}
         await self._get_websocket().send(ormsgpack.packb(flush_message))
@@ -191,9 +283,17 @@ class FishAudioTTSService(InterruptibleTTSService):
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using Fish Audio's streaming API.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames and control frames for the synthesized speech.
+        """
         logger.debug(f"{self}: Generating Fish TTS: [{text}]")
         try:
-            if not self._websocket or self._websocket.closed:
+            if not self._websocket or self._websocket.state is State.CLOSED:
                 await self._connect()
 
             if not self._request_id:

pipecat/services/gemini_multimodal_live/__init__.py

@@ -1 +1,2 @@
+from .file_api import GeminiFileAPI
 from .gemini import GeminiMultimodalLiveLLMService

pipecat/services/gemini_multimodal_live/events.py

@@ -44,6 +44,17 @@ class ContentPart(BaseModel):
 
     text: Optional[str] = Field(default=None, validate_default=False)
     inlineData: Optional[MediaChunk] = Field(default=None, validate_default=False)
+    fileData: Optional["FileData"] = Field(default=None, validate_default=False)
+
+
+class FileData(BaseModel):
+    """Represents a file reference in the Gemini File API."""
+
+    mimeType: str
+    fileUri: str
+
+
+ContentPart.model_rebuild()  # Rebuild model to resolve forward reference
 
 
 class Turn(BaseModel):
@@ -103,13 +114,15 @@ class RealtimeInputConfig(BaseModel):
 
 
 class RealtimeInput(BaseModel):
-    """Contains realtime input media chunks.
+    """Contains realtime input media chunks and text.
 
     Parameters:
         mediaChunks: List of media chunks for realtime processing.
+        text: Text for realtime processing.
     """
 
-    mediaChunks: List[MediaChunk]
+    mediaChunks: Optional[List[MediaChunk]] = None
+    text: Optional[str] = None
 
 
 class ClientContent(BaseModel):
@@ -179,6 +192,24 @@ class VideoInputMessage(BaseModel):
         )
 
 
+class TextInputMessage(BaseModel):
+    """Message containing text input data."""
+
+    realtimeInput: RealtimeInput
+
+    @classmethod
+    def from_text(cls, text: str) -> "TextInputMessage":
+        """Create a text input message from a string.
+
+        Args:
+            text: The text to send.
+
+        Returns:
+            A TextInputMessage instance.
+        """
+        return cls(realtimeInput=RealtimeInput(text=text))
+
+
 class ClientContentMessage(BaseModel):
     """Message containing client content for the API.
 
@@ -237,6 +268,55 @@ class Config(BaseModel):
     setup: Setup
 
 
+#
+# Grounding metadata models
+#
+
+
+class SearchEntryPoint(BaseModel):
+    """Represents the search entry point with rendered content for search suggestions."""
+
+    renderedContent: Optional[str] = None
+
+
+class WebSource(BaseModel):
+    """Represents a web source from grounding chunks."""
+
+    uri: Optional[str] = None
+    title: Optional[str] = None
+
+
+class GroundingChunk(BaseModel):
+    """Represents a grounding chunk containing web source information."""
+
+    web: Optional[WebSource] = None
+
+
+class GroundingSegment(BaseModel):
+    """Represents a segment of text that is grounded."""
+
+    startIndex: Optional[int] = None
+    endIndex: Optional[int] = None
+    text: Optional[str] = None
+
+
+class GroundingSupport(BaseModel):
+    """Represents support information for grounded text segments."""
+
+    segment: Optional[GroundingSegment] = None
+    groundingChunkIndices: Optional[List[int]] = None
+    confidenceScores: Optional[List[float]] = None
+
+
+class GroundingMetadata(BaseModel):
+    """Represents grounding metadata from Google Search."""
+
+    searchEntryPoint: Optional[SearchEntryPoint] = None
+    groundingChunks: Optional[List[GroundingChunk]] = None
+    groundingSupports: Optional[List[GroundingSupport]] = None
+    webSearchQueries: Optional[List[str]] = None
+
+
 #
 # Server events
 #
@@ -328,6 +408,7 @@ class ServerContent(BaseModel):
     turnComplete: Optional[bool] = None
     inputTranscription: Optional[BidiGenerateContentTranscription] = None
     outputTranscription: Optional[BidiGenerateContentTranscription] = None
+    groundingMetadata: Optional[GroundingMetadata] = None
 
 
 class FunctionCall(BaseModel):