tooluniverse 1.0.9.1__tar.gz → 1.0.10__tar.gz

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tooluniverse
-Version: 1.0.9.1
+Version: 1.0.10
 Summary: A comprehensive collection of scientific tools for Agentic AI, offering integration with the ToolUniverse SDK and MCP Server to support advanced scientific workflows.
 Author-email: Shanghua Gao <shanghuagao@gmail.com>
 Project-URL: Homepage, https://github.com/mims-harvard/ToolUniverse
@@ -86,8 +86,12 @@ Requires-Dist: kaleido>=0.2.1; extra == "visualization"
 Requires-Dist: scipy>=1.7.0; extra == "visualization"
 Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
 Requires-Dist: networkx>=3.4.0; extra == "visualization"
+Provides-Extra: space
+Requires-Dist: huggingface_hub>=0.34.0; extra == "space"
+Requires-Dist: pyyaml>=6.0.0; extra == "space"
+Requires-Dist: requests>=2.32.0; extra == "space"
 Provides-Extra: all
-Requires-Dist: tooluniverse[dev,docs,graph,visualization]; extra == "all"
+Requires-Dist: tooluniverse[dev,docs,graph,space,visualization]; extra == "all"
 Dynamic: license-file
 
 # <img src="docs/_static/logo.png" alt="ToolUniverse Logo" height="28" style="vertical-align: middle; margin-right: 8px;" /> ToolUniverse: Democratizing AI scientists

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tooluniverse"
-version = "1.0.9.1"
+version = "1.0.10"
 description = "A comprehensive collection of scientific tools for Agentic AI, offering integration with the ToolUniverse SDK and MCP Server to support advanced scientific workflows."
 authors = [
     { name = "Shanghua Gao", email = "shanghuagao@gmail.com" }
@@ -99,8 +99,13 @@ visualization = [
     "matplotlib>=3.5.0",
     "networkx>=3.4.0",
 ]
+space = [
+    "huggingface_hub>=0.34.0",
+    "pyyaml>=6.0.0",
+    "requests>=2.32.0",
+]
 all = [
-    "tooluniverse[dev,docs,graph,visualization]",
+    "tooluniverse[dev,docs,graph,visualization,space]",
 ]
 
 [project.urls]

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/admetai_tool.py

@@ -55,7 +55,7 @@ class ADMETAITool(BaseTool):
         Args:
             smiles: The SMILES string(s) of the molecule(s).
 
-        Returns:
+        Returns
             A dictionary mapping each SMILES string to a subdictionary of
             selected ADMET properties and their predicted values.
         """

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/agentic_tool.py

@@ -38,7 +38,7 @@ class AgenticTool(BaseTool):
         """
         Check if any API keys are available across all supported API types.
 
-        Returns:
+        Returns
             bool: True if at least one API type has all required keys, False otherwise
         """
         for _api_type, required_vars in API_KEY_ENV_VARS.items():
@@ -74,16 +74,44 @@ class AgenticTool(BaseTool):
         # Get configuration from nested 'configs' dict or fallback to top-level
         configs = tool_config.get("configs", {})
 
-        # Helper function to get config values with fallback
+        # Helper function to get config values with Space support
         def get_config(key: str, default: Any) -> Any:
-            return configs.get(key, tool_config.get(key, default))
+            tool_value = configs.get(key, tool_config.get(key))
+
+            # Get environment value directly (avoid calling self method during init)
+            env_value = None
+            if key == "api_type":
+                # Direct use of AgenticTool api_type values from Space
+                env_value = os.getenv("TOOLUNIVERSE_LLM_DEFAULT_PROVIDER")
+            elif key == "model_id":
+                task = tool_config.get("llm_task", "default").upper()
+                env_value = os.getenv(f"TOOLUNIVERSE_LLM_MODEL_{task}") or os.getenv(
+                    "TOOLUNIVERSE_LLM_MODEL_DEFAULT"
+                )
+            elif key == "temperature":
+                temp_str = os.getenv("TOOLUNIVERSE_LLM_TEMPERATURE")
+                env_value = float(temp_str) if temp_str else None
+
+            mode = os.getenv("TOOLUNIVERSE_LLM_CONFIG_MODE", "default")
+
+            if mode == "default":
+                # Space as default: tool config > env > built-in default
+                if tool_value is not None:
+                    return tool_value
+                if env_value is not None:
+                    return env_value
+                return default
+            else:  # mode == "fallback"
+                # Space as fallback: tool config > built-in default (env as fallback later)
+                if tool_value is not None:
+                    return tool_value
+                return default
 
         # LLM configuration
         self._api_type: str = get_config("api_type", "CHATGPT")
         self._model_id: str = get_config("model_id", "o1-mini")
         self._temperature: Optional[float] = get_config("temperature", 0.1)
-        # Ignore configured max_new_tokens; client will resolve per model/env
-        self._max_new_tokens: Optional[int] = None
+        # max_new_tokens is handled by LLM client automatically
         self._return_json: bool = get_config("return_json", False)
         self._max_retries: int = get_config("max_retries", 5)
         self._retry_delay: int = get_config("retry_delay", 5)
@@ -96,9 +124,8 @@ class AgenticTool(BaseTool):
 
         # Global fallback configuration
         self._use_global_fallback: bool = get_config("use_global_fallback", True)
-        self._global_fallback_chain: List[Dict[str, str]] = (
-            self._get_global_fallback_chain()
-        )
+        # Initialize fallback chain later after environment config is set
+        self._global_fallback_chain: List[Dict[str, str]] = []
 
         # Gemini model configuration (optional; env override)
         self._gemini_model_id: str = get_config(
@@ -133,11 +160,40 @@ class AgenticTool(BaseTool):
         self._current_api_type = None
         self._current_model_id = None
 
+        # Store environment config for fallback mode
+        # Direct use of AgenticTool api_type values from Space
+        self._env_api_type = os.getenv("TOOLUNIVERSE_LLM_DEFAULT_PROVIDER")
+
+        task = tool_config.get("llm_task", "default").upper()
+        self._env_model_id = os.getenv(f"TOOLUNIVERSE_LLM_MODEL_{task}") or os.getenv(
+            "TOOLUNIVERSE_LLM_MODEL_DEFAULT"
+        )
+
+        # Initialize global fallback chain now that environment config is set
+        self._global_fallback_chain = self._get_global_fallback_chain()
+
         # Try primary API first, then fallback if configured
         self._try_initialize_api()
 
     def _get_global_fallback_chain(self) -> List[Dict[str, str]]:
         """Get the global fallback chain from environment or use default."""
+        mode = os.getenv("TOOLUNIVERSE_LLM_CONFIG_MODE", "default")
+
+        # In fallback mode, prepend environment config to fallback chain
+        if mode == "fallback" and self._env_api_type and self._env_model_id:
+            env_fallback = {
+                "api_type": self._env_api_type,
+                "model_id": self._env_model_id,
+            }
+
+            # Check if env fallback is different from primary config
+            if (
+                env_fallback["api_type"] != self._api_type
+                or env_fallback["model_id"] != self._model_id
+            ):
+                # Add environment config as first fallback
+                return [env_fallback] + DEFAULT_FALLBACK_CHAIN.copy()
+
         # Check environment variable for custom fallback chain
         env_chain = os.getenv("AGENTIC_TOOL_FALLBACK_CHAIN")
         if env_chain:
@@ -257,8 +313,6 @@ class AgenticTool(BaseTool):
             raise ValueError(
                 f"Unsupported API type: {self._api_type}. Supported types: {supported_api_types}"
             )
-        if self._max_new_tokens is not None and self._max_new_tokens <= 0:
-            raise ValueError("max_new_tokens must be positive or None")
 
     # ------------------------------------------------------------------ public API --------------
     def run(
@@ -386,7 +440,6 @@ class AgenticTool(BaseTool):
                             "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(),
@@ -417,7 +470,6 @@ class AgenticTool(BaseTool):
                             "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(),
@@ -442,7 +494,6 @@ class AgenticTool(BaseTool):
                             "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,
                     },
@@ -511,7 +562,6 @@ class AgenticTool(BaseTool):
             "api_type": self._api_type,
             "model_id": self._model_id,
             "temperature": self._temperature,
-            "max_new_tokens": self._max_new_tokens,
             "return_json": self._return_json,
             "max_retries": self._max_retries,
             "retry_delay": self._retry_delay,
@@ -595,9 +645,7 @@ class AgenticTool(BaseTool):
     def estimate_token_usage(self, arguments: Dict[str, Any]) -> Dict[str, int]:
         prompt = self._format_prompt(arguments)
         estimated_input_tokens = len(prompt) // 4
-        estimated_max_output_tokens = (
-            self._max_new_tokens if self._max_new_tokens is not None else 2048
-        )
+        estimated_max_output_tokens = 2048  # Default estimation
         estimated_total_tokens = estimated_input_tokens + estimated_max_output_tokens
         return {
             "estimated_input_tokens": estimated_input_tokens,

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/base_tool.py

@@ -38,7 +38,7 @@ class BaseTool:
 
         Override this method in subclasses to specify a custom defaults file.
 
-        Returns:
+        Returns
             Path or resource object pointing to the defaults file
         """
         tool_type = cls.__name__
@@ -154,7 +154,7 @@ class BaseTool:
     def get_required_parameters(self):
         """
         Retrieve required parameters from the endpoint definition.
-        Returns:
+        Returns
         list: List of required parameters for the given endpoint.
         """
         schema = self.tool_config.get("parameter", {})
@@ -172,7 +172,7 @@ class BaseTool:
         Args:
             arguments: Dictionary of arguments to validate
 
-        Returns:
+        Returns
             ToolError if validation fails, None if validation passes
         """
         schema = self.tool_config.get("parameter", {})
@@ -207,7 +207,7 @@ class BaseTool:
         Args:
             exception: The raw exception to classify
 
-        Returns:
+        Returns
             Structured ToolError instance
         """
         error_str = str(exception).lower()
@@ -261,7 +261,7 @@ class BaseTool:
         Args:
             arguments: Dictionary of arguments for the tool call
 
-        Returns:
+        Returns
             String cache key
         """
         # Include tool name and arguments in cache key
@@ -276,7 +276,7 @@ class BaseTool:
         """
         Check if this tool supports streaming responses.
 
-        Returns:
+        Returns
             True if tool supports streaming, False otherwise
         """
         return self.tool_config.get("supports_streaming", False)
@@ -285,11 +285,22 @@ class BaseTool:
         """
         Check if this tool's results can be cached.
 
-        Returns:
+        Returns
             True if tool results can be cached, False otherwise
         """
         return self.tool_config.get("cacheable", True)
 
+    def get_batch_concurrency_limit(self) -> int:
+        """Return maximum concurrent executions allowed during batch runs (0 = unlimited)."""
+        limit = self.tool_config.get("batch_max_concurrency")
+        if limit is None:
+            return 0
+        try:
+            parsed = int(limit)
+        except (TypeError, ValueError):
+            return 0
+        return max(0, parsed)
+
     def get_cache_namespace(self) -> str:
         """Return cache namespace identifier for this tool."""
         return self.tool_config.get("name", self.__class__.__name__)
@@ -326,7 +337,7 @@ class BaseTool:
         """
         Get comprehensive information about this tool.
 
-        Returns:
+        Returns
             Dictionary containing tool metadata
         """
         return {

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/boltz_tool.py

@@ -91,7 +91,7 @@ class Boltz2DockingTool(BaseTool):
                 - other optional boltz CLI flags (e.g., 'recycling_steps').
             timeout (int): The maximum time in seconds to wait for the Boltz command to complete.
 
-        Returns:
+        Returns
             dict: A dictionary containing the path to the predicted structure and affinity data, or an error.
         """
         arguments = arguments or {}

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/cache/result_cache_manager.py

@@ -6,9 +6,11 @@ from __future__ import annotations
 
 import logging
 import os
+import queue
+import threading
 import time
 from dataclasses import dataclass
-from typing import Any, Dict, Iterator, Optional
+from typing import Any, Dict, Iterator, Optional, Sequence
 
 from .memory_cache import LRUCache, SingleFlight
 from .sqlite_backend import CacheEntry, PersistentCache
@@ -36,6 +38,8 @@ class ResultCacheManager:
         persistence_enabled: bool = True,
         singleflight: bool = True,
         default_ttl: Optional[int] = None,
+        async_persist: Optional[bool] = None,
+        async_queue_size: int = 10000,
     ):
         self.enabled = enabled
         self.default_ttl = default_ttl
