autobyteus 1.1.5__py3-none-any.whl → 1.1.7__py3-none-any.whl

autobyteus/tools/base_tool.py

@@ -2,18 +2,17 @@
 
 import logging
 from abc import ABC, abstractmethod
-from typing import Optional, Any, TYPE_CHECKING, List as TypingList, Dict
-import xml.sax.saxutils
+from typing import Optional, Any, TYPE_CHECKING, List as TypingList, Dict, Union
 
 from autobyteus.events.event_emitter import EventEmitter
-from autobyteus.events.event_types import EventType
+from autobyteus.tools.parameter_schema import ParameterType
 
 from .tool_meta import ToolMeta
 from .tool_state import ToolState
 
 if TYPE_CHECKING:
     from autobyteus.agent.context import AgentContext
-    from autobyteus.tools.parameter_schema import ParameterSchema
+    from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition
     from autobyteus.tools.tool_config import ToolConfig
     from .tool_state import ToolState
     from autobyteus.tools.registry import ToolDefinition
@@ -27,41 +26,115 @@ class BaseTool(ABC, EventEmitter, metaclass=ToolMeta):
     def __init__(self, config: Optional['ToolConfig'] = None):
         super().__init__()
         self.agent_id: Optional[str] = None
-        self.definition: Optional['ToolDefinition'] = None # Link back to its definition
-        # The config is stored primarily for potential use by subclasses or future base features.
+        self.definition: Optional['ToolDefinition'] = None
         self._config = config
-        # Add a dedicated state dictionary for the tool instance
-        # CHANGED: Use ToolState class for explicit state management.
         self.tool_state: 'ToolState' = ToolState()
         logger.debug(f"BaseTool instance initializing for potential class {self.__class__.__name__}. tool_state initialized.")
 
     @classmethod
     def get_name(cls) -> str:
-        """Returns the registered name of the tool."""
         return cls.__name__
     
     @classmethod
     @abstractmethod
     def get_description(cls) -> str:
-        """Returns the description of the tool."""
         raise NotImplementedError("Subclasses must implement get_description().")
 
     @classmethod
     @abstractmethod
     def get_argument_schema(cls) -> Optional['ParameterSchema']: 
-        """
-        Return a ParameterSchema defining the arguments this tool accepts for execution.
-        Return None if the tool accepts no arguments.
-        """
         raise NotImplementedError("Subclasses must implement get_argument_schema().")
 
     @classmethod
     def get_config_schema(cls) -> Optional['ParameterSchema']: 
