tooluniverse 1.0.11.1__py3-none-any.whl → 1.0.12__py3-none-any.whl

tooluniverse/alphafold_tool.py

@@ -11,7 +11,7 @@ ALPHAFOLD_BASE_URL = "https://alphafold.ebi.ac.uk/api"
 class AlphaFoldRESTTool(BaseTool):
     """
     AlphaFold Protein Structure Database API tool.
-    Generic wrapper for AlphaFold API endpoints defined in alphafold_tools.json.
+    Generic wrapper for AlphaFold API endpoints from alphafold_tools.json.
     """
 
     def __init__(self, tool_config):
@@ -22,6 +22,7 @@ class AlphaFoldRESTTool(BaseTool):
         self.endpoint_template: str = fields["endpoint"]
         self.required: List[str] = parameter.get("required", [])
         self.output_format: str = fields.get("return_format", "JSON")
+        self.auto_query_params: Dict[str, Any] = fields.get("auto_query_params", {})
 
     def _build_url(self, arguments: Dict[str, Any]) -> str | Dict[str, Any]:
         # Example: endpoint_template = "/annotations/{qualifier}.json"
@@ -40,14 +41,18 @@ class AlphaFoldRESTTool(BaseTool):
         # Now url_path = "/annotations/P69905.json"
 
         # Treat all remaining args as query parameters
-        #   "type" wasn’t a placeholder, so it becomes a query param
+        #   "type" wasn't a placeholder, so it becomes a query param
         query_args = {k: v for k, v in arguments.items() if k not in used}
+
+        # Add auto_query_params from config (e.g., type=MUTAGEN)
+        query_args.update(self.auto_query_params)
+
         if query_args:
             from urllib.parse import urlencode
 
             url_path += "?" + urlencode(query_args)
 
-        # Final result = "https://alphafold.ebi.ac.uk/api/annotations/P69905.json?type=MUTAGEN"
+        # Final example: annotations/P69905.json?type=MUTAGEN
         return ALPHAFOLD_BASE_URL + url_path
 
     def _make_request(self, url: str) -> Dict[str, Any]:
@@ -62,9 +67,37 @@ class AlphaFoldRESTTool(BaseTool):
                 },
             )
         except Exception as e:
-            return {"error": "Request to AlphaFold API failed", "detail": str(e)}
+            return {
+                "error": "Request to AlphaFold API failed",
+                "detail": str(e),
+            }
 
         if resp.status_code == 404:
+            # Try to provide more context about 404 errors
+            # Check if protein exists in AlphaFold DB
+            try:
+                qualifier_match = re.search(r"/annotations/([^/]+)\.json", url)
+                if qualifier_match:
+                    accession = qualifier_match.group(1)
+                    base = ALPHAFOLD_BASE_URL
+                    check_url = f"{base}/uniprot/summary/{accession}.json"
+                    check_resp = requests.get(check_url, timeout=10)
+                    if check_resp.status_code == 200:
+                        return {
+                            "error": "No MUTAGEN annotations available",
+                            "reason": (
+                                "Protein exists in AlphaFold DB but "
+                                "has no MUTAGEN annotations"
+                            ),
+                            "endpoint": url,
+                        }
+                    else:
+                        return {
+                            "error": "Protein not found in AlphaFold DB",
+                            "endpoint": url,
+                        }
+            except Exception:
+                pass  # Fall through to generic error
             return {"error": "Not found", "endpoint": url}
         if resp.status_code != 200:
             return {
@@ -98,9 +131,13 @@ class AlphaFoldRESTTool(BaseTool):
         if self.output_format.upper() == "JSON":
             try:
                 data = resp.json()
-                if not data:
+                if not data or (isinstance(data, dict) and not data):
                     return {
-                        "error": "AlphaFold returned an empty response",
+                        "error": "No MUTAGEN annotations available",
+                        "reason": (
+                            "Protein exists in AlphaFold DB but "
+                            "has no MUTAGEN annotations from UniProt"
+                        ),
                         "endpoint": url,
                         "query": arguments,
                     }
@@ -124,4 +161,7 @@ class AlphaFoldRESTTool(BaseTool):
                 }
 
         # Fallback for non-JSON output