@@ -55,6 +59,7 @@ class ResultCacheManager:
                 self.persistent = None
 
         self.singleflight = SingleFlight() if singleflight else None
+        self._init_async_persistence(async_persist, async_queue_size)
 
     # ------------------------------------------------------------------
     # Helper methods
@@ -69,6 +74,33 @@ class ResultCacheManager:
     def _ttl_or_default(self, ttl: Optional[int]) -> Optional[int]:
         return ttl if ttl is not None else self.default_ttl
 
+    def _init_async_persistence(
+        self, async_persist: Optional[bool], async_queue_size: int
+    ) -> None:
+        if async_persist is None:
+            async_persist = os.getenv(
+                "TOOLUNIVERSE_CACHE_ASYNC_PERSIST", "true"
+            ).lower() in ("true", "1", "yes")
+
+        self.async_persist = (
+            async_persist and self.persistent is not None and self.enabled
+        )
+
+        self._persist_queue: Optional["queue.Queue[tuple[str, Dict[str, Any]]]"] = None
+        self._worker_thread: Optional[threading.Thread] = None
+
+        if not self.async_persist:
+            return
+
+        queue_size = max(1, async_queue_size)
+        self._persist_queue = queue.Queue(maxsize=queue_size)
+        self._worker_thread = threading.Thread(
+            target=self._async_worker,
+            name="ResultCacheWriter",
+            daemon=True,
+        )
+        self._worker_thread.start()
+
     # ------------------------------------------------------------------
     # Public API
     # ------------------------------------------------------------------
