tooluniverse 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

tooluniverse/__init__.py

@@ -1,30 +1,54 @@
 from importlib.metadata import version
+import os
 import warnings
 from typing import Any, Optional, List
+
 from .execute_function import ToolUniverse
 from .base_tool import BaseTool
 from .default_config import default_tool_files
+from .tool_registry import register_tool, get_tool_registry
+
+_LIGHT_IMPORT = os.getenv("TOOLUNIVERSE_LIGHT_IMPORT", "false").lower() in (
+    "true",
+    "1",
+    "yes",
+)
 
 # Version information - read from package metadata or pyproject.toml
 __version__ = version("tooluniverse")
-from .tool_registry import register_tool, get_tool_registry
+
+# Import tools with graceful fallback
+if not _LIGHT_IMPORT:
+    try:
+        from . import tools
+
+        _TOOLS_AVAILABLE = True
+    except ImportError:
+        _TOOLS_AVAILABLE = False
+        tools = None  # type: ignore
+else:
+    _TOOLS_AVAILABLE = False
+    tools = None  # type: ignore
 
 # Check if lazy loading is enabled
-# LAZY_LOADING_ENABLED = os.getenv('TOOLUNIVERSE_LAZY_LOADING', 'true').lower() in ('true', '1', 'yes')
+# LAZY_LOADING_ENABLED = os.getenv('TOOLUNIVERSE_LAZY_LOADING', 'true').lower() in (
+#     'true', '1', 'yes'
+# )
 LAZY_LOADING_ENABLED = (
     False  # LAZY LOADING DISABLED BECAUSE IT'S STILL UNDER DEVELOPMENT
 )
 
 # Import MCP functionality
-try:
-    from .mcp_integration import _patch_tooluniverse
+if not _LIGHT_IMPORT:
+    try:
+        from .mcp_integration import _patch_tooluniverse
 
-    # Automatically patch ToolUniverse with MCP methods
-    _patch_tooluniverse()
+        # Automatically patch ToolUniverse with MCP methods
+        _patch_tooluniverse()
 
-except ImportError:
-    # MCP functionality not available
-    pass
+    except ImportError:
+        # MCP functionality not available
+        pass
 
 # Import SMCP with graceful fallback and consistent signatures for type checking
 try:
@@ -150,7 +174,10 @@ MCPAutoLoaderTool: Any
 ADMETAITool: Any
 AlphaFoldRESTTool: Any
 ComposeTool: Any
-if not LAZY_LOADING_ENABLED:
+CellosaurusSearchTool: Any
+CellosaurusQueryConverterTool: Any
+CellosaurusGetCellLineInfoTool: Any
+if not _LIGHT_IMPORT and not LAZY_LOADING_ENABLED:
     # Import all tool classes immediately (old behavior) with warning suppression  # noqa: E501
     with warnings.catch_warnings():
         warnings.filterwarnings("ignore", category=DeprecationWarning)
@@ -224,6 +251,12 @@ if not LAZY_LOADING_ENABLED:
         ODPHPTopicSearch,
         ODPHPOutlinkFetch,
     )
+    from .cellosaurus_tool import (
+        CellosaurusSearchTool,
+        CellosaurusQueryConverterTool,
+        CellosaurusGetCellLineInfoTool,
+    )
+
     # Literature search tools
     from .arxiv_tool import ArXivTool
     from .crossref_tool import CrossrefTool
@@ -318,6 +351,15 @@ else:
     ODPHPMyHealthfinder = _LazyImportProxy("odphp_tool", "ODHPHPMyHealthfinder")
     ODPHPTopicSearch = _LazyImportProxy("odphp_tool", "ODPHPTopicSearch")
     ODPHPOutlinkFetch = _LazyImportProxy("odphp_tool", "ODPHPOutlinkFetch")