-        return {"data": resp.text, "metadata": {"endpoint": url, "query": arguments}}
+        return {
+            "data": resp.text,
+            "metadata": {"endpoint": url, "query": arguments},
+        }

tooluniverse/base_tool.py

@@ -183,7 +183,15 @@ class BaseTool:
         try:
             import jsonschema
 
-            jsonschema.validate(arguments, schema)
+            # Filter out internal control parameters before validation
+            # Only filter known internal parameters, not all underscore-prefixed params
+            # to allow optional streaming parameter _tooluniverse_stream
+            internal_params = {"ctx", "_tooluniverse_stream"}
+            filtered_arguments = {
+                k: v for k, v in arguments.items() if k not in internal_params
+            }
+
+            jsonschema.validate(filtered_arguments, schema)
             return None
         except jsonschema.ValidationError as e:
             return ToolValidationError(

tooluniverse/build_optimizer.py

@@ -6,15 +6,52 @@ from pathlib import Path
 from typing import Dict, Any, Set, Tuple
 
 
-def calculate_tool_hash(tool_config: Dict[str, Any]) -> str:
-    """Calculate a hash for tool configuration to detect changes."""
+def _normalize_value(value: Any) -> Any:
+    """Recursively normalize values for consistent hashing."""
+    if isinstance(value, dict):
+        # Sort dictionary keys and normalize values
+        return {k: _normalize_value(v) for k, v in sorted(value.items())}
+    elif isinstance(value, list):
+        # Normalize list elements
+        return [_normalize_value(item) for item in value]
+    elif isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    else:
+        # Convert other types to string representation for hashing
+        return str(value)
+
+
+def calculate_tool_hash(tool_config: Dict[str, Any], verbose: bool = False) -> str:
+    """Calculate a hash for tool configuration to detect changes.
+
+    Args:
+        tool_config: Tool configuration dictionary
+        verbose: If True, print excluded fields (for debugging)
+
+    Returns:
+        MD5 hash string of the normalized configuration
+    """
+    # Fields to exclude from hash calculation (metadata/timestamp fields)
+    excluded_fields = {"timestamp", "last_updated", "created_at", "_cache", "_metadata"}
+
     # Create a normalized version of the config for hashing
     normalized_config = {}
-    for key, value in sorted(tool_config.items()):
-        if key not in ["timestamp", "last_updated", "created_at"]:
-            normalized_config[key] = value
+    excluded_values = []
 
-    config_str = json.dumps(normalized_config, sort_keys=True, separators=(",", ":"))
+    for key, value in sorted(tool_config.items()):
+        if key not in excluded_fields:
+            # Recursively normalize nested structures
+            normalized_config[key] = _normalize_value(value)
+        elif verbose:
+            excluded_values.append(key)
+
+    if verbose and excluded_values:
+        print(f"  Excluded fields from hash: {', '.join(excluded_values)}")
+
+    # Use consistent JSON serialization with sorted keys
+    config_str = json.dumps(
+        normalized_config, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    )
     return hashlib.md5(config_str.encode("utf-8")).hexdigest()
 
 
@@ -59,29 +96,85 @@ def cleanup_orphaned_files(tools_dir: Path, current_tool_names: Set[str]) -> int
     return cleaned_count
 
 
+def _compare_configs(old_config: Dict[str, Any], new_config: Dict[str, Any]) -> list:
+    """Compare two configs and return list of changed field paths."""
+    changes = []
+
+    all_keys = set(old_config.keys()) | set(new_config.keys())
+    excluded_fields = {"timestamp", "last_updated", "created_at", "_cache", "_metadata"}
+
+    for key in all_keys:
+        if key in excluded_fields:
+            continue
+
+        old_val = old_config.get(key)
+        new_val = new_config.get(key)
+
+        if old_val != new_val:
+            changes.append(key)
+
+    return changes
+
+
 def get_changed_tools(
-    current_tools: Dict[str, Any], metadata_file: Path
-) -> Tuple[list, list, list]:
-    """Get lists of new, changed, and unchanged tools."""
+    current_tools: Dict[str, Any],
+    metadata_file: Path,
+    force_regenerate: bool = False,
+    verbose: bool = False,
+) -> Tuple[list, list, list, Dict[str, list]]:
+    """Get lists of new, changed, and unchanged tools.
+
+    Args:
+        current_tools: Dictionary of current tool configurations
+        metadata_file: Path to metadata file storing previous hashes
+        force_regenerate: If True, mark all tools as changed
+        verbose: If True, provide detailed change information
+
+    Returns:
+        Tuple of (new_tools, changed_tools, unchanged_tools, change_details)
+        where change_details maps tool_name -> list of changed field names
+    """
     old_metadata = load_metadata(metadata_file)
     new_metadata = {}
     new_tools = []
     changed_tools = []
     unchanged_tools = []
