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

autobyteus/tools/registry/tool_definition.py

@@ -20,21 +20,26 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# A sentinel object to differentiate between a cached value of None and an unset cache.
+_CACHE_NOT_SET = object()
+
 class ToolDefinition:
     """
     Represents the definition of a tool, containing its metadata and the means
     to create an instance. It can generate provider-agnostic usage information on demand.
+    This class now supports dynamic schema generation with caching.
     """
     def __init__(self,
                  name: str,
                  description: str,
-                 argument_schema: Optional['ParameterSchema'],
                  origin: ToolOrigin,
                  category: str,
-                 config_schema: Optional['ParameterSchema'] = None,
+                 argument_schema_provider: Callable[[], Optional['ParameterSchema']],
+                 config_schema_provider: Callable[[], Optional['ParameterSchema']],
                  tool_class: Optional[Type['BaseTool']] = None,
                  custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None,
-                 metadata: Optional[Dict[str, Any]] = None):
+                 metadata: Optional[Dict[str, Any]] = None,
+                 description_provider: Optional[Callable[[], str]] = None):
         """
         Initializes the ToolDefinition.
         """
@@ -53,10 +58,10 @@ class ToolDefinition:
         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.")
+        if not callable(argument_schema_provider):
+             raise TypeError(f"ToolDefinition '{name}' requires a callable for 'argument_schema_provider'.")
+        if not callable(config_schema_provider):
+             raise TypeError(f"ToolDefinition '{name}' requires a callable for 'config_schema_provider'.")
         if not isinstance(origin, ToolOrigin):
             raise TypeError(f"ToolDefinition '{name}' requires a ToolOrigin for 'origin'. Got {type(origin)}")
         
@@ -65,14 +70,31 @@ class ToolDefinition:
             raise ValueError(f"ToolDefinition '{name}' with origin MCP must provide a 'mcp_server_id' in its metadata.")
 
         self._name = name
+        # Prefer an explicit description provider, otherwise derive one from the tool class when available.
+        if description_provider is not None and not callable(description_provider):
+            raise TypeError(f"ToolDefinition '{name}' requires a callable for 'description_provider' if provided.")
+
+        if description_provider:
+            self._description_provider = description_provider
+        elif tool_class is not None and hasattr(tool_class, "get_description") and callable(getattr(tool_class, "get_description")):
+            # Use the tool class' get_description as a dynamic provider by default.
+            self._description_provider = tool_class.get_description
+        else:
+            # Fall back to a static description provider.
+            self._description_provider = lambda: description
+
         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
         self._origin = origin
         self._category = category
         self._metadata = metadata or {}
+
+        # Store schema providers and initialize caches
+        self._argument_schema_provider = argument_schema_provider
+        self._config_schema_provider = config_schema_provider
+        self._cached_argument_schema: Any = _CACHE_NOT_SET
+        self._cached_config_schema: Any = _CACHE_NOT_SET
         
         logger.debug(f"ToolDefinition created for tool '{self.name}'.")
 
@@ -85,16 +107,85 @@ class ToolDefinition:
     def tool_class(self) -> Optional[Type['BaseTool']]: return self._tool_class
     @property
     def custom_factory(self) -> Optional[Callable[['ToolConfig'], 'BaseTool']]: return self._custom_factory
+    
     @property
-    def argument_schema(self) -> Optional['ParameterSchema']: return self._argument_schema
+    def argument_schema(self) -> Optional['ParameterSchema']:
+        """On-demand schema generation and caching for argument_schema."""
+        if self._cached_argument_schema is _CACHE_NOT_SET:
+            logger.debug(f"Cache miss for argument_schema of tool '{self.name}'. Generating...")
+            try:
+                self._cached_argument_schema = self._argument_schema_provider()
+            except Exception as e:
+                logger.warning(
+                    f"Failed to generate argument schema for tool '{self.name}' due to an error. "
+                    f"The tool will have no arguments. Error: {e}",
+                    exc_info=True
+                )
+                self._cached_argument_schema = None
+        return self._cached_argument_schema
+
     @property
