tooluniverse 1.0.9.1__py3-none-any.whl → 1.0.11__py3-none-any.whl

tooluniverse/execute_function.py

@@ -33,8 +33,11 @@ import os
 import time
 import hashlib
 import warnings
+import threading
 from pathlib import Path
 from contextlib import nullcontext
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 from .utils import read_json_list, evaluate_function_call, extract_function_call_json
 from .exceptions import (
@@ -96,6 +99,26 @@ for _tool_name, _tool_class in sorted(tool_type_mappings.items()):
     debug(f"  - {_tool_name}: {_tool_class.__name__}")
 
 
+@dataclass
+class _BatchCacheInfo:
+    namespace: str
+    version: str
+    cache_key: str
+
+
+@dataclass
+class _BatchJob:
+    signature: str
+    call: Dict[str, Any]
+    function_name: str
+    arguments: Dict[str, Any]
+    indices: List[int] = field(default_factory=list)
+    tool_instance: Any = None
+    cache_info: Optional[_BatchCacheInfo] = None
+    cache_key_composed: Optional[str] = None
+    skip_execution: bool = False
+
+
 class ToolCallable:
     """
     A callable wrapper for a tool that validates kwargs and calls run_one_function.
@@ -334,36 +357,102 @@ class ToolUniverse:
         # Initialize dynamic tools namespace
         self.tools = ToolNamespace(self)
 
-    def register_custom_tool(self, tool_class, tool_name=None, tool_config=None):
+    def register_custom_tool(
+        self,
+        tool_class,
+        tool_name=None,
+        tool_config=None,
+        instantiate=False,
+        tool_instance=None,
+    ):
         """
-        Register a custom tool class at runtime.
+        Register a custom tool class or instance at runtime.
 
         Args:
-            tool_class: The tool class to register
+            tool_class: The tool class to register (required if tool_instance is None)
             tool_name (str, optional): Name to register under. Uses class name if None.
             tool_config (dict, optional): Tool configuration dictionary to add to all_tools
+            instantiate (bool, optional): If True, immediately instantiate and cache the tool.
+                                         Defaults to False for backward compatibility.
+            tool_instance (optional): Pre-instantiated tool object. If provided, tool_class
+                                     is inferred from the instance.
 
         Returns:
             str: The name the tool was registered under
+
+        Examples:
+            # Register tool class only (lazy instantiation)
+            tu.register_custom_tool(MyTool, tool_config={...})
+
+            # Register and immediately instantiate
+            tu.register_custom_tool(MyTool, tool_config={...}, instantiate=True)
+
+            # Register pre-instantiated tool
+            instance = MyTool({...})
+            tu.register_custom_tool(tool_class=MyTool, tool_instance=instance, tool_config={...})
         """
+        # If tool_instance is provided, infer tool_class from it
+        if tool_instance is not None:
+            tool_class = tool_instance.__class__
+        elif tool_class is None:
+            raise ValueError("Either tool_class or tool_instance must be provided")
+
         name = tool_name or tool_class.__name__
 
-        # Register the tool class
+        # Register the tool class to global registry
         register_external_tool(name, tool_class)
 
         # Update the global tool_type_mappings
         global tool_type_mappings
         tool_type_mappings = get_tool_registry()
 
-        # If tool_config is provided, add it to all_tools
+        # Process tool_config if provided
         if tool_config:
             # Ensure the config has the correct type
             if "type" not in tool_config:
                 tool_config["type"] = name
 
             self.all_tools.append(tool_config)
-            if "name" in tool_config:
-                self.all_tool_dict[tool_config["name"]] = tool_config
+            tool_name_in_config = tool_config.get("name", name)
+            self.all_tool_dict[tool_name_in_config] = tool_config
+
+            # Handle tool instantiation
+            if tool_instance is not None:
+                # Use provided instance
+                self.callable_functions[tool_name_in_config] = tool_instance
+                self.logger.debug(
+                    f"Registered pre-instantiated tool '{tool_name_in_config}'"
+                )
+            elif instantiate:
+                # Instantiate now
+                try:
+                    # Use the same logic as _get_or_initialize_tool (line 2318)
+                    # Try to instantiate with tool_config parameter
+                    try:
+                        instance = tool_class(
+                            tool_config=tool_config
+                        )  # ✅ 使用关键字参数
+                    except TypeError:
+                        # If tool doesn't accept tool_config, try without parameters
+                        instance = tool_class()
+
+                    self.callable_functions[tool_name_in_config] = instance
+                    self.logger.debug(
+                        f"Instantiated and cached tool '{tool_name_in_config}'"
+                    )
+                except Exception as e:
+                    self.logger.error(
+                        f"Failed to instantiate tool '{tool_name_in_config}': {e}"
+                    )
+                    raise
+            # else: lazy instantiation (existing behavior)
+
+            # Add to category for proper organization
+            category = tool_config.get("category", "custom")
+            if category not in self.tool_category_dicts:
+                self.tool_category_dicts[category] = []
+            if tool_name_in_config not in self.tool_category_dicts[category]:
+                self.tool_category_dicts[category].append(tool_name_in_config)
 
         self.logger.info(f"Custom tool '{name}' registered successfully!")
         return name
@@ -474,8 +563,9 @@ class ToolUniverse:
             for key in sorted(all_missing_keys):
                 f.write(f"{key}=your_api_key_here\n\n")
 
-        self.logger.info(f"Generated API key template: {output_file}")
-        self.logger.info("Copy this file to .env and fill in your API keys")
+        self.logger.info(
+            f"Generated API key template: {output_file}. Copy this file to .env and fill in your API keys"
+        )
 
     def _create_hook_config_from_type(self, hook_type):
         """
@@ -877,8 +967,10 @@ class ToolUniverse:
 
         # Generate template for missing API keys
         if len(all_missing_keys) > 0:
-            warning(f"\nMissing API keys: {', '.join(all_missing_keys)}")
-            info("Generating .env.template file with missing API keys...")
+            warning(
+                f"Some tools will not be loaded due to missing API keys: {', '.join(all_missing_keys)}"
+            )
+            # info("Generating .env.template file with missing API keys...")
             self.generate_env_template(all_missing_keys)
 
     def _load_auto_discovered_configs(self):
@@ -899,7 +991,9 @@ class ToolUniverse:
             for _tool_type, config in discovered_configs.items():
                 # Add to all_tools if not already present
                 if "name" in config and config["name"] not in [
-                    tool.get("name") for tool in self.all_tools
+                    tool.get("name")
+                    for tool in self.all_tools
+                    if isinstance(tool, dict)
                 ]:
                     self.all_tools.append(config)
                     self.logger.debug(f"Added auto-discovered config: {config['name']}")
@@ -1674,6 +1768,198 @@ class ToolUniverse:
         """
         return copy.deepcopy(self.all_tools)
 
+    def _execute_function_call_list(
+        self,
+        function_calls: List[Dict[str, Any]],
+        stream_callback=None,
+        use_cache: bool = False,
+        max_workers: Optional[int] = None,
+    ) -> List[Any]:
+        """Execute a list of function calls, optionally in parallel.
+
+        Args:
+            function_calls: Ordered list of function call dictionaries.
+            stream_callback: Optional streaming callback.
+            use_cache: Whether to enable cache lookups for each call.
+            max_workers: Maximum parallel workers; values <=1 fall back to sequential execution.
+
+        Returns:
+            List of results aligned with ``function_calls`` order.
+        """
+
+        if not function_calls:
+            return []
+
+        if stream_callback is not None and max_workers and max_workers > 1:
+            # Streaming multiple calls concurrently is ambiguous; fall back to sequential execution.
+            self.logger.warning(
+                "stream_callback is not supported with parallel batch execution; falling back to sequential mode"
+            )
+            max_workers = 1
+
+        jobs = self._build_batch_jobs(function_calls)
+        results: List[Any] = [None] * len(function_calls)
+
+        jobs_to_run = self._prime_batch_cache(jobs, use_cache, results)
+        if not jobs_to_run:
+            return results
+
+        self._execute_batch_jobs(
+            jobs_to_run,
+            results,
+            stream_callback=stream_callback,
+            use_cache=use_cache,
+            max_workers=max_workers,
+        )
+
+        return results
+
+    def _build_batch_jobs(
+        self, function_calls: List[Dict[str, Any]]
+    ) -> List[_BatchJob]:
+        signature_to_job: Dict[str, _BatchJob] = {}
+        jobs: List[_BatchJob] = []
+
+        for idx, call in enumerate(function_calls):
+            function_name = call.get("name", "")
+            arguments = call.get("arguments", {})
+            if not isinstance(arguments, dict):
+                arguments = {}
+
+            signature = json.dumps(
+                {"name": function_name, "arguments": arguments}, sort_keys=True
+            )
+
+            job = signature_to_job.get(signature)
+            if job is None:
+                job = _BatchJob(
+                    signature=signature,
+                    call=call,
+                    function_name=function_name,
+                    arguments=arguments,
+                )
+                signature_to_job[signature] = job
+                jobs.append(job)
+
+            job.indices.append(idx)
+
+        return jobs
+
+    def _prime_batch_cache(
+        self,
+        jobs: List[_BatchJob],
+        use_cache: bool,
+        results: List[Any],
+    ) -> List[_BatchJob]:
+        if not (
+            use_cache and self.cache_manager is not None and self.cache_manager.enabled
+        ):
+            return jobs
+
+        cache_requests: List[Dict[str, str]] = []
+        for job in jobs:
+            if not job.function_name:
+                continue
+
+            tool_instance = self._ensure_tool_instance(job)
+            if not tool_instance or not tool_instance.supports_caching():
+                continue
+
+            cache_key = tool_instance.get_cache_key(job.arguments or {})
+            cache_info = _BatchCacheInfo(
+                namespace=tool_instance.get_cache_namespace(),
+                version=tool_instance.get_cache_version(),
+                cache_key=cache_key,
+            )
+            job.cache_info = cache_info
+            job.cache_key_composed = self.cache_manager.compose_key(
+                cache_info.namespace, cache_info.version, cache_info.cache_key
+            )
+            cache_requests.append(
+                {
+                    "namespace": cache_info.namespace,
+                    "version": cache_info.version,
+                    "cache_key": cache_info.cache_key,
+                }
+            )
+
+        if cache_requests:
+            cache_hits = self.cache_manager.bulk_get(cache_requests)
+            if cache_hits:
+                for job in jobs:
+                    if job.cache_key_composed and job.cache_key_composed in cache_hits:
+                        cached_value = cache_hits[job.cache_key_composed]
+                        for idx in job.indices:
+                            results[idx] = cached_value
+                        job.skip_execution = True
+
+        return [job for job in jobs if not job.skip_execution]
+
+    def _execute_batch_jobs(
+        self,
+        jobs_to_run: List[_BatchJob],
+        results: List[Any],
+        *,
+        stream_callback,
+        use_cache: bool,
+        max_workers: Optional[int],
+    ) -> None:
+        if not jobs_to_run:
+            return
+
+        tool_semaphores: Dict[str, Optional[threading.Semaphore]] = {}
+
+        def run_job(job: _BatchJob):
+            semaphore = self._get_tool_semaphore(job, tool_semaphores)
+            if semaphore:
+                semaphore.acquire()
+            try:
+                result = self.run_one_function(
+                    job.call,
+                    stream_callback=stream_callback,
+                    use_cache=use_cache,
+                )
+            finally:
+                if semaphore:
+                    semaphore.release()
+
+            for idx in job.indices:
+                results[idx] = result
+
+        if max_workers and max_workers > 1:
+            with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                futures = [executor.submit(run_job, job) for job in jobs_to_run]
+                for future in as_completed(futures):
+                    future.result()
+        else:
+            for job in jobs_to_run:
+                run_job(job)
+
+    def _ensure_tool_instance(self, job: _BatchJob):
+        if job.tool_instance is None and job.function_name:
+            job.tool_instance = self._get_tool_instance(job.function_name, cache=True)
+        return job.tool_instance
+
+    def _get_tool_semaphore(
+        self,
+        job: _BatchJob,
+        tool_semaphores: Dict[str, Optional[threading.Semaphore]],
+    ) -> Optional[threading.Semaphore]:
+        if job.function_name not in tool_semaphores:
+            tool_instance = self._ensure_tool_instance(job)
+            limit = (
+                tool_instance.get_batch_concurrency_limit()
+                if tool_instance is not None
+                else 0
+            )
+            self.logger.debug("Batch concurrency for %s: %s", job.function_name, limit)
+            if limit and limit > 0:
+                tool_semaphores[job.function_name] = threading.Semaphore(limit)
+            else:
+                tool_semaphores[job.function_name] = None
+
+        return tool_semaphores[job.function_name]
+
     def run(
         self,
         fcall_str,
@@ -1681,6 +1967,8 @@ class ToolUniverse:
         verbose=True,
         format="llama",
         stream_callback=None,
+        use_cache: bool = False,
+        max_workers: Optional[int] = None,
     ):
         """
         Execute function calls from input string or data.
@@ -1711,14 +1999,18 @@ class ToolUniverse:
             message = ""  # Initialize message for cases where return_message=False
         if function_call_json is not None:
             if isinstance(function_call_json, list):
-                # return the function call+result message with call id.
+                # Execute the batch (optionally in parallel) and attach call IDs to maintain downstream compatibility.
+                batch_results = self._execute_function_call_list(
+                    function_call_json,
+                    stream_callback=stream_callback,
+                    use_cache=use_cache,
+                    max_workers=max_workers,
+                )
+
                 call_results = []
-                for i in range(len(function_call_json)):
-                    call_result = self.run_one_function(
-                        function_call_json[i], stream_callback=stream_callback
-                    )
+                for idx, call_result in enumerate(batch_results):
                     call_id = self.call_id_gen()
-                    function_call_json[i]["call_id"] = call_id
+                    function_call_json[idx]["call_id"] = call_id
                     call_results.append(
                         {
                             "role": "tool",
@@ -1737,7 +2029,9 @@ class ToolUniverse:
                 return revised_messages
             else:
                 return self.run_one_function(
-                    function_call_json, stream_callback=stream_callback
+                    function_call_json,
+                    stream_callback=stream_callback,
+                    use_cache=use_cache,
                 )
         else:
             error("Not a function call")
@@ -1846,16 +2140,42 @@ class ToolUniverse:
                         tool_instance, arguments, stream_callback, use_cache, validate
                     )
                 else:
-                    error_msg = f"Tool '{function_name}' not found"
-                    return self._create_dual_format_error(
-                        ToolUnavailableError(
-                            error_msg,
-                            next_steps=[
-                                "Check tool name spelling",
-                                "Run tu.tools.refresh()",
-                            ],
+                    # Try to auto-load tools if dictionary is empty
+                    if not self._auto_load_tools_if_empty(function_name):
+                        error_msg = "Failed to auto-load tools"
+                        return self._create_dual_format_error(
+                            ToolUnavailableError(
+                                error_msg,
+                                next_steps=[
+                                    "Manually run tu.load_tools()",
+                                    "Check tool configuration",
+                                ],
+                            )
+                        )
+
+                    # Try to get the tool instance again after loading
+                    tool_instance = self._get_tool_instance(function_name, cache=True)
+                    if tool_instance:
+                        result, tool_arguments = self._execute_tool_with_stream(
+                            tool_instance,
+                            arguments,
+                            stream_callback,
+                            use_cache,
+                            validate,
+                        )
+                    else:
+                        error_msg = (
+                            f"Tool '{function_name}' not found even after loading tools"
+                        )
+                        return self._create_dual_format_error(
+                            ToolUnavailableError(
+                                error_msg,
+                                next_steps=[
+                                    "Check tool name spelling",
+                                    "Verify tool is available in loaded categories",
+                                ],
+                            )
                         )
-                    )
             except Exception as e:
                 # Classify and return structured error
                 classified_error = self._classify_exception(e, function_name, arguments)
@@ -2065,6 +2385,29 @@ class ToolUniverse:
 
         return None
 
+    def _auto_load_tools_if_empty(self, function_name: str = None) -> bool:
+        """
+        Automatically load tools if the tools dictionary is empty.
+
+        Args:
+            function_name: Optional tool name to check after loading
+
+        Returns:
+            bool: True if tools were loaded successfully, False otherwise
+        """
+        if not self.all_tool_dict:
+            print(
+                "⚠️  Warning: No tools loaded. Automatically running tu.load_tools()..."
+            )
+            try:
+                self.load_tools()
+                print("✅ Tools loaded successfully.")
+                return True
+            except Exception as load_error:
+                print(f"❌ Failed to auto-load tools: {load_error}")
+                return False
+        return True
+
     def _make_cache_key(self, function_name: str, arguments: dict) -> str:
         """Generate cache key by delegating to BaseTool."""
         tool_instance = self._get_tool_instance(function_name, cache=False)
@@ -2083,7 +2426,15 @@ class ToolUniverse:
     ) -> Optional[ToolError]:
         """Validate parameters by delegating to BaseTool."""
         if function_name not in self.all_tool_dict:
-            return ToolUnavailableError(f"Tool '{function_name}' not found")
+            # Try to auto-load tools if dictionary is empty
+            if not self._auto_load_tools_if_empty(function_name):
+                return ToolUnavailableError("Failed to auto-load tools")
+
+            # Check again after loading
+            if function_name not in self.all_tool_dict:
+                return ToolUnavailableError(
+                    f"Tool '{function_name}' not found even after loading tools"
+                )
 
         tool_instance = self._get_tool_instance(function_name, cache=False)
         if not tool_instance:
@@ -2658,3 +3009,217 @@ class ToolUniverse:
         original_count = len(self.all_tools)
         self.load_tools(include_tools=tool_names)
         return len(self.all_tools) - original_count
+
+    def load_space(self, uri: str, **kwargs) -> Dict[str, Any]:
+        """
+        Load Space configuration and apply it to the ToolUniverse instance.
+
+        This is a high-level method that loads a Space configuration from various
+        sources (HuggingFace, local files, HTTP URLs) and applies the tool settings
+        to the current instance.
+
+        Args:
+            uri: Space URI (e.g., "hf:user/repo", "./config.yaml", "https://example.com/config.yaml")
+            **kwargs: Additional parameters to override Space configuration
+                     (e.g., exclude_tools=["tool1"], include_tools=["tool2"])
+
+        Returns:
+            dict: The loaded Space configuration
+
+        Examples:
+            # Load from HuggingFace
+            config = tu.load_space("hf:community/proteomics-toolkit")
+
+            # Load local file with overrides
+            config = tu.load_space("./my-config.yaml", exclude_tools=["slow_tool"])
+
+            # Load from HTTP URL
+            config = tu.load_space("https://example.com/config.yaml")
+        """
+        # Lazy import to avoid circular import issues
+        from .space import SpaceLoader
+
+        # Load Space configuration
+        loader = SpaceLoader()
+        config = loader.load(uri)
+
+        # Extract tool configuration
+        tools_config = config.get("tools", {})
+
+        # Merge with override parameters
+        tool_type = kwargs.get("tool_type") or tools_config.get("categories")
+        exclude_tools = kwargs.get("exclude_tools") or tools_config.get(
+            "exclude_tools", []
+        )
+        exclude_categories = kwargs.get("exclude_categories") or tools_config.get(
+            "exclude_categories", []
+        )
+        include_tools = kwargs.get("include_tools") or tools_config.get(
+            "include_tools", []
+        )
+        include_tool_types = kwargs.get("include_tool_types") or tools_config.get(
+            "include_tool_types", []
+        )
+        exclude_tool_types = kwargs.get("exclude_tool_types") or tools_config.get(
+            "exclude_tool_types", []
+        )
+
+        # Load tools with merged configuration
+        self.load_tools(
+            tool_type=tool_type,
+            exclude_tools=exclude_tools,
+            exclude_categories=exclude_categories,
+            include_tools=include_tools,
+            include_tool_types=include_tool_types,
+            exclude_tool_types=exclude_tool_types,
+        )
+
+        # Store the configuration for reference
+        self._current_space_config = config
+
+        # Apply additional configurations (LLM, hooks, etc.)
+        try:
+            # Apply LLM configuration if present
+            llm_config = config.get("llm_config")
+            if llm_config:
+                self._apply_llm_config(llm_config)
+
+            # Apply hooks configuration if present
+            hooks_config = config.get("hooks")
+            if hooks_config:
+                self._apply_hooks_config(hooks_config)
+
+            # Store metadata
+            self._store_space_metadata(config)
+
+        except Exception as e:
+            # Use print since logging might not be available
+            print(f"⚠️  Failed to apply Space configurations: {e}")
+
+        return config
+
+    def _apply_llm_config(self, llm_config: Dict[str, Any]):
+        """
+        Apply LLM configuration from Space.
+
+        Args:
+            llm_config: LLM configuration dictionary
+        """
+        try:
+            import os
+
+            # Store LLM configuration
+            self._space_llm_config = llm_config
+
+            # Set environment variables for LLM configuration
+            # Set configuration mode
+            mode = llm_config.get("mode", "default")
+            os.environ["TOOLUNIVERSE_LLM_CONFIG_MODE"] = mode
+
+            # Set default provider
+            if "default_provider" in llm_config:
+                os.environ["TOOLUNIVERSE_LLM_DEFAULT_PROVIDER"] = llm_config[
+                    "default_provider"
+                ]
+
+            # Set model mappings
+            models = llm_config.get("models", {})
+            for task, model in models.items():
+                env_var = f"TOOLUNIVERSE_LLM_MODEL_{task.upper()}"
+                os.environ[env_var] = model
+
+            # Set temperature
+            temperature = llm_config.get("temperature")
+            if temperature is not None:
+                os.environ["TOOLUNIVERSE_LLM_TEMPERATURE"] = str(temperature)
+
+            # Note: max_tokens is handled by LLM client automatically, not needed here
+
+            print(
+                f"🤖 LLM configuration applied: {llm_config.get('default_provider', 'unknown')}"
+            )
+
+        except Exception as e:
+            print(f"⚠️  Failed to apply LLM configuration: {e}")
+
+    def _apply_hooks_config(self, hooks_config: List[Dict[str, Any]]):
+        """
+        Apply hooks configuration from Space.
+
+        Args:
+            hooks_config: Hooks configuration list
+        """
+        try:
+            # Convert Space hooks format to ToolUniverse hook_config format
+            hook_config = {
+                "hooks": hooks_config,
+                "global_settings": {
+                    "default_timeout": 30,
+                    "max_hook_depth": 3,
+                    "enable_hook_caching": True,
+                    "hook_execution_order": "priority_desc",
+                },
+            }
+
+            # Enable hooks if not already enabled
+            if not self.hooks_enabled:
+                self.toggle_hooks(True)
+
+            # Update hook manager configuration
+            if self.hook_manager:
+                self.hook_manager.config = hook_config
+                self.hook_manager._load_hooks()
+                print(f"🔗 Hooks configuration applied: {len(hooks_config)} hooks")
+            else:
+                print("⚠️  Hook manager not available")
+
+        except Exception as e:
+            print(f"⚠️  Failed to apply hooks configuration: {e}")
+
+    def _store_space_metadata(self, config: Dict[str, Any]):
+        """
+        Store Space metadata for reference.
+
+        Args:
+            config: Space configuration dictionary
+        """
+        try:
+            # Store metadata
+            self._space_metadata = {
+                "name": config.get("name"),
+                "version": config.get("version"),
+                "description": config.get("description"),
+                "tags": config.get("tags", []),
+                "required_env": config.get("required_env", []),
+            }
+
+            # Check for missing environment variables
+            if config.get("required_env"):
+                import os
+
+                missing_env = [
+                    env for env in config["required_env"] if not os.getenv(env)
+                ]
+                if missing_env:
+                    print(f"⚠️  Missing environment variables: {', '.join(missing_env)}")
+
+        except Exception as e:
+            print(f"⚠️  Failed to store Space metadata: {e}")
+
+    def get_space_llm_config(self) -> Optional[Dict[str, Any]]:
+        """
+        Get the current Space LLM configuration.
+
+        Returns:
+            LLM configuration dictionary or None if not set
+        """
+        return getattr(self, "_space_llm_config", None)
+
+    def get_space_metadata(self) -> Optional[Dict[str, Any]]:
+        """
+        Get the current Space metadata.
+
+        Returns:
+            Space metadata dictionary or None if not set
+        """
+        return getattr(self, "_space_metadata", None)