-
-    for tool_name, tool_config in current_tools.items():
-        current_hash = calculate_tool_hash(tool_config)
-        new_metadata[tool_name] = current_hash
-
-        old_hash = old_metadata.get(tool_name)
-        if old_hash is None:
-            new_tools.append(tool_name)
-        elif old_hash != current_hash:
-            changed_tools.append(tool_name)
-        else:
-            unchanged_tools.append(tool_name)
+    change_details: Dict[str, list] = {}
+
+    if force_regenerate:
+        print("🔄 Force regeneration enabled - all tools will be regenerated")
+        for tool_name, tool_config in current_tools.items():
+            current_hash = calculate_tool_hash(tool_config, verbose=verbose)
+            new_metadata[tool_name] = current_hash
+            if tool_name in old_metadata:
+                changed_tools.append(tool_name)
+                change_details[tool_name] = ["force_regenerate"]
+            else:
+                new_tools.append(tool_name)
+    else:
+        for tool_name, tool_config in current_tools.items():
+            current_hash = calculate_tool_hash(tool_config, verbose=verbose)
+            new_metadata[tool_name] = current_hash
+
+            old_hash = old_metadata.get(tool_name)
+            if old_hash is None:
+                new_tools.append(tool_name)
+                if verbose:
+                    print(f"  ✨ New tool detected: {tool_name}")
+            elif old_hash != current_hash:
+                changed_tools.append(tool_name)
+                # Try to identify which fields changed (if we have the old config)
+                # Note: We only have hashes, so we can't do detailed field comparison
+                # This would require storing full configs, which we avoid for size reasons
+                change_details[tool_name] = ["hash_mismatch"]
+                if verbose:
+                    print(
+                        f"  🔄 Tool changed: {tool_name} (hash: {old_hash[:8]}... -> {current_hash[:8]}...)"
+                    )
+            else:
+                unchanged_tools.append(tool_name)
 
     # Save updated metadata
     save_metadata(new_metadata, metadata_file)
 
-    return new_tools, changed_tools, unchanged_tools
+    return new_tools, changed_tools, unchanged_tools, change_details

tooluniverse/data/alphafold_tools.json

