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

autobyteus/tools/pdf_downloader.py

@@ -1,89 +1,88 @@
-# File: autobyteus/tools/pdf_downloader.py
-
+ # This was top-level, keep it there.
 import os
-import requests
 import logging
+import asyncio 
+import requests 
 from datetime import datetime
-from autobyteus.tools.base_tool import BaseTool
-from autobyteus.utils.file_utils import get_default_download_folder
-
-class PDFDownloader(BaseTool):
-    """
-    A tool that downloads a PDF file from a given URL and saves it locally.
-    """
-
-    def __init__(self, custom_download_folder=None):
-        super().__init__()
-        self.logger = logging.getLogger(__name__)
-        self.default_download_folder = get_default_download_folder()
-        self.download_folder = custom_download_folder or self.default_download_folder
-
-    @classmethod
-    def tool_usage_xml(cls):
-        """
-        Return an XML string describing the usage of the PDFDownloader tool.
-
-        Returns:
-            str: An XML description of how to use the PDFDownloader tool.
-        """
-        return '''PDFDownloader: Downloads a PDF file from a given URL. Usage:
-    <command name="PDFDownloader">
-    <arg name="url">https://example.com/file.pdf</arg>
-    </command>
-    '''
-
-    def _execute(self, **kwargs):
-        """
-        Download a PDF file from the given URL and save it locally.
+from typing import TYPE_CHECKING, Optional
 
-        Args:
-            **kwargs: Keyword arguments containing the URL.
-                      'url': The URL of the PDF file to download.
-                      'folder' (optional): Custom download folder path.
-
-        Returns:
-            str: A message indicating the result of the download operation.
-
-        Raises:
-            ValueError: If the 'url' keyword argument is not specified.
-        """
-        url = kwargs.get('url')
-        custom_folder = kwargs.get('folder')
-        download_folder = custom_folder or self.download_folder
-
-        if not url:
-            raise ValueError("The 'url' keyword argument must be specified.")
-
-        self.logger.info(f"Attempting to download PDF from {url}")
+from autobyteus.tools import tool
+from autobyteus.utils.file_utils import get_default_download_folder
 
-        try:
-            response = requests.get(url, stream=True)
-            response.raise_for_status()
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
 
-            content_type = response.headers.get('Content-Type', '').lower()
-            if 'application/pdf' not in content_type:
-                raise ValueError(f"The URL does not point to a PDF file. Content-Type: {content_type}")
+logger = logging.getLogger(__name__)
 
-            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+@tool(name="PDFDownloader")
+async def pdf_downloader( # function name can be pdf_downloader
+    context: 'AgentContext', 
+    url: str, 
+    folder: Optional[str] = None
+) -> str:
+    """
+    Downloads a PDF file from a given URL and saves it locally.
+    'url' is the URL of the PDF.
+    'folder' (optional) is a custom directory to save the PDF. If not given,
+    uses the system's default download folder. Validates Content-Type.
+    """
+    logger.debug(f"Functional PDFDownloader tool for agent {context.agent_id}, URL: {url}, Folder: {folder}")
+    
+    current_download_folder = folder if folder else get_default_download_folder()
+
+    try:
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, lambda: requests.get(url, stream=True, timeout=30))
+        response.raise_for_status()
+
+        content_type = response.headers.get('Content-Type', '').lower()
+        if 'application/pdf' not in content_type:
+            response.close()
+            raise ValueError(f"The URL does not point to a PDF file. Content-Type: {content_type}")
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename_from_header = None
+        if 'Content-Disposition' in response.headers:
+            import re
+            match = re.search(r'filename=[\'"]?([^\'"\s]+)[\'"]?', response.headers['Content-Disposition'])
+            if match: filename_from_header = match.group(1)
+        
+        if filename_from_header and filename_from_header.lower().endswith(".pdf"):
+            import string
+            valid_chars = "-_.() %s%s" % (string.ascii_letters, string.digits)
+            filename_from_header = ''.join(c for c in filename_from_header if c in valid_chars)[:200]
+            filename = f"{timestamp}_{filename_from_header}"
+        else:
             filename = f"downloaded_pdf_{timestamp}.pdf"
-            save_path = os.path.join(download_folder, filename)
 
-            os.makedirs(download_folder, exist_ok=True)
-            with open(save_path, 'wb') as file:
+        save_path = os.path.join(current_download_folder, filename)
+        os.makedirs(current_download_folder, exist_ok=True)
+        
+        def download_and_save_sync():
+            with open(save_path, 'wb') as file_handle:
                 for chunk in response.iter_content(chunk_size=8192):
