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

autobyteus/tools/parameter_schema.py

@@ -14,8 +14,6 @@ class ParameterType(str, Enum):
     FLOAT = "float"
     BOOLEAN = "boolean"
     ENUM = "enum"
-    # FILE_PATH = "file_path" # REMOVED
-    # DIRECTORY_PATH = "directory_path" # REMOVED
     OBJECT = "object"
     ARRAY = "array"
 
@@ -23,11 +21,8 @@ class ParameterType(str, Enum):
         """Maps parameter type to JSON schema type."""
         if self == ParameterType.FLOAT:
             return "number"
-        # REMOVED: FILE_PATH and DIRECTORY_PATH handling, ENUM still maps to string
         if self == ParameterType.ENUM:
             return "string"
-        # For OBJECT and ARRAY, their value is already the correct JSON schema type
-        # STRING, INTEGER, BOOLEAN also map directly to their values.
         if self in [ParameterType.OBJECT, ParameterType.ARRAY, ParameterType.STRING, ParameterType.INTEGER, ParameterType.BOOLEAN]:
             return self.value
         return self.value # Fallback, should be covered by above
@@ -46,8 +41,9 @@ class ParameterDefinition:
     min_value: Optional[Union[int, float]] = None
     max_value: Optional[Union[int, float]] = None
     pattern: Optional[str] = None
-    array_item_schema: Optional[Dict[str, Any]] = None 
-    
+    array_item_schema: Optional[Dict[str, Any]] = None
+    object_schema: Optional[Dict[str, Any]] = None
+
     def __post_init__(self):
         if not self.name or not isinstance(self.name, str):
             raise ValueError("ParameterDefinition name must be a non-empty string")
@@ -64,6 +60,9 @@ class ParameterDefinition:
         if self.param_type != ParameterType.ARRAY and self.array_item_schema is not None:
             raise ValueError(f"ParameterDefinition '{self.name}': array_item_schema should only be provided if param_type is ARRAY.")
 
+        if self.param_type != ParameterType.OBJECT and self.object_schema is not None:
+            raise ValueError(f"ParameterDefinition '{self.name}': object_schema should only be provided if param_type is OBJECT.")
+
         if self.required and self.default_value is not None:
             logger.debug(f"ParameterDefinition '{self.name}' is marked as required but has a default value. This is acceptable.")
 
@@ -103,8 +102,6 @@ class ParameterDefinition:
             if not isinstance(value, str) or value not in (self.enum_values or []):
                 return False
         
-        # REMOVED: Specific validation for FILE_PATH, DIRECTORY_PATH (they are now STRING)
-        
         elif self.param_type == ParameterType.OBJECT:
             if not isinstance(value, dict):
                 return False
@@ -129,9 +126,18 @@ class ParameterDefinition:
         }
         if self.param_type == ParameterType.ARRAY and self.array_item_schema is not None:
             data["array_item_schema"] = self.array_item_schema
+        if self.param_type == ParameterType.OBJECT and self.object_schema is not None:
+            data["object_schema"] = self.object_schema
         return data
 
     def to_json_schema_property_dict(self) -> Dict[str, Any]:
+        if self.param_type == ParameterType.OBJECT and self.object_schema:
+            # If a detailed object schema is provided, use it directly.
+            # We add the description at the top level for clarity.
+            schema = self.object_schema.copy()
+            schema["description"] = self.description
+            return schema
+
         prop_dict: Dict[str, Any] = {
             "type": self.param_type.to_json_schema_type(),
             "description": self.description,
@@ -150,7 +156,6 @@ class ParameterDefinition:
             if self.param_type in [ParameterType.INTEGER, ParameterType.FLOAT]:
                 prop_dict["maximum"] = self.max_value
         
-        # REMOVED: Pattern check specific to FILE_PATH/DIRECTORY_PATH as they are now STRING
         if self.pattern and self.param_type == ParameterType.STRING:
             prop_dict["pattern"] = self.pattern
             
@@ -255,7 +260,8 @@ class ParameterSchema:
                 min_value=param_data.get("min_value"),
                 max_value=param_data.get("max_value"),
                 pattern=param_data.get("pattern"),
-                array_item_schema=param_data.get("array_item_schema") 
+                array_item_schema=param_data.get("array_item_schema"),
+                object_schema=param_data.get("object_schema")
             )
             schema.add_parameter(param)
         

