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

tooluniverse/data/uniprot_tools.json

@@ -207,5 +207,82 @@
         "output_description": "Returns a list containing all isoform ID strings."
       },
       "type": "UniProtRESTTool"
+    },
+    {
+      "name": "UniProt_search",
+      "description": "Search UniProtKB database using flexible query syntax. Supports gene names (e.g., 'gene:TP53'), protein names, organism filters (e.g., 'organism:9606'), and complex queries using AND/OR operators. Returns matching proteins with accession numbers and key information. Use this to find UniProt accessions from gene or protein names.",
+      "parameter": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search query. Can be simple (e.g., 'MEIOB') or advanced ('gene:TP53 AND organism:9606'). Keywords: gene, protein_name, organism, reviewed, etc."
+          },
+          "organism": {
+            "type": "string",
+            "description": "Optional organism filter. Can use common name ('human') or taxonomy ID ('9606'). Automatically combined with query using AND."
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return (default: 25, max: 500)"
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional list of fields to return. Default returns: accession, id, protein_name, gene_names, organism, length"
+          }
+        },
+        "required": ["query"]
+      },
+      "fields": {
+        "endpoint": "https://rest.uniprot.org/uniprotkb/search",
+        "search_type": "search",
+        "format": "json"
+      },
+      "type": "UniProtRESTTool"
+    },
+    {
+      "name": "UniProt_id_mapping",
+      "description": "Map IDs between different databases (e.g., Ensembl to UniProt, Gene Name to UniProt). Supports batch mapping and async task processing. Use this to convert between different database identifiers.",
+      "parameter": {
+        "type": "object",
+        "properties": {
+          "ids": {
+            "oneOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "ID(s) to map. Can be single string or array of strings, e.g., 'ENSG00000141510' or ['MEIOB', 'TP53']"
+          },
+          "from_db": {
+            "type": "string",
+            "description": "Source database. Examples: 'Ensembl', 'Gene_Name', 'RefSeq_Protein', 'PDB', 'EMBL'"
+          },
+          "to_db": {
+            "type": "string",
+            "description": "Target database (default: 'UniProtKB')"
+          },
+          "max_wait_time": {
+            "type": "integer",
+            "description": "Maximum time to wait for async task completion in seconds (default: 30)"
+          }
+        },
+        "required": ["ids", "from_db"]
+      },
+      "fields": {
+        "endpoint": "https://rest.uniprot.org/idmapping",
+        "mapping_type": "async",
+        "format": "json"
+      },
+      "type": "UniProtRESTTool"
     }
   ]

tooluniverse/data/web_search_tools.json