+        return None
+
+    def _coerce_argument_types(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Return the ParameterSchema for tool *instantiation* parameters.
-        This is optional. By default, tools have no instantiation config.
+        Coerces argument values from the parser (often strings) to their proper
+        Python types based on the tool's argument schema.
+        This method is fully recursive to handle nested objects and arrays.
         """
-        return None
+        arg_schema = self.get_argument_schema()
+        if not arg_schema:
+            return kwargs
+
+        return self._coerce_object_recursively(kwargs, arg_schema)
+
+    def _coerce_object_recursively(self, data: Dict[str, Any], schema: 'ParameterSchema') -> Dict[str, Any]:
+        """ Helper to recursively coerce values in an object based on a ParameterSchema. """
+        coerced_data = data.copy()
+        for name, value in data.items():
+            param_def = schema.get_parameter(name)
+            if param_def:
+                coerced_data[name] = self._coerce_value_recursively(value, param_def)
+        return coerced_data
+
+    def _coerce_value_recursively(self, value: Any, param_def: 'ParameterDefinition') -> Any:
+        """ Coerces a single value based on its ParameterDefinition, recursing into complex types. """
+        if value is None:
+            return None
+
+        # 1. Coerce empty string to empty list for ARRAY types. This is a common parser artifact.
+        if param_def.param_type == ParameterType.ARRAY and value == "":
+            return []
+
+        # 2. Recurse into objects
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema and isinstance(value, dict):
+            return self._coerce_object_recursively(value, param_def.object_schema)
+
+        # 3. Recurse into arrays.
+        if param_def.param_type == ParameterType.ARRAY and isinstance(value, list):
+            item_schema_dict = param_def.array_item_schema
+            # If items are objects described by a schema, coerce each one.
+            if item_schema_dict and isinstance(item_schema_dict, dict) and item_schema_dict.get("type") == "object":
+                # Create a temporary ParameterSchema for the item type to enable recursion.
+                # This is a simplified conversion for coercion purposes only.
+                from .parameter_schema import ParameterSchema as TempSchema
+                from .parameter_schema import ParameterDefinition as TempDef
+
+                item_param_schema = TempSchema()
+                props = item_schema_dict.get("properties", {})
+                reqs = item_schema_dict.get("required", [])
+                for prop_name, prop_details in props.items():
+                    # This is a simplified conversion and might not capture all details,
+                    # but it's sufficient for recursive coercion.
+                    prop_type_str = prop_details.get("type", "string")
+                    try:
+                        prop_type = ParameterType(prop_type_str)
+                    except ValueError:
+                        prop_type = ParameterType.STRING
+                    
+                    item_param_schema.add_parameter(TempDef(
+                        name=prop_name,
+                        param_type=prop_type,
+                        description=prop_details.get("description", ""),
+                        required=prop_name in reqs,
+                        array_item_schema=prop_details.get("items") # Pass down nested array schemas
+                    ))
+                
+                return [self._coerce_object_recursively(item, item_param_schema) for item in value if isinstance(item, dict)]
+
+            return value # Return list of primitives as is
+
+        # 4. Coerce primitives if they are passed as strings
+        if isinstance(value, str):
+            try:
+                if param_def.param_type == ParameterType.INTEGER:
+                    return int(value)
+                elif param_def.param_type == ParameterType.FLOAT:
+                    return float(value)
+                elif param_def.param_type == ParameterType.BOOLEAN:
+                    lower_val = value.lower()
+                    if lower_val in ["true", "1", "yes"]:
+                        return True
+                    elif lower_val in ["false", "0", "no"]:
+                        return False
+            except (ValueError, TypeError):
+                logger.warning(f"Could not coerce argument '{param_def.name}' with value '{value}' to type {param_def.param_type}. "
+                               f"Passing string value to tool.")
+        
+        return value
 
     def set_agent_id(self, agent_id: str):
         if not isinstance(agent_id, str) or not agent_id:
@@ -71,30 +144,26 @@ class BaseTool(ABC, EventEmitter, metaclass=ToolMeta):
         logger.debug(f"Agent ID '{agent_id}' set for tool instance '{self.__class__.get_name()}'")
 
     async def execute(self, context: 'AgentContext', **kwargs):
-        # In this context, self.get_name() will call the instance-specific method if it exists.
         tool_name = self.get_name()
         if self.agent_id is None:
             self.set_agent_id(context.agent_id)
-        elif self.agent_id != context.agent_id:
-            logger.warning(
-                f"Tool '{tool_name}' current agent_id '{self.agent_id}' differs from "
-                f"calling context's agent_id '{context.agent_id}'. Updating tool's agent_id."
-            )
-            self.set_agent_id(context.agent_id)
+        
+        # Coerce types before validation and execution
+        coerced_kwargs = self._coerce_argument_types(kwargs)
         
         arg_schema = self.get_argument_schema() 
         if arg_schema:
-            is_valid, errors = arg_schema.validate_config(kwargs)
+            is_valid, errors = arg_schema.validate_config(coerced_kwargs)
             if not is_valid:
                 error_message = f"Invalid arguments for tool '{tool_name}': {'; '.join(errors)}"
                 logger.error(error_message)
                 raise ValueError(error_message)
-        elif kwargs: 
-            logger.warning(f"Tool '{tool_name}' does not define an argument schema but received arguments: {kwargs}. These will be passed to _execute.")
+        elif coerced_kwargs: 
+            logger.warning(f"Tool '{tool_name}' does not define an argument schema but received arguments: {coerced_kwargs}. These will be passed to _execute.")
 
-        logger.info(f"Executing tool '{tool_name}' for agent '{self.agent_id}' with args: {kwargs}")
+        logger.info(f"Executing tool '{tool_name}' for agent '{self.agent_id}' with args: {coerced_kwargs}")
         try:
-            result = await self._execute(context=context, **kwargs) 
+            result = await self._execute(context=context, **coerced_kwargs) 
             logger.info(f"Tool '{tool_name}' execution completed successfully for agent '{self.agent_id}'.")
             return result
         except Exception as e:

autobyteus/tools/browser/standalone/__init__.py

@@ -1,5 +1,4 @@
 # This file makes 'standalone' a package under 'browser'.
-# from .google_search_ui import GoogleSearch
 # from .webpage_reader import WebPageReader
 # from .webpage_screenshot_taker import WebPageScreenshotTaker
 # from .navigate_to import NavigateTo

autobyteus/tools/google_search.py

@@ -0,0 +1,149 @@
+import os
+import json
+import logging
+import aiohttp
+from typing import Optional, TYPE_CHECKING, Any, Dict, List
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_config import ToolConfig
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+from autobyteus.tools.tool_category import ToolCategory
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class GoogleSearch(BaseTool):
+    """
+    Performs a Google search using the Serper.dev API and returns a structured summary of the results.
+    This tool requires a Serper API key, which should be set in the SERPER_API_KEY environment variable.
+    """
+    CATEGORY = ToolCategory.WEB
+    API_URL = "https://google.serper.dev/search"
+
+    def __init__(self, config: Optional[ToolConfig] = None):
+        super().__init__(config=config)
+        self.api_key: Optional[str] = None
+        
+        if config:
+            self.api_key = config.get('api_key')
+        
+        if not self.api_key:
+            self.api_key = os.getenv("SERPER_API_KEY")
+
+        if not self.api_key:
+            raise ValueError(
+                "GoogleSearch tool requires a Serper API key. "
+                "Please provide it via the 'api_key' config parameter or set the 'SERPER_API_KEY' environment variable."
+            )
+        logger.debug("GoogleSearch (API-based) tool initialized.")
+    
+    @classmethod
+    def get_name(cls) -> str:
+        return "GoogleSearch"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Searches Google for a given query using the Serper API. "
+            "Returns a concise, structured summary of search results, including direct answers and top organic links."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="query",
+            param_type=ParameterType.STRING,
+            description="The search query string.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="num_results",
+            param_type=ParameterType.INTEGER,
+            description="The number of organic search results to return.",
+            required=False,
+            default_value=5,
+            min_value=1,
+            max_value=10
+        ))
+        return schema
+
+    @classmethod
+    def get_config_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="api_key",
+            param_type=ParameterType.STRING,
+            description="The API key for the Serper.dev service. Overrides the SERPER_API_KEY environment variable.",
+            required=False
+        ))
+        return schema
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from Serper into a clean string for an LLM."""
+        summary_parts = []
+        
+        # 1. Answer Box (most important for direct questions)
+        if "answerBox" in data:
+            answer_box = data["answerBox"]
+            title = answer_box.get("title", "")
+            snippet = answer_box.get("snippet") or answer_box.get("answer")
+            summary_parts.append(f"Direct Answer for '{title}':\n{snippet}")
+
+        # 2. Knowledge Graph (for entity information)
+        if "knowledgeGraph" in data:
+            kg = data["knowledgeGraph"]
+            title = kg.get("title", "")
+            description = kg.get("description")
+            summary_parts.append(f"Summary for '{title}':\n{description}")
+
+        # 3. Organic Results (the main search links)
+        if "organic" in data and data["organic"]:
+            organic_results = data["organic"]
+            results_str = "\n".join(
+                f"{i+1}. {result.get('title', 'No Title')}\n"
+                f"   Link: {result.get('link', 'No Link')}\n"
+                f"   Snippet: {result.get('snippet', 'No Snippet')}"
+                for i, result in enumerate(organic_results)
+            )
+            summary_parts.append(f"Search Results:\n{results_str}")
+        
+        if not summary_parts:
+            return "No relevant information found for the query."
+
+        return "\n\n---\n\n".join(summary_parts)
+
+
+    async def _execute(self, context: 'AgentContext', query: str, num_results: int = 5) -> str:
+        logger.info(f"Executing GoogleSearch (API) for agent {context.agent_id} with query: '{query}'")
+        
+        headers = {
+            'X-API-KEY': self.api_key,
+            'Content-Type': 'application/json'
+        }
+        payload = json.dumps({
+            "q": query,
+            "num": num_results
+        })
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(self.API_URL, headers=headers, data=payload) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"Serper API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during GoogleSearch API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in GoogleSearch tool: {e}", exc_info=True)
+            raise