-                    file.write(chunk)
-
-            self.logger.info(f"PDF successfully downloaded and saved to {save_path}")
-            return f"PDF successfully downloaded and saved to {save_path}"
-        except requests.exceptions.RequestException as e:
-            error_message = f"Error downloading PDF: {str(e)}"
-            self.logger.error(error_message)
-            return error_message
-        except ValueError as e:
-            error_message = str(e)
-            self.logger.error(error_message)
-            return error_message
-        except IOError as e:
-            error_message = f"Error saving PDF: {str(e)}"
-            self.logger.error(error_message)
-            return error_message
+                    file_handle.write(chunk)
+            response.close()
+        
+        await loop.run_in_executor(None, download_and_save_sync)
+
+        logger.info(f"PDF successfully downloaded and saved to {save_path}")
+        return f"PDF successfully downloaded and saved to {save_path}"
+    except requests.exceptions.Timeout:
+        logger.error(f"Timeout downloading PDF from {url}", exc_info=True)
+        return f"Error downloading PDF: Timeout occurred for URL {url}"
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Error downloading PDF from {url}: {str(e)}", exc_info=True)
+        return f"Error downloading PDF: {str(e)}"
+    except ValueError as e:
+        logger.error(f"Content type error for PDF from {url}: {str(e)}", exc_info=True)
+        return str(e)
+    except IOError as e:
+        logger.error(f"Error saving PDF to {current_download_folder}: {str(e)}", exc_info=True)
+        return f"Error saving PDF: {str(e)}"
+    except Exception as e:
+        logger.error(f"Unexpected error downloading PDF from {url}: {str(e)}", exc_info=True)
+        return f"An unexpected error occurred: {str(e)}"
+    finally:
+        if 'response' in locals() and hasattr(response, 'close') and response.raw and not response.raw.closed:
+             response.close()

autobyteus/tools/registry/__init__.py

@@ -1,11 +1,9 @@
 # file: autobyteus/autobyteus/tools/registry/__init__.py
 from .tool_definition import ToolDefinition
 from .tool_registry import ToolRegistry, default_tool_registry
-from autobyteus.tools.factory.tool_factory import ToolFactory
 
 __all__ = [
     "ToolDefinition",
     "ToolRegistry",
     "default_tool_registry",
-    "ToolFactory"
 ]

autobyteus/tools/registry/tool_definition.py

@@ -1,60 +1,132 @@
-# file: autobyteus/tools/registry/tool_definition.py
+# file: autobyteus/autobyteus/tools/registry/tool_definition.py
 import logging
-from typing import Dict, Any
+import json
+from typing import Dict, Any, List as TypingList, Type, TYPE_CHECKING, Optional, Callable
+
+from autobyteus.llm.providers import LLMProvider
+from autobyteus.tools.tool_config import ToolConfig
+from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.tools.usage.providers import (
+    XmlSchemaProvider, 
+    JsonSchemaProvider, 
+    XmlExampleProvider, 
+    JsonExampleProvider
+)
+
+if TYPE_CHECKING:
+    from autobyteus.tools.base_tool import BaseTool
 
 logger = logging.getLogger(__name__)
 
 class ToolDefinition:
     """
-    Represents the simplified static definition of a tool, containing
-    only its name and usage description string.
+    Represents the definition of a tool, containing its metadata and the means
+    to create an instance. It can generate provider-specific usage information on demand.
     """
     def __init__(self,
                  name: str,
-                 description: str):
+                 description: str,
+                 argument_schema: Optional['ParameterSchema'],
+                 config_schema: Optional['ParameterSchema'] = None,
+                 tool_class: Optional[Type['BaseTool']] = None,
+                 custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None):
         """
         Initializes the ToolDefinition.
-
-        Args:
-            name: The unique name/identifier of the tool.
-            description: The static usage description string for the tool (e.g., XML usage format).
-
-        Raises:
-            ValueError: If name or description are empty or invalid.
         """
         if not name or not isinstance(name, str):
             raise ValueError("ToolDefinition requires a non-empty string 'name'.")
         if not description or not isinstance(description, str):
             raise ValueError(f"ToolDefinition '{name}' requires a non-empty string 'description'.")
 
+        if tool_class is None and custom_factory is None:
+            raise ValueError(f"ToolDefinition '{name}' must provide either a 'tool_class' or a 'custom_factory'.")
+        if tool_class is not None and custom_factory is not None:
+            raise ValueError(f"ToolDefinition '{name}' cannot have both a 'tool_class' and a 'custom_factory'.")
+        
+        if tool_class and not isinstance(tool_class, type):
+            raise TypeError(f"ToolDefinition '{name}' requires a valid class for 'tool_class'.")
+        if custom_factory and not callable(custom_factory):
+            raise TypeError(f"ToolDefinition '{name}' requires a callable for 'custom_factory'.")
+
+        if argument_schema is not None and not isinstance(argument_schema, ParameterSchema):
+             raise TypeError(f"ToolDefinition '{name}' received an invalid 'argument_schema'. Expected ParameterSchema or None.")
+        if config_schema is not None and not isinstance(config_schema, ParameterSchema):
+             raise TypeError(f"ToolDefinition '{name}' received an invalid 'config_schema'. Expected ParameterSchema or None.")
+
         self._name = name
         self._description = description