@@ -0,0 +1,250 @@
+[
+  {
+    "type": "WebSearchTool",
+    "name": "web_search",
+    "description": "General web search using DDGS (Dux Distributed Global Search) supporting multiple search engines including Google, Bing, Brave, Yahoo, and DuckDuckGo. No API keys required.",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search query string"
+        },
+        "max_results": {
+          "type": "integer",
+          "description": "Maximum number of results to return",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 50
+        },
+        "search_type": {
+          "type": "string",
+          "description": "Type of search to perform",
+          "enum": ["general", "api_documentation", "python_packages", "github"],
+          "default": "general"
+        },
+        "backend": {
+          "type": "string",
+          "description": "Search engine backend to use",
+          "enum": ["auto", "google", "bing", "brave", "yahoo", "duckduckgo"],
+          "default": "auto"
+        },
+        "region": {
+          "type": "string",
+          "description": "Search region/locale",
+          "enum": ["us-en", "cn-zh", "uk-en", "de-de", "fr-fr", "ja-jp"],
+          "default": "us-en"
+        },
+        "safesearch": {
+          "type": "string",
+          "description": "Safe search level",
+          "enum": ["on", "moderate", "off"],
+          "default": "moderate"
+        }
+      },
+      "required": ["query"]
+    },
+    "return_schema": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "description": "Status of the search operation",
+          "enum": ["success", "error"]
+        },
+        "query": {
+          "type": "string",
+          "description": "The search query that was executed"
+        },
+        "search_type": {
+          "type": "string",
+          "description": "Type of search that was performed"
+        },
+        "total_results": {
+          "type": "integer",
+          "description": "Total number of results found"
+        },
+        "results": {
+          "type": "array",
+          "description": "Array of search results",
+          "items": {
+            "type": "object",
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Title of the search result"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL of the search result"
+              },
+              "snippet": {
+                "type": "string",
+                "description": "Snippet or description of the result"
+              },
+              "rank": {
+                "type": "integer",
+                "description": "Rank of the result in search results"
+              }
+            },
+            "required": ["title", "url", "snippet", "rank"]
+          }
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message if status is error"
+        }
+      },
+      "required": ["status", "query", "total_results", "results"]
+    },
+    "test_examples": [
+      {
+        "input": {
+          "query": "python requests library",
+          "max_results": 5
+        },
+        "expected_output_type": "object",
+        "description": "Search for Python requests library information"
+      },
+      {
+        "input": {
+          "query": "machine learning APIs",
+          "search_type": "api_documentation",
+          "max_results": 3
+        },
+        "expected_output_type": "object",
+        "description": "Search for machine learning API documentation"
+      }
+    ],
+    "metadata": {
+      "tags": ["web-search", "multi-engine", "no-api-key", "ddgs"],
+      "difficulty_level": "easy",
+      "estimated_execution_time": "2-5 seconds"
+    }
+  },
+  {
+    "type": "WebAPIDocumentationSearchTool",
+    "name": "web_api_documentation_search",
+    "description": "Specialized web search for API documentation, Python packages, and technical resources using DDGS with multiple search engines. Optimized for finding official documentation and library information.",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search query string (e.g., tool name, library name, API name)"
+        },
+        "max_results": {
+          "type": "integer",
+          "description": "Maximum number of results to return",
+          "default": 10,
+          "minimum": 1,
+          "maximum": 50
+        },
+        "focus": {
+          "type": "string",
+          "description": "Focus area for the search",
+          "enum": ["api_docs", "python_packages", "github_repos"],
+          "default": "api_docs"
+        },
+        "backend": {
+          "type": "string",
+          "description": "Search engine backend to use",
+          "enum": ["auto", "google", "bing", "brave", "yahoo", "duckduckgo"],
+          "default": "auto"
+        }
+      },
+      "required": ["query"]
+    },
+    "return_schema": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "description": "Status of the search operation",
+          "enum": ["success", "error"]
+        },
+        "query": {
+          "type": "string",
+          "description": "The search query that was executed"
+        },
+        "focus": {
+          "type": "string",
+          "description": "Focus area that was used for the search"
+        },
+        "enhanced_query": {
+          "type": "string",
+          "description": "Enhanced query that was actually executed"
+        },
+        "total_results": {
+          "type": "integer",
+          "description": "Total number of results found"
+        },
+        "results": {
+          "type": "array",
+          "description": "Array of search results",
+          "items": {
+            "type": "object",
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Title of the search result"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL of the search result"
+              },
+              "snippet": {
+                "type": "string",
+                "description": "Snippet or description of the result"
+              },
+              "rank": {
+                "type": "integer",
+                "description": "Rank of the result in search results"
+              }
+            },
+            "required": ["title", "url", "snippet", "rank"]
+          }
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message if status is error"
+        }
+      },
+      "required": ["status", "query", "total_results", "results"]
+    },
+    "test_examples": [
+      {
+        "input": {
+          "query": "pandas",
+          "focus": "api_docs",
+          "max_results": 5
+        },
+        "expected_output_type": "object",
+        "description": "Search for pandas API documentation"
+      },
+      {
+        "input": {
+          "query": "requests",
+          "focus": "python_packages",
+          "max_results": 3
+        },
+        "expected_output_type": "object",
+        "description": "Search for requests Python package information"
+      },
+      {
+        "input": {
+          "query": "scikit-learn",
+          "focus": "github_repos",
+          "max_results": 3
+        },
+        "expected_output_type": "object",
+        "description": "Search for scikit-learn GitHub repositories"
+      }
+    ],
+    "metadata": {
+      "tags": ["web-search", "api-documentation", "python-packages", "technical-resources", "multi-engine", "ddgs"],
+      "difficulty_level": "easy",
+      "estimated_execution_time": "2-5 seconds"
+    }
+  }
+]