autobyteus/tools/pdf_downloader.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from typing import TYPE_CHECKING, Optional
 
 from autobyteus.tools import tool
+from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.utils.file_utils import get_default_download_folder
 
 if TYPE_CHECKING:
@@ -14,7 +15,7 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-@tool(name="PDFDownloader")
+@tool(name="PDFDownloader", category=ToolCategory.WEB)
 async def pdf_downloader( # function name can be pdf_downloader
     context: 'AgentContext', 
     url: str, 

autobyteus/tools/registry/tool_definition.py

@@ -6,12 +6,13 @@ from typing import Dict, Any, List as TypingList, Type, TYPE_CHECKING, Optional,
 from autobyteus.llm.providers import LLMProvider
 from autobyteus.tools.tool_config import ToolConfig
 from autobyteus.tools.parameter_schema import ParameterSchema
-from autobyteus.tools.tool_category import ToolCategory
-from autobyteus.tools.usage.providers import (
-    XmlSchemaProvider, 
-    JsonSchemaProvider, 
-    XmlExampleProvider, 
-    JsonExampleProvider
+from autobyteus.tools.tool_origin import ToolOrigin
+# Import default formatters directly to provide convenience methods
+from autobyteus.tools.usage.formatters import (
+    DefaultXmlSchemaFormatter,
+    DefaultJsonSchemaFormatter,
+    DefaultXmlExampleFormatter,
+    DefaultJsonExampleFormatter
 )
 
 if TYPE_CHECKING:
@@ -22,13 +23,14 @@ logger = logging.getLogger(__name__)
 class ToolDefinition:
     """
     Represents the definition of a tool, containing its metadata and the means
-    to create an instance. It can generate provider-specific usage information on demand.
+    to create an instance. It can generate provider-agnostic usage information on demand.
     """
     def __init__(self,
                  name: str,
                  description: str,
                  argument_schema: Optional['ParameterSchema'],
-                 category: ToolCategory,
+                 origin: ToolOrigin,
+                 category: str,
                  config_schema: Optional['ParameterSchema'] = None,
                  tool_class: Optional[Type['BaseTool']] = None,
                  custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None,
@@ -55,12 +57,12 @@ class ToolDefinition:
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'argument_schema'. Expected ParameterSchema or None.")
         if config_schema is not None and not isinstance(config_schema, ParameterSchema):
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'config_schema'. Expected ParameterSchema or None.")
-        if not isinstance(category, ToolCategory):
-            raise TypeError(f"ToolDefinition '{name}' requires a ToolCategory for 'category'. Got {type(category)}")
+        if not isinstance(origin, ToolOrigin):
+            raise TypeError(f"ToolDefinition '{name}' requires a ToolOrigin for 'origin'. Got {type(origin)}")
         
         # Validation for MCP-specific metadata
-        if category == ToolCategory.MCP and not (metadata and metadata.get("mcp_server_id")):
-            raise ValueError(f"ToolDefinition '{name}' with category MCP must provide a 'mcp_server_id' in its metadata.")
+        if origin == ToolOrigin.MCP and not (metadata and metadata.get("mcp_server_id")):
+            raise ValueError(f"ToolDefinition '{name}' with origin MCP must provide a 'mcp_server_id' in its metadata.")
 
         self._name = name
         self._description = description
@@ -68,6 +70,7 @@ class ToolDefinition:
         self._config_schema: Optional['ParameterSchema'] = config_schema
         self._tool_class = tool_class
         self._custom_factory = custom_factory
+        self._origin = origin
         self._category = category
         self._metadata = metadata or {}
         
@@ -87,48 +90,44 @@ class ToolDefinition:
     @property
     def config_schema(self) -> Optional['ParameterSchema']: return self._config_schema
     @property
-    def category(self) -> ToolCategory: return self._category
+    def origin(self) -> ToolOrigin: return self._origin
+    @property
+    def category(self) -> str: return self._category
     @property
     def metadata(self) -> Dict[str, Any]: return self._metadata
     
-    # --- Schema Generation API ---
+    # --- Convenience Schema/Example Generation API (using default formatters) ---
     def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:
         """
-        Generates the standardized XML usage schema string for this tool.
-        The provider argument is included for API consistency and future-proofing.
+        Generates the default XML usage schema string for this tool.
+        The provider argument is ignored, kept for API consistency.
         """
-        provider_instance = XmlSchemaProvider()
-        return provider_instance.provide(self, llm_provider=provider)
+        formatter = DefaultXmlSchemaFormatter()
+        return formatter.provide(self)
 
     def get_usage_json(self, provider: Optional[LLMProvider] = None) -> Dict[str, Any]:
         """
-        Generates the usage schema as a dictionary.
-        
-        Args:
-            provider: If provided, generates a provider-specific JSON format.
-                      If None, generates a default, generic JSON format.
-        
-        Returns:
-            A dictionary representing the tool's usage schema.
+        Generates the default JSON usage schema as a dictionary.
+        The provider argument is ignored, kept for API consistency.
         """
-        provider_instance = JsonSchemaProvider()
-        return provider_instance.provide(self, llm_provider=provider)
+        formatter = DefaultJsonSchemaFormatter()
+        return formatter.provide(self)
 
-    # --- Example Generation API ---
     def get_usage_xml_example(self, provider: Optional[LLMProvider] = None) -> str:
         """
-        Generates a standardized XML usage example string for this tool.
-        The provider argument is included for API consistency and future-proofing.
+        Generates a default XML usage example string for this tool.
+        The provider argument is ignored, kept for API consistency.
         """
-        provider_instance = XmlExampleProvider()
-        return provider_instance.provide(self, llm_provider=provider)
+        formatter = DefaultXmlExampleFormatter()
+        return formatter.provide(self)
 
     def get_usage_json_example(self, provider: Optional[LLMProvider] = None) -> Any:
         """
-        Generates a usage example, either as a dict or a string.
+        Generates a default JSON usage example as a dictionary.
+        The provider argument is ignored, kept for API consistency.
         """
-        provider_instance = JsonExampleProvider()
-        return provider_instance.provide(self, llm_provider=provider)
+        formatter = DefaultJsonExampleFormatter()
+        return formatter.provide(self)
 
     # --- Other methods ---
     @property
@@ -145,4 +144,4 @@ class ToolDefinition:
     def __repr__(self) -> str:
         creator_repr = f"class='{self._tool_class.__name__}'" if self._tool_class else "factory=True"
         metadata_repr = f", metadata={self.metadata}" if self.metadata else ""
-        return (f"ToolDefinition(name='{self.name}', category='{self.category.value}'{metadata_repr}, {creator_repr})")
+        return (f"ToolDefinition(name='{self.name}', origin='{self.origin.value}', category='{self.category}'{metadata_repr}, {creator_repr})")

autobyteus/tools/registry/tool_registry.py

@@ -1,11 +1,12 @@
 # file: autobyteus/tools/registry/tool_registry.py
 import logging
 from typing import Dict, List, Optional, Type, TYPE_CHECKING
+from collections import defaultdict
 
 from autobyteus.tools.registry.tool_definition import ToolDefinition
 from autobyteus.utils.singleton import SingletonMeta
 from autobyteus.tools.tool_config import ToolConfig
-from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.tools.tool_origin import ToolOrigin
 
 if TYPE_CHECKING:
     from autobyteus.tools.base_tool import BaseTool
@@ -141,7 +142,54 @@ class ToolRegistry(metaclass=SingletonMeta):
         
         return [
             td for td in self._definitions.values()
-            if td.category == ToolCategory.MCP and td.metadata.get("mcp_server_id") == server_id
+            if td.origin == ToolOrigin.MCP and td.metadata.get("mcp_server_id") == server_id
         ]
 
+    def get_tools_by_category(self, category: str) -> List[ToolDefinition]:
+        """
+        Returns a list of all registered tool definitions that match a specific category.
+
+        Args:
+            category: The category string to filter by.
+
+        Returns:
+            A list of matching ToolDefinition objects, sorted by name.
+        """
+        if not category:
+            return []
+        
+        matching_tools = [
+            td for td in self._definitions.values() if td.category == category
+        ]
+        return sorted(matching_tools, key=lambda td: td.name)
+
+    def get_tools_grouped_by_category(self, origin: Optional[ToolOrigin] = None) -> Dict[str, List[ToolDefinition]]:
+        """
+        Returns all registered tool definitions, grouped into a dictionary by their category.
+        Can optionally filter by tool origin before grouping.
+
+        Args:
+            origin: If provided, only tools from this origin will be included.
+
+        Returns:
+            A dictionary where keys are category strings and values are lists
+            of ToolDefinition objects belonging to that category. Both the categories
+            and the tools within each category are sorted alphabetically.
+        """
+        grouped_tools = defaultdict(list)
+        
+        tools_to_process = self._definitions.values()
+        if origin:
+            tools_to_process = [td for td in tools_to_process if td.origin == origin]
+
+        for td in tools_to_process:
+            grouped_tools[td.category].append(td)
+        
+        # Sort tools within each category and sort the categories themselves for deterministic output
+        sorted_grouped_tools = {}
+        for category in sorted(grouped_tools.keys()):
+            sorted_grouped_tools[category] = sorted(grouped_tools[category], key=lambda td: td.name)
+            
+        return sorted_grouped_tools
+
 default_tool_registry = ToolRegistry()

autobyteus/tools/timer.py

@@ -3,6 +3,7 @@ from typing import Optional, TYPE_CHECKING, Any
 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
 from autobyteus.events.event_emitter import EventEmitter 
 from autobyteus.events.event_types import EventType
 import logging 
@@ -17,6 +18,7 @@ class Timer(BaseTool, EventEmitter):
     A tool that provides timer functionality with configurable duration and event emission.
     The timer runs independently after being started and emits TIMER_UPDATE events.
     """
+    CATEGORY = ToolCategory.UTILITY
 
     def __init__(self, config: Optional[ToolConfig] = None):
         BaseTool.__init__(self, config=config)

autobyteus/tools/tool_category.py

@@ -2,10 +2,21 @@
 from enum import Enum
 
 class ToolCategory(str, Enum):
-    """Enumeration of tool categories to identify their origin."""
-    LOCAL = "local"
-    MCP = "mcp"
-    # BUILT_IN, USER_DEFINED etc. could be added later.
+    """
+    Provides standardized string constants for common tool categories.
+    While tools can use any string for a category, using these constants
+    is recommended to ensure consistency in UI grouping.
+    """
+    USER_INTERACTION = "User Interaction"
+    FILE_SYSTEM = "File System"
+    WEB = "Web"
+    SYSTEM = "System"
+    UTILITY = "Utility"
+    AGENT_COMMUNICATION = "Agent Communication"
+    PROMPT_MANAGEMENT = "Prompt Management"
+    TASK_MANAGEMENT = "Task Management" # NEW CATEGORY ADDED
+    GENERAL = "General"
+    MCP = "MCP"
 
     def __str__(self) -> str:
         return self.value

autobyteus/tools/tool_meta.py

@@ -5,6 +5,7 @@ from typing import Dict, Any
 
 from autobyteus.tools.registry import default_tool_registry, ToolDefinition
 from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.tools.tool_origin import ToolOrigin
 from autobyteus.tools.tool_category import ToolCategory
 
 logger = logging.getLogger(__name__)
@@ -53,6 +54,9 @@ class ToolMeta(ABCMeta):
                         instantiation_config_schema = None
                 except Exception as e:
                     logger.warning(f"Tool class {name} ({tool_name}) has get_config_schema() but it failed: {e}. Assuming no instantiation config.")
+
+            # Get category from class attribute, defaulting to "General"
+            category_str = getattr(cls, 'CATEGORY', ToolCategory.GENERAL)
             
             # Create the definition without pre-generating usage strings
             definition = ToolDefinition(
@@ -62,7 +66,8 @@ class ToolMeta(ABCMeta):
                 custom_factory=None,
                 argument_schema=argument_schema,
                 config_schema=instantiation_config_schema,
-                category=ToolCategory.LOCAL
+                origin=ToolOrigin.LOCAL,
+                category=category_str
             )
             default_tool_registry.register_tool(definition)
             

autobyteus/tools/tool_origin.py

@@ -0,0 +1,10 @@
+# file: autobyteus/autobyteus/tools/tool_origin.py
+from enum import Enum
+
+class ToolOrigin(str, Enum):
+    """Enumeration of tool origins to identify their execution model."""
+    LOCAL = "local"
+    MCP = "mcp"
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/tools/usage/formatters/default_json_example_formatter.py

@@ -1,5 +1,5 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/default_json_example_formatter.py
-from typing import Dict, Any, TYPE_CHECKING
+from typing import Dict, Any, TYPE_CHECKING, List, Optional
 
 from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
@@ -9,8 +9,8 @@ if TYPE_CHECKING:
 
 class DefaultJsonExampleFormatter(BaseExampleFormatter):
     """
-    Formats a tool usage example into a generic JSON format, inspired by
-    the default XML format.
+    Formats a tool usage example into a generic JSON format.
+    It intelligently generates detailed examples for complex object schemas.
     """
 
     def provide(self, tool_definition: 'ToolDefinition') -> Dict:
@@ -20,6 +20,8 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
 
         if arg_schema and arg_schema.parameters:
             for param_def in arg_schema.parameters:
+                # Always include required parameters in the example.
+                # Also include optional parameters that have a default value to show common usage.
                 if param_def.required or param_def.default_value is not None:
                     arguments[param_def.name] = self._generate_placeholder_value(param_def)
 
@@ -31,6 +33,12 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
         }
 
     def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        # If an object parameter has a detailed schema, generate a structured example from it.
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+            # We pass the full schema document to allow for resolving $refs
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+        
+        # Fallback to simple placeholder generation for primitives or objects without schemas.
         if param_def.default_value is not None: return param_def.default_value
         if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
         if param_def.param_type == ParameterType.INTEGER: return 123
@@ -40,3 +48,70 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
         if param_def.param_type == ParameterType.OBJECT: return {"key": "value"}
         if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
         return "placeholder"
+
+    @staticmethod
+    def _generate_example_from_schema(sub_schema: Dict[str, Any], full_schema: Dict[str, Any]) -> Any:
+        """
+        Recursively generates an example value from a JSON schema dictionary.
+        This is a static method so it can be reused by other formatters.
+        """
+        if "$ref" in sub_schema:
+            ref_path = sub_schema["$ref"]
+            try:
+                # Resolve the reference, e.g., "#/$defs/MySchema"
+                parts = ref_path.lstrip("#/").split("/")
+                resolved_schema = full_schema
+                for part in parts:
+                    resolved_schema = resolved_schema[part]
+                return DefaultJsonExampleFormatter._generate_example_from_schema(resolved_schema, full_schema)
+            except (KeyError, IndexError):
+                return {"error": f"Could not resolve schema reference: {ref_path}"}
+
+        schema_type = sub_schema.get("type")
+        
+        if "default" in sub_schema:
+            return sub_schema["default"]
+        
+        if "enum" in sub_schema and sub_schema["enum"]:
+            return sub_schema["enum"][0]
+
+        if schema_type == "object":
+            example_obj = {}
+            properties = sub_schema.get("properties", {})
+            required_fields = sub_schema.get("required", [])
+            for prop_name, prop_schema in properties.items():
+                # Include required fields and a subset of optional fields for a concise example.
+                if prop_name in required_fields:
+                    example_obj[prop_name] = DefaultJsonExampleFormatter._generate_example_from_schema(prop_schema, full_schema)
+            return example_obj
+        
+        elif schema_type == "array":
+            items_schema = sub_schema.get("items")
+            if isinstance(items_schema, dict):
+                # Generate one example item for the array to keep it concise
+                return [DefaultJsonExampleFormatter._generate_example_from_schema(items_schema, full_schema)]
+            else:
+                return ["example_item_1"]
+
+        elif schema_type == "string":
+            description = sub_schema.get("description", "")
+            if "e.g." in description.lower():
+                try:
+                    return description.split("e.g.,")[1].split(')')[0].strip().strip("'\"")
+                except IndexError:
+                    pass
+            return "example_string"
+        
+        elif schema_type == "integer":
+            return 1
+            
+        elif schema_type == "number":
+            return 1.1
+            
+        elif schema_type == "boolean":
+            return True
+        
+        elif schema_type == "null":
+            return None
+
+        return "unknown_type"

autobyteus/tools/usage/formatters/default_xml_example_formatter.py

@@ -1,9 +1,11 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/default_xml_example_formatter.py
 import xml.sax.saxutils
+import json # Import json for embedding complex objects
 from typing import Any, TYPE_CHECKING
 
 from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
+from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
@@ -22,8 +24,21 @@ class DefaultXmlExampleFormatter(BaseExampleFormatter):
             for param_def in arg_schema.parameters:
                 if param_def.required or param_def.default_value is not None:
                     placeholder_value = self._generate_placeholder_value(param_def)
-                    escaped_value = xml.sax.saxutils.escape(str(placeholder_value))
-                    arguments_part.append(f'        <arg name="{param_def.name}">{escaped_value}</arg>')
+                    # For complex objects/arrays, we now get a dict/list.
+                    # Convert it to a JSON string for embedding in XML.
+                    if isinstance(placeholder_value, (dict, list)):
+                        value_str = json.dumps(placeholder_value, indent=2)
+                    else:
+                        value_str = str(placeholder_value)
+
+                    escaped_value = xml.sax.saxutils.escape(value_str)
+                    
+                    # Add newlines for readability if the value is a multiline JSON string
+                    if '\n' in escaped_value:
+                        arguments_part.append(f'        <arg name="{param_def.name}">\n{escaped_value}\n        </arg>')
+                    else:
+                        arguments_part.append(f'        <arg name="{param_def.name}">{escaped_value}</arg>')
+
 
         if arguments_part:
             example_xml_parts.append("    <arguments>")
@@ -36,6 +51,11 @@ class DefaultXmlExampleFormatter(BaseExampleFormatter):
         return "\n".join(example_xml_parts)
 
     def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        # REUSE a more intelligent generator for complex objects
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+
+        # Fallback for primitives
         if param_def.default_value is not None:
             return param_def.default_value
         if param_def.param_type == ParameterType.STRING:
@@ -49,7 +69,7 @@ class DefaultXmlExampleFormatter(BaseExampleFormatter):
         if param_def.param_type == ParameterType.ENUM:
             return param_def.enum_values[0] if param_def.enum_values else "enum_val"
         if param_def.param_type == ParameterType.OBJECT:
-            return {"key": "value"}
+            return {"key": "value"} # Fallback if no schema
         if param_def.param_type == ParameterType.ARRAY:
             return ["item1", "item2"]
         return "placeholder"

autobyteus/tools/usage/formatters/gemini_json_example_formatter.py

@@ -3,6 +3,7 @@ from typing import Dict, Any, TYPE_CHECKING
 
 from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
+from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
@@ -23,6 +24,11 @@ class GeminiJsonExampleFormatter(BaseExampleFormatter):
         return {"name": tool_name, "args": arguments}
 
     def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        # REUSE a more intelligent generator for complex objects
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+            
+        # Fallback for primitives
         if param_def.default_value is not None: return param_def.default_value
         if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
         if param_def.param_type == ParameterType.INTEGER: return 123

autobyteus/tools/usage/formatters/google_json_example_formatter.py

@@ -3,6 +3,8 @@ from typing import Dict, Any, TYPE_CHECKING
 
 from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
+# Import for reuse of the intelligent example generation logic
+from .default_json_example_formatter import DefaultJsonExampleFormatter
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
@@ -23,6 +25,11 @@ class GoogleJsonExampleFormatter(BaseExampleFormatter):
         return {"name": tool_name, "args": arguments}
 
     def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        # REUSE the intelligent generator for complex objects
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+
+        # Fallback for primitives
         if param_def.default_value is not None: return param_def.default_value
         if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
         if param_def.param_type == ParameterType.INTEGER: return 123

autobyteus/tools/usage/formatters/openai_json_example_formatter.py

@@ -4,6 +4,7 @@ from typing import Dict, Any, TYPE_CHECKING
 
 from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
+from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
@@ -12,7 +13,6 @@ class OpenAiJsonExampleFormatter(BaseExampleFormatter):
     """
     Formats a tool usage example into a format resembling an entry in the
     OpenAI JSON 'tool_calls' array, intended for prompting a model.
-    The output is wrapped in a 'tool' key for consistency in prompts.
     """
 
     def provide(self, tool_definition: 'ToolDefinition') -> Dict:
@@ -25,8 +25,6 @@ class OpenAiJsonExampleFormatter(BaseExampleFormatter):
                 if param_def.required or param_def.default_value is not None:
                     arguments[param_def.name] = self._generate_placeholder_value(param_def)
 
-        # This format contains the 'function' wrapper with a stringified 'arguments' field.
-        # This aligns with the structure often seen inside an OpenAI API tool_calls object.
         function_call = {
             "function": {
                 "name": tool_name,
@@ -34,10 +32,14 @@ class OpenAiJsonExampleFormatter(BaseExampleFormatter):
             },
         }
 
-        # Wrap in a 'tool' key for consistency in prompt generation.
         return {"tool": function_call}
 
     def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        # REUSE a more intelligent generator for complex objects
+        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+
+        # Fallback for primitives
         if param_def.default_value is not None: return param_def.default_value
         if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
         if param_def.param_type == ParameterType.INTEGER: return 123