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

pipecat/services/mcp_service.py

@@ -13,6 +13,7 @@ from loguru import logger
 
 from pipecat.adapters.schemas.function_schema import FunctionSchema
 from pipecat.adapters.schemas.tools_schema import ToolsSchema
+from pipecat.services.llm_service import FunctionCallParams
 from pipecat.utils.base_object import BaseObject
 
 try:
@@ -35,10 +36,6 @@ class MCPClient(BaseObject):
     to LLMs. Supports both stdio and SSE server connections with automatic tool
     registration and schema conversion.
 
-    Args:
-        server_params: Server connection parameters (stdio or SSE).
-        **kwargs: Additional arguments passed to the parent BaseObject.
-
     Raises:
         TypeError: If server_params is not a supported parameter type.
     """
@@ -48,9 +45,16 @@ class MCPClient(BaseObject):
         server_params: Tuple[StdioServerParameters, SseServerParameters, StreamableHttpParameters],
         **kwargs,
     ):
+        """Initialize the MCP client with server parameters.
+
+        Args:
+            server_params: Server connection parameters (stdio or SSE).
+            **kwargs: Additional arguments passed to the parent BaseObject.
+        """
         super().__init__(**kwargs)
         self._server_params = server_params
         self._session = ClientSession
+        self._needs_alternate_schema = False
 
         if isinstance(server_params, StdioServerParameters):
             self._client = stdio_client
@@ -78,9 +82,48 @@ class MCPClient(BaseObject):
         Returns:
             A ToolsSchema containing all successfully registered tools.
         """
+        # Check once if the LLM needs alternate strict schema
+        self._needs_alternate_schema = llm and llm.needs_mcp_alternate_schema()
         tools_schema = await self._register_tools(llm)
         return tools_schema
 
+    def _get_alternate_schema_for_strict_validation(self, schema: Dict[str, Any]) -> Dict[str, Any]:
+        """Get an alternate JSON schema to be compatible with LLMs that have strict validation.
+
+        Some LLMs have stricter validation and don't allow certain schema properties
+        that are valid in standard JSON Schema.
+
+        Args:
+            schema: The JSON schema to get an alternate schema for
+
+        Returns:
+            An alternate schema compatible with strict validation
+        """
+        if not isinstance(schema, dict):
+            return schema
+
+        alternate_schema = {}
+
+        for key, value in schema.items():
+            # Skip additionalProperties as some LLMs don't like additionalProperties: false
+            if key == "additionalProperties":
+                continue
+
+            # Recursively get alternate schema for nested objects
+            if isinstance(value, dict):
+                alternate_schema[key] = self._get_alternate_schema_for_strict_validation(value)
+            elif isinstance(value, list):
+                alternate_schema[key] = [
+                    self._get_alternate_schema_for_strict_validation(item)
+                    if isinstance(item, dict)
+                    else item
+                    for item in value
+                ]
+            else:
+                alternate_schema[key] = value
+
+        return alternate_schema
+
     def _convert_mcp_schema_to_pipecat(
         self, tool_name: str, tool_schema: Dict[str, Any]
     ) -> FunctionSchema:
@@ -98,6 +141,11 @@ class MCPClient(BaseObject):
         properties = tool_schema["input_schema"].get("properties", {})
         required = tool_schema["input_schema"].get("required", [])
 
