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

pipecat/services/google/llm.py

@@ -53,7 +53,6 @@ from pipecat.services.openai.llm import (
     OpenAIAssistantContextAggregator,
     OpenAIUserContextAggregator,
 )
-from pipecat.utils.asyncio.watchdog_async_iterator import WatchdogAsyncIterator
 from pipecat.utils.tracing.service_decorators import traced_llm
 
 # Suppress gRPC fork warnings
@@ -68,6 +67,7 @@ try:
         FunctionCall,
         FunctionResponse,
         GenerateContentConfig,
+        HttpOptions,
         Part,
     )
 except ModuleNotFoundError as e:
@@ -83,21 +83,13 @@ class GoogleUserContextAggregator(OpenAIUserContextAggregator):
     Content and Part message format for user messages.
     """
 
-    async def push_aggregation(self):
-        """Push aggregated user text as a Google Content message."""
-        if len(self._aggregation) > 0:
-            self._context.add_message(Content(role="user", parts=[Part(text=self._aggregation)]))
-
-            # Reset the aggregation. Reset it before pushing it down, otherwise
-            # if the tasks gets cancelled we won't be able to clear things up.
-            self._aggregation = ""
-
-            # Push context frame
-            frame = OpenAILLMContextFrame(self._context)
-            await self.push_frame(frame)
+    async def handle_aggregation(self, aggregation: str):
+        """Add the aggregated user text to the context as a Google Content message.
 
-            # Reset our accumulator state.
-            await self.reset()
+        Args:
+            aggregation: The aggregated user text to add as a user message.
+        """
+        self._context.add_message(Content(role="user", parts=[Part(text=aggregation)]))
 
 
 class GoogleAssistantContextAggregator(OpenAIAssistantContextAggregator):
@@ -233,11 +225,6 @@ class GoogleLLMContext(OpenAILLMContext):
 
     This class handles conversion between OpenAI-style messages and Google AI's
     Content/Part format, including system messages, function calls, and media.
-
-    Args:
-        messages: Initial messages in OpenAI format.
-        tools: Available tools/functions for the model.
-        tool_choice: Tool choice configuration.
     """
 
     def __init__(
@@ -246,6 +233,13 @@ class GoogleLLMContext(OpenAILLMContext):
         tools: Optional[List[dict]] = None,
         tool_choice: Optional[dict] = None,
     ):
+        """Initialize GoogleLLMContext.
+
+        Args:
+            messages: Initial messages in OpenAI format.
+            tools: Available tools/functions for the model.
+            tool_choice: Tool choice configuration.
+        """
         super().__init__(messages=messages, tools=tools, tool_choice=tool_choice)
         self.system_message = None
 
@@ -378,18 +372,48 @@ class GoogleLLMContext(OpenAILLMContext):
         System messages are stored separately and return None.
 
         Args:
-            message: Message in standard format:
+            message: Message in standard format.
+
+        Returns:
+            Content object with role and parts, or None for system messages.
+
+        Examples:
+            Standard text message::
+
                 {
-                    "role": "user/assistant/system/tool",
-                    "content": str | [{"type": "text/image_url", ...}] | None,
-                    "tool_calls": [{"function": {"name": str, "arguments": str}}]
+                    "role": "user",
+                    "content": "Hello there"
                 }
 
