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

pipecat/adapters/schemas/direct_function.py

@@ -0,0 +1,296 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Direct function wrapper utilities for LLM function calling.
+
+This module provides utilities for wrapping "direct" functions that handle LLM
+function calls. Direct functions have their metadata automatically extracted
+from function signatures and docstrings, allowing them to be used without
+accompanying configurations (as FunctionSchemas or in provider-specific
+formats).
+"""
+
+import inspect
+import types
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Mapping,
+    Protocol,
+    Set,
+    Tuple,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+import docstring_parser
+
+from pipecat.adapters.schemas.function_schema import FunctionSchema
+
+if TYPE_CHECKING:
+    from pipecat.services.llm_service import FunctionCallParams
+
+
+class DirectFunction(Protocol):
+    """Protocol for a "direct" function that handles LLM function calls.
+
+    "Direct" functions' metadata is automatically extracted from their function signature and
+    docstrings, allowing them to be used without accompanying function configurations (as
+    FunctionSchemas or in provider-specific formats).
+    """
+
+    async def __call__(self, params: "FunctionCallParams", **kwargs: Any) -> None:
+        """Execute the direct function.
+
+        Args:
+            params: Function call parameters from the LLM service.
+            **kwargs: Additional keyword arguments passed to the function.
+        """
+        ...
+
+
+class BaseDirectFunctionWrapper:
+    """Base class for a wrapper around a DirectFunction.
+
+    Provides functionality to:
+
+    - extract metadata from the function signature and docstring
+    - use that metadata to generate a corresponding FunctionSchema
+    """
+
+    def __init__(self, function: Callable):
+        """Initialize the direct function wrapper.
+
+        Args:
+            function: The function to wrap and extract metadata from.
+        """
+        self.__class__.validate_function(function)
+        self.function = function
+        self._initialize_metadata()
+
+    @classmethod
+    def special_first_param_name(cls) -> str:
+        """Get the name of the special first function parameter.
+
+        The special first parameter is ignored by metadata extraction as it's
+        not relevant to the LLM (e.g., 'params' for FunctionCallParams).
+
+        Returns:
+            The name of the special first parameter.
+        """
+        raise NotImplementedError("Subclasses must define the special first parameter name.")
+
+    @classmethod
+    def validate_function(cls, function: Callable) -> None:
+        """Validate that the function meets direct function requirements.
+
+        Args:
+            function: The function to validate.
+
+        Raises:
+            Exception: If function doesn't meet requirements (not async, missing
+                parameters, incorrect first parameter name).
+        """
+        if not inspect.iscoroutinefunction(function):
+            raise Exception(f"Direct function {function.__name__} must be async")
+        params = list(inspect.signature(function).parameters.items())
+        special_first_param_name = cls.special_first_param_name()
+        if len(params) == 0:
+            raise Exception(
+                f"Direct function {function.__name__} must have at least one parameter ({special_first_param_name})"
+            )
+        first_param_name = params[0][0]
+        if first_param_name != special_first_param_name:
+            raise Exception(
+                f"Direct function {function.__name__} first parameter must be named '{special_first_param_name}'"
+            )
+
+    def to_function_schema(self) -> FunctionSchema:
+        """Convert the wrapped function to a FunctionSchema.
+
+        Returns:
+            A FunctionSchema instance with extracted metadata.
+        """
+        return FunctionSchema(
+            name=self.name,
+            description=self.description,
+            properties=self.properties,
+            required=self.required,
+        )
+
+    def _initialize_metadata(self):
+        """Initialize metadata from function signature and docstring."""
+        # Get function name
+        self.name = self.function.__name__
+
+        # Parse docstring for description and parameters
+        docstring = docstring_parser.parse(inspect.getdoc(self.function))
+
+        # Get function description
+        self.description = (docstring.description or "").strip()
+
+        # Get function parameters as JSON schemas, and the list of required parameters
+        self.properties, self.required = self._get_parameters_as_jsonschema(
+            self.function, docstring.params
+        )
+
+    # TODO: maybe to better support things like enums, check if each type is a pydantic type and use its convert-to-jsonschema function
+    def _get_parameters_as_jsonschema(
+        self, func: Callable, docstring_params: List[docstring_parser.DocstringParam]
+    ) -> Tuple[Dict[str, Any], List[str]]:
+        """Get function parameters as a dictionary of JSON schemas and a list of required parameters.
+
+        Ignore the first parameter, as it's expected to be the "special" one.
+
+        Args:
+            func: Function to get parameters from.
+            docstring_params: List of parameters extracted from the function's docstring.
+
+        Returns:
+            A tuple containing:
+
+            - A dictionary mapping each function parameter to its JSON schema
+            - A list of required parameter names
+        """
+        sig = inspect.signature(func)
+        hints = get_type_hints(func)
+        properties = {}
+        required = []
+
+        for name, param in sig.parameters.items():
+            # Ignore 'self' parameter
+            if name == "self":
+                continue
+
+            # Ignore the first parameter, which is expected to be the "special" one
+            # (We have already validated that this is the case in validate_function())
+            is_first_param = name == next(iter(sig.parameters))
+            if is_first_param:
+                continue
+
+            type_hint = hints.get(name)
+
+            # Convert type hint to JSON schema
+            properties[name] = self._typehint_to_jsonschema(type_hint)
+
+            # Add whether the parameter is required
+            # If the parameter has no default value, it's required
+            if param.default is inspect.Parameter.empty:
+                required.append(name)
+
+            # Add parameter description from docstring
+            for doc_param in docstring_params:
+                if doc_param.arg_name == name:
+                    properties[name]["description"] = doc_param.description or ""
+
+        return properties, required
+
+    def _typehint_to_jsonschema(self, type_hint: Any) -> Dict[str, Any]:
+        """Convert a Python type hint to a JSON Schema.
+
+        Args:
+            type_hint: A Python type hint
+
+        Returns:
+            A dictionary representing the JSON Schema
+        """
+        if type_hint is None:
+            return {}
+
+        # Handle basic types
+        if type_hint is type(None):
+            return {"type": "null"}
+        if type_hint is str:
+            return {"type": "string"}
+        elif type_hint is int:
+            return {"type": "integer"}
+        elif type_hint is float:
+            return {"type": "number"}
+        elif type_hint is bool:
+            return {"type": "boolean"}
+        elif type_hint is dict or type_hint is Dict:
+            return {"type": "object"}
+        elif type_hint is list or type_hint is List:
+            return {"type": "array"}
+
+        # Get origin and arguments for complex types
+        origin = get_origin(type_hint)
+        args = get_args(type_hint)
+
+        # Handle Optional/Union types
+        if origin is Union or origin is types.UnionType:
+            return {"anyOf": [self._typehint_to_jsonschema(arg) for arg in args]}
+
+        # Handle List, Tuple, Set with specific item types
+        if origin in (list, List, tuple, Tuple, set, Set) and args:
+            return {"type": "array", "items": self._typehint_to_jsonschema(args[0])}
+
+        # Handle Dict with specific key/value types
+        if origin in (dict, Dict) and len(args) == 2:
+            # For JSON Schema, keys must be strings
+            return {"type": "object", "additionalProperties": self._typehint_to_jsonschema(args[1])}
+
+        # Handle TypedDict
+        if hasattr(type_hint, "__annotations__"):
+            properties = {}
+            required = []
+
+            # NOTE: this does not yet support some fields being required and others not, which could happen when:
+            # - the base class is a TypedDict with required fields (total=True or not specified) and the derived class has optional fields (total=False)
+            # - Python 3.11+ NotRequired is used
+            all_fields_required = getattr(type_hint, "__total__", True)
+
+            for field_name, field_type in get_type_hints(type_hint).items():
+                properties[field_name] = self._typehint_to_jsonschema(field_type)
+                if all_fields_required:
+                    required.append(field_name)
+
+            schema = {"type": "object", "properties": properties}
+
+            if required:
+                schema["required"] = required
+
+            return schema
+
+        # Default to any type if we can't determine the specific schema
+        return {}
+
+
+class DirectFunctionWrapper(BaseDirectFunctionWrapper):
+    """Wrapper around a DirectFunction for LLM function calling.
+
+    This class:
+
+    - Extracts metadata from the function signature and docstring
+    - Generates a corresponding FunctionSchema
+    - Helps with function invocation
+    """
+
+    @classmethod
+    def special_first_param_name(cls) -> str:
+        """Get the special first parameter name for direct functions.
+
+        Returns:
+            The string "params" which is expected as the first parameter.
+        """
+        return "params"
+
+    async def invoke(self, args: Mapping[str, Any], params: "FunctionCallParams"):
+        """Invoke the wrapped function with the provided arguments.
+
+        Args:
+            args: Arguments to pass to the function.
+            params: Function call parameters from the LLM service.
+
+        Returns:
+            The result of the function call.
+        """
+        return await self.function(params=params, **args)

pipecat/adapters/schemas/function_schema.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Function schema utilities for AI tool definitions.
+
+This module provides standardized function schema representation for defining
+tools and functions used with AI models, ensuring consistent formatting
+across different AI service providers.
+"""
+
 from typing import Any, Dict, List
 
 