tooluniverse/data/worms_tools.json

@@ -0,0 +1,55 @@
+[
+  {
+    "type": "WoRMSRESTTool",
+    "name": "WoRMS_search_species",
+    "description": "Search marine species in World Register of Marine Species",
+    "parameter": {
+      "type": "object",
+      "properties": {
+        "query": {"type": "string", "description": "Species name or search term"},
+        "limit": {"type": "integer", "default": 20, "description": "Number of results"}
+      },
+      "required": ["query"]
+    },
+    "fields": {
+      "endpoint": "https://www.marinespecies.org/rest/AphiaIDByName/{query}",
+      "return_format": "JSON"
+    },
+    "return_schema": {
+      "type": "object",
+      "properties": {
+        "AphiaID": {"type": "integer"},
+        "url": {"type": "string"},
+        "scientificname": {"type": "string"},
+        "authority": {"type": "string"},
+        "status": {"type": "string"},
+        "unacceptreason": {"type": "string"},
+        "taxonRankID": {"type": "integer"},
+        "rank": {"type": "string"},
+        "valid_AphiaID": {"type": "integer"},
+        "valid_name": {"type": "string"},
+        "valid_authority": {"type": "string"},
+        "parentNameUsageID": {"type": "integer"},
+        "kingdom": {"type": "string"},
+        "phylum": {"type": "string"},
+        "class": {"type": "string"},
+        "order": {"type": "string"},
+        "family": {"type": "string"},
+        "genus": {"type": "string"},
+        "citation": {"type": "string"},
+        "lsid": {"type": "string"},
+        "isMarine": {"type": "boolean"},
+        "isBrackish": {"type": "boolean"},
+        "isFreshwater": {"type": "boolean"},
+        "isTerrestrial": {"type": "boolean"},
+        "isExtinct": {"type": "boolean"},
+        "match_type": {"type": "string"},
+        "modified": {"type": "string"}
+      }
+    },
+    "test_examples": [
+      {"query": "Actinia equina", "limit": 5},
+      {"query": "Scleractinia", "limit": 10}
+    ]
+  }
+]

tooluniverse/dbsnp_tool.py

@@ -1,71 +1,209 @@
-import requests
-from .base_tool import BaseTool
+"""
+dbSNP REST API Tool
+
+This tool provides access to the dbSNP (Single Nucleotide Polymorphism) database
+for variant information, allele frequencies, and genomic coordinates.
+"""
+
+from typing import Dict, Any
+from .ncbi_eutils_tool import NCBIEUtilsTool
 from .tool_registry import register_tool
 
 
-@register_tool("DbSnpTool")
-class DbSnpTool(BaseTool):
-    """
-    Local tool wrapper for dbSNP via NCBI Variation Services.
-    Fetches variant by rsID using the refsnp endpoint.
-    """
+class dbSNPRESTTool(NCBIEUtilsTool):
+    """Base class for dbSNP REST API tools with rate limiting."""
+
+
+@register_tool("dbSNPGetVariantByRsID")
+class dbSNPGetVariantByRsID(dbSNPRESTTool):
+    """Get variant information by rsID."""
 
     def __init__(self, tool_config):
         super().__init__(tool_config)
