autobyteus 1.0.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

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__}>"

autobyteus/tools/usage/parsers/default_json_tool_usage_parser.py

@@ -0,0 +1,106 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/default_json_tool_usage_parser.py
+import json
+import re
+import logging
+from typing import Optional, Dict, Any, TYPE_CHECKING, List
+import uuid
+
+from autobyteus.agent.tool_invocation import ToolInvocation
+from .base_parser import BaseToolUsageParser
+
+if TYPE_CHECKING:
+    from autobyteus.llm.utils.response_types import CompleteResponse
+
+logger = logging.getLogger(__name__)
+
+class DefaultJsonToolUsageParser(BaseToolUsageParser):
+    """
+    A default parser for tool usage commands formatted as custom JSON.
+    It expects a 'tool' object with 'function' and 'parameters' keys.
+    """
+    def get_name(self) -> str:
+        return "default_json_tool_usage_parser"
+
+    def parse(self, response: 'CompleteResponse') -> List[ToolInvocation]:
+        response_text = self._extract_json_from_response(response.content)
+        if not response_text:
+            return []
+
+        try:
+            data = json.loads(response_text)
+        except json.JSONDecodeError:
+            logger.debug(f"Could not parse extracted text as JSON. Text: {response_text[:200]}")
+            return []
+
+        tool_calls_data = []
+        if isinstance(data, list):
+            tool_calls_data = data
+        elif isinstance(data, dict):
+            if "tools" in data and isinstance(data.get("tools"), list):
+                tool_calls_data = data["tools"]
+            else:
+                tool_calls_data = [data]
+        else:
+            return []
+
+        invocations: List[ToolInvocation] = []
+        for call_data in tool_calls_data:
+            if not isinstance(call_data, dict):
+                continue
+
+            tool_block = call_data.get("tool")
+            if not isinstance(tool_block, dict):
+                continue
+            
+            tool_name = tool_block.get("function")
+            arguments = tool_block.get("parameters")
+
+            if not tool_name or not isinstance(tool_name, str):
+                logger.debug(f"Skipping malformed tool block (missing or invalid 'function'): {tool_block}")
+                continue
+            
+            if arguments is None:
+                arguments = {}
+            
+            if not isinstance(arguments, dict):
+                logger.debug(f"Skipping tool block with invalid 'parameters' type ({type(arguments)}): {tool_block}")
+                continue
+            
+            # The custom format does not have a tool ID, so we generate one.
+            tool_id = str(uuid.uuid4())
+            try:
+                tool_invocation = ToolInvocation(name=tool_name, arguments=arguments, id=tool_id)
+                invocations.append(tool_invocation)
+            except Exception as e:
+                logger.error(f"Unexpected error creating ToolInvocation for tool '{tool_name}': {e}", exc_info=True)
+        
+        return invocations
+
+    def _extract_json_from_response(self, text: str) -> Optional[str]:
+        match = re.search(r"```(?:json)?\s*([\s\S]+?)\s*```", text)
+        if match:
+            return match.group(1).strip()
+        
+        # Try to find a JSON object or array in the text
+        first_bracket = text.find('[')
+        first_brace = text.find('{')
+
+        if first_brace == -1 and first_bracket == -1:
+            return None
+
+        start_index = -1
+        if first_bracket != -1 and first_brace != -1:
+            start_index = min(first_bracket, first_brace)
+        elif first_bracket != -1:
+            start_index = first_bracket
+        else: # first_brace != -1
+            start_index = first_brace
+
+        json_substring = text[start_index:]
+        try:
+            # Check if the substring is valid JSON
+            json.loads(json_substring)
+            return json_substring
+        except json.JSONDecodeError:
+            logger.debug(f"Found potential start of JSON, but substring was not valid: {json_substring[:100]}")
+            return None

autobyteus/tools/usage/parsers/default_xml_tool_usage_parser.py