@@ -13,17 +20,19 @@ class FunctionSchema:
     Provides a structured way to define function tools used with AI models like OpenAI.
     This schema defines the function's name, description, parameter properties, and
     required parameters, following specifications required by AI service providers.
-
-    Args:
-        name: Name of the function to be called.
-        description: Description of what the function does.
-        properties: Dictionary defining parameter types, descriptions, and constraints.
-        required: List of property names that are required parameters.
     """
 
     def __init__(
         self, name: str, description: str, properties: Dict[str, Any], required: List[str]
     ) -> None:
+        """Initialize the function schema.
+
+        Args:
+            name: Name of the function to be called.
+            description: Description of what the function does.
+            properties: Dictionary defining parameter types, descriptions, and constraints.
+            required: List of property names that are required parameters.
+        """
         self._name = name
         self._description = description
         self._properties = properties

pipecat/adapters/schemas/tools_schema.py

@@ -4,40 +4,88 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Tools schema definitions for function calling adapters.
+
+This module provides schemas for managing both standardized function tools
+and custom adapter-specific tools in the Pipecat framework.
+"""
+
 from enum import Enum
 from typing import Any, Dict, List, Optional
 
+from pipecat.adapters.schemas.direct_function import DirectFunction, DirectFunctionWrapper
 from pipecat.adapters.schemas.function_schema import FunctionSchema
 
 
 class AdapterType(Enum):