@@ -387,31 +387,26 @@
   },
   {
     "name": "alphafold_get_annotations",
-    "description": "Retrieve AlphaFold variant annotations (e.g., missense mutations) for a given UniProt accession. IMPORTANT: The qualifier must be a UniProt ACCESSION (e.g., 'P69905'), along with an annotation type (currently only 'MUTAGEN'). Do NOT use UniProt entry names as they will cause API errors. To find UniProt accession from a gene/protein name, use `UniProt_search` (e.g., query='gene:TP53' organism='human') or `UniProt_id_mapping` for ID conversion. Use this tool to explore predicted pathogenicity or functional effects of substitutions. For experimentally curated variants, use `UniProt_get_disease_variants_by_accession`. To view the full 3D structure, call `alphafold_get_prediction`; for overall model metadata, use `alphafold_get_summary`.",
+    "description": "Retrieve AlphaFold MUTAGEN annotations for a given UniProt accession. Returns experimental mutagenesis data mapped onto protein structures from UniProt. The qualifier must be a UniProt ACCESSION (e.g., 'P69905'). Note: Not all proteins have MUTAGEN annotations available in the database.",
     "type": "AlphaFoldRESTTool",
     "parameter": {
       "type": "object",
       "properties": {
         "qualifier": {
           "type": "string",
-          "description": "Protein identifier: UniProt ACCESSION (e.g., 'P69905'). Do NOT use entry names. To find accession from gene name: use `UniProt_search` or `UniProt_id_mapping`."
-        },
-        "type": {
-          "type": "string",
-          "description": "Annotation type (currently only 'MUTAGEN' is supported).",
-          "enum": [
-            "MUTAGEN"
-          ]
+          "description": "UniProt ACCESSION (e.g., 'P69905'). Must be an accession number, not an entry name."
         }
       },
       "required": [
-        "qualifier",
-        "type"
+        "qualifier"
       ]
     },
     "fields": {
       "endpoint": "/annotations/{qualifier}.json",
-      "return_format": "JSON"
+      "return_format": "JSON",
+      "auto_query_params": {
+        "type": "MUTAGEN"
+      }
     },
     "return_schema": {
       "type": "object",

tooluniverse/data/encode_tools.json

@@ -0,0 +1,139 @@
+[
+  {
+    "name": "ENCODE_search_experiments",
+    "type": "ENCODESearchTool",
+    "description": "Search ENCODE functional genomics experiments (e.g., ChIP-seq, ATAC-seq) by assay/target/organism/status. Use to discover datasets and access experiment-level metadata.",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "assay_title": {
+          "type": "string",
+          "description": "Assay name filter (e.g., 'ChIP-seq', 'ATAC-seq')."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target filter (e.g., 'CTCF')."
+        },
+        "organism": {
+          "type": "string",
+          "description": "Organism filter (e.g., 'Homo sapiens', 'Mus musculus')."
+        },
+        "status": {
+          "type": "string",
+          "default": "released",
+          "description": "Record status filter (default 'released')."
+        },
+        "limit": {
+          "type": "integer",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Max number of results (1–100)."
+        }
+      }
+    },
+    "fields": {
+      "endpoint": "https://www.encodeproject.org/search/",
+      "format": "json"
+    },
+    "return_schema": {
+      "type": "object",
+      "description": "ENCODE experiments search response",
+      "properties": {
+        "status": {"type": "string"},
+        "data": {
+          "type": "object",
+          "properties": {
+            "total": {"type": "integer"},
+            "@graph": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "accession": {"type": "string"},
+                  "assay_title": {"type": "string"},
+                  "target": {"type": "object"},
+                  "organism": {"type": "string"},
+                  "status": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "url": {"type": "string"}
+      }
+    },
+    "test_examples": [
+      {"assay_title": "ChIP-seq", "limit": 1},
+      {"assay_title": "ATAC-seq", "limit": 1}
+    ],
+    "label": ["ENCODE", "Experiment", "Search"],
+    "metadata": {
+      "tags": ["functional-genomics", "chip-seq", "atac-seq"],
+      "estimated_execution_time": "< 3 seconds"
+    }
+  },
+  {
+    "name": "ENCODE_list_files",
+    "type": "ENCODEFilesTool",
+    "description": "List ENCODE files with filters (file_format, output_type, assay). Use to programmatically retrieve downloadable artifact metadata (FASTQ, BAM, bigWig, peaks).",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "file_type": {
+          "type": "string",
+          "description": "File type filter (e.g., 'fastq', 'bam', 'bigWig')."
+        },
+        "assay_title": {
+          "type": "string",
+          "description": "Assay filter (e.g., 'ChIP-seq')."
+        },
+        "limit": {
+          "type": "integer",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Max number of results (1–100)."
+        }
+      }
+    },
+    "fields": {
+      "endpoint": "https://www.encodeproject.org/search/",
+      "format": "json"
+    },
+    "return_schema": {
+      "type": "object",
+      "description": "ENCODE files search response",
+      "properties": {
+        "status": {"type": "string"},
+        "data": {
+          "type": "object",
+          "properties": {
+            "total": {"type": "integer"},
+            "@graph": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "accession": {"type": "string"},
+                  "file_format": {"type": "string"},
+                  "output_type": {"type": "string"},
+                  "file_type": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "url": {"type": "string"}
+      }
+    },
+    "test_examples": [
+      {"file_type": "fastq", "limit": 1}
+    ],
+    "label": ["ENCODE", "File", "Search"],
+    "metadata": {
+      "tags": ["downloads", "artifacts", "metadata"],
+      "estimated_execution_time": "< 3 seconds"
+    }
+  }
+]

tooluniverse/data/gbif_tools.json

@@ -0,0 +1,152 @@
+[
+  {
+    "name": "GBIF_search_species",
+    "type": "GBIFTool",
+    "description": "Find taxa by keyword (scientific/common names) in GBIF. Use to resolve organism names to stable taxon keys (rank, lineage) for downstream biodiversity/occurrence queries.",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search string for species/taxa (supports scientific/common names), e.g., 'Homo', 'Atlantic cod'."
+        },
+        "limit": {
+          "type": "integer",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 300,
+          "description": "Maximum number of results to return (1–300)."
+        },
+        "offset": {
+          "type": "integer",
+          "default": 0,
+          "minimum": 0,
+          "description": "Result offset for pagination (0-based)."
+        }
+      },
+      "required": ["query"]
+    },
+    "fields": {
+      "endpoint": "https://api.gbif.org/v1/species/search",
+      "format": "json"
+    },
+    "return_schema": {
+      "type": "object",
+      "description": "GBIF species search response",
+      "properties": {
+        "status": {"type": "string"},
+        "data": {
+          "type": "object",
+          "properties": {
+            "count": {"type": "integer"},
+            "results": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "key": {"type": "integer", "description": "taxonKey"},
+                  "scientificName": {"type": "string"},
+                  "rank": {"type": "string"},
+                  "kingdom": {"type": "string"},
+                  "phylum": {"type": "string"},
+                  "class": {"type": "string"},
+                  "order": {"type": "string"},
+                  "family": {"type": "string"},
+                  "genus": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "url": {"type": "string"}
+      }
+    },
+    "test_examples": [
+      {"query": "Homo", "limit": 1},
+      {"query": "Gadus", "limit": 1}
+    ],
+    "label": ["GBIF", "Taxonomy", "Search"],
+    "metadata": {
+      "tags": ["biodiversity", "taxonomy", "species", "search"],
+      "estimated_execution_time": "< 2 seconds"
+    }
+  },
+  {
+    "name": "GBIF_search_occurrences",
+    "type": "GBIFOccurrenceTool",
+    "description": "Retrieve species occurrence records from GBIF with optional filters (taxonKey, country, coordinates). Use for distribution mapping, presence-only modeling, and sampling context.",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "taxonKey": {
+          "type": "integer",
+          "description": "GBIF taxon key to filter occurrences by a specific taxon (from species search)."
+        },
+        "country": {
+          "type": "string",
+          "description": "ISO 3166-1 alpha-2 country code filter (e.g., 'US', 'CN')."
+        },
+        "hasCoordinate": {
+          "type": "boolean",
+          "default": true,
+          "description": "Only return records with valid latitude/longitude coordinates when true."
+        },
+        "limit": {
+          "type": "integer",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 300,
+          "description": "Maximum number of results to return (1–300)."
+        },
+        "offset": {
+          "type": "integer",
+          "default": 0,
+          "minimum": 0,
+          "description": "Result offset for pagination (0-based)."
+        }
+      }
+    },
+    "fields": {
+      "endpoint": "https://api.gbif.org/v1/occurrence/search",
+      "format": "json"
+    },
+    "return_schema": {
+      "type": "object",
+      "description": "GBIF occurrence search response",
+      "properties": {
+        "status": {"type": "string"},
+        "data": {
+          "type": "object",
+          "properties": {
+            "count": {"type": "integer"},
+            "results": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "key": {"type": "integer"},
+                  "speciesKey": {"type": "integer"},
+                  "scientificName": {"type": "string"},
+                  "decimalLatitude": {"type": "number"},
+                  "decimalLongitude": {"type": "number"},
+                  "eventDate": {"type": "string"},
+                  "countryCode": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "url": {"type": "string"}
+      }
+    },
+    "test_examples": [
+      {"hasCoordinate": true, "limit": 1},
+      {"country": "US", "limit": 1}
+    ],
+    "label": ["GBIF", "Occurrence", "Geospatial"],
+    "metadata": {
+      "tags": ["biodiversity", "occurrence", "distribution", "geospatial"],
+      "estimated_execution_time": "< 3 seconds"
+    }
+  }
+]