autobyteus 1.0.6__py3-none-any.whl → 1.1.1__py3-none-any.whl

autobyteus/tools/tool_state.py

@@ -0,0 +1,20 @@
+# file: autobyteus/autobyteus/tools/tool_state.py
+"""
+Defines the ToolState class, an explicit container for a tool's internal state,
+providing a dictionary-like interface for backward compatibility.
+"""
+from collections import UserDict
+
+class ToolState(UserDict):
+    """
+    A specialized container for a tool's state.
+
+    This class inherits from collections.UserDict to provide a dictionary-like
+    interface, ensuring that existing tools can interact with the state attribute
+    (tool.tool_state) just as they would with a regular dictionary.
+
+    The primary purpose of this class is to make the concept of a tool's
+    state explicit in the framework's type system, improving code clarity
+    and developer experience.
+    """
+    pass

autobyteus/tools/usage/__init__.py

@@ -0,0 +1,6 @@
+# file: autobyteus/autobyteus/tools/usage/__init__.py
+"""
+This package contains the framework for generating provider-specific
+tool usage information (schemas and examples) and for parsing
+tool usage from LLM responses.
+"""

autobyteus/tools/usage/formatters/__init__.py

@@ -0,0 +1,31 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/__init__.py
+"""
+This package contains concrete formatter classes that translate a BaseTool's
+metadata into a specific provider's format (e.g., OpenAI JSON, Anthropic JSON, XML).
+"""
+from .base_formatter import BaseSchemaFormatter, BaseExampleFormatter
+from .default_xml_schema_formatter import DefaultXmlSchemaFormatter
+from .default_json_schema_formatter import DefaultJsonSchemaFormatter
+from .openai_json_schema_formatter import OpenAiJsonSchemaFormatter
+from .anthropic_json_schema_formatter import AnthropicJsonSchemaFormatter
+from .gemini_json_schema_formatter import GeminiJsonSchemaFormatter
+from .default_xml_example_formatter import DefaultXmlExampleFormatter
+from .default_json_example_formatter import DefaultJsonExampleFormatter
+from .openai_json_example_formatter import OpenAiJsonExampleFormatter
+from .anthropic_json_example_formatter import AnthropicJsonExampleFormatter
+from .gemini_json_example_formatter import GeminiJsonExampleFormatter
+
+__all__ = [
+    "BaseSchemaFormatter",
+    "BaseExampleFormatter",
+    "DefaultXmlSchemaFormatter",
+    "DefaultJsonSchemaFormatter",
+    "OpenAiJsonSchemaFormatter",
+    "AnthropicJsonSchemaFormatter",
+    "GeminiJsonSchemaFormatter",
+    "DefaultXmlExampleFormatter",
+    "DefaultJsonExampleFormatter",
+    "OpenAiJsonExampleFormatter",
+    "AnthropicJsonExampleFormatter",
+    "GeminiJsonExampleFormatter",
+]

autobyteus/tools/usage/formatters/anthropic_json_example_formatter.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/anthropic_json_example_formatter.py
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseExampleFormatter
+from .default_xml_example_formatter import DefaultXmlExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class AnthropicJsonExampleFormatter(BaseExampleFormatter):
+    """
+    Formats a tool usage example for Anthropic models. Since Anthropic uses XML
+    for tool calls, this formatter returns a string representing the XML call.
+    """
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        # Anthropic expects XML tool call examples.
+        # We use the XML formatter's logic directly.
+        return DefaultXmlExampleFormatter().provide(tool_definition)

autobyteus/tools/usage/formatters/anthropic_json_schema_formatter.py

@@ -0,0 +1,25 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/anthropic_json_schema_formatter.py
+from typing import Dict, TYPE_CHECKING
+
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class AnthropicJsonSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into the Anthropic JSON format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        name = tool_definition.name
+        description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
+
+        input_schema = arg_schema.to_json_schema_dict() if arg_schema else {
+            "type": "object", "properties": {}, "required": []
+        }
+
+        return {
+            "name": name,
+            "description": description,
+            "input_schema": input_schema,
+        }

autobyteus/tools/usage/formatters/base_formatter.py