-        Returns:
-            Content object with:
-                - role: "user" or "model" (converted from "assistant")
-                - parts: List[Part] containing text, inline_data, or function calls
-            Returns None for system messages.
+            Converts to Google Content with::
+
+                Content(
+                    role="user",
+                    parts=[Part(text="Hello there")]
+                )
+
+            Standard function call message::
+
+                {
+                    "role": "assistant",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "search",
+                                "arguments": '{"query": "test"}'
+                            }
+                        }
+                    ]
+                }
+
+            Converts to Google Content with::
+
+                Content(
+                    role="model",
+                    parts=[Part(function_call=FunctionCall(name="search", args={"query": "test"}))]
+                )
+
+            System message returns None and stores content in self.system_message.
         """
         role = message["role"]
         content = message.get("content", [])
@@ -445,21 +469,73 @@ class GoogleLLMContext(OpenAILLMContext):
         Handles text, images, and function calls from Google's Content/Part objects.
 
         Args:
-            obj: Google Content object with:
-                - role: "model" (converted to "assistant") or "user"
-                - parts: List[Part] containing text, inline_data, or function calls
+            obj: Google Content object with role and parts.
 
         Returns:
-            List of messages in standard format:
-            [
-                {
-                    "role": "user/assistant/tool",
-                    "content": [
-                        {"type": "text", "text": str} |
-                        {"type": "image_url", "image_url": {"url": str}}
-                    ]
-                }
-            ]
+            List containing a single message in standard format.
+
+        Examples:
+            Google Content with text::
+
+                Content(
+                    role="user",
+                    parts=[Part(text="Hello")]
+                )
+
+            Converts to::
+
+                [
+                    {
+                        "role": "user",
+                        "content": [{"type": "text", "text": "Hello"}]
+                    }
+                ]
+
+            Google Content with function call::
+
+                Content(
+                    role="model",
+                    parts=[Part(function_call=FunctionCall(name="search", args={"q": "test"}))]
+                )
+
+            Converts to::
+
+                [
+                    {
+                        "role": "assistant",
+                        "tool_calls": [
+                            {
+                                "id": "search",
+                                "type": "function",
+                                "function": {
+                                    "name": "search",
+                                    "arguments": '{"q": "test"}'
+                                }
+                            }
+                        ]
+                    }
+                ]
+
+            Google Content with image::
+
+                Content(
+                    role="user",
+                    parts=[Part(inline_data=Blob(mime_type="image/jpeg", data=bytes_data))]
+                )
+
+            Converts to::
+
+                [
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "image_url",
+                                "image_url": {"url": "data:image/jpeg;base64,<encoded_data>"}
+                            }
+                        ]
+                    }
+                ]
         """
         msg = {"role": obj.role, "content": []}
         if msg["role"] == "model":
@@ -542,9 +618,9 @@ class GoogleLLMContext(OpenAILLMContext):
         # Check if we only have function-related messages (no regular text)
         has_regular_messages = any(
             len(msg.parts) == 1
-            and not getattr(msg.parts[0], "text", None)
-            and getattr(msg.parts[0], "function_call", None)
-            and getattr(msg.parts[0], "function_response", None)
+            and getattr(msg.parts[0], "text", None)
+            and not getattr(msg.parts[0], "function_call", None)
+            and not getattr(msg.parts[0], "function_response", None)
             for msg in self._messages
         )
 
@@ -563,15 +639,6 @@ class GoogleLLMService(LLMService):
     from OpenAILLMContext to the messages format expected by the Google AI model.
     We use OpenAILLMContext as a lingua franca for all LLM services to enable
     easy switching between different LLMs.
-
-    Args:
-        api_key: Google AI API key for authentication.
-        model: Model name to use. Defaults to "gemini-2.0-flash".
-        params: Input parameters for the model.
-        system_instruction: System instruction/prompt for the model.
-        tools: List of available tools/functions.
-        tool_config: Configuration for tool usage.
-        **kwargs: Additional arguments passed to parent class.
     """
 
     # Overriding the default adapter to use the Gemini one.
@@ -603,8 +670,21 @@ class GoogleLLMService(LLMService):
         system_instruction: Optional[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
         tool_config: Optional[Dict[str, Any]] = None,
+        http_options: Optional[HttpOptions] = None,
         **kwargs,
     ):
+        """Initialize the Google LLM service.
+
+        Args:
+            api_key: Google AI API key for authentication.
+            model: Model name to use. Defaults to "gemini-2.0-flash".
+            params: Input parameters for the model.
+            system_instruction: System instruction/prompt for the model.
+            tools: List of available tools/functions.
+            tool_config: Configuration for tool usage.
+            http_options: HTTP options for the client.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
 
         params = params or GoogleLLMService.InputParams()