+    CellosaurusSearchTool = _LazyImportProxy(
+        "cellosaurus_tool", "CellosaurusSearchTool"
+    )
+    CellosaurusQueryConverterTool = _LazyImportProxy(
+        "cellosaurus_tool", "CellosaurusQueryConverterTool"
+    )
+    CellosaurusGetCellLineInfoTool = _LazyImportProxy(
+        "cellosaurus_tool", "CellosaurusGetCellLineInfoTool"
+    )
     # Literature search tools
     ArXivTool = _LazyImportProxy("arxiv_tool", "ArXivTool")
     CrossrefTool = _LazyImportProxy("crossref_tool", "CrossrefTool")
@@ -338,6 +380,7 @@ __all__ = [
     "BaseTool",
     "register_tool",
     "get_tool_registry",
+    "tools",
     "MonarchTool",
     "MonarchDiseasesForMultiplePhenoTool",
     "ClinicalTrialsSearchTool",
@@ -402,6 +445,9 @@ __all__ = [
     "ODPHPItemList",
     "ODPHPTopicSearch",
     "ODPHPOutlinkFetch",
+    "CellosaurusSearchTool",
+    "CellosaurusQueryConverterTool",
+    "CellosaurusGetCellLineInfoTool",
     # Literature search tools
     "ArXivTool",
     "CrossrefTool",

tooluniverse/admetai_tool.py

@@ -30,13 +30,15 @@ class ADMETAITool(BaseTool):
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+        # Initialize the model once during tool initialization
+        self.model = ADMETModel()
 
     def _predict(self, smiles: str) -> dict:
         """
         Gets ADMET predictions for the given smiles
         """
-        model = ADMETModel()
-        preds = model.predict(smiles=smiles)
+        # Reuse the pre-loaded model instead of creating a new one
+        preds = self.model.predict(smiles=smiles)
         return preds
 
     def run(self, arguments: dict) -> dict:
@@ -47,7 +49,8 @@ class ADMETAITool(BaseTool):
             smiles: The SMILES string(s) of the molecule(s).
 
         Returns:
-            A dictionary mapping each SMILES string to a subdictionary of selected ADMET properties and their predicted values.
+            A dictionary mapping each SMILES string to a subdictionary of
+            selected ADMET properties and their predicted values.
         """
         smiles = arguments.get("smiles", [])
         if not smiles:
@@ -65,7 +68,8 @@ class ADMETAITool(BaseTool):
             ):
                 return {"error": "No predictions could be extracted."}
 
-            # Expand columns to include _drugbank_approved_percentile columns if present
+            # Expand columns to include _drugbank_approved_percentile columns
+            # if present
             if columns is not None:
                 expanded_columns = []
                 for col in columns:

tooluniverse/agentic_tool.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Dict, List, Optional
 from .base_tool import BaseTool
 from .tool_registry import register_tool
 from .logging_config import get_logger
-from .llm_clients import AzureOpenAIClient, GeminiClient, OpenRouterClient
+from .llm_clients import AzureOpenAIClient, GeminiClient, OpenRouterClient, VLLMClient
 
 
 # Global default fallback configuration
@@ -23,6 +23,7 @@ API_KEY_ENV_VARS = {
     "CHATGPT": ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"],
     "OPENROUTER": ["OPENROUTER_API_KEY"],
     "GEMINI": ["GEMINI_API_KEY"],
+    "VLLM": ["VLLM_SERVER_URL"],
 }
 
 
@@ -201,7 +202,9 @@ class AgenticTool(BaseTool):
             f"Tool '{self.name}' failed to initialize with all available APIs"
         )
 
-    def _try_api(self, api_type: str, model_id: str) -> bool:
+    def _try_api(
+        self, api_type: str, model_id: str, server_url: Optional[str] = None
+    ) -> bool:
         """Try to initialize a specific API and model."""
         try:
             if api_type == "CHATGPT":
@@ -210,6 +213,12 @@ class AgenticTool(BaseTool):
                 self._llm_client = OpenRouterClient(model_id, self.logger)
             elif api_type == "GEMINI":
                 self._llm_client = GeminiClient(model_id, self.logger)
+            elif api_type == "VLLM":
+                if not server_url:
+                    server_url = os.getenv("VLLM_SERVER_URL")
+                if not server_url:
+                    raise ValueError("VLLM_SERVER_URL environment variable not set")
+                self._llm_client = VLLMClient(model_id, server_url, self.logger)
             else:
                 raise ValueError(f"Unsupported API type: {api_type}")
 
@@ -243,7 +252,7 @@ class AgenticTool(BaseTool):
 
     # ------------------------------------------------------------------ LLM utilities -----------
     def _validate_model_config(self):
-        supported_api_types = ["CHATGPT", "OPENROUTER", "GEMINI"]
+        supported_api_types = ["CHATGPT", "OPENROUTER", "GEMINI", "VLLM"]
         if self._api_type not in supported_api_types:
             raise ValueError(
                 f"Unsupported API type: {self._api_type}. Supported types: {supported_api_types}"
@@ -415,7 +424,29 @@ class AgenticTool(BaseTool):
                     },
                 }
             else:
-                return f"error: {str(e)} error_type: {type(e).__name__}"
+                from .utils import format_error_response
+
+                return format_error_response(
+                    e,
+                    self.name,
+                    {
+                        "prompt_used": (
+                            formatted_prompt
+                            if "formatted_prompt" in locals()
+                            else "Failed to format prompt"
+                        ),
+                        "input_arguments": {
+                            arg: arguments.get(arg) for arg in self._input_arguments
+                        },
+                        "model_info": {
+                            "api_type": self._api_type,
+                            "model_id": self._model_id,
+                            "temperature": self._temperature,
+                            "max_new_tokens": self._max_new_tokens,
+                        },
+                        "execution_time_seconds": execution_time,
+                    },
+                )
 
     @staticmethod
     def _iter_chunks(text: str, size: int = 800):
@@ -518,6 +549,11 @@ class AgenticTool(BaseTool):
                 self._llm_client = OpenRouterClient(self._model_id, self.logger)
             elif self._api_type == "GEMINI":
                 self._llm_client = GeminiClient(self._gemini_model_id, self.logger)
+            elif self._api_type == "VLLM":
+                server_url = os.getenv("VLLM_SERVER_URL")
+                if not server_url:
+                    raise ValueError("VLLM_SERVER_URL environment variable not set")
+                self._llm_client = VLLMClient(self._model_id, server_url, self.logger)
             else:
                 raise ValueError(f"Unsupported API type: {self._api_type}")
 

tooluniverse/arxiv_tool.py

@@ -83,18 +83,14 @@ class ArXivTool(BaseTool):
                 link = link_el.get("href")
             else:
                 link = entry.findtext("atom:id", default="", namespaces=ns)
-            published = entry.findtext(
-                "atom:published", default="", namespaces=ns
-            )
+            published = entry.findtext("atom:published", default="", namespaces=ns)
             updated = entry.findtext("atom:updated", default="", namespaces=ns)
             authors = [
                 a.findtext("atom:name", default="", namespaces=ns)
                 for a in entry.findall("atom:author", ns)
             ]
             primary_category = ""
-            cat_el = entry.find(
-                "{http://arxiv.org/schemas/atom}primary_category"
-            )
+            cat_el = entry.find("{http://arxiv.org/schemas/atom}primary_category")
             if cat_el is not None:
                 primary_category = cat_el.get("term", "")
 

tooluniverse/base_tool.py

@@ -1,28 +1,27 @@
 from .utils import extract_function_call_json, evaluate_function_call
+from .exceptions import (
+    ToolError,
+    ToolValidationError,
+    ToolAuthError,
+    ToolRateLimitError,
+    ToolUnavailableError,
+    ToolConfigError,
+    ToolDependencyError,
+    ToolServerError,
+)
 import json
 from pathlib import Path
-from typing import no_type_check
-
-
-class ToolExecutionError(Exception):
-    """Base exception for tool execution errors."""
-
-
-class ValidationError(Exception):
-    """Exception raised when input validation fails."""
-
-
-class AuthenticationError(Exception):
-    """Exception raised when authentication fails."""
-
-
-class RateLimitError(Exception):
-    """Exception raised when API rate limit is exceeded."""
+from typing import no_type_check, Optional, Dict, Any
+import hashlib
+import inspect
 
 
 class BaseTool:
+    STATIC_CACHE_VERSION = "1"
+
     def __init__(self, tool_config):
         self.tool_config = self._apply_defaults(tool_config)
+        self._cached_version_hash: Optional[str] = None
 
     @classmethod
     def get_default_config_file(cls):
@@ -122,12 +121,26 @@ class BaseTool:
         return merged_config
 
     @no_type_check
-    def run(self, arguments=None):
+    def run(self, arguments=None, stream_callback=None, use_cache=False, validate=True):
         """Execute the tool.
 
         The default BaseTool implementation accepts an optional arguments
         mapping to align with most concrete tool implementations which expect
         a dictionary of inputs.
+
+        Args:
+            arguments (dict, optional): Tool-specific arguments
+            stream_callback (callable, optional): Callback for streaming responses
+            use_cache (bool, optional): Whether result caching is enabled
+            validate (bool, optional): Whether parameter validation was performed
+
+        Note:
+            These additional parameters (stream_callback, use_cache, validate) are
+            passed from run_one_function() to provide context about the execution.
+            Tools can use these for optimization or special handling.
+
+            For backward compatibility, tools that don't accept these parameters
+            will still work - they will only receive the arguments parameter.
         """
 
     def check_function_call(self, function_call_json):
@@ -144,12 +157,184 @@ class BaseTool:
         Returns:
         list: List of required parameters for the given endpoint.
         """
-        required_params = []
-        parameters = self.tool_config.get("parameter", {}).get("properties", {})
+        schema = self.tool_config.get("parameter", {})
+        required_params = schema.get("required", [])
+        return required_params
+
+    def validate_parameters(self, arguments: Dict[str, Any]) -> Optional[ToolError]:
+        """
+        Validate parameters against tool schema.
 
-        # Check each parameter to see if it is required
-        for param, details in parameters.items():
-            if details.get("required", False):
-                required_params.append(param.lower())
+        This method provides standard parameter validation using jsonschema.
+        Subclasses can override this method to implement custom validation
+        logic.
 
-        return required_params
+        Args:
+            arguments: Dictionary of arguments to validate
+
+        Returns:
+            ToolError if validation fails, None if validation passes
+        """
+        schema = self.tool_config.get("parameter", {})
+
+        if not schema:
+            return None  # No schema to validate against
+
+        try:
+            import jsonschema
+
+            jsonschema.validate(arguments, schema)
+            return None
+        except jsonschema.ValidationError as e:
+            return ToolValidationError(
+                f"Parameter validation failed: {e.message}",
+                details={
+                    "validation_error": str(e),
+                    "path": list(e.absolute_path) if e.absolute_path else [],
+                    "schema": schema,
+                },
+            )
+        except Exception as e:
+            return ToolValidationError(f"Validation error: {str(e)}")
+
+    def handle_error(self, exception: Exception) -> ToolError:
+        """
+        Classify a raw exception into a structured ToolError.
+
+        This method provides standard error classification. Subclasses can
+        override this method to implement custom error handling logic.
+
+        Args:
+            exception: The raw exception to classify
+
+        Returns:
+            Structured ToolError instance
+        """
+        error_str = str(exception).lower()
+
+        if any(
+            keyword in error_str
+            for keyword in ["auth", "unauthorized", "401", "403", "api key", "token"]
+        ):
+            return ToolAuthError(f"Authentication failed: {exception}")
+        elif any(
+            keyword in error_str
+            for keyword in ["rate limit", "429", "quota", "limit exceeded"]
+        ):
+            return ToolRateLimitError(f"Rate limit exceeded: {exception}")
+        elif any(
+            keyword in error_str
+            for keyword in [
+                "unavailable",
+                "timeout",
+                "connection",
+                "network",
+                "not found",
+                "404",
+            ]
+        ):
+            return ToolUnavailableError(f"Tool unavailable: {exception}")
+        elif any(
+            keyword in error_str
+            for keyword in ["validation", "invalid", "schema", "parameter"]
+        ):
+            return ToolValidationError(f"Validation error: {exception}")
+        elif any(
+            keyword in error_str for keyword in ["config", "configuration", "setup"]
+        ):
+            return ToolConfigError(f"Configuration error: {exception}")
+        elif any(
+            keyword in error_str
+            for keyword in ["import", "module", "dependency", "package"]
+        ):
+            return ToolDependencyError(f"Dependency error: {exception}")
+        else:
+            return ToolServerError(f"Unexpected error: {exception}")
+
+    def get_cache_key(self, arguments: Dict[str, Any]) -> str:
+        """
+        Generate a cache key for this tool call.
+
+        This method provides standard cache key generation. Subclasses can
+        override this method to implement custom caching logic.
+
+        Args:
+            arguments: Dictionary of arguments for the tool call
+
+        Returns:
+            String cache key
+        """
+        # Include tool name and arguments in cache key
+        cache_data = {
+            "tool_name": self.tool_config.get("name", self.__class__.__name__),
+            "arguments": arguments,
+        }
+        serialized = json.dumps(cache_data, sort_keys=True)
+        return hashlib.md5(serialized.encode()).hexdigest()
+
+    def supports_streaming(self) -> bool:
+        """
+        Check if this tool supports streaming responses.
+
+        Returns:
+            True if tool supports streaming, False otherwise
+        """
+        return self.tool_config.get("supports_streaming", False)
+
+    def supports_caching(self) -> bool:
+        """
+        Check if this tool's results can be cached.
+
+        Returns:
+            True if tool results can be cached, False otherwise
+        """
+        return self.tool_config.get("cacheable", True)
+
+    def get_cache_namespace(self) -> str:
+        """Return cache namespace identifier for this tool."""
+        return self.tool_config.get("name", self.__class__.__name__)
+
+    def get_cache_version(self) -> str:
+        """Return a stable cache version fingerprint for this tool."""
+        if self._cached_version_hash:
+            return self._cached_version_hash
+
+        hasher = hashlib.sha256()
+        hasher.update(self.STATIC_CACHE_VERSION.encode("utf-8"))
+
+        try:
+            source = inspect.getsource(self.__class__)
+            hasher.update(source.encode("utf-8"))
+        except (OSError, TypeError):
+            pass
+
+        try:
+            schema = json.dumps(self.tool_config.get("parameter", {}), sort_keys=True)
+            hasher.update(schema.encode("utf-8"))
+        except (TypeError, ValueError):
+            pass
+
+        self._cached_version_hash = hasher.hexdigest()[:16]
+        return self._cached_version_hash
+
+    def get_cache_ttl(self, result: Any = None) -> Optional[int]:
+        """Return TTL (seconds) for cached results; None means no expiration."""
+        ttl = self.tool_config.get("cache_ttl")
+        return int(ttl) if ttl is not None else None
+
+    def get_tool_info(self) -> Dict[str, Any]:
+        """
+        Get comprehensive information about this tool.
+
+        Returns:
+            Dictionary containing tool metadata
+        """
+        return {
+            "name": self.tool_config.get("name", self.__class__.__name__),
+            "description": self.tool_config.get("description", ""),
+            "supports_streaming": self.supports_streaming(),
+            "supports_caching": self.supports_caching(),
+            "required_parameters": self.get_required_parameters(),
+            "parameter_schema": self.tool_config.get("parameter", {}),
+            "tool_type": self.__class__.__name__,
+        }

tooluniverse/biogrid_tool.py

@@ -0,0 +1,118 @@
+"""
+BioGRID Database REST API Tool
+
+This tool provides access to protein and genetic interaction data from the BioGRID database.
+BioGRID is a comprehensive database of physical and genetic interactions.
+"""
+
+import requests
+from typing import Dict, Any, List
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+BIOGRID_BASE_URL = "https://webservice.thebiogrid.org"
+
+
+@register_tool("BioGRIDRESTTool")
+class BioGRIDRESTTool(BaseTool):
+    """
+    BioGRID Database REST API tool.
+    Generic wrapper for BioGRID API endpoints defined in ppi_tools.json.
+    """
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        fields = tool_config.get("fields", {})
+        parameter = tool_config.get("parameter", {})
+
+        self.endpoint_template: str = fields.get("endpoint", "/interactions/")
+        self.required: List[str] = parameter.get("required", [])
+        self.output_format: str = fields.get("return_format", "JSON")
+
+    def _build_url(self, arguments: Dict[str, Any]) -> str | Dict[str, Any]:
+        """Build URL for BioGRID API request."""
+        url_path = self.endpoint_template
+        return BIOGRID_BASE_URL + url_path
+
+    def _build_params(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Build parameters for BioGRID API request."""
+        params = {"format": "json", "interSpeciesExcluded": "false"}
+
+        # Check for API key
+        api_key = arguments.get("api_key") or arguments.get("accesskey")
+        if not api_key:
+            # Try to get from environment variable
+            import os
+
+            api_key = os.getenv("BIOGRID_API_KEY")
+
+        if not api_key:
+            raise ValueError(
+                "BioGRID API key is required. Please provide 'api_key' parameter "
+                "or set BIOGRID_API_KEY environment variable. "
+                "Register at: https://webservice.thebiogrid.org/"
+            )
+
+        params["accesskey"] = api_key
+
+        # Map gene names to BioGRID format
+        if "gene_names" in arguments:
+            gene_names = arguments["gene_names"]
+            if isinstance(gene_names, list):
+                params["geneList"] = "|".join(gene_names)
+            else:
+                params["geneList"] = str(gene_names)
+
+        # Add other parameters
+        if "organism" in arguments:
+            # Convert organism name to taxonomy ID
+            organism = arguments["organism"]
+            if organism.lower() == "homo sapiens":
+                params["organism"] = 9606
+            elif organism.lower() == "mus musculus":
+                params["organism"] = 10090
+            else:
+                params["organism"] = organism
+
+        if "interaction_type" in arguments:
+            interaction_type = arguments["interaction_type"]
+            if interaction_type == "physical":
+                params["evidenceList"] = "physical"
+            elif interaction_type == "genetic":
+                params["evidenceList"] = "genetic"
+            # "both" means no evidence filter
+
+        if "limit" in arguments:
+            params["max"] = arguments["limit"]
+
+        return params
+
+    def _make_request(self, url: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Perform a GET request and handle common errors."""
+        try:
+            response = requests.get(url, params=params, timeout=30)
+            response.raise_for_status()
+
+            if self.output_format == "JSON":
+                return response.json()
+            else:
+                return {"data": response.text}
+
+        except requests.exceptions.RequestException as e:
+            return {"error": f"Request failed: {str(e)}"}
+        except Exception as e:
+            return {"error": f"Unexpected error: {str(e)}"}
+
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute the tool with given arguments."""
+        # Validate required parameters
+        for param in self.required:
+            if param not in arguments:
+                return {"error": f"Missing required parameter: {param}"}
+
+        url = self._build_url(arguments)
+        if isinstance(url, dict) and "error" in url:
+            return url
+
+        params = self._build_params(arguments)
+        return self._make_request(url, params)