autobyteus/tools/mcp/schema_mapper.py

@@ -1,4 +1,4 @@
-# file: autobyteus/autobyteus/mcp/schema_mapper.py
+# file: autobyteus/autobyteus/tools/mcp/schema_mapper.py
 import logging
 from typing import Dict, Any, List, Optional
 
@@ -8,7 +8,8 @@ logger = logging.getLogger(__name__)
 
 class McpSchemaMapper:
     """
-    Converts MCP tool JSON schemas to AutoByteUs ParameterSchema.
+    Converts MCP tool JSON schemas to AutoByteUs ParameterSchema,
+    handling nested object structures recursively.
     """
 
     _MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP = {
@@ -19,12 +20,6 @@ class McpSchemaMapper:
         "object": ParameterType.OBJECT, 
         "array": ParameterType.ARRAY,   
     }
-    
-    # REMOVED: _FILE_PATH_NAMES, _DIR_PATH_PARAM_NAMES, _URI_FORMATS
-    # as FILE_PATH and DIRECTORY_PATH types are removed.
-    # All string-based path parameters will now be ParameterType.STRING.
-    # The 'format' hint from MCP schema (e.g., "uri", "url") will still be available
-    # on the ParameterDefinition if it includes 'pattern', but it won't change the type from STRING.
 
     def map_to_autobyteus_schema(self, mcp_json_schema: Dict[str, Any]) -> ParameterSchema:
         if not isinstance(mcp_json_schema, dict):