+        # Only get alternate schema for LLMs that need strict schema validation
+        if self._needs_alternate_schema:
+            logger.debug("Getting alternate schema for strict validation")
+            properties = self._get_alternate_schema_for_strict_validation(properties)
+
         schema = FunctionSchema(
             name=tool_name,
             description=tool_schema["description"],
@@ -118,27 +166,24 @@ class MCPClient(BaseObject):
             A ToolsSchema containing all registered tools
         """
 
-        async def mcp_tool_wrapper(
-            function_name: str,
-            tool_call_id: str,
-            arguments: Dict[str, Any],
-            llm: any,
-            context: any,
-            result_callback: any,
-        ) -> None:
+        async def mcp_tool_wrapper(params: FunctionCallParams) -> None:
             """Wrapper for mcp tool calls to match Pipecat's function call interface."""
-            logger.debug(f"Executing tool '{function_name}' with call ID: {tool_call_id}")
-            logger.trace(f"Tool arguments: {json.dumps(arguments, indent=2)}")
+            logger.debug(
+                f"Executing tool '{params.function_name}' with call ID: {params.tool_call_id}"
+            )
+            logger.trace(f"Tool arguments: {json.dumps(params.arguments, indent=2)}")
             try:
                 async with self._client(**self._server_params.model_dump()) as (read, write):
                     async with self._session(read, write) as session:
                         await session.initialize()
-                        await self._call_tool(session, function_name, arguments, result_callback)
+                        await self._call_tool(
+                            session, params.function_name, params.arguments, params.result_callback
+                        )
             except Exception as e:
-                error_msg = f"Error calling mcp tool {function_name}: {str(e)}"
+                error_msg = f"Error calling mcp tool {params.function_name}: {str(e)}"
                 logger.error(error_msg)
                 logger.exception("Full exception details:")
-                await result_callback(error_msg)
+                await params.result_callback(error_msg)
 
         logger.debug(f"SSE server parameters: {self._server_params}")
         logger.debug("Starting registration of mcp tools")
@@ -158,27 +203,24 @@ class MCPClient(BaseObject):
             A ToolsSchema containing all registered tools
         """
 
-        async def mcp_tool_wrapper(
-            function_name: str,
-            tool_call_id: str,
-            arguments: Dict[str, Any],
-            llm: any,
-            context: any,
-            result_callback: any,
-        ) -> None:
+        async def mcp_tool_wrapper(params: FunctionCallParams) -> None:
             """Wrapper for mcp tool calls to match Pipecat's function call interface."""
-            logger.debug(f"Executing tool '{function_name}' with call ID: {tool_call_id}")
-            logger.trace(f"Tool arguments: {json.dumps(arguments, indent=2)}")
+            logger.debug(
+                f"Executing tool '{params.function_name}' with call ID: {params.tool_call_id}"
+            )
+            logger.trace(f"Tool arguments: {json.dumps(params.arguments, indent=2)}")
             try:
                 async with self._client(self._server_params) as streams:
                     async with self._session(streams[0], streams[1]) as session:
                         await session.initialize()
-                        await self._call_tool(session, function_name, arguments, result_callback)
+                        await self._call_tool(
+                            session, params.function_name, params.arguments, params.result_callback
+                        )
             except Exception as e:
-                error_msg = f"Error calling mcp tool {function_name}: {str(e)}"
+                error_msg = f"Error calling mcp tool {params.function_name}: {str(e)}"
                 logger.error(error_msg)
                 logger.exception("Full exception details:")
-                await result_callback(error_msg)
+                await params.result_callback(error_msg)
 
         logger.debug("Starting registration of mcp tools")
 
@@ -190,23 +232,19 @@ class MCPClient(BaseObject):
 
     async def _streamable_http_register_tools(self, llm) -> ToolsSchema:
         """Register all available mcp tools with the LLM service using streamable HTTP.
+
         Args:
             llm: The Pipecat LLM service to register tools with
         Returns:
             A ToolsSchema containing all registered tools
         """
 
-        async def mcp_tool_wrapper(
-            function_name: str,
-            tool_call_id: str,
-            arguments: Dict[str, Any],
-            llm: any,
-            context: any,
-            result_callback: any,
-        ) -> None:
+        async def mcp_tool_wrapper(params: FunctionCallParams) -> None:
             """Wrapper for mcp tool calls to match Pipecat's function call interface."""
-            logger.debug(f"Executing tool '{function_name}' with call ID: {tool_call_id}")
-            logger.trace(f"Tool arguments: {json.dumps(arguments, indent=2)}")
+            logger.debug(
+                f"Executing tool '{params.function_name}' with call ID: {params.tool_call_id}"
+            )
+            logger.trace(f"Tool arguments: {json.dumps(params.arguments, indent=2)}")
             try:
                 async with self._client(**self._server_params.model_dump()) as (
                     read_stream,
@@ -215,12 +253,14 @@ class MCPClient(BaseObject):
                 ):
                     async with self._session(read_stream, write_stream) as session:
                         await session.initialize()
-                        await self._call_tool(session, function_name, arguments, result_callback)
+                        await self._call_tool(
+                            session, params.function_name, params.arguments, params.result_callback
+                        )
             except Exception as e:
-                error_msg = f"Error calling mcp tool {function_name}: {str(e)}"
+                error_msg = f"Error calling mcp tool {params.function_name}: {str(e)}"
                 logger.error(error_msg)
                 logger.exception("Full exception details:")
-                await result_callback(error_msg)
+                await params.result_callback(error_msg)
 
         logger.debug("Starting registration of mcp tools using streamable HTTP")
 
@@ -277,7 +317,8 @@ class MCPClient(BaseObject):
             try:
                 # Convert the schema
                 function_schema = self._convert_mcp_schema_to_pipecat(
-                    tool_name, {"description": tool.description, "input_schema": tool.inputSchema}
+                    tool_name,
+                    {"description": tool.description, "input_schema": tool.inputSchema},
                 )
 
                 # Register the wrapped function

pipecat/services/mem0/memory.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Mem0 memory service integration for Pipecat.
+
+This module provides a memory service that integrates with Mem0 to store
+and retrieve conversational memories, enhancing LLM context with relevant
+historical information.
+"""
+
 from typing import Any, Dict, List, Optional
 
 from loguru import logger
@@ -31,14 +38,21 @@ class Mem0MemoryService(FrameProcessor):
 
     This service intercepts message frames in the pipeline, stores them in Mem0,
     and enhances context with relevant memories before passing them downstream.
-
-    Args:
-        api_key (str): The API key for accessing Mem0's API
-        user_id (str): The user ID to associate with memories in Mem0
-        params (InputParams, optional): Configuration parameters for memory retrieval
+    Supports both local and cloud-based Mem0 configurations.
     """
 
     class InputParams(BaseModel):
+        """Configuration parameters for Mem0 memory service.
+
+        Parameters:
+            search_limit: Maximum number of memories to retrieve per query.
+            search_threshold: Minimum similarity threshold for memory retrieval.
+            api_version: API version to use for Mem0 client operations.
+            system_prompt: Prefix text for memory context messages.
+            add_as_system_message: Whether to add memories as system messages.
+            position: Position to insert memory messages in context.
+        """
+
         search_limit: int = Field(default=10, ge=1)
         search_threshold: float = Field(default=0.1, ge=0.0, le=1.0)
         api_version: str = Field(default="v2")
@@ -55,7 +69,22 @@ class Mem0MemoryService(FrameProcessor):
         agent_id: Optional[str] = None,
         run_id: Optional[str] = None,
         params: Optional[InputParams] = None,
+        host: Optional[str] = None,
     ):
