autobyteus 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

autobyteus/tools/transaction_management/operation_lifecycle_manager.py

@@ -0,0 +1,62 @@
+"""
+tools/coordinator/operation_lifecycle_manager.py
+
+This module contains the OperationLifecycleManager class which manages the
+transaction lifecycle including starting, committing, and rolling back transactions.
+"""
+
+import uuid
+from autobyteus.tools.operation_executor.journal_manager import JournalManager
+from autobyteus.tools.operation_executor.operation_event_producer import OperationEventProducer
+from autobyteus.tools.transaction_management.backup_handler import BackupHandler
+from tools.operation_executor.operation_executor import OperationExecutor
+# Assuming the other required classes are located in their respective modules.
+
+class OperationLifecycleManager:
+    def __init__(self,
+                 journal_manager: JournalManager,
+                 operation_executor: OperationExecutor,
+                 backup_handler: BackupHandler,
+                 event_producer: OperationEventProducer) -> None:
+        self.journal_manager = journal_manager
+        self.operation_executor = operation_executor
+        self.backup_handler = backup_handler
+        self.event_producer = event_producer
+
+    def start_transaction(self) -> str:
+        """
+        Initializes a transaction and returns a unique transaction ID.
+        """
+        transaction_id = str(uuid.uuid4())
+        self.journal_manager.initialize_journal(transaction_id)
+        return transaction_id
+
+    def commit(self, transaction_id: str) -> None:
+        """
+        Commits all the operations, journals them, and emits an event indicating
+        a successful commit.
+        
+        Args:
+            transaction_id (str): The unique ID of the transaction to be committed.
+        """
+        try:
+            self.journal_manager.finalize_journal(transaction_id, status="committed")
+            self.event_producer.emit_event(f"Transaction {transaction_id} committed.")
+        except Exception as e:
+            self.journal_manager.log_error(transaction_id, str(e))
+            raise
+
+    def rollback(self, transaction_id: str) -> None:
+        """
+        Reverts all executed operations, restores files if necessary, and emits a rollback event.
+        
+        Args:
+            transaction_id (str): The unique ID of the transaction to be rolled back.
+        """
+        try:
+            self.operation_executor.rollback_operations()
+            self.backup_handler.restore_backup(transaction_id)
+            self.event_producer.emit_event(f"Transaction {transaction_id} rolled back.")
+        except Exception as e:
+            self.journal_manager.log_error(transaction_id, str(e))
+            raise

autobyteus/tools/usage/__init__.py

@@ -1,6 +1,5 @@
 # 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.
+tool usage information (schemas and examples).
 """

autobyteus/tools/usage/formatters/__init__.py

@@ -3,7 +3,7 @@
 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 .base_formatter import BaseSchemaFormatter, BaseExampleFormatter, BaseXmlSchemaFormatter
 from .default_xml_schema_formatter import DefaultXmlSchemaFormatter
 from .default_json_schema_formatter import DefaultJsonSchemaFormatter
 from .openai_json_schema_formatter import OpenAiJsonSchemaFormatter
@@ -15,9 +15,18 @@ from .openai_json_example_formatter import OpenAiJsonExampleFormatter
 from .anthropic_json_example_formatter import AnthropicJsonExampleFormatter
 from .gemini_json_example_formatter import GeminiJsonExampleFormatter
 
+# Tool-specific formatters
+from .write_file_xml_schema_formatter import WriteFileXmlSchemaFormatter
+from .write_file_xml_example_formatter import WriteFileXmlExampleFormatter
+from .patch_file_xml_schema_formatter import PatchFileXmlSchemaFormatter
+from .patch_file_xml_example_formatter import PatchFileXmlExampleFormatter
+from .run_bash_xml_schema_formatter import RunBashXmlSchemaFormatter
+from .run_bash_xml_example_formatter import RunBashXmlExampleFormatter
+
 __all__ = [
     "BaseSchemaFormatter",
     "BaseExampleFormatter",
+    "BaseXmlSchemaFormatter",
     "DefaultXmlSchemaFormatter",
     "DefaultJsonSchemaFormatter",
     "OpenAiJsonSchemaFormatter",
@@ -28,4 +37,11 @@ __all__ = [
     "OpenAiJsonExampleFormatter",
     "AnthropicJsonExampleFormatter",
     "GeminiJsonExampleFormatter",
+    # Tool-specific formatters
+    "WriteFileXmlSchemaFormatter",
+    "WriteFileXmlExampleFormatter",
+    "PatchFileXmlSchemaFormatter",
+    "PatchFileXmlExampleFormatter",
+    "RunBashXmlSchemaFormatter",
+    "RunBashXmlExampleFormatter",
 ]

autobyteus/tools/usage/formatters/base_formatter.py

@@ -23,6 +23,14 @@ class BaseSchemaFormatter(ABC):
         """
         pass
 