@@ -126,17 +158,15 @@ class ResultCacheManager:
         )
 
         if self.persistent:
-            try:
-                self.persistent.set(
-                    composed,
-                    value,
-                    namespace=namespace,
-                    version=version,
-                    ttl=effective_ttl,
-                )
-            except Exception as exc:
-                logger.warning("Persistent cache write failed: %s", exc)
-                self.persistent = None
+            payload = {
+                "composed": composed,
+                "value": value,
+                "namespace": namespace,
+                "version": version,
+                "ttl": effective_ttl,
+            }
+            if not self._schedule_persist("set", payload):
+                self._perform_persist_set(**payload)
 
     def delete(self, *, namespace: str, version: str, cache_key: str):
         composed = self.compose_key(namespace, version, cache_key)
@@ -162,10 +192,40 @@ class ResultCacheManager:
 
         if self.persistent:
             try:
+                self.flush()
                 self.persistent.clear(namespace=namespace)
             except Exception as exc:
                 logger.warning("Persistent cache clear failed: %s", exc)
 
+    def bulk_get(self, requests: Sequence[Dict[str, str]]) -> Dict[str, Any]:
+        """Fetch multiple cache entries at once.
+
+        Args:
+            requests: Iterable of dicts containing ``namespace``, ``version`` and ``cache_key``.
+
+        Returns
+            Mapping of composed cache keys to cached values.
+        """
+
+        if not self.enabled:
+            return {}
+
+        hits: Dict[str, Any] = {}
+        for request in requests:
+            namespace = request["namespace"]
+            version = request["version"]
+            cache_key = request["cache_key"]
+            value = self.get(
+                namespace=namespace,
+                version=version,
+                cache_key=cache_key,
+            )
+            if value is not None:
+                composed = self.compose_key(namespace, version, cache_key)
+                hits[composed] = value
+
+        return hits
+
     def stats(self) -> Dict[str, Any]:
         return {
             "enabled": self.enabled,
@@ -173,11 +233,18 @@ class ResultCacheManager:
             "persistent": (
                 self.persistent.stats() if self.persistent else {"enabled": False}
             ),
+            "async_persist": self.async_persist,
+            "pending_writes": (
+                self._persist_queue.qsize()
+                if self.async_persist and self._persist_queue is not None
+                else 0
+            ),
         }
 
     def dump(self, namespace: Optional[str] = None) -> Iterator[Dict[str, Any]]:
         if not self.persistent:
             return iter([])