+        """Initialize the Mem0 memory service.
+
+        Args:
+            api_key: The API key for accessing Mem0's cloud API.
+            local_config: Local configuration for Mem0 client (alternative to cloud API).
+            user_id: The user ID to associate with memories in Mem0.
+            agent_id: The agent ID to associate with memories in Mem0.
+            run_id: The run ID to associate with memories in Mem0.
+            params: Configuration parameters for memory retrieval and storage.
+            host: The host of the Mem0 server.
+
+        Raises:
+            ValueError: If none of user_id, agent_id, or run_id are provided.
+        """
         # Important: Call the parent class __init__ first
         super().__init__()
 
@@ -65,7 +94,7 @@ class Mem0MemoryService(FrameProcessor):
         if local_config:
             self.memory_client = Memory.from_config(local_config)
         else:
-            self.memory_client = MemoryClient(api_key=api_key)
+            self.memory_client = MemoryClient(api_key=api_key, host=host)
         # At least one of user_id, agent_id, or run_id must be provided
         if not any([user_id, agent_id, run_id]):
             raise ValueError("At least one of user_id, agent_id, or run_id must be provided")
@@ -86,7 +115,7 @@ class Mem0MemoryService(FrameProcessor):
         """Store messages in Mem0.
 
         Args:
-            messages: List of message dictionaries to store
+            messages: List of message dictionaries to store in memory.
         """
         try:
             logger.debug(f"Storing {len(messages)} messages in Mem0")