+class BaseXmlSchemaFormatter(BaseSchemaFormatter):
+    """
+    Marker base class for all XML schema formatters.
+    Subclass this for any formatter that produces XML output.
+    """
+    pass
+
+
 class BaseExampleFormatter(ABC):
     """
     Abstract base class for formatting a usage example of a single tool

autobyteus/tools/usage/formatters/default_xml_schema_formatter.py

@@ -3,12 +3,12 @@ import xml.sax.saxutils
 from typing import TYPE_CHECKING, List, Dict
 
 from autobyteus.utils.parameter_schema import ParameterType, ParameterDefinition, ParameterSchema
-from .base_formatter import BaseSchemaFormatter
+from .base_formatter import BaseXmlSchemaFormatter
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
 
-class DefaultXmlSchemaFormatter(BaseSchemaFormatter):
+class DefaultXmlSchemaFormatter(BaseXmlSchemaFormatter):
     """Formats a tool's schema into a standardized, potentially nested, XML string."""
 
     def provide(self, tool_definition: 'ToolDefinition') -> str:

autobyteus/tools/usage/formatters/mistral_json_schema_formatter.py

@@ -0,0 +1,18 @@
+from typing import Dict, TYPE_CHECKING
+from .base_formatter import BaseSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+class MistralJsonSchemaFormatter(BaseSchemaFormatter):
+    """Formats a tool's schema into the Mistral JSON format (standard JSON schema)."""
+
+    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": tool_definition.name,
+                "description": tool_definition.description,
+                "parameters": tool_definition.argument_schema.to_json_schema_dict() if tool_definition.argument_schema else {"type": "object", "properties": {}}
+            }
+        }

autobyteus/tools/usage/formatters/patch_file_xml_example_formatter.py

