tooluniverse 1.0.9__py3-none-any.whl → 1.0.10__py3-none-any.whl

tooluniverse/space/validator.py

@@ -0,0 +1,353 @@
+"""
+Space Configuration Validator
+
+Comprehensive validation for Space configurations using JSON Schema.
+Supports validation, default value filling, and structure checking for
+Space YAML files.
+
+The validation system is based on a comprehensive JSON Schema that defines:
+- All possible fields and their types
+- Default values for optional fields
+- Required fields and validation rules
+- Enum values for specific fields
+- Nested object structures and arrays
+
+This provides a robust, flexible, and maintainable validation system that can:
+1. Validate YAML structure and content
+2. Fill in missing default values automatically
+3. Provide detailed error messages for validation failures
+4. Support both simple tool collections and complex workspaces
+"""
+
+from typing import Any, Dict, List, Tuple
+import yaml
+import jsonschema
+from jsonschema import validate
+
+
+# Space JSON Schema Definition
+# ================================
+# This schema defines the complete structure and validation rules for
+# Space configurations. It serves as the single source of truth for:
+# - Field definitions and types
+# - Default values
+# - Required fields
+# - Validation constraints
+# - Enum values for specific fields
+#
+# The schema supports two main configuration types:
+# 1. Simple tool collections (e.g., literature-search.yaml) - minimal config
+# 2. Complete workspaces (e.g., full-workspace.yaml) - full config with LLM
+#
+# Key features:
+# - Automatic default value filling
+# - Comprehensive validation rules
+# - Support for nested objects and arrays
+# - Flexible tool selection (by name, category, type)
+# - LLM configuration with provider and model settings
+# - Hook system for output processing
+# - Environment variable requirements documentation
+SPACE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "Space name - unique identifier for this configuration",
+        },
+        "version": {
+            "type": "string",
+            "default": "1.0.0",
+            "description": "Space version - follows semantic versioning "
+            "(e.g., 1.0.0, 1.2.3)",
+        },
+        "description": {
+            "type": "string",
+            "description": "Space description - explains what this "
+            "configuration does and its purpose",
+        },
+        "tags": {
+            "type": "array",
+            "items": {"type": "string"},
+            "default": [],
+            "description": "Space tags - keywords for categorization and "
+            'discovery (e.g., ["research", "biology", "literature"])',
+        },
+        "tools": {
+            "type": "object",
+            "properties": {
+                "include_tools": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tools to include by exact name - most precise "
+                    "way to select specific tools",
+                },
+                "categories": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tool categories to include - broader selection "
+                    'based on tool categories (e.g., ["literature", "clinical"])',
+                },
+                "exclude_tools": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tools to exclude by exact name - removes "
+                    "specific tools from the selection",
+                },
+                "include_tool_types": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tool types to include - filter by tool type "
+                    '(e.g., ["api", "local", "agentic"])',
+                },
+                "exclude_tool_types": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tool types to exclude - removes tools of "
+                    "specific types from the selection",
+                },
+            },
+            "additionalProperties": False,
+            "description": "Tool configuration - defines which tools to load "
+            "and how to filter them",
+        },
+        "llm_config": {
+            "type": "object",
+            "properties": {
+                "mode": {
+                    "type": "string",
+                    "enum": ["default", "fallback"],
+                    "default": "default",
+                    "description": 'LLM configuration mode - "default" uses this '
+                    'config as primary, "fallback" uses as backup '
+                    "when primary fails",
+                },
+                "default_provider": {
+                    "type": "string",
+                    "description": "Default LLM provider - must match AgenticTool "
+                    "API types (CHATGPT, GEMINI, OPENROUTER, VLLM, etc.)",
+                },
+                "models": {
+                    "type": "object",
+                    "additionalProperties": {"type": "string"},
+                    "description": "Task-specific model mappings - maps task names "
+                    'to model IDs (e.g., {"default": "gpt-4o", '
+                    '"analysis": "gpt-4-turbo"})',
+                },
+                "temperature": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 2,
+                    "description": "LLM temperature - controls randomness in "
+                    "responses (0.0 = deterministic, 2.0 = very random)",
+                },
+            },
+            "additionalProperties": False,
+            "description": "LLM configuration - settings for AI-powered tools "
+            "(AgenticTool) - only needed for complete workspaces",
+        },
+        "hooks": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "description": "Hook type - identifies the hook implementation "
+                        '(e.g., "output_summarization", "file_save")',
+                    },
+                    "enabled": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Whether hook is enabled - allows enabling/"
+                        "disabling hooks without removing them",
+                    },
+                    "config": {
+                        "type": "object",
+                        "description": "Hook configuration - specific settings for "
+                        "this hook instance",
+                    },
+                },
+                "required": ["type"],
+                "additionalProperties": False,
+            },
+            "description": "Hook configurations - post-processing functions for "
+            "tool outputs (e.g., summarization, file saving)",
+        },
+        "required_env": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Required environment variables - documents which "
+            "environment variables should be set (for documentation "
+            "purposes only)",
+        },
+    },
+    "required": ["name", "version"],
+    "additionalProperties": False,
+    "description": "Space Configuration Schema - defines the structure for "
+    "Space YAML configuration files",
+}
+
+
+class ValidationError(Exception):
+    """Raised when configuration validation fails."""
+
+
+def validate_space_config(config: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """
+    Validate a Space configuration using JSON Schema.
+
+    This is a legacy function that now uses the JSON Schema validation system.
+    For new code, use validate_with_schema() instead.
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    # Convert dict to YAML string for validation
+    yaml_content = yaml.dump(config, default_flow_style=False, allow_unicode=True)
+    is_valid, errors, _ = validate_with_schema(yaml_content, fill_defaults_flag=False)
+    return is_valid, errors
+
+
+def validate_yaml_format_by_template(yaml_content: str) -> Tuple[bool, List[str]]:
+    """
+    Validate YAML format by comparing against default template format.
+
+    This method uses the JSON Schema as a reference to validate
+    the structure and content of Space YAML configurations.
+
+    Args:
+        yaml_content: YAML content string
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    # Use the new JSON Schema validation instead
+    is_valid, errors, _ = validate_with_schema(yaml_content, fill_defaults_flag=False)
+    return is_valid, errors
+
+
+def validate_yaml_file(file_path: str) -> Tuple[bool, List[str]]:
+    """
+    Validate a YAML file by comparing against default template format.
+
+    Args:
+        file_path: Path to YAML file
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            yaml_content = f.read()
+        return validate_yaml_format_by_template(yaml_content)
+    except FileNotFoundError:
+        return False, [f"File not found: {file_path}"]
+    except Exception as e:
+        return False, [f"Error reading file: {e}"]
+
+
+def fill_defaults(data: Dict[str, Any], schema: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Recursively fill default values from JSON schema.
+
+    Args:
+        data: Configuration data
+        schema: JSON schema with default values
+
+    Returns:
+        Configuration with default values filled
+    """
+    if not isinstance(data, dict) or not isinstance(schema, dict):
+        return data
+
+    result = data.copy()
+
+    for key, value in schema.get("properties", {}).items():
+        if key not in result and "default" in value:
+            result[key] = value["default"]
+        elif key in result and isinstance(value, dict) and "properties" in value:
+            result[key] = fill_defaults(result[key], value)
+        elif (
+            key in result
+            and isinstance(value, dict)
+            and value.get("type") == "array"
+            and "items" in value
+        ):
+            if isinstance(result[key], list) and value["items"].get("type") == "object":
+                result[key] = [
+                    fill_defaults(item, value["items"]) for item in result[key]
+                ]
+
+    return result
+
+
+def validate_with_schema(
+    yaml_content: str, fill_defaults_flag: bool = True
+) -> Tuple[bool, List[str], Dict[str, Any]]:
+    """
+    Validate YAML content using JSON Schema and optionally fill default values.
+
+    Args:
+        yaml_content: YAML content string
+        fill_defaults_flag: Whether to fill default values
+
+    Returns:
+        Tuple of (is_valid, list_of_errors, processed_config)
+    """
+    errors = []
+
+    try:
+        # Parse YAML
+        config = yaml.safe_load(yaml_content)
+        if not isinstance(config, dict):
+            return False, ["YAML content must be a dictionary"], {}
+
+        # Fill default values if requested
+        if fill_defaults_flag:
+            config = fill_defaults(config, SPACE_SCHEMA)
+
+        # Validate against schema
+        validate(instance=config, schema=SPACE_SCHEMA)
+
+        return True, [], config
+
+    except yaml.YAMLError as e:
+        return False, [f"YAML parsing error: {e}"], {}
+    except jsonschema.ValidationError as e:
+        return (
+            False,
+            [f"Schema validation error: {e.message}"],
+            (config if "config" in locals() else {}),
+        )
+    except Exception as e:
+        return (
+            False,
+            [f"Validation error: {e}"],
+            (config if "config" in locals() else {}),
+        )
+
+
+def validate_yaml_file_with_schema(
+    file_path: str, fill_defaults_flag: bool = True
+) -> Tuple[bool, List[str], Dict[str, Any]]:
+    """
+    Validate a YAML file using JSON Schema and optionally fill default values.
+
+    Args:
+        file_path: Path to YAML file
+        fill_defaults_flag: Whether to fill default values
+
+    Returns:
+        Tuple of (is_valid, list_of_errors, processed_config)
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            yaml_content = f.read()
+        return validate_with_schema(yaml_content, fill_defaults_flag)
+    except FileNotFoundError:
+        return False, [f"File not found: {file_path}"], {}
+    except Exception as e:
+        return False, [f"Error reading file: {e}"], {}

tooluniverse/tool_finder_embedding.py

@@ -161,7 +161,7 @@ class ToolFinderEmbedding(BaseTool):
             query (str): User query or description of desired functionality
             top_k (int, optional): Number of top tools to return. Defaults to 5.
 
-        Returns:
+        Returns
             list: List of top-k tool names ranked by relevance to the query
 
         Raises:
@@ -203,7 +203,7 @@ class ToolFinderEmbedding(BaseTool):
             return_call_result (bool, optional): If True, returns both prompts and tool names. Defaults to False.
             categories (list, optional): List of tool categories to filter by. Currently not implemented for embedding-based search.
 
-        Returns:
+        Returns
             str or tuple:
                 - If return_call_result is False: Tool prompts as a formatted string
                 - If return_call_result is True: Tuple of (tool_prompts, tool_names)

tooluniverse/tool_finder_keyword.py

@@ -182,7 +182,7 @@ class ToolFinderKeyword(BaseTool):
         Args:
             text (str): Input text to tokenize
 
-        Returns:
+        Returns
             List[str]: List of processed tokens
         """
         if not text:
@@ -210,7 +210,7 @@ class ToolFinderKeyword(BaseTool):
         Args:
             word (str): Word to stem
 
-        Returns:
+        Returns
             str: Stemmed word
         """
         if len(word) <= 3:
@@ -232,7 +232,7 @@ class ToolFinderKeyword(BaseTool):
             tokens (List[str]): Tokenized words
             max_phrase_length (int): Maximum length of phrases to extract
 
-        Returns:
+        Returns
             List[str]: List of phrases and individual tokens
         """
         phrases = []
@@ -305,7 +305,7 @@ class ToolFinderKeyword(BaseTool):
         Args:
             parameter_schema (Dict): Tool parameter schema
 
-        Returns:
+        Returns
             List[str]: List of text elements from parameters
         """
         text_elements = []
@@ -329,7 +329,7 @@ class ToolFinderKeyword(BaseTool):
             query_terms (List[str]): Processed query terms and phrases
             tool_name (str): Name of the tool to score
 
-        Returns:
+        Returns
             float: TF-IDF relevance score
         """
         if tool_name not in self._tool_index:
@@ -364,7 +364,7 @@ class ToolFinderKeyword(BaseTool):
             query (str): Original query string
             tool (Dict): Tool configuration
 
-        Returns:
+        Returns
             float: Exact match bonus score
         """
         query_lower = query.lower()
@@ -414,7 +414,7 @@ class ToolFinderKeyword(BaseTool):
             return_call_result (bool, optional): If True, returns both prompts and tool names. Defaults to False.
             categories (list, optional): List of tool categories to filter by.
 
-        Returns:
+        Returns
             str or tuple:
                 - If return_call_result is False: Tool prompts as a formatted string
                 - If return_call_result is True: Tuple of (tool_prompts, tool_names)
@@ -472,7 +472,7 @@ class ToolFinderKeyword(BaseTool):
                 - picked_tool_names (list, optional): Pre-selected tool names to process
                 - return_call_result (bool, optional): Whether to return both prompts and names. Defaults to False.
 
-        Returns:
+        Returns
             str or tuple:
                 - If return_call_result is False: Tool prompts as a formatted string
                 - If return_call_result is True: Tuple of (tool_prompts, tool_names)
@@ -504,7 +504,7 @@ class ToolFinderKeyword(BaseTool):
         Args:
             arguments (dict): Search arguments
 
-        Returns:
+        Returns
             str: JSON string containing search results with relevance scores
         """
         try:

tooluniverse/tool_finder_llm.py

@@ -167,7 +167,7 @@ Requirements:
         Args:
             force_refresh (bool): Whether to force refresh the cache
 
-        Returns:
+        Returns
             list: List of tool dictionaries with names and descriptions
         """
         current_time = datetime.now()
@@ -220,7 +220,7 @@ Requirements:
             query (str): User query
             max_tools (int): Maximum number of tools to send to LLM
 
-        Returns:
+        Returns
             list: Filtered list of tools
         """
         if len(available_tools) <= max_tools:
@@ -269,7 +269,7 @@ Requirements:
         Args:
             tools (list): List of tool dictionaries
 
-        Returns:
+        Returns
             str: Compact formatted tool descriptions for the prompt
         """
         formatted_tools = []
@@ -296,7 +296,7 @@ Requirements:
             include_reasoning (bool): Whether to include selection reasoning
             categories (list, optional): List of tool categories to filter by
 
-        Returns:
+        Returns
             dict: Dictionary containing selected tools and metadata
         """
         try:
@@ -452,7 +452,7 @@ Requirements:
             categories (list, optional): List of tool categories to filter by. Applied before LLM selection.
             return_list_only (bool, optional): If True, returns only a list of tool specifications. Overrides other return options.
 
-        Returns:
+        Returns
             str, tuple, or list:
                 - If return_list_only is True: List of tool specifications
                 - If return_call_result is False: Tool prompts as a formatted string
@@ -532,7 +532,7 @@ Requirements:
             categories: Requested categories filter
             return_call_result: Whether return_call_result was True
 
-        Returns:
+        Returns
             str: JSON formatted search results
         """
         import json

tooluniverse/tools/_shared_client.py

@@ -64,7 +64,7 @@ def get_shared_client(
                         shared instance already exists, these parameters are
                         ignored.
 
-    Returns:
+    Returns
         ToolUniverse: The client instance to use for tool execution
 
     Thread Safety:
@@ -76,7 +76,7 @@ def get_shared_client(
         of the shared instance. Subsequent calls with different parameters
         will not affect the already-created instance.
 
-    Examples:
+    Examples
         # Basic usage
         client = get_shared_client()
 
@@ -125,7 +125,7 @@ def reset_shared_client():
         may cause unexpected behavior. It's recommended to only call this
         function when you're certain no other threads are accessing the client.
 
-    Examples:
+    Examples
         # Reset for testing
         reset_shared_client()
 

tooluniverse/url_tool.py

@@ -94,7 +94,7 @@ class URLToPDFTextTool(BaseTool):
         """
         Ensure Playwright browser binaries are installed.
 
-        Returns:
+        Returns
             None on success, or an error string on failure.
         """
         # Allow user to skip auto-install via env var

tooluniverse/uspto_tool.py

@@ -132,7 +132,7 @@ class USPTOOpenDataPortalTool(BaseTool):
         Args:
             arguments: A dictionary of arguments for the tool, matching the parameters in the tool definition.
 
-        Returns:
+        Returns
             The result of the API call, either as a dictionary (for JSON) or a string (for CSV).
         """
         endpoint = self.tool_config.get("api_endpoint")

tooluniverse/utils.py

@@ -113,7 +113,7 @@ def yaml_to_dict(yaml_file_path):
     Args:
         yaml_file_path (str): Path to the YAML file.
 
-    Returns:
+    Returns
         dict: Dictionary representation of the YAML file content.
     """
     try:
@@ -130,10 +130,10 @@ def read_json_list(file_path):
     """
     Reads a list of JSON objects from a file.
 
-    Parameters:
+    Parameters
     file_path (str): The path to the JSON file.
 
-    Returns:
+    Returns
     list: A list of dictionaries containing the JSON objects.
     """
     with open(file_path, "r") as file:
@@ -355,7 +355,7 @@ def format_error_response(
         tool_name (str, optional): Name of the tool that failed
         context (Dict[str, Any], optional): Additional context about the error
 
-    Returns:
+    Returns
         Dict[str, Any]: Standardized error response
     """
     from .exceptions import ToolError
@@ -391,7 +391,7 @@ def get_parameter_schema(tool_config: Dict[str, Any]) -> Dict[str, Any]:
     Args:
         tool_config (Dict[str, Any]): Tool configuration dictionary
 
-    Returns:
+    Returns
         Dict[str, Any]: Parameter schema dictionary
     """
     return tool_config.get("parameter", {})
@@ -404,7 +404,7 @@ def validate_query(query: Dict[str, Any]) -> bool:
     Args:
         query (Dict[str, Any]): The query dictionary to validate
 
-    Returns:
+    Returns
         bool: True if query is valid, False otherwise
     """
     if not isinstance(query, dict):
@@ -427,7 +427,7 @@ def normalize_gene_symbol(gene_symbol: str) -> str:
     Args:
         gene_symbol (str): The gene symbol to normalize
 
-    Returns:
+    Returns
         str: Normalized gene symbol
     """
     if not isinstance(gene_symbol, str):
@@ -454,7 +454,7 @@ def format_api_response(
         response_data (Any): The response data to format
         format_type (str): The desired output format ('json', 'pretty', 'minimal')
 
-    Returns:
+    Returns
         Union[str, Dict[str, Any]]: Formatted response
     """
     if format_type == "json":
@@ -493,7 +493,7 @@ def validate_hook_config(config: Dict[str, Any]) -> bool:
     Args:
         config (Dict[str, Any]): Hook configuration to validate
 
-    Returns:
+    Returns
         bool: True if configuration is valid, False otherwise
     """
     try:
@@ -561,7 +561,7 @@ def validate_hook_conditions(conditions: Dict[str, Any]) -> bool:
     Args:
         conditions (Dict[str, Any]): Hook conditions to validate
 
-    Returns:
+    Returns
         bool: True if conditions are valid, False otherwise
     """
     try:

{tooluniverse-1.0.9.dist-info → tooluniverse-1.0.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tooluniverse
-Version: 1.0.9
+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,14 +86,18 @@ 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
 
 [![Paper](https://img.shields.io/badge/Paper-Arxiv-blue)](https://arxiv.org/abs/2509.23426)
-[![ToolUniverse-PIP](https://img.shields.io/badge/PyPI-ToolUniverse-blue)](https://pypi.org/project/tooluniverse/)
+[![PyPI version](https://badge.fury.io/py/tooluniverse.svg)](https://badge.fury.io/py/tooluniverse)
 [![ToolUniverse](https://img.shields.io/badge/Code-ToolUniverse-purple)](https://github.com/mims-harvard/ToolUniverse)
 [![Model context protocol (MCP)](https://img.shields.io/badge/Model_Context_Protocol_(MCP)_Supported-green)](README_USAGE.md#running-the-mcp-server)
 [![Documentation](https://img.shields.io/badge/Documentation-Available-green)](https://zitniklab.hms.harvard.edu/ToolUniverse/)