@@ -110,10 +139,10 @@ class Mem0MemoryService(FrameProcessor):
         """Retrieve relevant memories from Mem0.
 
         Args:
-            query: The query to search for relevant memories
+            query: The query to search for relevant memories.
 
         Returns:
-            List of relevant memory dictionaries
+            List of relevant memory dictionaries matching the query.
         """
         try:
             logger.debug(f"Retrieving memories for query: {query}")
@@ -154,8 +183,8 @@ class Mem0MemoryService(FrameProcessor):
         """Enhance the LLM context with relevant memories.
 
         Args:
-            context: The OpenAILLMContext to enhance
-            query: The query to search for relevant memories
+            context: The OpenAILLMContext to enhance with memory information.
+            query: The query to search for relevant memories.
         """
         # Skip if this is the same query we just processed
         if self.last_query == query:
@@ -184,8 +213,8 @@ class Mem0MemoryService(FrameProcessor):
         """Process incoming frames, intercept context frames for memory integration.
 
         Args:
-            frame: The incoming frame to process
-            direction: The direction of frame flow in the pipeline
+            frame: The incoming frame to process.
+            direction: The direction of frame flow in the pipeline.
         """
         await super().process_frame(frame, direction)
 

pipecat/services/minimax/tts.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""MiniMax text-to-speech service implementation.
+
+This module provides integration with MiniMax's T2A (Text-to-Audio) API
+for streaming text-to-speech synthesis.
+"""
+
 import json
 from typing import AsyncGenerator, Optional
 
@@ -25,6 +31,14 @@ from pipecat.utils.tracing.service_decorators import traced_tts
 
 
 def language_to_minimax_language(language: Language) -> Optional[str]:
+    """Convert a Language enum to MiniMax language format.
+
+    Args:
+        language: The Language enum value to convert.
+
+    Returns:
+        The corresponding MiniMax language name, or None if not supported.
+    """
     BASE_LANGUAGES = {
         Language.AR: "Arabic",
         Language.CS: "Czech",
@@ -71,24 +85,18 @@ def language_to_minimax_language(language: Language) -> Optional[str]:
 class MiniMaxHttpTTSService(TTSService):
     """Text-to-speech service using MiniMax's T2A (Text-to-Audio) API.
 
+    Provides streaming text-to-speech synthesis using MiniMax's HTTP API
+    with support for various voice settings, emotions, and audio configurations.
+    Supports real-time audio streaming with configurable voice parameters.
+
     Platform documentation:
     https://www.minimax.io/platform/document/T2A%20V2?key=66719005a427f0c8a5701643
-
-    Args:
-        api_key: MiniMax API key for authentication.
-        group_id: MiniMax Group ID to identify project.
-        model: TTS model name (default: "speech-02-turbo"). Options include
-            "speech-02-hd", "speech-02-turbo", "speech-01-hd", "speech-01-turbo".
-        voice_id: Voice identifier (default: "Calm_Woman").
-        aiohttp_session: aiohttp.ClientSession for API communication.
-        sample_rate: Output audio sample rate in Hz (default: None, set from pipeline).
-        params: Additional configuration parameters.
     """
 
     class InputParams(BaseModel):
         """Configuration parameters for MiniMax TTS.
 