@@ -37,95 +32,58 @@ class McpSchemaMapper:
 
         schema_type = mcp_json_schema.get("type")
         if schema_type != "object":
-            logger.warning(f"MCP JSON schema root 'type' is '{schema_type}', not 'object'. "
-                           "Mapping may be incomplete or incorrect for non-object root schemas.")
-            if schema_type in McpSchemaMapper._MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP:
-                 param_type_enum = McpSchemaMapper._MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP[schema_type]
-                 array_item_schema_for_root: Optional[Dict[str, Any]] = None
-                 if param_type_enum == ParameterType.ARRAY:
-                     array_item_schema_for_root = mcp_json_schema.get("items", True) 
-
-                 param_def = ParameterDefinition(
-                     name="input_value", 
-                     param_type=param_type_enum,
-                     description=mcp_json_schema.get("description", "Input value for the tool."),
-                     required=True, 
-                     default_value=mcp_json_schema.get("default"),
-                     enum_values=mcp_json_schema.get("enum") if schema_type == "string" else None,
-                     array_item_schema=array_item_schema_for_root
-                 )
-                 autobyteus_schema.add_parameter(param_def)
-                 return autobyteus_schema
-            else: 
-                logger.error(f"Unsupported root schema type '{schema_type}' for direct mapping to ParameterSchema properties.")
-                raise ValueError(f"MCP JSON schema root 'type' must be 'object' for typical mapping, got '{schema_type}'.")
-
+            logger.error(f"Unsupported root schema type '{schema_type}' for mapping to ParameterSchema. Must be 'object'.")
+            raise ValueError(f"MCP JSON schema root 'type' must be 'object', got '{schema_type}'.")
 
         properties = mcp_json_schema.get("properties")
         if not isinstance(properties, dict):
-            logger.warning("MCP JSON schema of type 'object' has no 'properties' or 'properties' is not a dict. Resulting ParameterSchema will be empty.")
+            logger.warning("MCP JSON schema of type 'object' has no 'properties'. Resulting ParameterSchema will be empty.")
             return autobyteus_schema 
-
-        required_params: List[str] = mcp_json_schema.get("required", [])
-        if not isinstance(required_params, list) or not all(isinstance(p, str) for p in required_params):
-            logger.warning("MCP JSON schema 'required' field is not a list of strings. Treating all params as optional.")
-            required_params = []
+        
+        # FIX: The 'required' list is specific to its own schema level.
+        required_params_at_this_level: List[str] = mcp_json_schema.get("required", [])
 
         for param_name, param_mcp_schema in properties.items():
             if not isinstance(param_mcp_schema, dict):
-                logger.warning(f"Property '{param_name}' in MCP schema is not a dictionary. Skipping this parameter.")
+                logger.warning(f"Property '{param_name}' in MCP schema is not a dictionary. Skipping.")
                 continue
 
             mcp_param_type_str = param_mcp_schema.get("type")
             description = param_mcp_schema.get("description", f"Parameter '{param_name}'.")