-
+        self._argument_schema: Optional['ParameterSchema'] = argument_schema
+        self._config_schema: Optional['ParameterSchema'] = config_schema
+        self._tool_class = tool_class
+        self._custom_factory = custom_factory
+        
         logger.debug(f"ToolDefinition created for tool '{self.name}'.")
 
+    # --- Properties ---
+    @property
+    def name(self) -> str: return self._name
+    @property
+    def description(self) -> str: return self._description
+    @property
+    def tool_class(self) -> Optional[Type['BaseTool']]: return self._tool_class
     @property
-    def name(self) -> str:
-        """The unique name/identifier of the tool."""
-        return self._name
+    def custom_factory(self) -> Optional[Callable[['ToolConfig'], 'BaseTool']]: return self._custom_factory
+    @property
+    def argument_schema(self) -> Optional['ParameterSchema']: return self._argument_schema
+    @property
+    def config_schema(self) -> Optional['ParameterSchema']: return self._config_schema
+    
+    # --- Schema Generation API ---
+    def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:
+        """
+        Generates the standardized XML usage schema string for this tool.
+        The provider argument is included for API consistency and future-proofing.
+        """
+        provider_instance = XmlSchemaProvider()
+        return provider_instance.provide(self, llm_provider=provider)
 
+    def get_usage_json(self, provider: Optional[LLMProvider] = None) -> Dict[str, Any]:
+        """
+        Generates the usage schema as a dictionary.
+        
+        Args:
+            provider: If provided, generates a provider-specific JSON format.
+                      If None, generates a default, generic JSON format.
+        
+        Returns:
+            A dictionary representing the tool's usage schema.
+        """
+        provider_instance = JsonSchemaProvider()
+        return provider_instance.provide(self, llm_provider=provider)
+
+    # --- Example Generation API ---
+    def get_usage_xml_example(self, provider: Optional[LLMProvider] = None) -> str:
+        """
+        Generates a standardized XML usage example string for this tool.
+        The provider argument is included for API consistency and future-proofing.
+        """
+        provider_instance = XmlExampleProvider()
+        return provider_instance.provide(self, llm_provider=provider)
+
+    def get_usage_json_example(self, provider: Optional[LLMProvider] = None) -> Any:
+        """
+        Generates a usage example, either as a dict or a string.
+        """
+        provider_instance = JsonExampleProvider()
+        return provider_instance.provide(self, llm_provider=provider)
+
+    # --- Other methods ---
     @property
-    def description(self) -> str:
-        """The static usage description string for the tool."""
-        return self._description
+    def has_instantiation_config(self) -> bool:
+        return self._config_schema is not None and len(self._config_schema) > 0
 
-    def __repr__(self) -> str:
-        """Provides a developer-friendly string representation."""
-        desc_repr = self.description
-        if len(desc_repr) > 70:
-             desc_repr = desc_repr[:67] + "..."
-        # Remove newlines/tabs from repr for cleaner logging if description is multiline XML
-        desc_repr = desc_repr.replace('\n', '\\n').replace('\t', '\\t')
-        return (f"ToolDefinition(name='{self.name}', description='{desc_repr}')")
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Returns a dictionary representation of the tool definition."""
-        return {
-            "name": self.name,
-            "description": self.description,
-        }
+    def validate_instantiation_config(self, config_data: Dict[str, Any]) -> tuple[bool, TypingList[str]]:
+        if not self._config_schema:
+            if config_data:
+                return False, [f"Tool '{self.name}' does not accept instantiation configuration parameters"]
+            return True, []
+        return self._config_schema.validate_config(config_data)
 
+    def __repr__(self) -> str:
+        creator_repr = f"class='{self._tool_class.__name__}'" if self._tool_class else "factory=True"
+        return (f"ToolDefinition(name='{self.name}', {creator_repr})")

autobyteus/tools/registry/tool_registry.py

@@ -1,34 +1,32 @@
-# file: autobyteus/autobyteus/tools/registry/tool_registry.py
+# file: autobyteus/tools/registry/tool_registry.py
 import logging
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Type, TYPE_CHECKING
 
 from autobyteus.tools.registry.tool_definition import ToolDefinition
 from autobyteus.utils.singleton import SingletonMeta
-from autobyteus.tools.factory.tool_factory import ToolFactory
+from autobyteus.tools.tool_config import ToolConfig
 
+if TYPE_CHECKING:
+    from autobyteus.tools.base_tool import BaseTool
 
 logger = logging.getLogger(__name__)
 
 class ToolRegistry(metaclass=SingletonMeta):
     """