+    """Supported adapter types for custom tools.
+
+    Parameters:
+        GEMINI: Google Gemini adapter - currently the only service supporting custom tools.
+    """
+
     GEMINI = "gemini"  # that is the only service where we are able to add custom tools for now
 
 
 class ToolsSchema:
+    """Schema for managing both standard and custom function calling tools.
+
+    This class provides a unified interface for handling standardized function
+    schemas alongside custom tools that may not follow the standard format,
+    such as adapter-specific search tools.
+    """
+
     def __init__(
         self,
-        standard_tools: List[FunctionSchema],
+        standard_tools: List[FunctionSchema | DirectFunction],
         custom_tools: Optional[Dict[AdapterType, List[Dict[str, Any]]]] = None,
     ) -> None:
-        """
-        A schema for tools that includes both standardized function schemas
-        and custom tools that do not follow the FunctionSchema format.
+        """Initialize the tools schema.
 
-        :param standard_tools: List of tools following FunctionSchema.
-        :param custom_tools: List of tools in a custom format (e.g., search_tool).
+        Args:
+            standard_tools: List of tools following the standardized FunctionSchema format.
+            custom_tools: Dictionary mapping adapter types to their custom tool definitions.
+                These tools may not follow the FunctionSchema format (e.g., search_tool).
         """
-        self._standard_tools = standard_tools
+
+        def _map_standard_tools(tools):
+            schemas = []
+            for tool in tools:
+                if isinstance(tool, FunctionSchema):
+                    schemas.append(tool)
+                elif callable(tool):
+                    wrapper = DirectFunctionWrapper(tool)
+                    schemas.append(wrapper.to_function_schema())
+                else:
+                    raise TypeError(f"Unsupported tool type: {type(tool)}")
+            return schemas
+
+        self._standard_tools = _map_standard_tools(standard_tools)
         self._custom_tools = custom_tools
 
     @property
     def standard_tools(self) -> List[FunctionSchema]:
+        """Get the list of standard function schema tools.
+
+        Returns:
+            List of tools following the FunctionSchema format.
+        """
         return self._standard_tools
 
     @property
     def custom_tools(self) -> Dict[AdapterType, List[Dict[str, Any]]]:
+        """Get the custom tools dictionary.
+
+        Returns:
+            Dictionary mapping adapter types to their custom tool definitions.
+        """
         return self._custom_tools
 
     @custom_tools.setter
     def custom_tools(self, value: Dict[AdapterType, List[Dict[str, Any]]]) -> None:
+        """Set the custom tools dictionary.
+
+        Args:
+            value: Dictionary mapping adapter types to their custom tool definitions.
+        """
         self._custom_tools = value

pipecat/adapters/services/anthropic_adapter.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Anthropic LLM adapter for Pipecat."""
+
 from typing import Any, Dict, List
 
 from pipecat.adapters.base_llm_adapter import BaseLLMAdapter