-        Attributes:
+        Parameters:
             language: Language for TTS generation.
             speed: Speech speed (range: 0.5 to 2.0).
             volume: Speech volume (range: 0 to 10).
@@ -101,7 +109,7 @@ class MiniMaxHttpTTSService(TTSService):
         language: Optional[Language] = Language.EN
         speed: Optional[float] = 1.0
         volume: Optional[float] = 1.0
-        pitch: Optional[float] = 0
+        pitch: Optional[int] = 0
         emotion: Optional[str] = None
         english_normalization: Optional[bool] = None
 
@@ -109,6 +117,7 @@ class MiniMaxHttpTTSService(TTSService):
         self,
         *,
         api_key: str,
+        base_url: str = "https://api.minimax.io/v1/t2a_v2",
         group_id: str,
         model: str = "speech-02-turbo",
         voice_id: str = "Calm_Woman",
@@ -117,13 +126,29 @@ class MiniMaxHttpTTSService(TTSService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the MiniMax TTS service.
+
+        Args:
+            api_key: MiniMax API key for authentication.
+            base_url: API base URL, defaults to MiniMax's T2A endpoint.
+                Global: https://api.minimax.io/v1/t2a_v2
+                Mainland China: https://api.minimaxi.chat/v1/t2a_v2
+            group_id: MiniMax Group ID to identify project.
+            model: TTS model name. Defaults to "speech-02-turbo". Options include
+                "speech-02-hd", "speech-02-turbo", "speech-01-hd", "speech-01-turbo".
+            voice_id: Voice identifier. Defaults to "Calm_Woman".
+            aiohttp_session: aiohttp.ClientSession for API communication.
+            sample_rate: Output audio sample rate in Hz. If None, uses pipeline default.
+            params: Additional configuration parameters.
+            **kwargs: Additional arguments passed to parent TTSService.
+        """
         super().__init__(sample_rate=sample_rate, **kwargs)
 
         params = params or MiniMaxHttpTTSService.InputParams()
 
         self._api_key = api_key
         self._group_id = group_id
-        self._base_url = f"https://api.minimaxi.chat/v1/t2a_v2?GroupId={group_id}"
+        self._base_url = f"{base_url}?GroupId={group_id}"
         self._session = aiohttp_session
         self._model_name = model
         self._voice_id = voice_id
@@ -175,28 +200,62 @@ class MiniMaxHttpTTSService(TTSService):
             self._settings["english_normalization"] = params.english_normalization
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as MiniMax service supports metrics generation.
+        """
         return True
 
     def language_to_service_language(self, language: Language) -> Optional[str]:
+        """Convert a Language enum to MiniMax service language format.
+
+        Args:
+            language: The language to convert.
+
+        Returns:
+            The MiniMax-specific language name, or None if not supported.
+        """
         return language_to_minimax_language(language)
 
     def set_model_name(self, model: str):
-        """Set the TTS model to use"""
+        """Set the TTS model to use.
+
+        Args:
+            model: The model name to use for synthesis.
+        """
         self._model_name = model
 
     def set_voice(self, voice: str):
-        """Set the voice to use"""
+        """Set the voice to use.
+
+        Args:
+            voice: The voice identifier to use for synthesis.
+        """
         self._voice_id = voice
         if "voice_setting" in self._settings:
             self._settings["voice_setting"]["voice_id"] = voice
 
     async def start(self, frame: StartFrame):
+        """Start the MiniMax TTS service.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
         self._settings["audio_setting"]["sample_rate"] = self.sample_rate
         logger.debug(f"MiniMax TTS initialized with sample rate: {self.sample_rate}")
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate TTS audio from text using MiniMax's streaming API.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames containing the synthesized speech.
+        """
         logger.debug(f"{self}: Generating TTS [{text}]")
 
         headers = {