@@ -0,0 +1,42 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/base_formatter.py
+from abc import ABC, abstractmethod
+from typing import Union, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class BaseSchemaFormatter(ABC):
+    """
+    Abstract base class for formatting the schema of a single tool
+    into a provider-specific format.
+    """
+    @abstractmethod
+    def provide(self, tool_definition: 'ToolDefinition') -> Union[str, Dict]:
+        """
+        Formats the schema of the given tool definition.
+
+        Args:
+            tool_definition: The tool definition to format.
+
+        Returns:
+            An XML string or a dictionary representing the tool's schema.
+        """
+        pass
+
+class BaseExampleFormatter(ABC):
+    """
+    Abstract base class for formatting a usage example of a single tool
+    into a provider-specific format.
+    """
+    @abstractmethod
+    def provide(self, tool_definition: 'ToolDefinition') -> Union[str, Dict]:
+        """
+        Formats a usage example for the given tool definition.
+
+        Args:
+            tool_definition: The tool definition to format an example for.
+
+        Returns:
+            An XML string or a dictionary representing a tool usage example.
+        """
+        pass

autobyteus/tools/usage/formatters/default_json_example_formatter.py

@@ -0,0 +1,42 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/default_json_example_formatter.py
+from typing import Dict, Any, TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class DefaultJsonExampleFormatter(BaseExampleFormatter):
+    """
+    Formats a tool usage example into a generic JSON format, inspired by
+    the default XML format.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        tool_name = tool_definition.name
+        arg_schema = tool_definition.argument_schema
+        arguments = {}
+
+        if arg_schema and arg_schema.parameters:
+            for param_def in arg_schema.parameters:
+                if param_def.required or param_def.default_value is not None:
+                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
+
+        return {
+            "tool": {
+                "function": tool_name,
+                "parameters": arguments,
+            },
+        }
+
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        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
+        if param_def.param_type == ParameterType.FLOAT: return 123.45
+        if param_def.param_type == ParameterType.BOOLEAN: return True
+        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"}
+        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
+        return "placeholder"

autobyteus/tools/usage/formatters/default_json_schema_formatter.py

@@ -0,0 +1,28 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/default_json_schema_formatter.py
+from typing import Dict, TYPE_CHECKING
+
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class DefaultJsonSchemaFormatter(BaseSchemaFormatter):
+    """
+    Formats a tool's schema into a generic, provider-agnostic JSON format.
+    This serves as the default for JSON-based schema representation.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        name = tool_definition.name
+        description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
+
+        input_schema = arg_schema.to_json_schema_dict() if arg_schema else {
+            "type": "object", "properties": {}, "required": []
+        }
+
+        return {
+            "name": name,
+            "description": description,
+            "inputSchema": input_schema,
+        }

autobyteus/tools/usage/formatters/default_xml_example_formatter.py