-            default_value = param_mcp_schema.get("default")
-            enum_values = param_mcp_schema.get("enum")
-            # format_hint is still read but won't be used to change type to FILE_PATH/DIR_PATH
-            # format_hint = param_mcp_schema.get("format", "").lower() 
             
+            nested_object_schema: Optional[ParameterSchema] = None
             item_schema_for_array: Optional[Dict[str, Any]] = None
-            if mcp_param_type_str == "array":
-                item_schema_for_array = param_mcp_schema.get("items")
-                if item_schema_for_array is None: 
-                    item_schema_for_array = True 
-                    logger.debug(f"MCP parameter '{param_name}' is 'array' type with no 'items' schema. Defaulting to generic items (true).")
-            
-            autobyteus_param_type: Optional[ParameterType] = None
-            # REMOVED: Logic block that inferred FILE_PATH or DIRECTORY_PATH based on format_hint or param_name_lower.
-            # All string types from MCP will now map to STRING or ENUM.
 
-            if mcp_param_type_str in McpSchemaMapper._MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP:
-                autobyteus_param_type = McpSchemaMapper._MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP[mcp_param_type_str]
-                if autobyteus_param_type == ParameterType.STRING and enum_values: 
-                    autobyteus_param_type = ParameterType.ENUM
-            elif mcp_param_type_str: 
-                logger.warning(f"Unsupported MCP parameter type '{mcp_param_type_str}' for parameter '{param_name}'. Defaulting to STRING.")
-                autobyteus_param_type = ParameterType.STRING
-            else: 
-                logger.warning(f"MCP parameter '{param_name}' has no 'type' specified. Defaulting to STRING.")
-                autobyteus_param_type = ParameterType.STRING
+            if mcp_param_type_str == "object" and "properties" in param_mcp_schema:
+                # Recursively map the nested object schema. The recursive call will handle its own 'required' list.
+                nested_object_schema = self.map_to_autobyteus_schema(param_mcp_schema)
             
-            if autobyteus_param_type == ParameterType.ENUM:
-                if not enum_values or not isinstance(enum_values, list) or not all(isinstance(ev, str) for ev in enum_values):
-                    logger.warning(f"Parameter '{param_name}' is ENUM type but 'enum' field is missing, not a list, or not list of strings in MCP schema. Problematic. Schema: {enum_values}")
+            elif mcp_param_type_str == "array":
+                item_schema_for_array = param_mcp_schema.get("items", True)
+            
+            autobyteus_param_type = self._MCP_TYPE_TO_AUTOBYTEUS_TYPE_MAP.get(mcp_param_type_str, ParameterType.STRING)
+            enum_values = param_mcp_schema.get("enum")
+            if autobyteus_param_type == ParameterType.STRING and enum_values: 
+                autobyteus_param_type = ParameterType.ENUM
 
             try:
                 param_def = ParameterDefinition(
                     name=param_name,
-                    param_type=autobyteus_param_type, # This will now be STRING for former path types
+                    param_type=autobyteus_param_type,
                     description=description,
-                    required=(param_name in required_params),
-                    default_value=default_value,
+                    required=(param_name in required_params_at_this_level), # FIX: Use the list for the current level.
+                    default_value=param_mcp_schema.get("default"),
                     enum_values=enum_values if autobyteus_param_type == ParameterType.ENUM else None,
                     min_value=param_mcp_schema.get("minimum"),
                     max_value=param_mcp_schema.get("maximum"),
-                    pattern=param_mcp_schema.get("pattern") if mcp_param_type_str == "string" else None,
-                    array_item_schema=item_schema_for_array 
+                    pattern=param_mcp_schema.get("pattern"),
+                    array_item_schema=item_schema_for_array,
+                    object_schema=nested_object_schema,
                 )
                 autobyteus_schema.add_parameter(param_def)
             except ValueError as e:
-                 logger.error(f"Failed to create ParameterDefinition for '{param_name}': {e}. MCP schema for param: {param_mcp_schema}")
+                 logger.error(f"Failed to create ParameterDefinition for '{param_name}': {e}.")
                  continue
 
-        logger.debug(f"Successfully mapped MCP schema to AutoByteUs ParameterSchema with {len(autobyteus_schema.parameters)} parameters.")
+        logger.debug(f"Successfully mapped MCP schema to ParameterSchema with {len(autobyteus_schema.parameters)} params.")
         return autobyteus_schema

autobyteus/tools/multimedia/__init__.py