-    def config_schema(self) -> Optional['ParameterSchema']: return self._config_schema
+    def config_schema(self) -> Optional['ParameterSchema']:
+        """On-demand schema generation and caching for config_schema."""
+        if self._cached_config_schema is _CACHE_NOT_SET:
+            logger.debug(f"Cache miss for config_schema of tool '{self.name}'. Generating...")
+            try:
+                self._cached_config_schema = self._config_schema_provider()
+            except Exception as e:
+                logger.warning(
+                    f"Failed to generate config schema for tool '{self.name}' due to an error. "
+                    f"The tool will have no config. Error: {e}",
+                    exc_info=True
+                )
+                self._cached_config_schema = None
+        return self._cached_config_schema
+        
     @property
     def origin(self) -> ToolOrigin: return self._origin
     @property
     def category(self) -> str: return self._category
     @property
     def metadata(self) -> Dict[str, Any]: return self._metadata
+
+    def reload_cached_schema(self) -> None:
+        """
+        Actively re-generates the schemas from their providers and updates the cache.
+        Also refreshes the description if a provider is available. This is an eager operation.
+        """
+        logger.info(f"Eagerly reloading schema cache for tool '{self.name}'.")
+        self._reload_description()
+        self._cached_argument_schema = _CACHE_NOT_SET
+        self._cached_config_schema = _CACHE_NOT_SET
+        # The schemas will be regenerated on the next property access.
+        # To make it fully eager, we can trigger the access here.
+        _ = self.argument_schema
+        _ = self.config_schema
+
+    def _reload_description(self) -> None:
+        """
+        Refreshes the cached description using the provider if available.
+        """
+        if not self._description_provider:
+            return
+        try:
+            new_description = self._description_provider()
+            if isinstance(new_description, str) and new_description:
+                if new_description != self._description:
+                    logger.info(
+                        f"Description for tool '{self.name}' updated during reload."
+                    )
+                self._description = new_description
+            else:
+                logger.warning(
+                    f"Description provider for tool '{self.name}' returned an invalid value. "
+                    "Keeping existing description."
+                )
+        except Exception as exc:
+            logger.warning(
+                f"Failed to refresh description for tool '{self.name}' during reload: {exc}. "
+                "Keeping existing description.",
+                exc_info=True
+            )
     
     # --- Convenience Schema/Example Generation API (using default formatters) ---
     def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:
@@ -132,14 +223,17 @@ class ToolDefinition:
     # --- Other methods ---
     @property
     def has_instantiation_config(self) -> bool:
-        return self._config_schema is not None and len(self._config_schema) > 0
+        # Use the property to access the schema
+        return self.config_schema is not None and len(self.config_schema) > 0
 
     def validate_instantiation_config(self, config_data: Dict[str, Any]) -> tuple[bool, TypingList[str]]:
-        if not self._config_schema:
+        # Use the property to access the schema
+        schema = self.config_schema
+        if not 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)
+        return schema.validate_config(config_data)
 
     def __repr__(self) -> str:
         creator_repr = f"class='{self._tool_class.__name__}'" if self._tool_class else "factory=True"

autobyteus/tools/registry/tool_registry.py

@@ -63,6 +63,35 @@ class ToolRegistry(metaclass=SingletonMeta):
             logger.warning(f"Attempted to unregister tool '{name}', but it was not found in the registry.")
             return False
 