+        self.flush()
         return (
             {
                 "cache_key": entry.key,
@@ -220,12 +287,100 @@ class ResultCacheManager:
         return _DummyContext()
 
     def close(self):
+        self.flush()
+        self._shutdown_async_worker()
         if self.persistent:
             try:
                 self.persistent.close()
             except Exception as exc:
                 logger.warning("Persistent cache close failed: %s", exc)
 
+    # ------------------------------------------------------------------
+    # Async persistence helpers
+    # ------------------------------------------------------------------
+
+    def flush(self):
+        if self.async_persist and self._persist_queue is not None:
+            self._persist_queue.join()
+
+    def _schedule_persist(self, op: str, payload: Dict[str, Any]) -> bool:
+        if not self.async_persist or self._persist_queue is None:
+            return False
+        try:
+            self._persist_queue.put_nowait((op, payload))
+            return True
+        except queue.Full:
+            logger.warning(
+                "Async cache queue full; falling back to synchronous persistence"
+            )
+            return False
+
+    def _async_worker(self):
+        queue_ref = self._persist_queue
+        if queue_ref is None:
+            return
+
+        while True:
+            try:
+                op, payload = queue_ref.get()
+            except Exception:
+                continue
+
+            if op == "__STOP__":
+                queue_ref.task_done()
+                break
+
+            try:
+                if op == "set":
+                    self._perform_persist_set(**payload)
+                else:
+                    logger.warning("Unknown async cache operation: %s", op)
+            except Exception as exc:
+                logger.warning("Async cache write failed: %s", exc)
+                # Disable async persistence to avoid repeated failures
+                self.async_persist = False
+            finally:
+                queue_ref.task_done()
+
+    def _perform_persist_set(
+        self,
+        *,
+        composed: str,
+        value: Any,
+        namespace: str,
+        version: str,
+        ttl: Optional[int],
+    ):
+        if not self.persistent:
+            return
+        try:
+            self.persistent.set(
+                composed,
+                value,
+                namespace=namespace,
+                version=version,
+                ttl=ttl,
+            )
+        except Exception as exc:
+            logger.warning("Persistent cache write failed: %s", exc)
+            self.persistent = None
+            raise
+
+    def _shutdown_async_worker(self) -> None:
+        if not self.async_persist or self._persist_queue is None:
+            return
+
+        try:
+            self._persist_queue.put_nowait(("__STOP__", {}))
+        except queue.Full:
+            self._persist_queue.put(("__STOP__", {}))
+
+        if self._worker_thread is not None:
+            self._worker_thread.join(timeout=5)
+
+        self._worker_thread = None
+        self._persist_queue = None
+
 
 class _DummyContext:
     def __enter__(self):

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/compose_scripts/drug_safety_analyzer.py

@@ -13,7 +13,7 @@ def compose(arguments, tooluniverse, call_tool):
         tooluniverse: ToolUniverse instance
         call_tool: Function to call other tools
 
-    Returns:
+    Returns
         dict: Comprehensive drug safety analysis result
     """
     drug_name = arguments["drug_name"]

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/compose_scripts/multi_agent_literature_search.py

@@ -46,7 +46,7 @@ def compose(arguments, tooluniverse, call_tool, stream_callback=None):
         call_tool (function): Function to call other tools
         stream_callback (callable, optional): Callback function for streaming output
 
-    Returns:
+    Returns
         dict: The result of the multi-agent search
     """
     query = arguments.get("query", "")

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/compose_scripts/output_summarizer.py

@@ -39,7 +39,7 @@ def compose(arguments: Dict[str, Any], tooluniverse, call_tool) -> Dict[str, Any
         tooluniverse: ToolUniverse instance for tool execution
         call_tool: Function to call other tools within the composition
 
-    Returns:
+    Returns
         Dict[str, Any]: Dictionary containing:
             - success (bool): Whether summarization was successful
             - original_length (int): Length of original output
@@ -165,7 +165,7 @@ def _chunk_output(text: str, chunk_size: int) -> List[str]:
         text (str): The text to be chunked
         chunk_size (int): Maximum size of each chunk
 
-    Returns:
+    Returns
         List[str]: List of text chunks
     """
     if len(text) <= chunk_size:
@@ -208,7 +208,7 @@ def _summarize_chunk(
         focus_areas (str): Areas to focus on during summarization
         call_tool: Function to call the summarizer tool
 
-    Returns:
+    Returns
         str: Summarized chunk text, or empty string if summarization fails
     """
     try:
@@ -296,7 +296,7 @@ def _merge_summaries(
         max_length (int): Maximum length of final summary
         call_tool: Function to call the summarizer tool
 
-    Returns:
+    Returns
         str: Final merged summary
     """
     if not chunk_summaries:

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/compose_scripts/tool_graph_composer.py

@@ -18,7 +18,7 @@ def compose(arguments, tooluniverse, call_tool):
         tooluniverse: ToolUniverse instance
         call_tool: Function to call other tools
 
-    Returns:
+    Returns
         Dictionary with results and file paths
     """
     try:

{tooluniverse-1.0.9.1 → tooluniverse-1.0.10}/src/tooluniverse/compose_scripts/tool_metadata_generator.py

@@ -13,7 +13,7 @@ def compose(arguments, tooluniverse, call_tool):
         tooluniverse: ToolUniverse instance
         call_tool: Function to call other tools
 
-    Returns:
+    Returns
         list: List of tool metadata dictionaries (JSON-compatible)
     """
     import json