@@ -12,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema
 
 
 class AnthropicLLMAdapter(BaseLLMAdapter):
+    """Adapter for converting tool schemas to Anthropic's function-calling format.
+
+    This adapter handles the conversion of Pipecat's standard function schemas
+    to the specific format required by Anthropic's Claude models for function calling.
+    """
+
     @staticmethod
     def _to_anthropic_function_format(function: FunctionSchema) -> Dict[str, Any]:
+        """Convert a single function schema to Anthropic's format.
+
+        Args:
+            function: The function schema to convert.
+
+        Returns:
+            Dictionary containing the function definition in Anthropic's format.
+        """
         return {
             "name": function.name,
             "description": function.description,
@@ -25,10 +41,13 @@ class AnthropicLLMAdapter(BaseLLMAdapter):
         }
 
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]:
-        """Converts function schemas to Anthropic's function-calling format.
+        """Convert function schemas to Anthropic's function-calling format.
 
-        :return: Anthropic formatted function call definition.
-        """
+        Args:
+            tools_schema: The tools schema containing functions to convert.
 
+        Returns:
+            List of function definitions formatted for Anthropic's API.
+        """
         functions_schema = tools_schema.standard_tools
         return [self._to_anthropic_function_format(func) for func in functions_schema]

pipecat/adapters/services/aws_nova_sonic_adapter.py

@@ -3,6 +3,9 @@
 #
 # SPDX-License-Identifier: BSD 2-Clause License
 #
+
+"""AWS Nova Sonic LLM adapter for Pipecat."""
+
 import json
 from typing import Any, Dict, List
 
@@ -12,8 +15,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema
 
 
 class AWSNovaSonicLLMAdapter(BaseLLMAdapter):
+    """Adapter for AWS Nova Sonic language models.
+
+    Converts Pipecat's standard function schemas into AWS Nova Sonic's
+    specific function-calling format, enabling tool use with Nova Sonic models.
+    """
+
     @staticmethod
     def _to_aws_nova_sonic_function_format(function: FunctionSchema) -> Dict[str, Any]:
+        """Convert a function schema to AWS Nova Sonic format.
+
+        Args:
+            function: The function schema to convert.
+
+        Returns:
+            Dictionary in AWS Nova Sonic function format with toolSpec structure.
+        """
         return {
             "toolSpec": {
                 "name": function.name,
@@ -31,10 +48,13 @@ class AWSNovaSonicLLMAdapter(BaseLLMAdapter):
         }
 
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]:
-        """Converts function schemas to AWS Nova Sonic function-calling format.
+        """Convert tools schema to AWS Nova Sonic function-calling format.
 