@@ -0,0 +1,8 @@
+from .image_tools import GenerateImageTool, EditImageTool
+from .audio_tools import GenerateSpeechTool
+
+__all__ = [
+    "GenerateImageTool",
+    "EditImageTool",
+    "GenerateSpeechTool",
+]

autobyteus/tools/multimedia/audio_tools.py

@@ -0,0 +1,116 @@
+import os
+import logging
+from typing import Optional, List
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.multimedia.audio import audio_client_factory, AudioModel, AudioClientFactory
+
+logger = logging.getLogger(__name__)
+
+
+def _get_configured_model_identifier(env_var: str, default_model: Optional[str] = None) -> str:
+    """
+    Retrieves a model identifier from an environment variable.
+    """
+    model_identifier = os.getenv(env_var)
+    if not model_identifier:
+        if default_model:
+            return default_model
+        raise ValueError(f"The '{env_var}' environment variable is not set. Please configure it.")
+    return model_identifier
+
+
+def _build_dynamic_audio_schema(base_params: List[ParameterDefinition], model_env_var: str, default_model: str) -> ParameterSchema:
+    """
+    Builds a tool schema dynamically based on a configured audio model.
+    """
+    try:
+        model_identifier = _get_configured_model_identifier(model_env_var, default_model)
+        AudioClientFactory.ensure_initialized()
+        model = AudioModel[model_identifier]
+    except (ValueError, KeyError) as e:
+        logger.error(f"Cannot generate audio tool schema. Check environment and model registry. Error: {e}")
+        raise RuntimeError(f"Failed to configure audio tool. Error: {e}")
+
+    config_schema = ParameterSchema()
+    if model.parameter_schema:
+        for name, meta in model.parameter_schema.items():
+            param_type_str = meta.get("type", "string").upper()
+            param_type = getattr(ParameterType, param_type_str, ParameterType.STRING)
+            
+            allowed_values = meta.get("allowed_values")
+            if param_type == ParameterType.STRING and allowed_values:
+                param_type = ParameterType.ENUM
+
+            config_schema.add_parameter(ParameterDefinition(
+                name=name,
+                param_type=param_type,
+                description=meta.get("description", ""),
+                required=False,
+                default_value=meta.get("default"),
+                enum_values=allowed_values
+            ))
+
+    schema = ParameterSchema()
+    for param in base_params:
+        schema.add_parameter(param)
+    
+    if config_schema.parameters:
+        schema.add_parameter(ParameterDefinition(
+            name="generation_config",
+            param_type=ParameterType.OBJECT,
+            description=f"Model-specific parameters for the configured '{model_identifier}' model.",
+            required=False,
+            object_schema=config_schema
+        ))
+    return schema
+
+
+class GenerateSpeechTool(BaseTool):
+    """
+    An agent tool for generating speech from text using a Text-to-Speech (TTS) model.
+    """
+    CATEGORY = ToolCategory.MULTIMEDIA
+    MODEL_ENV_VAR = "DEFAULT_SPEECH_GENERATION_MODEL"
+    DEFAULT_MODEL = "gemini-2.5-flash-tts"
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "GenerateSpeech"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Generates spoken audio from text using the system's default Text-to-Speech (TTS) model. "
+            "Returns a list of local file paths to the generated audio files (.wav) upon success."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        base_params = [
+            ParameterDefinition(
+                name="prompt",
+                param_type=ParameterType.STRING,
+                description="The text to be converted into spoken audio.",
+                required=True
+            )
+        ]
+        return _build_dynamic_audio_schema(base_params, cls.MODEL_ENV_VAR, cls.DEFAULT_MODEL)
+
+    async def _execute(self, context, prompt: str, generation_config: Optional[dict] = None) -> List[str]:
+        model_identifier = _get_configured_model_identifier(self.MODEL_ENV_VAR, self.DEFAULT_MODEL)
+        logger.info(f"GenerateSpeechTool executing with configured model '{model_identifier}'.")
+        client = None
+        try:
+            client = audio_client_factory.create_audio_client(model_identifier=model_identifier)
+            response = await client.generate_speech(prompt=prompt, generation_config=generation_config)
+            
+            if not response.audio_urls:
+                raise ValueError("Speech generation failed to return any audio file paths.")
+            
+            return response.audio_urls
+        finally:
+            if client:
+                await client.cleanup()