@@ -0,0 +1,64 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/patch_file_xml_example_formatter.py
+"""
+XML Example formatter for the patch_file tool using standard <tool name="patch_file"> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class PatchFileXmlExampleFormatter(BaseExampleFormatter):
+    """
+    Formats usage examples for patch_file using the standard <tool name="patch_file"> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates usage examples for patch_file.
+        """
+        return '''### Example 1: Modify a function in a Python file
+
+<tool name="patch_file">
+    <arguments>
+        <arg name="path">/path/to/utils.py</arg>
+        <arg name="patch">
+__START_PATCH__
+--- a/utils.py
++++ b/utils.py
+@@ -10,7 +10,7 @@
+ def calculate_total(items):
+     """Calculate the total price of items."""
+     total = 0
+-    for item in items:
++    for item in sorted(items, key=lambda x: x.price):
+         total += item.price
+     return total
+__END_PATCH__
+        </arg>
+    </arguments>
+</tool>
+
+### Example 2: Add new lines to a configuration file
+
+<tool name="patch_file">
+    <arguments>
+        <arg name="path">config/settings.yaml</arg>
+        <arg name="patch">
+__START_PATCH__
+--- a/settings.yaml
++++ b/settings.yaml
+@@ -5,3 +5,6 @@
+ logging:
+   level: INFO
+   format: "%(asctime)s - %(message)s"
++
++cache:
++  enabled: true
++  ttl: 3600
+__END_PATCH__
+        </arg>
+    </arguments>
+</tool>'''

autobyteus/tools/usage/formatters/patch_file_xml_schema_formatter.py

@@ -0,0 +1,31 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/patch_file_xml_schema_formatter.py
+"""
+XML Schema formatter for the patch_file tool using standard <tool name="patch_file"> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseXmlSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class PatchFileXmlSchemaFormatter(BaseXmlSchemaFormatter):
+    """
+    Formats the patch_file tool schema using the standard <tool name="patch_file"> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates the schema description for patch_file using standard XML syntax
+        with specific instructions for sentinel tags to support robust streaming.
+        """
+        return '''<tool name="patch_file">
+    <arguments>
+        <arg name="path" type="string" description="The absolute or relative path to the file to patch." required="true" />
+        <arg name="patch" type="string" description="The unified diff patch to apply to the file." required="true">
+            IMPORTANT: To ensure reliable streaming, you MUST enclose the patch content with the sentinel tags __START_PATCH__ and __END_PATCH__.
+            The parser will strip these tags, but they are critical for preventing XML parsing errors if the patch contains special characters.
+        </arg>
+    </arguments>
+</tool>'''

autobyteus/tools/usage/formatters/run_bash_xml_example_formatter.py

@@ -0,0 +1,32 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/run_bash_xml_example_formatter.py
+"""
+XML Example formatter for the run_bash tool using shorthand <run_bash> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class RunBashXmlExampleFormatter(BaseExampleFormatter):
+    """
+    Formats usage examples for run_bash using the shorthand <run_bash> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates usage examples for run_bash.
+        """
+        return '''### Example 1: List files
+
+<run_bash>
+ls -la
+</run_bash>
+
+### Example 2: Run tests
+
+<run_bash>
+python -m pytest tests/ -v
+</run_bash>'''

autobyteus/tools/usage/formatters/run_bash_xml_schema_formatter.py

@@ -0,0 +1,36 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/run_bash_xml_schema_formatter.py
+"""
+XML Schema formatter for the run_bash tool using shorthand <run_bash> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseXmlSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class RunBashXmlSchemaFormatter(BaseXmlSchemaFormatter):
+    """
+    Formats the run_bash tool schema using the shorthand <run_bash> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates the schema description for run_bash using shorthand syntax.
+        """
+        return '''## run_bash
+
+Runs a command in the terminal.
+
+**Syntax:**
+```xml
+<run_bash>
+command_to_execute
+</run_bash>
+```
+
+**Parameters:**
+- Content between tags: The shell command to execute.
+
+The command runs in the agent's configured working directory.'''

autobyteus/tools/usage/formatters/write_file_xml_example_formatter.py