@@ -0,0 +1,135 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/default_xml_tool_usage_parser.py
+import xml.etree.ElementTree as ET
+import re
+import uuid
+from xml.sax.saxutils import escape, unescape
+import xml.parsers.expat
+import logging
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from autobyteus.agent.tool_invocation import ToolInvocation
+from .base_parser import BaseToolUsageParser
+from .exceptions import ToolUsageParseException
+
+if TYPE_CHECKING:
+    from autobyteus.llm.utils.response_types import CompleteResponse
+
+logger = logging.getLogger(__name__)
+
+class DefaultXmlToolUsageParser(BaseToolUsageParser):
+    """
+    Parses LLM responses for tool usage commands formatted as XML.
+    It looks for either a <tools> block (for multiple calls) or a
+    single <tool> block.
+    """
+    def get_name(self) -> str:
+        return "default_xml_tool_usage_parser"
+
+    def parse(self, response: 'CompleteResponse') -> List[ToolInvocation]:
+        response_text = response.content
+        logger.debug(f"{self.get_name()} attempting to parse response (first 500 chars): {response_text[:500]}...")
+        
+        invocations: List[ToolInvocation] = []
+        match = re.search(r"<tools\b[^>]*>.*?</tools\s*>|<tool\b[^>]*>.*?</tool\s*>", response_text, re.DOTALL | re.IGNORECASE)
+        if not match:
+            logger.debug(f"No <tools> or <tool> block found by {self.get_name()}.")
+            return invocations
+
+        xml_content = match.group(0)
+        processed_xml = self._preprocess_xml_for_parsing(xml_content)
+
+        try:
+            root = ET.fromstring(processed_xml)
+            tool_elements = []
+
+            if root.tag.lower() == "tools":
+                tool_elements = root.findall('tool')
+                if not tool_elements:
+                    logger.debug("Found <tools> but no <tool> children.")
+                    return invocations
+            elif root.tag.lower() == "tool":
+                tool_elements = [root]
+            else:
+                logger.warning(f"Root XML tag is '{root.tag}', not 'tools' or 'tool'. Skipping parsing.")
+                return invocations
+
+            for tool_elem in tool_elements:
+                tool_name = tool_elem.attrib.get("name")
+                tool_id = tool_elem.attrib.get("id") or str(uuid.uuid4())
+                arguments = self._parse_arguments_from_xml(tool_elem)
+
+                if tool_name:
+                    tool_invocation = ToolInvocation(name=tool_name, arguments=arguments, id=tool_id)
+                    invocations.append(tool_invocation)
+                else:
+                    logger.warning(f"Parsed a <tool> element but its 'name' attribute is missing or empty.")
+        
+        except (ET.ParseError, xml.parsers.expat.ExpatError) as e:
+            error_msg = f"XML parsing error in '{self.get_name()}': {e}. Content: '{processed_xml[:200]}'"
+            logger.debug(error_msg)
+            # Raise a specific exception to be caught upstream.
+            raise ToolUsageParseException(error_msg, original_exception=e)
+        
+        except Exception as e:
+            logger.error(f"Unexpected error in {self.get_name()} processing XML: {e}. XML Content: {xml_content[:200]}", exc_info=True)
+            # Also wrap unexpected errors for consistent handling.
+            raise ToolUsageParseException(f"Unexpected error during XML parsing: {e}", original_exception=e)
+
+        return invocations
+
+    def _preprocess_xml_for_parsing(self, xml_content: str) -> str:
+        """
+        Preprocesses raw XML string from an LLM to fix common errors before parsing.
+        """
+        processed_content = re.sub(
+            r'(<arg\s+name\s*=\s*")([^"]+?)>',
+            r'\1\2">',
+            xml_content,
+            flags=re.IGNORECASE
+        )
+        if processed_content != xml_content:
+            logger.debug("Preprocessor fixed a missing quote in an <arg> tag.")
+
+        cdata_sections: Dict[str, str] = {}
+        def cdata_replacer(match_obj: re.Match) -> str:
+            placeholder = f"__CDATA_PLACEHOLDER_{len(cdata_sections)}__"
+            cdata_sections[placeholder] = match_obj.group(0)
+            return placeholder
+
+        xml_no_cdata = re.sub(r'<!\[CDATA\[.*?\]\]>', cdata_replacer, processed_content, flags=re.DOTALL)
+
+        def escape_arg_value(match_obj: re.Match) -> str:
+            open_tag = match_obj.group(1)
+            content = match_obj.group(2)
+            close_tag = match_obj.group(3)
+            if re.search(r'<\s*/?[a-zA-Z]', content.strip()):
+                return f"{open_tag}{content}{close_tag}"
+            escaped_content = escape(content) if not content.startswith("__CDATA_PLACEHOLDER_") else content
+            return f"{open_tag}{escaped_content}{close_tag}"
+
+        processed_content = re.sub(
+            r'(<arg\s+name\s*=\s*"[^"]*"\s*>\s*)(.*?)(\s*</arg\s*>)',
+            escape_arg_value,
+            xml_no_cdata,
+            flags=re.DOTALL | re.IGNORECASE
+        )
+
+        for placeholder, original_cdata_tag in cdata_sections.items():
+            processed_content = processed_content.replace(placeholder, original_cdata_tag)
+
+        return processed_content
+
+    def _parse_arguments_from_xml(self, command_element: ET.Element) -> Dict[str, Any]:
+        arguments: Dict[str, Any] = {}
+        arguments_container = command_element.find('arguments')
+        if arguments_container is None:
+            logger.debug(f"No <arguments> tag found in <tool name='{command_element.attrib.get('name')}'>. No arguments will be parsed.")
+            return arguments
+        
+        for arg_element in arguments_container.findall('arg'):
+            arg_name = arg_element.attrib.get('name')
+            if arg_name:
+                raw_text = "".join(arg_element.itertext())
+                unescaped_value = unescape(raw_text)
+                arguments[arg_name] = unescaped_value
+        return arguments

autobyteus/tools/usage/parsers/exceptions.py

@@ -0,0 +1,13 @@
+# file: autobyteus/autobyteus/tools/usage/parsers/exceptions.py
+"""
+Custom exceptions for the tool usage parsing module.
+"""
+
+class ToolUsageParseException(Exception):
+    """
+    Raised when a tool usage parser fails to parse an LLM response due to
+    malformed content or other parsing errors.
+    """
+    def __init__(self, message: str, original_exception: Exception = None):
+        super().__init__(message)
+        self.original_exception = original_exception