-    Manages ToolDefinitions (name, description, tool_class), populated exclusively via
-    programmatic registration. Uses ToolFactory to create tool instances.
+    Manages ToolDefinitions and creates tool instances. It can create instances
+    from a tool_class or by using a custom_factory provided in the definition.
     """
     _definitions: Dict[str, ToolDefinition] = {}
 
-    def __init__(self, tool_factory: ToolFactory):
+    def __init__(self):
         """
-        Initializes the ToolRegistry with a ToolFactory.
-
-        Args:
-            tool_factory: The ToolFactory instance used to create tool instances.
+        Initializes the ToolRegistry.
         """
-        self.tool_factory = tool_factory
-        logger.info("ToolRegistry initialized with ToolFactory.")
+        logger.info("ToolRegistry initialized.")
 
     def register_tool(self, definition: ToolDefinition):
         """
-        Registers a tool definition (name, description, tool_class) programmatically.
+        Registers a tool definition.
 
         Args:
             definition: The ToolDefinition object to register.
@@ -53,40 +51,66 @@ class ToolRegistry(metaclass=SingletonMeta):
             name: The unique name of the tool definition to retrieve.
 
         Returns:
-            The ToolDefinition object (name, description, tool_class) if found, otherwise None.
+            The ToolDefinition object if found, otherwise None.
         """
         definition = self._definitions.get(name)
         if not definition:
             logger.debug(f"Tool definition not found for name: '{name}'")
         return definition
 
-    def create_tool(self, name: str):
+    def create_tool(self, name: str, config: Optional[ToolConfig] = None) -> 'BaseTool':
         """
-        Creates a tool instance using the ToolFactory based on the tool definition.
+        Creates a tool instance using its definition, either from a factory or a class.
 
         Args:
             name: The name of the tool to create.
+            config: Optional ToolConfig with constructor parameters for class-based tools
+                    or to be passed to a custom factory.
 
         Returns:
-            The tool instance if the definition exists, otherwise None.
+            The tool instance if the definition exists.
 
         Raises:
-            ValueError: If the tool definition is not found.
+            ValueError: If the tool definition is not found or is invalid.
+            TypeError: If tool instantiation fails.
         """
         definition = self.get_tool_definition(name)
         if not definition:
             logger.error(f"Cannot create tool: No definition found for name '{name}'")
             raise ValueError(f"No tool definition found for name '{name}'")
         
-        logger.info(f"Creating tool instance for '{name}' using ToolFactory")
-        return self.tool_factory.create_tool(name)
+        try:
+            # Prefer the custom factory if it exists
+            if definition.custom_factory:
+                logger.info(f"Creating tool instance for '{name}' using its custom factory.")
+                # Pass the config to the factory. The factory can choose to use it or not.
+                tool_instance = definition.custom_factory(config)
+            
+            # Fall back to instantiating the tool_class
+            elif definition.tool_class:
+                # For class-based tools, the convention is to pass the ToolConfig object
+                # itself to the constructor under the 'config' keyword argument.
+                logger.info(f"Creating tool instance for '{name}' using class '{definition.tool_class.__name__}' and passing ToolConfig.")
+                tool_instance = definition.tool_class(config=config)
+            
+            else:
+                # This case should be prevented by ToolDefinition's validation
+                raise ValueError(f"ToolDefinition for '{name}' is invalid: missing both tool_class and custom_factory.")
+
+            logger.debug(f"Successfully created tool instance for '{name}'")
+            return tool_instance
+
+        except Exception as e:
+            creator_type = "factory" if definition.custom_factory else f"class '{definition.tool_class.__name__}'"
+            logger.error(f"Failed to create tool instance for '{name}' using {creator_type}: {e}", exc_info=True)
+            raise TypeError(f"Failed to create tool '{name}': {e}") from e
 
     def list_tools(self) -> List[ToolDefinition]:
         """
         Returns a list of all registered tool definitions.
 
         Returns:
-            A list of ToolDefinition objects (name, description, tool_class).
+            A list of ToolDefinition objects.
         """
         return list(self._definitions.values())
 
@@ -103,4 +127,4 @@ class ToolRegistry(metaclass=SingletonMeta):
         """Returns the internal dictionary of definitions."""
         return dict(ToolRegistry._definitions)
 
-default_tool_registry = ToolRegistry(tool_factory=ToolFactory())
+default_tool_registry = ToolRegistry()