@@ -0,0 +1,53 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/write_file_xml_example_formatter.py
+"""
+XML Example formatter for the write_file tool using shorthand <write_file> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseExampleFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class WriteFileXmlExampleFormatter(BaseExampleFormatter):
+    """
+    Formats usage examples for write_file using the shorthand <write_file> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates usage examples for write_file.
+        """
+        return '''### Example 1: Create a Python file
+        
+<tool name="write_file">
+    <arguments>
+        <arg name="path">/path/to/hello.py</arg>
+        <arg name="content">
+__START_CONTENT__
+def hello():
+    print("Hello, World!")
+
+if __name__ == "__main__":
+    hello()
+__END_CONTENT__
+        </arg>
+    </arguments>
+</tool>
+
+### Example 2: Create a configuration file
+
+<tool name="write_file">
+    <arguments>
+        <arg name="path">config/settings.json</arg>
+        <arg name="content">
+__START_CONTENT__
+{
+    "debug": true,
+    "log_level": "INFO"
+}
+__END_CONTENT__
+        </arg>
+    </arguments>
+</tool>'''

autobyteus/tools/usage/formatters/write_file_xml_schema_formatter.py

@@ -0,0 +1,31 @@
+# file: autobyteus/autobyteus/tools/usage/formatters/write_file_xml_schema_formatter.py
+"""
+XML Schema formatter for the write_file tool using shorthand <write_file> syntax.
+"""
+from typing import TYPE_CHECKING
+
+from .base_formatter import BaseXmlSchemaFormatter
+
+if TYPE_CHECKING:
+    from autobyteus.tools.registry import ToolDefinition
+
+
+class WriteFileXmlSchemaFormatter(BaseXmlSchemaFormatter):
+    """
+    Formats the write_file tool schema using the shorthand <write_file> XML syntax.
+    """
+
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates the schema description for write_file using standard XML syntax
+        but with specific instructions for sentinel tags to support robust streaming.
+        """
+        return '''<tool name="write_file">
+    <arguments>
+        <arg name="path" type="string" description="The absolute or relative path where the file will be written." required="true" />
+        <arg name="content" type="string" description="The content to write to the file." required="true">
+            IMPORTANT: To ensure reliable streaming, you MUST enclose the file content with the sentinel tags __START_CONTENT__ and __END_CONTENT__.
+            The parser will strip these tags, but they are critical for preventing XML parsing errors if the content contains special characters.
+        </arg>
+    </arguments>
+</tool>'''

autobyteus/tools/usage/providers/tool_manifest_provider.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, List, Optional
 
 from autobyteus.llm.providers import LLMProvider
 from autobyteus.tools.usage.registries.tool_formatting_registry import ToolFormattingRegistry
-from autobyteus.tools.usage.formatters import DefaultXmlSchemaFormatter
+from autobyteus.tools.usage.formatters import BaseXmlSchemaFormatter
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
@@ -52,29 +52,29 @@ class ToolManifestProvider:
 
     def provide(self,
                 tool_definitions: List['ToolDefinition'],
-                provider: Optional[LLMProvider] = None,
-                use_xml_tool_format: bool = False) -> str:
+                provider: Optional[LLMProvider] = None) -> str:
         """
         Generates the manifest string for a list of tools.
 
         Args:
             tool_definitions: A list of ToolDefinition objects.
             provider: The LLM provider, for provider-specific formatting.
-            use_xml_tool_format: If True, forces the use of XML formatters.
 
         Returns:
             A single string containing the formatted manifest.
         """
         tool_blocks = []
 
-        formatter_pair = self._formatting_registry.get_formatter_pair(provider, use_xml_tool_format=use_xml_tool_format)
-        schema_formatter = formatter_pair.schema_formatter
-        example_formatter = formatter_pair.example_formatter
-
-        is_xml_format = isinstance(schema_formatter, DefaultXmlSchemaFormatter)
-
         for td in tool_definitions:
             try:
+                # Get formatter pair per-tool (with fallback to provider)
+                formatter_pair = self._formatting_registry.get_formatter_pair_for_tool(
+                    td.name, provider
+                )
+                schema_formatter = formatter_pair.schema_formatter
+                example_formatter = formatter_pair.example_formatter
+                is_xml_format = isinstance(schema_formatter, BaseXmlSchemaFormatter)
+
                 schema = schema_formatter.provide(td)
                 example = example_formatter.provide(td) # This is now a pre-formatted string for both XML and JSON
 

autobyteus/tools/usage/registries/__init__.py

@@ -1,15 +1,13 @@
 # file: autobyteus/autobyteus/tools/usage/registries/__init__.py
 """
-This package contains registries for schema/example formatters and parsers,
+This package contains registries for schema/example formatters,
 allowing for easy retrieval of the correct component based on the LLM provider.
 """
 # Import the new consolidated components
 from .tool_formatter_pair import ToolFormatterPair
 from .tool_formatting_registry import ToolFormattingRegistry
