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

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.")

autobyteus/tools/usage/tool_schema_provider.py

@@ -0,0 +1,51 @@
+# file: autobyteus/autobyteus/tools/usage/tool_schema_provider.py
+"""
+Provider-aware tool schema builder for API tool calls.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Iterable, List, Dict, Optional
+
+from autobyteus.llm.providers import LLMProvider
+from autobyteus.tools.registry import default_tool_registry
+from autobyteus.tools.usage.formatters.anthropic_json_schema_formatter import AnthropicJsonSchemaFormatter
+from autobyteus.tools.usage.formatters.gemini_json_schema_formatter import GeminiJsonSchemaFormatter
+from autobyteus.tools.usage.formatters.openai_json_schema_formatter import OpenAiJsonSchemaFormatter
+from autobyteus.tools.registry.tool_definition import ToolDefinition
+
+logger = logging.getLogger(__name__)
+
+
+class ToolSchemaProvider:
+    """Builds API tool schemas for a provider."""
+
+    def __init__(self, registry=default_tool_registry):
+        self._registry = registry
+
+    def build_schema(
+        self,
+        tool_names: Iterable[str],
+        provider: Optional[LLMProvider],
+    ) -> List[Dict]:
+        tool_definitions: List[ToolDefinition] = []
+        for name in tool_names:
+            tool_def = self._registry.get_tool_definition(name)
+            if tool_def:
+                tool_definitions.append(tool_def)
+            else:
+                logger.warning("Tool '%s' not found in registry.", name)
+
+        if not tool_definitions:
+            return []
+
+        formatter = self._select_formatter(provider)
+        return [formatter.provide(td) for td in tool_definitions]
+
+    @staticmethod
+    def _select_formatter(provider: Optional[LLMProvider]):
+        if provider == LLMProvider.ANTHROPIC:
+            return AnthropicJsonSchemaFormatter()
+        if provider == LLMProvider.GEMINI:
+            return GeminiJsonSchemaFormatter()
+        return OpenAiJsonSchemaFormatter()

autobyteus/tools/web/__init__.py

@@ -0,0 +1,4 @@
+
+from .read_url_tool import ReadUrl
+
+__all__ = ["ReadUrl"]

autobyteus/tools/web/read_url_tool.py

@@ -0,0 +1,80 @@
+import logging
+import aiohttp
+from typing import Optional, TYPE_CHECKING
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.utils.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+from autobyteus.utils.html_cleaner import clean, CleaningMode
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+class ReadUrl(BaseTool):
+    """
+    Lightweight URL content reader that fetches web page content using aiohttp.
+    Optimized for fast, efficient reading of static content by extracting pure text.
+    """
+    CATEGORY = ToolCategory.WEB
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "read_url"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Reads the content of a specific URL using a lightweight HTTP client. "
+            "Faster and more efficient than using a browser tool for static pages. "
+            "Returns cleaned text content optimized for reading."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="url",
+            param_type=ParameterType.STRING,
+            description="The URL of the webpage to read.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="output_format",
+            param_type=ParameterType.STRING,
+            description="The desired output format: 'text' (default) or 'html'. 'text' returns cleaned text content, 'html' returns cleaned HTML.",
+            required=False,
+            default_value="text",
+            enum_values=["text", "html"]
+        ))
+        return schema
+
+    async def _execute(self, context: 'AgentContext', url: str, output_format: str = "text") -> str:
+        logger.info(f"Executing read_url for agent {context.agent_id} with URL: '{url}'")
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                # aiohttp handles redirects by default (up to 10)
+                async with session.get(url, timeout=30) as response:
+                    if response.status != 200:
+                        error_msg = f"Failed to fetch content from {url}. Status code: {response.status}"
+                        logger.error(error_msg)
+                        return error_msg
+                    
+                    html_content = await response.text()
+            
+            # Use appropriate cleaning mode based on requested format
+            mode = CleaningMode.TEXT_CONTENT_FOCUSED if output_format == "text" else CleaningMode.THOROUGH
+            cleaned_content = clean(html_content, mode=mode)
+            
+            if not cleaned_content.strip():
+                return f"Successfully fetched content from {url}, but the cleaned result was empty."
+                
+            return cleaned_content
+
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error reading URL '{url}': {e}", exc_info=True)
+            return f"Error reading URL '{url}': Network error ({str(e)})"
+        except Exception as e:
+            logger.error(f"Unexpected error reading URL '{url}': {e}", exc_info=True)
+            return f"Error reading URL '{url}': {str(e)}"

autobyteus/utils/diff_utils.py

@@ -0,0 +1,271 @@
+"""
+Unified diff utilities for applying patches to text content.
+"""
+import re
+import logging
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(?P<old_start>\d+)(?:,(?P<old_count>\d+))? \+(?P<new_start>\d+)(?:,(?P<new_count>\d+))? @@")
+_GIT_HEADER_PREFIXES = (
+    "diff --git ",
+    "index ",
+    "new file mode ",
+    "deleted file mode ",
+    "old mode ",
+    "new mode ",
+    "similarity index ",
+    "dissimilarity index ",
+    "rename from ",
+    "rename to ",
+    "copy from ",
+    "copy to ",
+    "binary files ",
+)
+
+
+class PatchApplicationError(ValueError):
+    """Raised when a unified diff patch cannot be applied to the target content."""
+
+
+def apply_unified_diff(
+    original_lines: List[str], 
+    patch: str, 
+    fuzz_factor: int = 0, 
+    ignore_whitespace: bool = False
+) -> List[str]:
+    """Applies a unified diff patch to the provided original lines and returns the patched lines.
+    
+    Args:
+        original_lines: List of strings representing the original content lines (with line endings preserved).
+        patch: Unified diff patch string describing the edits to apply.
+        fuzz_factor: Number of lines to search up/down if exact line number match fails.
+        ignore_whitespace: If True, ignores leading/trailing whitespace when matching context.
+        
+    Returns:
+        List of strings representing the patched content lines.
+        
+    Raises:
+        PatchApplicationError: If the patch content cannot be applied cleanly.
+    """
+    if not patch or not patch.strip():
+        raise PatchApplicationError("Patch content is empty; nothing to apply.")
+
+    patched_lines: List[str] = []
+    orig_idx = 0
+    patch_lines = patch.splitlines(keepends=True)
+    line_idx = 0
+
+    def lines_match(l1: str, l2: str, *, allow_eof_newline_mismatch: bool = False) -> bool:
+        if ignore_whitespace:
+            return l1.strip() == l2.strip()
+        if l1 == l2:
+            return True
+        if allow_eof_newline_mismatch:
+            return l1.rstrip('\n') == l2.rstrip('\n')
+        return False
+
+    while line_idx < len(patch_lines):
+        line = patch_lines[line_idx]
+
+        if line.startswith('---') or line.startswith('+++'):
+            logger.debug("apply_unified_diff: skipping diff header line '%s'.", line.strip())
+            line_idx += 1
+            continue
+        stripped_line = line.lstrip().lower()
+        if any(stripped_line.startswith(prefix) for prefix in _GIT_HEADER_PREFIXES):
+            logger.debug("apply_unified_diff: skipping git diff header line '%s'.", line.strip())
+            line_idx += 1
+            continue
+
+        if not line.startswith('@@'):
+            stripped = line.strip()
+            if stripped == '':
+                # Handle empty lines between hunks or at start as noise, but
+                # legacy behavior might have been to append them?
+                # The previous loop skipped them if start of file (implicit in while loop start?), 
+                # but inside the hunk loop it appended them.
+                # Here we are searching for hunk headers.
+                line_idx += 1
+                continue
+            raise PatchApplicationError(f"Unexpected content outside of hunk header: '{stripped}'.")
+
+        match = _HUNK_HEADER_RE.match(line)
+        if not match:
+            raise PatchApplicationError(f"Malformed hunk header: '{line.strip()}'.")
+
+        old_start = int(match.group('old_start'))
+        old_count = int(match.group('old_count') or '1')
+        new_start = int(match.group('new_start'))
+        new_count = int(match.group('new_count') or '1')
+        logger.debug("apply_unified_diff: processing hunk old_start=%s old_count=%s new_start=%s new_count=%s.",
+                     old_start, old_count, new_start, new_count)
+        
+        line_idx += 1 # Move past header
+        
+        # Capture the hunk body
+        hunk_body = []
+        while line_idx < len(patch_lines):
+            h_line = patch_lines[line_idx]
+            if h_line.startswith('@@'):
+                break
+            hunk_body.append(h_line)
+            line_idx += 1
+            
+        # Extract expected original content from hunk
+        # We process the hunk body to confirm what we expect to see in original_lines
+        refined_expected_orig = []
+        h_i = 0
+        while h_i < len(hunk_body):
+            h_line = hunk_body[h_i]
+            if h_line.startswith(' ') or h_line.startswith('-'):
+                content = h_line[1:]
+                # Check next line for '\ No newline...' to handle EOF correctly during match
+                if h_i + 1 < len(hunk_body) and hunk_body[h_i+1].startswith('\\ No newline'):
+                    content = content.rstrip('\n')
+                elif h_i + 1 == len(hunk_body) and not content.endswith('\n'):
+                     # Last line of patch might legitimately not have newline? 
+                     # Usually lines have newlines. If it's a file without newline at end, diff shows \ No newline.
+                     pass
+                refined_expected_orig.append(content)
+            elif h_line.startswith('+'):
+                pass
+            elif h_line.startswith('\\'):
+                pass 
+            elif h_line.strip() == '':
+                 # Treat bare empty line as non-match content (noise/insert)?
+                 # Previous code appended it to output but didn't check against input.
+                 # So we do NOT add to refined_expected_orig.
+                 pass
+            else:
+                 raise PatchApplicationError(f"Unsupported patch line: '{h_line.strip()}'.")
+            h_i += 1
+
+        expected_count = len(refined_expected_orig)
+
+        # Fuzzy Search for Match
+        # Ideally target is old_start - 1 (converting 1-based old_start to 0-based index)
+        target_idx_base = old_start - 1 if old_start > 0 else 0
+        
+        found_idx = -1
+        
+        # Generate search offsets: 0, -1, 1, -2, 2, ...
+        offsets = [0]
+        for f in range(1, fuzz_factor + 1):
+            offsets.append(-f)
+            offsets.append(f)
+            
+        for offset in offsets:
+            candidate_idx = target_idx_base + offset
+            
+            # Constraints:
+            # 1. Must proceed forward from where we left off (orig_idx)
+            # 2. Must not go beyond EOF (handled by slicing)
+            if candidate_idx < orig_idx:
+                continue 
+            
+            # Check if this candidate location matches expected_orig
+            # We need to verify that original_lines[candidate_idx : candidate_idx + expected_count] matches refined_expected_orig
+            
+            if candidate_idx + expected_count > len(original_lines):
+                # Ensure we don't go out of bounds (though partial match at EOF might be a thing? No, hunk must match fully)
+                continue
+
+            match_success = True
+            for k in range(expected_count):
+                # Note: lines_match handles whitespace if needed.
+                is_eof_line = (
+                    candidate_idx + expected_count == len(original_lines)
+                    and k == expected_count - 1
+                )
+                if not lines_match(
+                    original_lines[candidate_idx + k],
+                    refined_expected_orig[k],
+                    allow_eof_newline_mismatch=is_eof_line,
+                ):
+                    match_success = False
+                    break
+            
+            if match_success:
+                found_idx = candidate_idx
+                break
+                
+        if found_idx == -1:
+             raise PatchApplicationError(f"Could not find context for hunk starting at {old_start} (fuzz={fuzz_factor}).")
+             
+        # Apply changes
+        
+        # 1. Copy lines from orig_idx to found_idx (these are the lines BEFORE the hunk that we skipped over/accepted)
+        patched_lines.extend(original_lines[orig_idx:found_idx])
+        
+        # 2. Process hunk body to generate new lines
+        h_i = 0
+        while h_i < len(hunk_body):
+            h_line = hunk_body[h_i]
+            if h_line.startswith(' ') or h_line.startswith('-'):
+                # Valid context or removal - we skip them in output (they are either preserved via context or removed)
+                # If context (' '), we should actually append the ORIGINAL line to allow for fuzziness?
+                # Standard patch behavior: if fuzz matches, we output the *hunk's* version of the line? 
+                # OR we output the *original* file's version?
+                # `patch` man page says: "patch takes the context from the diff file"
+                # Wait, if we fuzzy matched, likely we want to keep what was in the file unless the patch explicitly changes it.
+                # However, typically ' ' lines are just copied.
+                # If we use `patched_lines.append(original_lines[found_idx + handled_count])`, that preserves the file's indentation/whitespace.
+                # If we use `h_line[1:]`, we enforce the patch's indentation.
+                # Requirement: "Ignore Whitespace... Allow context comparisons to ignore...".
+                # If the patch "autocorrects" indentation in context lines, we probably want to KEEP the file's original indentation 
+                # for context lines, so we don't accidentally "fix" them if we aren't touching them.
+                # Unified diff: ' ' means "unchanged". So we should emit the *original* line.
+                
+                if h_line.startswith(' '):
+                    # Find which original line this corresponds to.
+                    # We are iterating h_i through hunk_body.
+                    # We need to track our position in the matched original block.
+                    # Let's track `current_match_offset`
+                    pass 
+            elif h_line.startswith('+'):
+                pass
+            h_i += 1
+            
+        # Let's redo step 2 cleanly to handle the ' ' vs '-' vs '+' and the '\ No newline' logic.
+        
+        matched_orig_offset = 0 # Offset into the matched block of original_lines [found_idx : found_idx+expected_count]
+        
+        h_i = 0
+        while h_i < len(hunk_body):
+            h_line = hunk_body[h_i]
+            
+            if h_line.startswith(' '):
+                # Context line: preserve original content from file
+                if found_idx + matched_orig_offset < len(original_lines):
+                    patched_lines.append(original_lines[found_idx + matched_orig_offset])
+                matched_orig_offset += 1
+                
+            elif h_line.startswith('-'):
+                # Removal: skip original content
+                matched_orig_offset += 1
+                
+            elif h_line.startswith('+'):
+                # Addition: add content from patch
+                content = h_line[1:]
+                if h_i + 1 < len(hunk_body) and hunk_body[h_i+1].startswith('\\ No newline'):
+                    content = content.rstrip('\n')
+                patched_lines.append(content)
+                
+            elif h_line.strip() == '':
+                 # "Empty" line in patch. Legacy behavior: append to output. 
+                 # Does not consume original.
+                 patched_lines.append(h_line)
+                 
+            elif h_line.startswith('\\'):
+                 # No newline marker, handled by lookahead in + case. 
+                 # For - and space, we used original lines so their newline status is preserved automatically!
+                 pass
+                 
+            h_i += 1
+            
+        orig_idx = found_idx + expected_count
+
+    patched_lines.extend(original_lines[orig_idx:])
+    return patched_lines

autobyteus/utils/download_utils.py

@@ -0,0 +1,109 @@
+import logging
+import aiohttp
+import base64
+import shutil
+import os
+import ssl
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SSL_VERIFY_ENV_VAR = "AUTOBYTEUS_DOWNLOAD_VERIFY_SSL"
+SSL_CERT_FILE_ENV_VAR = "AUTOBYTEUS_DOWNLOAD_SSL_CERT_FILE"
+
+
+def _resolve_ssl_param() -> bool | ssl.SSLContext:
+    """
+    Resolve SSL verification behavior for downloads.
+
+    - If AUTOBYTEUS_DOWNLOAD_SSL_CERT_FILE is set, use it as CA file.
+    - Else if AUTOBYTEUS_DOWNLOAD_VERIFY_SSL is truthy, verify using system CAs.
+    - Else (default), disable verification to allow self-signed certs.
+    """
+    cert_path = os.getenv(SSL_CERT_FILE_ENV_VAR)
+    if cert_path:
+        cert_file = Path(cert_path)
+        if not cert_file.is_file():
+            raise IOError(f"SSL cert file not found: {cert_file}")
+        return ssl.create_default_context(cafile=str(cert_file))
+
+    verify_env = os.getenv(SSL_VERIFY_ENV_VAR)
+    if verify_env and verify_env.strip().lower() in {"1", "true", "yes", "on"}:
+        return True
+    return False
+
+
+async def download_file_from_url(url: str, file_path: Path) -> None:
+    """
+    Asynchronously downloads a file from a URL, decodes a data URI, or copies a local file 
+    to a specified file path.
+    
+    Features:
+    - Supports http/https URLs, data: URIs (base64), and local file paths.
+    - Creates parent directories if they don't exist.
+    - Uses streaming for HTTP URLs to handle large files efficiently.
+    - Guarantees cleanup of partial files on failure.
+    
+    Args:
+        url: The source URL, data URI, or local path.
+        file_path: The specific local path (including filename) to save to.
+        
+    Raises:
+        IOError: If download, decoding, or copying fails.
+    """
+    # Ensure parent directory exists
+    try:
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        logger.error(f"Failed to create directory structure for {file_path}: {e}")
+        raise IOError(f"Filesystem error: {e}")
+
+    try:
+        if url.startswith("data:"):
+            # Handle Data URI
+            try:
+                header, encoded = url.split(",", 1)
+                data = base64.b64decode(encoded)
+                with open(file_path, "wb") as f:
+                    f.write(data)
+                logger.info(f"Successfully decoded and saved data URI to: {file_path}")
+                return
+            except Exception as e:
+                logger.error(f"Failed to decode data URI: {e}")
+                raise IOError(f"Invalid data URI format: {e}")
+
+        if os.path.exists(url) and os.path.isfile(url):
+            # Handle Local File Path (Copy)
+            try:
+                shutil.copy(url, file_path)
+                logger.info(f"Successfully copied local file from {url} to {file_path}")
+                return
+            except Exception as e:
+                logger.error(f"Failed to copy local file from {url} to {file_path}: {e}")
+                raise IOError(f"File copy error: {e}")
+
+        # Handle HTTP URL
+        ssl_param = _resolve_ssl_param()
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, ssl=ssl_param) as response:
+                if response.status != 200:
+                    raise IOError(f"Failed to download from {url}: HTTP {response.status}")
+                
+                # Open file for writing binary
+                with open(file_path, "wb") as f:
+                    # Iterate over chunks to avoid loading large files into memory
+                    async for chunk in response.content.iter_chunked(8192):
+                        f.write(chunk)
+                        
+        logger.info(f"Successfully downloaded file to: {file_path}")
+
+    except Exception as e:
+        logger.error(f"Failed to process media from {url} to {file_path}: {e}")
+        # Cleanup: Delete the partial/empty file if it was created
+        if file_path.exists():
+            try:
+                file_path.unlink()
+                logger.debug(f"Cleaned up partial file: {file_path}")
+            except OSError as cleanup_error:
+                logger.warning(f"Failed to clean up partial file {file_path}: {cleanup_error}")
+        raise