@@ -0,0 +1,55 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/default_xml_example_formatter.py
+import xml.sax.saxutils
+from typing import Any, TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class DefaultXmlExampleFormatter(BaseExampleFormatter):
+    """Formats a tool usage example into a standardized XML <tool> string."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        tool_name = tool_definition.name
+        arg_schema = tool_definition.argument_schema
+
+        example_xml_parts = [f'<tool name="{tool_name}">']
+        arguments_part = []
+
+        if arg_schema and arg_schema.parameters:
+            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>')
+
+        if arguments_part:
+            example_xml_parts.append("    <arguments>")
+            example_xml_parts.extend(arguments_part)
+            example_xml_parts.append("    </arguments>")
+        else:
+            example_xml_parts.append("    <!-- This tool takes no arguments -->")
+
+        example_xml_parts.append("</tool>")
+        return "\n".join(example_xml_parts)
+
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        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
+        if param_def.param_type == ParameterType.FLOAT:
+            return 123.45
+        if param_def.param_type == ParameterType.BOOLEAN:
+            return True
+        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"}
+        if param_def.param_type == ParameterType.ARRAY:
+            return ["item1", "item2"]
+        return "placeholder"

autobyteus/tools/usage/formatters/default_xml_schema_formatter.py

@@ -0,0 +1,46 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/default_xml_schema_formatter.py
+import xml.sax.saxutils
+from typing import TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class DefaultXmlSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into a standardized XML string."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        arg_schema = tool_definition.argument_schema
+        tool_name = tool_definition.name
+        description = tool_definition.description
+
+        escaped_description = xml.sax.saxutils.escape(description) if description else ""
+        tool_tag = f'<tool name="{tool_name}" description="{escaped_description}">'
+        xml_parts = [tool_tag]
+
+        if arg_schema and arg_schema.parameters:
+            xml_parts.append("    <arguments>")
+            for param in arg_schema.parameters:
+                arg_tag = f'        <arg name="{param.name}"'
+                arg_tag += f' type="{param.param_type.value}"'
+                if param.description:
+                    escaped_param_desc = xml.sax.saxutils.escape(param.description)
+                    arg_tag += f' description="{escaped_param_desc}"'
+                arg_tag += f" required=\"{'true' if param.required else 'false'}\""
+
+                if param.default_value is not None:
+                    arg_tag += f' default="{xml.sax.saxutils.escape(str(param.default_value))}"'
+                if param.param_type == ParameterType.ENUM and param.enum_values:
+                    escaped_enum_values = [xml.sax.saxutils.escape(ev) for ev in param.enum_values]
+                    arg_tag += f' enum_values="{",".join(escaped_enum_values)}"'
+
+                arg_tag += " />"
+                xml_parts.append(arg_tag)
+            xml_parts.append("    </arguments>")
+        else:
+            xml_parts.append("    <!-- This tool takes no arguments -->")
+
+        xml_parts.append("</tool>")
+        return "\n".join(xml_parts)

autobyteus/tools/usage/formatters/gemini_json_example_formatter.py

@@ -0,0 +1,34 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/gemini_json_example_formatter.py
+from typing import Dict, Any, TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class GeminiJsonExampleFormatter(BaseExampleFormatter):
+    """Formats a tool usage example into the Google Gemini tool_calls format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        tool_name = tool_definition.name
+        arg_schema = tool_definition.argument_schema
+        arguments = {}
+
+        if arg_schema and arg_schema.parameters:
+            for param_def in arg_schema.parameters:
+                if param_def.required or param_def.default_value is not None:
+                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
+
+        return {"name": tool_name, "args": arguments}
+
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        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
+        if param_def.param_type == ParameterType.FLOAT: return 123.45
+        if param_def.param_type == ParameterType.BOOLEAN: return True
+        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"}
+        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
+        return "placeholder"

autobyteus/tools/usage/formatters/gemini_json_schema_formatter.py

@@ -0,0 +1,25 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/gemini_json_schema_formatter.py
+from typing import Dict, TYPE_CHECKING
+
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class GeminiJsonSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into a Google Gemini function declaration format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        name = tool_definition.name
+        description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
+
+        parameters = arg_schema.to_json_schema_dict() if arg_schema else {
+            "type": "object", "properties": {}, "required": []
+        }
+
+        return {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
+        }

autobyteus/tools/usage/formatters/google_json_example_formatter.py