@@ -612,7 +692,8 @@ class GoogleLLMService(LLMService):
         self.set_model_name(model)
         self._api_key = api_key
         self._system_instruction = system_instruction
-        self._create_client(api_key)
+        self._http_options = http_options
+        self._create_client(api_key, http_options)
         self._settings = {
             "max_tokens": params.max_tokens,
             "temperature": params.temperature,
@@ -631,8 +712,33 @@ class GoogleLLMService(LLMService):
         """
         return True
 
-    def _create_client(self, api_key: str):
-        self._client = genai.Client(api_key=api_key)
+    def _create_client(self, api_key: str, http_options: Optional[HttpOptions] = None):
+        self._client = genai.Client(api_key=api_key, http_options=http_options)
+
+    def needs_mcp_alternate_schema(self) -> bool:
+        """Check if this LLM service requires alternate MCP schema.
+
+        Google/Gemini has stricter JSON schema validation and requires
+        certain properties to be removed or modified for compatibility.
+
+        Returns:
+            True for Google/Gemini services.
+        """
+        return True
+
+    def _maybe_unset_thinking_budget(self, generation_params: Dict[str, Any]):
+        try:
+            # There's no way to introspect on model capabilities, so
+            # to check for models that we know default to thinkin on
+            # and can be configured to turn it off.
+            if not self._model_name.startswith("gemini-2.5-flash"):
+                return
+            # If thinking_config is already set, don't override it.
+            if "thinking_config" in generation_params:
+                return
+            generation_params.setdefault("thinking_config", {})["thinking_budget"] = 0
+        except Exception as e:
+            logger.exception(f"Failed to unset thinking budget: {e}")
 
     @traced_llm
     async def _process_context(self, context: OpenAILLMContext):
@@ -641,6 +747,8 @@ class GoogleLLMService(LLMService):
         prompt_tokens = 0
         completion_tokens = 0
         total_tokens = 0
+        cache_read_input_tokens = 0
+        reasoning_tokens = 0
 
         grounding_metadata = None
         search_result = ""
@@ -680,6 +788,12 @@ class GoogleLLMService(LLMService):
                 if v is not None
             }
 
+            if self._settings["extra"]:
+                generation_params.update(self._settings["extra"])
+
+            # possibly modify generation_params (in place) to set thinking to off by default
+            self._maybe_unset_thinking_budget(generation_params)
+
             generation_config = (
                 GenerateContentConfig(**generation_params) if generation_params else None
             )
@@ -692,13 +806,15 @@ class GoogleLLMService(LLMService):
             )
 
             function_calls = []
-            async for chunk in WatchdogAsyncIterator(response, manager=self.task_manager):
+            async for chunk in response:
                 # Stop TTFB metrics after the first chunk
                 await self.stop_ttfb_metrics()
                 if chunk.usage_metadata:
                     prompt_tokens += chunk.usage_metadata.prompt_token_count or 0
                     completion_tokens += chunk.usage_metadata.candidates_token_count or 0
                     total_tokens += chunk.usage_metadata.total_token_count or 0
+                    cache_read_input_tokens += chunk.usage_metadata.cached_content_token_count or 0
+                    reasoning_tokens += chunk.usage_metadata.thoughts_token_count or 0
 
                 if not chunk.candidates:
                     continue
@@ -780,6 +896,8 @@ class GoogleLLMService(LLMService):
                     prompt_tokens=prompt_tokens,
                     completion_tokens=completion_tokens,
                     total_tokens=total_tokens,
+                    cache_read_input_tokens=cache_read_input_tokens,
+                    reasoning_tokens=reasoning_tokens,
                 )
             )
             await self.push_frame(LLMFullResponseEndFrame())

pipecat/services/google/llm_openai.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google LLM service using OpenAI-compatible API format.
+
+This module provides integration with Google's AI LLM models using the OpenAI
+API format through Google's Gemini API OpenAI compatibility layer.
+"""
+
 import json
 import os
 
@@ -11,7 +17,6 @@ from openai import AsyncStream
 from openai.types.chat import ChatCompletionChunk
 
 from pipecat.services.llm_service import FunctionCallFromLLM
-from pipecat.utils.asyncio.watchdog_async_iterator import WatchdogAsyncIterator
 
 # Suppress gRPC fork warnings
 os.environ["GRPC_ENABLE_FORK_SUPPORT"] = "false"
@@ -27,8 +32,17 @@ from pipecat.services.openai.llm import OpenAILLMService
 
 
 class GoogleLLMOpenAIBetaService(OpenAILLMService):
-    """This class implements inference with Google's AI LLM models using the OpenAI format.
-    Ref - https://ai.google.dev/gemini-api/docs/openai
+    """Google LLM service using OpenAI-compatible API format.
+
+    This service provides access to Google's AI LLM models (like Gemini) through
+    the OpenAI API format. It handles streaming responses, function calls, and
+    tool usage while maintaining compatibility with OpenAI's interface.
+
+    Note: This service includes a workaround for a Google API bug where function
+    call indices may be incorrectly set to None, resulting in empty function names.
+
+    Reference:
+        https://ai.google.dev/gemini-api/docs/openai
     """
 
     def __init__(
@@ -39,6 +53,14 @@ class GoogleLLMOpenAIBetaService(OpenAILLMService):
         model: str = "gemini-2.0-flash",
         **kwargs,
     ):
+        """Initialize the Google LLM service.
+
+        Args:
+            api_key: Google API key for authentication.
+            base_url: Base URL for Google's OpenAI-compatible API.
+            model: Google model name to use (e.g., "gemini-2.0-flash").
+            **kwargs: Additional arguments passed to the parent OpenAILLMService.
+        """
         super().__init__(api_key=api_key, base_url=base_url, model=model, **kwargs)
 
     async def _process_context(self, context: OpenAILLMContext):
@@ -56,7 +78,7 @@ class GoogleLLMOpenAIBetaService(OpenAILLMService):
             context
         )
 
-        async for chunk in WatchdogAsyncIterator(chunk_stream, manager=self.task_manager):
+        async for chunk in chunk_stream:
             if chunk.usage:
                 tokens = LLMTokenUsage(
                     prompt_tokens=chunk.usage.prompt_tokens,

pipecat/services/google/llm_vertex.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google Vertex AI LLM service implementation.
+
+This module provides integration with Google's AI models via Vertex AI while
+maintaining OpenAI API compatibility through Google's OpenAI-compatible endpoint.
+"""
+
 import json
 import os
 
@@ -31,16 +37,24 @@ except ModuleNotFoundError as e:
 
 
 class GoogleVertexLLMService(OpenAILLMService):
-    """Implements inference with Google's AI models via Vertex AI while
-    maintaining OpenAI API compatibility.
+    """Google Vertex AI LLM service with OpenAI API compatibility.
 
-    Reference:
-    https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/call-vertex-using-openai-library
+    Provides access to Google's AI models via Vertex AI while maintaining
+    OpenAI API compatibility. Handles authentication using Google service
+    account credentials and constructs appropriate endpoint URLs for
+    different GCP regions and projects.
 
+    Reference:
+        https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/call-vertex-using-openai-library
     """
 
     class InputParams(OpenAILLMService.InputParams):
-        """Input parameters specific to Vertex AI."""
+        """Input parameters specific to Vertex AI.
+
+        Parameters:
+            location: GCP region for Vertex AI endpoint (e.g., "us-east4").
+            project_id: Google Cloud project ID.
+        """
 
         # https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations
         location: str = "us-east4"
@@ -58,11 +72,11 @@ class GoogleVertexLLMService(OpenAILLMService):
         """Initializes the VertexLLMService.
 
         Args:
-            credentials (Optional[str]): JSON string of service account credentials.
-            credentials_path (Optional[str]): Path to the service account JSON file.
-            model (str): Model identifier. Defaults to "google/gemini-2.0-flash-001".
-            params (InputParams): Vertex AI input parameters.
-            **kwargs: Additional arguments for OpenAILLMService.
+            credentials: JSON string of service account credentials.
+            credentials_path: Path to the service account JSON file.
+            model: Model identifier (e.g., "google/gemini-2.0-flash-001").
+            params: Vertex AI input parameters including location and project.
+            **kwargs: Additional arguments passed to OpenAILLMService.
         """
         params = params or OpenAILLMService.InputParams()
         base_url = self._get_base_url(params)
@@ -74,7 +88,7 @@ class GoogleVertexLLMService(OpenAILLMService):
 
     @staticmethod
     def _get_base_url(params: InputParams) -> str:
-        """Constructs the base URL for the Vertex AI API."""
+        """Constructs the base URL for Vertex AI API."""
         hostname_prefix = "" if params.location == "global" else f"{params.location}-"
         return (
             f"https://{hostname_prefix}aiplatform.googleapis.com/v1/"
@@ -83,14 +97,22 @@ class GoogleVertexLLMService(OpenAILLMService):
 
     @staticmethod
     def _get_api_token(credentials: Optional[str], credentials_path: Optional[str]) -> str:
-        """Retrieves an authentication token using Google service account credentials.
+        """Retrieve an authentication token using Google service account credentials.
+
+        Supports multiple authentication methods:
+        1. Direct JSON credentials string
+        2. Path to service account JSON file
+        3. Default application credentials (ADC)
 
         Args:
-            credentials (Optional[str]): JSON string of service account credentials.
-            credentials_path (Optional[str]): Path to the service account JSON file.
+            credentials: JSON string of service account credentials.
+            credentials_path: Path to the service account JSON file.
 
         Returns:
-            str: OAuth token for API authentication.
+            OAuth token for API authentication.
+
+        Raises:
+            ValueError: If no valid credentials are provided or found.
         """
         creds: Optional[service_account.Credentials] = None
 

pipecat/services/google/rtvi.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Google RTVI integration models and observer implementation.
+
+This module provides integration with Google's services through the RTVI framework,
+including models for search responses and an observer for handling Google-specific
+frame types.
+"""
+
 from typing import List, Literal, Optional
 
 from pydantic import BaseModel
@@ -16,22 +23,56 @@ from pipecat.services.google.frames import LLMSearchOrigin, LLMSearchResponseFra
 
 
 class RTVISearchResponseMessageData(BaseModel):
+    """Data payload for search response messages in RTVI protocol.
+
+    Parameters:
+        search_result: The search result text, if available.
+        rendered_content: The rendered content from the search, if available.
+        origins: List of search result origins with metadata.
+    """
+
     search_result: Optional[str]
     rendered_content: Optional[str]
     origins: List[LLMSearchOrigin]
 
 
 class RTVIBotLLMSearchResponseMessage(BaseModel):
+    """RTVI message for bot LLM search responses.
+
+    Parameters:
+        label: Always "rtvi-ai" for RTVI protocol messages.
+        type: Always "bot-llm-search-response" for this message type.
+        data: The search response data payload.
+    """
+
     label: Literal["rtvi-ai"] = "rtvi-ai"
     type: Literal["bot-llm-search-response"] = "bot-llm-search-response"
     data: RTVISearchResponseMessageData
 
 
 class GoogleRTVIObserver(RTVIObserver):
+    """RTVI observer for Google service integration.
+
+    Extends the base RTVIObserver to handle Google-specific frame types,
+    particularly LLM search response frames from Google services.
+    """
+
     def __init__(self, rtvi: RTVIProcessor):
+        """Initialize the Google RTVI observer.
+
+        Args:
+            rtvi: The RTVI processor to send messages through.
+        """
         super().__init__(rtvi)
 
     async def on_push_frame(self, data: FramePushed):
+        """Process frames being pushed through the pipeline.
+
+        Handles Google-specific frames in addition to the base RTVI frame types.
+
+        Args:
+            data: Frame push event data containing frame and metadata.
+        """
         await super().on_push_frame(data)
 
         frame = data.frame