-from .tool_usage_parser_registry import ToolUsageParserRegistry
 
 __all__ = [
     "ToolFormatterPair",
     "ToolFormattingRegistry",
-    "ToolUsageParserRegistry",
 ]

autobyteus/tools/usage/registries/tool_formatting_registry.py

@@ -5,12 +5,18 @@ from typing import Dict, Optional
 from autobyteus.llm.providers import LLMProvider
 from autobyteus.utils.singleton import SingletonMeta
 from .tool_formatter_pair import ToolFormatterPair
+from autobyteus.utils.tool_call_format import resolve_tool_call_format
 
 # Import all necessary formatters
 from autobyteus.tools.usage.formatters import (
     DefaultJsonSchemaFormatter, OpenAiJsonSchemaFormatter, AnthropicJsonSchemaFormatter, GeminiJsonSchemaFormatter,
     DefaultJsonExampleFormatter, OpenAiJsonExampleFormatter, AnthropicJsonExampleFormatter, GeminiJsonExampleFormatter,
-    DefaultXmlSchemaFormatter, DefaultXmlExampleFormatter
+    DefaultXmlSchemaFormatter, DefaultXmlExampleFormatter,
+    BaseSchemaFormatter, BaseExampleFormatter,
+    # Tool-specific formatters
+    WriteFileXmlSchemaFormatter, WriteFileXmlExampleFormatter,
+    PatchFileXmlSchemaFormatter, PatchFileXmlExampleFormatter,
+    RunBashXmlSchemaFormatter, RunBashXmlExampleFormatter,
 )
 
 logger = logging.getLogger(__name__)
@@ -19,6 +25,9 @@ class ToolFormattingRegistry(metaclass=SingletonMeta):
     """
     A consolidated registry that maps an LLMProvider directly to its required
     ToolFormatterPair, which contains both schema and example formatters.
+    
+    Also supports tool-specific formatter pairs that take priority over provider defaults.
+    Priority cascade: tool-specific → provider-specific → default
     """
 
     def __init__(self):
@@ -38,28 +47,126 @@ class ToolFormattingRegistry(metaclass=SingletonMeta):
         self._default_pair = ToolFormatterPair(DefaultJsonSchemaFormatter(), DefaultJsonExampleFormatter())
         # A specific pair for the XML override
         self._xml_override_pair = ToolFormatterPair(DefaultXmlSchemaFormatter(), DefaultXmlExampleFormatter())
+        # Tool-specific formatter pairs (tool_name -> ToolFormatterPair)
+        self._tool_pairs: Dict[str, ToolFormatterPair] = {}
+        
+        # Register tool-specific formatters
+        self._register_tool_formatters()
         
         logger.info("ToolFormattingRegistry initialized with direct provider-to-formatter mappings.")
 
