tooluniverse 1.0.5__py3-none-any.whl → 1.0.7__py3-none-any.whl

tooluniverse/__init__.py

@@ -9,6 +9,15 @@ from .default_config import default_tool_files
 __version__ = version("tooluniverse")
 from .tool_registry import register_tool, get_tool_registry
 
+# Import tools with graceful fallback
+try:
+    from . import tools
+
+    _TOOLS_AVAILABLE = True
+except ImportError:
+    _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 = (
@@ -150,6 +159,9 @@ MCPAutoLoaderTool: Any
 ADMETAITool: Any
 AlphaFoldRESTTool: Any
 ComposeTool: Any
+CellosaurusSearchTool: Any
+CellosaurusQueryConverterTool: Any
+CellosaurusGetCellLineInfoTool: Any
 if not LAZY_LOADING_ENABLED:
     # Import all tool classes immediately (old behavior) with warning suppression  # noqa: E501
     with warnings.catch_warnings():
@@ -224,6 +236,25 @@ 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
+    from .dblp_tool import DBLPTool
+    from .pubmed_tool import PubMedTool
+    from .doaj_tool import DOAJTool
+    from .unpaywall_tool import UnpaywallTool
+    from .biorxiv_tool import BioRxivTool
+    from .medrxiv_tool import MedRxivTool
+    from .hal_tool import HALTool
+    from .core_tool import CoreTool
+    from .pmc_tool import PMCTool
+    from .zenodo_tool import ZenodoTool
 else:
     # With lazy loading, create lazy import proxies that import modules only when accessed
     MonarchTool = _LazyImportProxy("restful_tool", "MonarchTool")
@@ -305,6 +336,28 @@ 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")
+    DBLPTool = _LazyImportProxy("dblp_tool", "DBLPTool")
+    PubMedTool = _LazyImportProxy("pubmed_tool", "PubMedTool")
+    DOAJTool = _LazyImportProxy("doaj_tool", "DOAJTool")
+    UnpaywallTool = _LazyImportProxy("unpaywall_tool", "UnpaywallTool")
+    BioRxivTool = _LazyImportProxy("biorxiv_tool", "BioRxivTool")
+    MedRxivTool = _LazyImportProxy("medrxiv_tool", "MedRxivTool")
+    HALTool = _LazyImportProxy("hal_tool", "HALTool")
+    CoreTool = _LazyImportProxy("core_tool", "CoreTool")
+    PMCTool = _LazyImportProxy("pmc_tool", "PMCTool")
+    ZenodoTool = _LazyImportProxy("zenodo_tool", "ZenodoTool")
 
 __all__ = [
     "__version__",
@@ -312,6 +365,7 @@ __all__ = [
     "BaseTool",
     "register_tool",
     "get_tool_registry",
+    "tools",
     "MonarchTool",
     "MonarchDiseasesForMultiplePhenoTool",
     "ClinicalTrialsSearchTool",
@@ -376,4 +430,20 @@ __all__ = [
     "ODPHPItemList",
     "ODPHPTopicSearch",
     "ODPHPOutlinkFetch",
+    "CellosaurusSearchTool",
+    "CellosaurusQueryConverterTool",
+    "CellosaurusGetCellLineInfoTool",
+    # Literature search tools
+    "ArXivTool",
+    "CrossrefTool",
+    "DBLPTool",
+    "PubMedTool",
+    "DOAJTool",
+    "UnpaywallTool",
+    "BioRxivTool",
+    "MedRxivTool",
+    "HALTool",
+    "CoreTool",
+    "PMCTool",
+    "ZenodoTool",
 ]

tooluniverse/agentic_tool.py

@@ -3,12 +3,12 @@ from __future__ import annotations
 import os
 import json
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+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"],
 }
 
 
@@ -30,6 +31,8 @@ API_KEY_ENV_VARS = {
 class AgenticTool(BaseTool):
     """Generic wrapper around LLM prompting supporting JSON-defined configs with prompts and input arguments."""
 
+    STREAM_FLAG_KEY = "_tooluniverse_stream"
+
     @staticmethod
     def has_any_api_keys() -> bool:
         """
@@ -199,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":
@@ -208,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}")
 
@@ -241,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}"
@@ -250,9 +261,18 @@ class AgenticTool(BaseTool):
             raise ValueError("max_new_tokens must be positive or None")
 
     # ------------------------------------------------------------------ public API --------------
-    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    def run(
+        self,
+        arguments: Dict[str, Any],
+        stream_callback: Optional[Callable[[str], None]] = None,
+    ) -> Dict[str, Any]:
         start_time = datetime.now()
 
+        # Work on a copy so we can remove control flags without mutating caller data
+        arguments = dict(arguments or {})
+        stream_flag = bool(arguments.pop("_tooluniverse_stream", False))
+        streaming_requested = stream_flag or stream_callback is not None
+
         # Check if tool is available before attempting to run
         if not self._is_available:
             error_msg = f"Tool '{self.name}' is not available due to initialization error: {self._initialization_error}"
@@ -300,16 +320,52 @@ class AgenticTool(BaseTool):
             custom_format = arguments.get("response_format", None)
 
             # Delegate to client; client handles provider-specific logic
-            response = self._llm_client.infer(
-                messages=messages,
-                temperature=self._temperature,
-                max_tokens=None,  # client resolves per-model defaults/env
-                return_json=self._return_json,
-                custom_format=custom_format,
-                max_retries=self._max_retries,
-                retry_delay=self._retry_delay,
+            response = None
+
+            streaming_permitted = (
+                streaming_requested and not self._return_json and custom_format is None
             )
 
+            if streaming_permitted and hasattr(self._llm_client, "infer_stream"):
+                try:
+                    chunks_collected: List[str] = []
+                    stream_iter = self._llm_client.infer_stream(
+                        messages=messages,
+                        temperature=self._temperature,
+                        max_tokens=None,
+                        return_json=self._return_json,
+                        custom_format=custom_format,
+                        max_retries=self._max_retries,
+                        retry_delay=self._retry_delay,
+                    )
+                    for chunk in stream_iter:
+                        if not chunk:
+                            continue
+                        chunks_collected.append(chunk)
+                        self._emit_stream_chunk(chunk, stream_callback)
+                    if chunks_collected:
+                        response = "".join(chunks_collected)
+                except Exception as stream_error:  # noqa: BLE001
+                    self.logger.warning(
+                        f"Streaming failed for tool '{self.name}': {stream_error}. Falling back to buffered response."
+                    )
+                    response = None
+
+            if response is None:
+                response = self._llm_client.infer(
+                    messages=messages,
+                    temperature=self._temperature,
+                    max_tokens=None,  # client resolves per-model defaults/env
+                    return_json=self._return_json,
+                    custom_format=custom_format,
+                    max_retries=self._max_retries,
+                    retry_delay=self._retry_delay,
+                )
+
+                if streaming_requested and response:
+                    for chunk in self._iter_chunks(response):
+                        self._emit_stream_chunk(chunk, stream_callback)
+
             end_time = datetime.now()
             execution_time = (end_time - start_time).total_seconds()
 
@@ -338,7 +394,8 @@ class AgenticTool(BaseTool):
                 }
             else:
                 return response
-        except Exception as e:
+
+        except Exception as e:  # noqa: BLE001
             end_time = datetime.now()
             execution_time = (end_time - start_time).total_seconds()
             self.logger.error(f"Error executing {self.name}: {str(e)}")
@@ -359,13 +416,57 @@ class AgenticTool(BaseTool):
                         "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,
                         "timestamp": start_time.isoformat(),
                     },
                 }
             else:
-                return "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):
+        if not text:
+            return
+        for idx in range(0, len(text), size):
+            yield text[idx : idx + size]
+
+    def _emit_stream_chunk(
+        self, chunk: Optional[str], stream_callback: Optional[Callable[[str], None]]
+    ) -> None:
+        if not stream_callback or not chunk:
+            return
+        try:
+            stream_callback(chunk)
+        except Exception as callback_error:  # noqa: BLE001
+            # Streaming callbacks should not break tool execution; log and continue
+            self.logger.debug(
+                f"Stream callback for tool '{self.name}' raised an exception: {callback_error}"
+            )
 
     # ------------------------------------------------------------------ helpers -----------------
     def _validate_arguments(self, arguments: Dict[str, Any]):
@@ -448,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

@@ -0,0 +1,109 @@
+import requests
+import xml.etree.ElementTree as ET
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+
+@register_tool("ArXivTool")
+class ArXivTool(BaseTool):
+    """
+    Search arXiv for papers by keyword using the public arXiv API.
+    """
+
+    def __init__(
+        self,
+        tool_config,
+        base_url="http://export.arxiv.org/api/query",
+    ):
+        super().__init__(tool_config)
+        self.base_url = base_url
+
+    def run(self, arguments):
+        query = arguments.get("query")
+        limit = int(arguments.get("limit", 10))
+        # sort_by: relevance | lastUpdatedDate | submittedDate
+        sort_by = arguments.get("sort_by", "relevance")
+        # sort_order: ascending | descending
+        sort_order = arguments.get("sort_order", "descending")
+
+        if not query:
+            return {"error": "`query` parameter is required."}
+
+        return self._search(query, limit, sort_by, sort_order)
+
+    def _search(self, query, limit, sort_by, sort_order):
+        params = {
+            "search_query": f"all:{query}",
+            "start": 0,
+            "max_results": max(1, min(limit, 200)),
+            "sortBy": sort_by,
+            "sortOrder": sort_order,
+        }
+
+        try:
+            response = requests.get(self.base_url, params=params, timeout=20)
+        except requests.RequestException as e:
+            return {
+                "error": "Network error calling arXiv API",
+                "reason": str(e),
+            }
+
+        if response.status_code != 200:
+            return {
+                "error": f"arXiv API error {response.status_code}",
+                "reason": response.reason,
+            }
+
+        # Parse Atom XML
+        try:
+            root = ET.fromstring(response.text)
+        except ET.ParseError as e:
+            return {
+                "error": "Failed to parse arXiv response",
+                "reason": str(e),
+            }
+
+        ns = {"atom": "http://www.w3.org/2005/Atom"}
+        entries = []
+        for entry in root.findall("atom:entry", ns):
+            title_text = entry.findtext(
+                "atom:title",
+                default="",
+                namespaces=ns,
+            )
+            title = (title_text or "").strip()
+            summary_text = entry.findtext(
+                "atom:summary",
+                default="",
+                namespaces=ns,
+            )
+            summary = (summary_text or "").strip()
+            link_el = entry.find("atom:link[@type='text/html']", ns)
+            if link_el is not None:
+                link = link_el.get("href")
+            else:
+                link = entry.findtext("atom:id", 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")
+            if cat_el is not None:
+                primary_category = cat_el.get("term", "")
+
+            entries.append(
+                {
+                    "title": title,
+                    "abstract": summary,
+                    "authors": authors,
+                    "published": published,
+                    "updated": updated,
+                    "category": primary_category,
+                    "url": link,
+                }
+            )
+
+        return entries

tooluniverse/base_tool.py

@@ -1,23 +1,18 @@
 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
 
 
 class BaseTool:
@@ -122,12 +117,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 +153,152 @@ 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_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__,
+        }