-        :return: AWS Nova Sonic formatted function call definition.
-        """
+        Args:
+            tools_schema: The tools schema containing function definitions to convert.
 
+        Returns:
+            List of dictionaries in AWS Nova Sonic function format.
+        """
         functions_schema = tools_schema.standard_tools
         return [self._to_aws_nova_sonic_function_format(func) for func in functions_schema]

pipecat/adapters/services/bedrock_adapter.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""AWS Bedrock LLM adapter for Pipecat."""
+
 from typing import Any, Dict, List
 
 from pipecat.adapters.base_llm_adapter import BaseLLMAdapter
@@ -12,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema
 
 
 class AWSBedrockLLMAdapter(BaseLLMAdapter):
+    """Adapter for AWS Bedrock LLM integration with Pipecat.
+
+    Provides conversion utilities for transforming Pipecat function schemas
+    into AWS Bedrock's expected tool format for function calling capabilities.
+    """
+
     @staticmethod
     def _to_bedrock_function_format(function: FunctionSchema) -> Dict[str, Any]:
+        """Convert a function schema to Bedrock's tool format.
+
+        Args:
+            function: The function schema to convert.
+
+        Returns:
+            Dictionary formatted for Bedrock's tool specification.
+        """
         return {
             "toolSpec": {
                 "name": function.name,
@@ -29,10 +45,13 @@ class AWSBedrockLLMAdapter(BaseLLMAdapter):
         }
 
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]:
-        """Converts function schemas to Bedrock's function-calling format.
+        """Convert function schemas to Bedrock's function-calling format.
 
-        :return: Bedrock formatted function call definition.
-        """
+        Args:
+            tools_schema: The tools schema containing functions to convert.
 
+        Returns:
+            List of Bedrock formatted function call definitions.
+        """
         functions_schema = tools_schema.standard_tools
         return [self._to_bedrock_function_format(func) for func in functions_schema]

pipecat/adapters/services/gemini_adapter.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Gemini LLM adapter for Pipecat."""
+
 from typing import Any, Dict, List, Union
 
 from pipecat.adapters.base_llm_adapter import BaseLLMAdapter
@@ -11,12 +13,23 @@ from pipecat.adapters.schemas.tools_schema import AdapterType, ToolsSchema
 
 
 class GeminiLLMAdapter(BaseLLMAdapter):
+    """LLM adapter for Google's Gemini service.
+
+    Provides tool schema conversion functionality to transform standard tool
+    definitions into Gemini's specific function-calling format for use with
+    Gemini LLM models.
+    """
+
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]:
-        """Converts function schemas to Gemini's function-calling format.
+        """Convert tool schemas to Gemini's function-calling format.
 
-        :return: Gemini formatted function call definition.
-        """
+        Args:
+            tools_schema: The tools schema containing standard and custom tool definitions.
 
+        Returns:
+            List of tool definitions formatted for Gemini's function-calling API.
+            Includes both converted standard tools and any custom Gemini-specific tools.
+        """
         functions_schema = tools_schema.standard_tools
         formatted_standard_tools = [
             {"function_declarations": [func.to_default_dict() for func in functions_schema]}

pipecat/adapters/services/open_ai_adapter.py

@@ -3,6 +3,9 @@
 #
 # SPDX-License-Identifier: BSD 2-Clause License
 #
+
+"""OpenAI LLM adapter for Pipecat."""
+
 from typing import List
 
 from openai.types.chat import ChatCompletionToolParam
@@ -12,10 +15,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema
 
 
 class OpenAILLMAdapter(BaseLLMAdapter):
+    """Adapter for converting tool schemas to OpenAI's format.
+
+    Provides conversion utilities for transforming Pipecat's standard tool
+    schemas into the format expected by OpenAI's ChatCompletion API for
+    function calling capabilities.
+    """
+
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[ChatCompletionToolParam]:
-        """Converts function schemas to OpenAI's function-calling format.
+        """Convert function schemas to OpenAI's function-calling format.
+
+        Args:
+            tools_schema: The Pipecat tools schema to convert.
 
-        :return: OpenAI formatted function call definition.
+        Returns:
+            List of OpenAI formatted function call definitions ready for use
+            with ChatCompletion API.
         """
         functions_schema = tools_schema.standard_tools
         return [