-        self.base = "https://api.ncbi.nlm.nih.gov/variation/v0"
-        self.session = requests.Session()
+        self.endpoint = "/esummary.fcgi"
 
-    def run(self, arguments):
-        rsid = arguments.get("rsid")
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Get variant by rsID using E-utilities."""
+        rsid = arguments.get("rsid", "")
         if not rsid:
-            return {"error": "Missing required parameter: rsid"}
+            return {"status": "error", "error": "rsid is required"}
 
-        # Clean rsid (remove 'rs' prefix if present)
+        # Remove 'rs' prefix if present
         if rsid.startswith("rs"):
             rsid = rsid[2:]
 
-        url = f"{self.base}/refsnp/{rsid}"
-        resp = self.session.get(url, timeout=20)
-        resp.raise_for_status()
-        data = resp.json()
-
-        # Extract key fields from primary snapshot
-        primary = data.get("primary_snapshot_data", {})
-        placements = primary.get("placements_with_allele", [])
-
-        chrom = ""
-        pos = None
-        alleles = []
-        hgvs = []
-
-        if placements:
-            placement = placements[0]
-            chrom = (
-                placement.get("seq_id", "").replace("NC_0000", "").replace(".11", "")
-            )
-            if chrom.startswith("0"):
-                chrom = chrom[1:]
-            chrom = f"chr{chrom}"
-
-            allele_data = placement.get("alleles", [])
-            for allele in allele_data:
-                spdi = allele.get("allele", {}).get("spdi", {})
-                if spdi:
-                    ref = spdi.get("deleted_sequence", "")
-                    alt = spdi.get("inserted_sequence", "")
-                    if ref and alt:
-                        alleles.append(f"{ref}>{alt}")
-                    elif ref:
-                        alleles.append(ref)
-
-                hgvs_val = allele.get("hgvs", "")
-                if hgvs_val:
-                    hgvs.append(hgvs_val)
-
-        return {
-            "refsnp_id": f"rs{rsid}",
-            "chrom": chrom,
-            "pos": pos,
-            "alleles": alleles,
-            "hgvs": hgvs,
+        params = {"db": "snp", "id": rsid, "retmode": "json"}
+
+        result = self._make_request(self.endpoint, params)
+
+        # Parse and extract useful data from NCBI response
+        if result.get("status") == "success":
+            data = result.get("data", {})
+            if isinstance(data, dict) and "result" in data:
+                result_data = data["result"]
+                if rsid in result_data:
+                    variant_data = result_data[rsid]
+
+                    # Extract key information
+                    parsed_data = {
+                        "refsnp_id": f"rs{rsid}",
+                        "snp_id": variant_data.get("snp_id"),
+                        "chromosome": variant_data.get("chr"),
+                        "position": variant_data.get("chrpos"),
+                        "allele": variant_data.get("allele"),
+                        "snp_class": variant_data.get("snp_class"),
+                        "clinical_significance": variant_data.get(
+                            "clinical_significance", ""
+                        ).split(","),
+                        "genes": [
+                            gene.get("name") for gene in variant_data.get("genes", [])
+                        ],
+                        "allele_frequencies": variant_data.get("global_mafs", []),
+                        "hgvs_notation": variant_data.get("docsum", ""),
+                        "spdi_notation": variant_data.get("spdi", ""),
+                        "function_class": variant_data.get("fxn_class", "").split(","),
+                        "validated": variant_data.get("validated", "").split(","),
+                        "created_date": variant_data.get("createdate"),
+                        "updated_date": variant_data.get("updatedate"),
+                    }
+
+                    result["data"] = parsed_data
+                    result["rsid"] = f"rs{rsid}"
+                else:
+                    result["status"] = "error"
+                    result["error"] = f"Variant rs{rsid} not found in dbSNP"
+            else:
+                result["status"] = "error"
+                result["error"] = "Invalid response format from NCBI E-utilities"
+
+        return result
+
+
+@register_tool("dbSNPSearchByGene")
+class dbSNPSearchByGene(dbSNPRESTTool):
+    """Search variants by gene symbol."""
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        self.endpoint = "/esearch.fcgi"
+
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Search variants by gene using E-utilities."""
+        gene_symbol = arguments.get("gene_symbol", "")
+        if not gene_symbol:
+            return {"status": "error", "error": "gene_symbol is required"}
+
+        params = {
+            "db": "snp",
+            "term": f"{gene_symbol}[gene]",
+            "retmode": "json",
+            "retmax": arguments.get("limit", 20),
         }
