tooluniverse 1.0.9.1__py3-none-any.whl → 1.0.11__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)
@@ -225,7 +225,9 @@ class ToolFinderEmbedding(BaseTool):
         picked_tool_names_no_special = picked_tool_names_no_special[:rag_num]
         picked_tool_names = picked_tool_names_no_special[:rag_num]
 
-        picked_tools = self.tooluniverse.get_tool_by_name(picked_tool_names)
+        picked_tools = self.tooluniverse.get_tool_specification_by_names(
+            picked_tool_names
+        )
         picked_tools_prompt = self.tooluniverse.prepare_tool_prompts(picked_tools)
         if return_call_result:
             return picked_tools_prompt, picked_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)
@@ -451,7 +451,9 @@ class ToolFinderKeyword(BaseTool):
         picked_tool_names = picked_tool_names_no_special[:rag_num]
 
         # Get tool objects and prepare prompts (matching original behavior)
-        picked_tools = self.tooluniverse.get_tool_by_name(picked_tool_names)
+        picked_tools = self.tooluniverse.get_tool_specification_by_names(
+            picked_tool_names
+        )
         picked_tools_prompt = self.tooluniverse.prepare_tool_prompts(picked_tools)
 
         if return_call_result:
@@ -472,7 +474,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 +506,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:
@@ -387,7 +387,9 @@ Requirements:
 
             # Get actual tool objects
             if tool_names:
-                selected_tool_objects = self.tooluniverse.get_tool_by_name(tool_names)
+                selected_tool_objects = (
+                    self.tooluniverse.get_tool_specification_by_names(tool_names)
+                )
                 tool_prompts = self.tooluniverse.prepare_tool_prompts(
                     selected_tool_objects
                 )
@@ -452,7 +454,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
@@ -495,7 +497,9 @@ Requirements:
         picked_tool_names = picked_tool_names_no_special[:rag_num]
 
         # Get tool objects and prepare prompts (needed for both list and other formats)
-        picked_tools = self.tooluniverse.get_tool_by_name(picked_tool_names)
+        picked_tools = self.tooluniverse.get_tool_specification_by_names(
+            picked_tool_names
+        )
         picked_tools_prompt = self.tooluniverse.prepare_tool_prompts(picked_tools)
 
         # If only list format is requested, return the tool specifications as a list
@@ -532,7 +536,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/{UCSC_get_genes_by_region.py → BLAST_nucleotide_search.py}

@@ -1,39 +1,36 @@
 """
-UCSC_get_genes_by_region
+BLAST_nucleotide_search
 
-Query UCSC Genome Browser track API for knownGene features in a genomic window.
+Search nucleotide sequences using NCBI BLAST blastn against nucleotide databases
 """
 
 from typing import Any, Optional, Callable
 from ._shared_client import get_shared_client
 
 
-def UCSC_get_genes_by_region(
-    chrom: str,
-    start: int,
-    end: int,
-    genome: Optional[str] = "hg38",
-    track: Optional[str] = "knownGene",
+def BLAST_nucleotide_search(
+    sequence: str,
+    database: Optional[str] = "nt",
+    expect: Optional[float] = 10.0,
+    hitlist_size: Optional[int] = 50,
     *,
     stream_callback: Optional[Callable[[str], None]] = None,
     use_cache: bool = False,
     validate: bool = True,
 ) -> dict[str, Any]:
     """
-    Query UCSC Genome Browser track API for knownGene features in a genomic window.
+    Search nucleotide sequences using NCBI BLAST blastn against nucleotide databases
 
     Parameters
     ----------
-    genome : str
-        Genome assembly (e.g., hg38).
-    chrom : str
-        Chromosome (e.g., chr17).
-    start : int
-        Start position (0-based).
-    end : int
-        End position.
-    track : str
-        Track name.
+    sequence : str
+        DNA sequence to search
+    database : str
+        Database (nt, est, etc.)
+    expect : float
+        E-value threshold
+    hitlist_size : int
+        Max hits to return
     stream_callback : Callable, optional
         Callback for streaming output
     use_cache : bool, default False
@@ -49,13 +46,12 @@ def UCSC_get_genes_by_region(
 
     return get_shared_client().run_one_function(
         {
-            "name": "UCSC_get_genes_by_region",
+            "name": "BLAST_nucleotide_search",
             "arguments": {
-                "genome": genome,
-                "chrom": chrom,
-                "start": start,
-                "end": end,
-                "track": track,
+                "sequence": sequence,
+                "database": database,
+                "expect": expect,
+                "hitlist_size": hitlist_size,
             },
         },
         stream_callback=stream_callback,
@@ -64,4 +60,4 @@ def UCSC_get_genes_by_region(
     )
 
 
-__all__ = ["UCSC_get_genes_by_region"]
+__all__ = ["BLAST_nucleotide_search"]

tooluniverse/tools/BLAST_protein_search.py

@@ -0,0 +1,63 @@
+"""
+BLAST_protein_search
+
+Search protein sequences using NCBI BLAST blastp against protein databases
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def BLAST_protein_search(
+    sequence: str,
+    database: Optional[str] = "nr",
+    expect: Optional[float] = 10.0,
+    hitlist_size: Optional[int] = 50,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Search protein sequences using NCBI BLAST blastp against protein databases
+
+    Parameters
+    ----------
+    sequence : str
+        Protein sequence to search
+    database : str
+        Database (nr, swissprot, etc.)
+    expect : float
+
+    hitlist_size : int
+
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "BLAST_protein_search",
+            "arguments": {
+                "sequence": sequence,
+                "database": database,
+                "expect": expect,
+                "hitlist_size": hitlist_size,
+            },
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["BLAST_protein_search"]