@@ -0,0 +1,34 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/google_json_example_formatter.py
+from typing import Dict, Any, TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class GoogleJsonExampleFormatter(BaseExampleFormatter):
+    """Formats a tool usage example into the Google JSON tool_calls format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        tool_name = tool_definition.name
+        arg_schema = tool_definition.argument_schema
+        arguments = {}
+
+        if arg_schema and arg_schema.parameters:
+            for param_def in arg_schema.parameters:
+                if param_def.required or param_def.default_value is not None:
+                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
+
+        return {"name": tool_name, "args": arguments}
+
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        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
+        if param_def.param_type == ParameterType.FLOAT: return 123.45
+        if param_def.param_type == ParameterType.BOOLEAN: return True
+        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"}
+        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
+        return "placeholder"

autobyteus/tools/usage/formatters/google_json_schema_formatter.py

@@ -0,0 +1,25 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/google_json_schema_formatter.py
+from typing import Dict, TYPE_CHECKING
+
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class GoogleJsonSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into a Google function declaration format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        name = tool_definition.name
+        description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
+
+        parameters = arg_schema.to_json_schema_dict() if arg_schema else {
+            "type": "object", "properties": {}, "required": []
+        }
+
+        return {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
+        }

autobyteus/tools/usage/formatters/openai_json_example_formatter.py

@@ -0,0 +1,49 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/openai_json_example_formatter.py
+import json
+from typing import Dict, Any, TYPE_CHECKING
+
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+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:
+        tool_name = tool_definition.name
+        arg_schema = tool_definition.argument_schema
+        arguments = {}
+
+        if arg_schema and arg_schema.parameters:
+            for param_def in arg_schema.parameters:
+                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,
+                "arguments": json.dumps(arguments),
+            },
+        }
+
+        # Wrap in a 'tool' key for consistency in prompt generation.
+        return {"tool": function_call}
+
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        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
+        if param_def.param_type == ParameterType.FLOAT: return 123.45
+        if param_def.param_type == ParameterType.BOOLEAN: return True
+        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"}
+        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
+        return "placeholder"

autobyteus/tools/usage/formatters/openai_json_schema_formatter.py

@@ -0,0 +1,28 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/openai_json_schema_formatter.py
+from typing import Dict, TYPE_CHECKING
+
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class OpenAiJsonSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into the OpenAI JSON function format."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        name = tool_definition.name
+        description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
+
+        parameters = arg_schema.to_json_schema_dict() if arg_schema else {
+            "type": "object", "properties": {}, "required": []
+        }
+
+        return {
+            "type": "function",
+            "function": {
+                "name": name,
+                "description": description,
+                "parameters": parameters,
+            },
+        }

autobyteus/tools/usage/parsers/__init__.py

@@ -0,0 +1,22 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/__init__.py
+"""
+This package contains concrete parser classes that translate an LLM's raw response
+text into structured ToolInvocation objects.
+"""
+from .base_parser import BaseToolUsageParser
+from .provider_aware_tool_usage_parser import ProviderAwareToolUsageParser
+from .default_xml_tool_usage_parser import DefaultXmlToolUsageParser
+from .anthropic_xml_tool_usage_parser import AnthropicXmlToolUsageParser
+from .default_json_tool_usage_parser import DefaultJsonToolUsageParser
+from .openai_json_tool_usage_parser import OpenAiJsonToolUsageParser
+from .gemini_json_tool_usage_parser import GeminiJsonToolUsageParser
+
+__all__ = [
+    "BaseToolUsageParser",
+    "ProviderAwareToolUsageParser",
+    "DefaultXmlToolUsageParser",
+    "AnthropicXmlToolUsageParser",
+    "DefaultJsonToolUsageParser",
+    "OpenAiJsonToolUsageParser",
+    "GeminiJsonToolUsageParser",
+]

autobyteus/tools/usage/parsers/anthropic_xml_tool_usage_parser.py

@@ -0,0 +1,10 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/anthropic_xml_tool_usage_parser.py
+from .default_xml_tool_usage_parser import DefaultXmlToolUsageParser
+
+class AnthropicXmlToolUsageParser(DefaultXmlToolUsageParser):
+    """
+    Parser for Anthropic models. Anthropic uses XML for tool calls,
+    so this is an alias for the default XML parser.
+    """
+    def get_name(self) -> str:
+        return "anthropic_xml_tool_usage_parser"

autobyteus/tools/usage/parsers/base_parser.py

@@ -0,0 +1,41 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/base_parser.py
+import logging
+from abc import ABC, abstractmethod
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.agent.tool_invocation import ToolInvocation
+    from autobyteus.llm.utils.response_types import CompleteResponse
+
+logger = logging.getLogger(__name__)
+
+class BaseToolUsageParser(ABC):
+    """
+    Abstract base class for parsing tool usage from an LLM's response text.
+    These parsers are responsible for extracting structured tool call information.
+    """
+
+    def get_name(self) -> str:
+        """
+        Returns the unique name for this parser.
+        Defaults to the class name.
+        """
+        return self.__class__.__name__
+
+    @abstractmethod
+    def parse(self, response: 'CompleteResponse') -> List['ToolInvocation']:
+        """
+        Parses the LLM's response. If actionable tool calls are found,
+        this method should return a list of ToolInvocation objects.
+
+        Args:
+            response: The CompleteResponse object from the LLM.
+
+        Returns:
+            A list of ToolInvocation objects. Returns an empty list if no
+            valid tool calls are found.
+        """
+        raise NotImplementedError("Subclasses must implement the 'parse' method.")
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"