+
+        result = self._make_request(self.endpoint, params)
+
+        # Parse and extract useful data from NCBI response
+        if result.get("status") == "success":
+            data = result.get("data", {})
+            if isinstance(data, dict) and "esearchresult" in data:
+                esearch_data = data["esearchresult"]
+
+                # Extract variant IDs
+                variant_ids = esearch_data.get("idlist", [])
+                count = int(esearch_data.get("count", 0))
+
+                # Create variant list with basic info
+                variants = []
+                for variant_id in variant_ids:
+                    variants.append(
+                        {"refsnp_id": f"rs{variant_id}", "snp_id": int(variant_id)}
+                    )
+
+                parsed_data = {
+                    "variants": variants,
+                    "total_count": count,
+                    "returned_count": len(variants),
+                }
+
+                result["data"] = parsed_data
+                result["gene_symbol"] = gene_symbol
+            else:
+                result["status"] = "error"
+                result["error"] = "Invalid response format from NCBI E-utilities"
+
+        return result
+
+
+@register_tool("dbSNPGetFrequencies")
+class dbSNPGetFrequencies(dbSNPRESTTool):
+    """Get allele frequencies for a variant."""
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        self.endpoint = "/esummary.fcgi"
+
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Get allele frequencies by rsID using E-utilities."""
+        rsid = arguments.get("rsid", "")
+        if not rsid:
+            return {"status": "error", "error": "rsid is required"}
+
+        # Remove 'rs' prefix if present
+        if rsid.startswith("rs"):
+            rsid = rsid[2:]
+
+        params = {"db": "snp", "id": rsid, "retmode": "json"}
+
+        result = self._make_request(self.endpoint, params)
+
+        # Parse and extract frequency data from NCBI response
+        if result.get("status") == "success":
+            data = result.get("data", {})
+            if isinstance(data, dict) and "result" in data:
+                result_data = data["result"]
+                if rsid in result_data:
+                    variant_data = result_data[rsid]
+
+                    # Extract allele frequency data
+                    frequencies = []
+                    global_mafs = variant_data.get("global_mafs", [])
+
+                    for maf in global_mafs:
+                        study = maf.get("study", "Unknown")
+                        freq_str = maf.get("freq", "")
+
+                        # Parse frequency string (e.g., "C=0.1505591/754")
+                        if "=" in freq_str and "/" in freq_str:
+                            try:
+                                allele_part, count_part = freq_str.split("/")
+                                allele = allele_part.split("=")[0]
+                                frequency = float(allele_part.split("=")[1])
+                                sample_count = int(count_part)
+
+                                frequencies.append(
+                                    {
+                                        "study": study,
+                                        "allele": allele,
+                                        "frequency": frequency,
+                                        "sample_count": sample_count,
+                                    }
+                                )
+                            except (ValueError, IndexError):
+                                # Skip malformed frequency entries
+                                continue
+
+                    parsed_data = {
+                        "frequencies": frequencies,
+                        "total_studies": len(frequencies),
+                    }
+
+                    result["data"] = parsed_data
+                    result["rsid"] = f"rs{rsid}"
+                else:
+                    result["status"] = "error"
+                    result["error"] = f"Variant rs{rsid} not found in dbSNP"
+            else:
+                result["status"] = "error"
+                result["error"] = "Invalid response format from NCBI E-utilities"
+
+        return result