-    def get_formatter_pair(self, provider: Optional[LLMProvider], use_xml_tool_format: bool = False) -> ToolFormatterPair:
+    def _register_tool_formatters(self) -> None:
+        """Register built-in tool-specific formatters."""
+        # write_file uses standard <tool name="write_file"> syntax with custom sentinel instructions
+        self._tool_pairs["write_file"] = ToolFormatterPair(
+            WriteFileXmlSchemaFormatter(),
+            WriteFileXmlExampleFormatter()
+        )
+        # patch_file uses standard <tool name="patch_file"> syntax with custom sentinel instructions
+        self._tool_pairs["patch_file"] = ToolFormatterPair(
+            PatchFileXmlSchemaFormatter(),
+            PatchFileXmlExampleFormatter()
+        )
+        # run_bash uses shorthand <run_bash> syntax
+        #self._tool_pairs["run_bash"] = ToolFormatterPair(
+        #    RunBashXmlSchemaFormatter(),
+        #    RunBashXmlExampleFormatter()
+        #)
+
+    def register_tool_formatter(self, tool_name: str, formatter_pair: ToolFormatterPair) -> None:
+        """
+        Register a tool-specific formatter pair.
+        
+        Args:
+            tool_name: The name of the tool (e.g., 'write_file').
+            formatter_pair: The formatter pair to use for this tool.
+        """
+        self._tool_pairs[tool_name] = formatter_pair
+        logger.info(f"Registered tool-specific formatter for '{tool_name}'.")
+
+    def get_formatter_pair_for_tool(
+        self, 
+        tool_name: str, 
+        provider: Optional[LLMProvider]
+    ) -> ToolFormatterPair:
+        """
+        Get the formatter pair for a specific tool with priority cascade.
+        
+        Priority:
+        1. Tool-specific pair (if registered)
+        2. Provider-specific pair (if provider known)
+        3. Default pair
+        
+        Args:
+            tool_name: The name of the tool.
+            provider: The LLM provider.
+            
+        Returns:
+            The appropriate ToolFormatterPair.
+        """
+        if tool_name in self._tool_pairs:
+            logger.debug(f"Using tool-specific formatter for '{tool_name}'.")
+            return self._tool_pairs[tool_name]
+        return self.get_formatter_pair(provider)
+
+    def get_formatter_pair(self, provider: Optional[LLMProvider]) -> ToolFormatterPair:
         """
-        Retrieves the appropriate formatting pair for a given provider, honoring the XML override.
+        Retrieves the appropriate formatting pair for a given provider, honoring the env format override.
 
         Args:
             provider: The LLMProvider enum member.
-            use_xml_tool_format: If True, forces the use of XML formatters.
 
         Returns:
             The corresponding ToolFormatterPair instance.
         """
-        if use_xml_tool_format:
-            logger.debug("XML tool format is forced by configuration. Returning XML formatter pair.")
+        format_override = resolve_tool_call_format()
+        if format_override == "xml":
+            logger.info("Tool format resolved to XML (env override).")
             return self._xml_override_pair
+        if format_override == "json":
+            logger.info("Tool format resolved to JSON (env override).")
+            return self._default_pair
+        if format_override in {"sentinel", "api_tool_call"}:
+            logger.info(
+                "Tool format '%s' is not supported by formatter registry. "
+                "Falling back to JSON formatters.",
+                format_override,
+            )
+            return self._default_pair
 
         if provider and provider in self._pairs:
             pair = self._pairs[provider]
-            logger.debug(f"Found specific formatter pair for provider {provider.name}: {pair}")
+            logger.info(
+                "Tool format resolved by provider '%s' to %s.",
+                provider.name,
+                "XML" if pair is self._xml_override_pair else "JSON",
+            )
             return pair
         
-        logger.debug(f"No specific formatter pair for provider {provider.name if provider else 'Unknown'}. Returning default pair.")
+        logger.info(
+            "Tool format resolved by default to JSON (provider=%s).",
+            provider.name if provider else "Unknown",
+        )
         return self._default_pair
+
+
+def register_tool_formatter(
+    tool_name: str, 
+    schema_formatter: BaseSchemaFormatter, 
+    example_formatter: BaseExampleFormatter
+) -> None:
+    """
+    Registers a custom schema and example formatter for a specific tool.
+    
+    This allows developers to define exactly how a tool's schema and usage example 
+    should be presented to the LLM, overriding default provider-specific behavior.
+
+    Args:
+        tool_name: The name of the tool (must match the @tool name).
+        schema_formatter: An instance of a class inheriting from BaseSchemaFormatter.
+        example_formatter: An instance of a class inheriting from BaseExampleFormatter.
+    """
+    registry = ToolFormattingRegistry()
+    pair = ToolFormatterPair(schema_formatter, example_formatter)
+    registry.register_tool_formatter(tool_name, pair)
+    logger.info(f"Registered custom formatter pair for tool '{tool_name}' via facade.")