+    def reload_tool_schema(self, name: str) -> bool:
+        """
+        Actively reloads the schema for a specific tool by calling its schema provider.
+
+        Args:
+            name: The unique name of the tool to reload the schema for.
+
+        Returns:
+            True if the tool was found and its schema was reloaded, False otherwise.
+        """
+        definition = self.get_tool_definition(name)
+        if definition:
+            definition.reload_cached_schema()
+            return True
+        else:
+            logger.warning(f"Attempted to reload schema for tool '{name}', but it was not found in the registry.")
+            return False
+
+    def reload_all_tool_schemas(self) -> None:
+        """
+        Actively reloads the schemas for all registered tools.
+        """
+        logger.info("Eagerly reloading schemas for all registered tools...")
+        count = 0
+        for definition in self._definitions.values():
+            definition.reload_cached_schema()
+            count += 1
+        logger.info(f"Schemas for {count} tool(s) have been reloaded.")
+
     def get_tool_definition(self, name: str) -> Optional[ToolDefinition]:
         """
         Retrieves the definition for a specific tool name.

autobyteus/tools/search/__init__.py

@@ -0,0 +1,17 @@
+from .providers import SearchProvider
+from .base_strategy import SearchStrategy
+from .serper_strategy import SerperSearchStrategy
+from .serpapi_strategy import SerpApiSearchStrategy
+from .google_cse_strategy import GoogleCSESearchStrategy
+from .client import SearchClient
+from .factory import SearchClientFactory
+
+__all__ = [
+    "SearchProvider",
+    "SearchStrategy",
+    "SerperSearchStrategy",
+    "SerpApiSearchStrategy",
+    "GoogleCSESearchStrategy",
+    "SearchClient",
+    "SearchClientFactory",
+]

autobyteus/tools/search/base_strategy.py

@@ -0,0 +1,35 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+
+class SearchStrategy(ABC):
+    """
+    Abstract base class for a search provider strategy.
+    Defines the common interface for performing a search and formatting results.
+    """
+
+    @abstractmethod
+    async def search(self, query: str, num_results: int) -> str:
+        """
+        Executes a search query against a specific provider.
+
+        Args:
+            query: The search query string.
+            num_results: The desired number of organic search results.
+
+        Returns:
+            A formatted string summarizing the search results, suitable for an LLM.
+        """
+        pass
+
+    @abstractmethod
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """
+        Formats the raw JSON response from the search API into a clean string.
+
+        Args:
+            data: The JSON data from the API response.
+
+        Returns:
+            A formatted summary string.
+        """
+        pass

autobyteus/tools/search/client.py

@@ -0,0 +1,24 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SearchClient:
+    """
+    A client that uses a configured search strategy to perform searches.
+    This acts as the 'Context' in the Strategy pattern.
+    """
+    def __init__(self, strategy: 'SearchStrategy'):
+        if not strategy:
+            raise ValueError("SearchClient must be initialized with a valid SearchStrategy.")
+        self._strategy = strategy
+        logger.debug(f"SearchClient initialized with strategy: {type(strategy).__name__}")
+
+    async def search(self, query: str, num_results: int) -> str:
+        """
+        Delegates the search operation to the configured strategy.
+        """
+        return await self._strategy.search(query, num_results)

autobyteus/tools/search/factory.py

@@ -0,0 +1,81 @@
+import os
+import logging
+from typing import Optional
+
+from autobyteus.utils.singleton import SingletonMeta
+from .providers import SearchProvider
+from .client import SearchClient
+from .serper_strategy import SerperSearchStrategy
+from .serpapi_strategy import SerpApiSearchStrategy
+from .google_cse_strategy import GoogleCSESearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SearchClientFactory(metaclass=SingletonMeta):
+    """
+    Factory for creating a SearchClient with the appropriate strategy
+    based on environment variable configuration.
+    """
+    _instance: Optional[SearchClient] = None
+
+    def create_search_client(self) -> SearchClient:
+        """
+        Creates and returns a singleton instance of the SearchClient, configured
+        with the appropriate search strategy.
+        """
+        if self._instance:
+            return self._instance
+
+        provider_name = os.getenv("DEFAULT_SEARCH_PROVIDER", "").lower()
+        
+        serper_key = os.getenv("SERPER_API_KEY")
+        serpapi_key = os.getenv("SERPAPI_API_KEY")
+        google_api_key = os.getenv("GOOGLE_CSE_API_KEY")
+        google_cse_id = os.getenv("GOOGLE_CSE_ID")
+        
+        is_serper_configured = bool(serper_key)
+        is_serpapi_configured = bool(serpapi_key)
+        is_google_cse_configured = bool(google_api_key and google_cse_id)
+        
+        strategy = None
+
+        if provider_name == SearchProvider.GOOGLE_CSE:
+            if is_google_cse_configured:
+                logger.info("DEFAULT_SEARCH_PROVIDER is 'google_cse', using Google CSE strategy.")
+                strategy = GoogleCSESearchStrategy()
+            else:
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'google_cse', but Google CSE is not configured. "
+                                 "Set GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID.")
+
+        elif provider_name == SearchProvider.SERPAPI:
+            if is_serpapi_configured:
+                logger.info("DEFAULT_SEARCH_PROVIDER is 'serpapi', using SerpApi strategy.")
+                strategy = SerpApiSearchStrategy()
+            else:
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'serpapi', but SerpApi is not configured. "
+                                 "Set SERPAPI_API_KEY.")
+        
+        # Default to Serper if explicitly set, or if not set and Serper is available.
+        # This handles the case where multiple providers are configured but no provider is specified.
+        elif provider_name == SearchProvider.SERPER or is_serper_configured:
+            if is_serper_configured:
+                logger.info("Using Serper search strategy (either as default or as first fallback).")
+                strategy = SerperSearchStrategy()
+            else:
+                # This branch is only taken if provider_name is 'serper' but it's not configured.
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'serper', but Serper is not configured. Set SERPER_API_KEY.")
+
+        elif is_serpapi_configured:
+            logger.info("Serper not configured, falling back to available SerpApi strategy.")
+            strategy = SerpApiSearchStrategy()
+
+        elif is_google_cse_configured:
+            logger.info("Neither Serper nor SerpApi are configured, falling back to available Google CSE strategy.")
+            strategy = GoogleCSESearchStrategy()
+        
+        else:
+            raise ValueError("No search provider is configured. Please set either SERPER_API_KEY, SERPAPI_API_KEY, "
+                             "or both GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID environment variables.")
+
+        self._instance = SearchClient(strategy=strategy)
+        return self._instance

autobyteus/tools/search/google_cse_strategy.py

@@ -0,0 +1,68 @@
+import os
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class GoogleCSESearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the official Google Custom Search Engine (CSE) API.
+    """
+    API_URL = "https://www.googleapis.com/customsearch/v1"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("GOOGLE_CSE_API_KEY")
+        self.cse_id: Optional[str] = os.getenv("GOOGLE_CSE_ID")
+        if not self.api_key or not self.cse_id:
+            raise ValueError(
+                "GoogleCSESearchStrategy requires both 'GOOGLE_CSE_API_KEY' and 'GOOGLE_CSE_ID' environment variables to be set."
+            )
+        logger.debug("GoogleCSESearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from Google CSE API into a clean string for an LLM."""
+        if "items" not in data or not data["items"]:
+            return "No relevant information found for the query via Google CSE."
+
+        results = data["items"]
+        results_str = "\n".join(
+            f"{i+1}. {result.get('title', 'No Title')}\n"
+            f"   Link: {result.get('link', 'No Link')}\n"
+            f"   Snippet: {result.get('snippet', 'No Snippet')}"
+            for i, result in enumerate(results)
+        )
+        
+        return f"Search Results:\n{results_str}"
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with Google CSE strategy for query: '{query}'")
+        
+        params = {
+            'key': self.api_key,
+            'cx': self.cse_id,
+            'q': query,
+            'num': num_results
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self.API_URL, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"Google CSE API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"Google CSE API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during Google CSE API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during Google CSE search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in Google CSE strategy: {e}", exc_info=True)
+            raise

autobyteus/tools/search/providers.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+class SearchProvider(str, Enum):
+    """Enumerates the supported search providers."""
+    SERPER = "serper"
+    GOOGLE_CSE = "google_cse"
+    SERPAPI = "serpapi"
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/tools/search/serpapi_strategy.py

@@ -0,0 +1,65 @@
+import os
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SerpApiSearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the SerpApi.com API.
+    """
+    API_URL = "https://serpapi.com/search.json"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("SERPAPI_API_KEY")
+        if not self.api_key:
+            raise ValueError("SerpApiSearchStrategy requires the 'SERPAPI_API_KEY' environment variable to be set.")
+        logger.debug("SerpApiSearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from SerpApi into a clean string for an LLM."""
+        if "organic_results" not in data or not data["organic_results"]:
+            return "No relevant information found for the query via SerpApi."
+
+        results = data["organic_results"]
+        results_str = "\n".join(
+            f"{i+1}. {result.get('title', 'No Title')}\n"
+            f"   Link: {result.get('link', 'No Link')}\n"
+            f"   Snippet: {result.get('snippet', 'No Snippet')}"
+            for i, result in enumerate(results)
+        )
+        
+        return f"Search Results:\n{results_str}"
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with SerpApi strategy for query: '{query}'")
+        
+        params = {
+            'api_key': self.api_key,
+            'engine': 'google',
+            'q': query,
+            'num': num_results
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self.API_URL, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"SerpApi API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"SerpApi API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during SerpApi API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during SerpApi search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in SerpApi strategy: {e}", exc_info=True)
+            raise

autobyteus/tools/search/serper_strategy.py

@@ -0,0 +1,87 @@
+import os
+import json
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SerperSearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the Serper.dev API.
+    """
+    API_URL = "https://google.serper.dev/search"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("SERPER_API_KEY")
+        if not self.api_key:
+            raise ValueError("SerperSearchStrategy requires the 'SERPER_API_KEY' environment variable to be set.")
+        logger.debug("SerperSearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from Serper into a clean string for an LLM."""
+        summary_parts = []
+        
+        # 1. Answer Box (most important for direct questions)
+        if "answerBox" in data:
+            answer_box = data["answerBox"]
+            title = answer_box.get("title", "")
+            snippet = answer_box.get("snippet") or answer_box.get("answer")
+            summary_parts.append(f"Direct Answer for '{title}':\n{snippet}")
+
+        # 2. Knowledge Graph (for entity information)
+        if "knowledgeGraph" in data:
+            kg = data["knowledgeGraph"]
+            title = kg.get("title", "")
+            description = kg.get("description")
+            summary_parts.append(f"Summary for '{title}':\n{description}")
+
+        # 3. Organic Results (the main search links)
+        if "organic" in data and data["organic"]:
+            organic_results = data["organic"]
+            results_str = "\n".join(
+                f"{i+1}. {result.get('title', 'No Title')}\n"
+                f"   Link: {result.get('link', 'No Link')}\n"
+                f"   Snippet: {result.get('snippet', 'No Snippet')}"
+                for i, result in enumerate(organic_results)
+            )
+            summary_parts.append(f"Search Results:\n{results_str}")
+        
+        if not summary_parts:
+            return "No relevant information found for the query via Serper."
+
+        return "\n\n---\n\n".join(summary_parts)
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with Serper strategy for query: '{query}'")
+        
+        headers = {
+            'X-API-KEY': self.api_key,
+            'Content-Type': 'application/json'
+        }
+        payload = json.dumps({
+            "q": query,
+            "num": num_results
+        })
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(self.API_URL, headers=headers, data=payload) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"Serper API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"Serper API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during Serper API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during Serper search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in Serper strategy: {e}", exc_info=True)
+            raise