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

tooluniverse/uniprot_tool.py

@@ -1,3 +1,4 @@
+import time
 import requests
 from typing import Any, Dict
 from .base_tool import BaseTool
@@ -22,7 +23,7 @@ class UniProtRESTTool(BaseTool):
         """Custom data extraction with support for filtering"""
 
         # Handle specific UniProt extraction patterns
-        if extract_path == "comments[?(@.commentType=='FUNCTION')].texts[*].value":
+        if extract_path == ("comments[?(@.commentType==" "'FUNCTION')].texts[*].value"):
             # Extract function comments
             result = []
             for comment in data.get("comments", []):
@@ -32,41 +33,40 @@ class UniProtRESTTool(BaseTool):
                             result.append(text["value"])
             return result
 
-        elif (
-            extract_path
-            == "comments[?(@.commentType=='SUBCELLULAR LOCATION')].subcellularLocations[*].location.value"
+        elif extract_path == (
+            "comments[?(@.commentType=="
+            "'SUBCELLULAR LOCATION')].subcellularLocations[*].location.value"
         ):
             # Extract subcellular locations
             result = []
             for comment in data.get("comments", []):
                 if comment.get("commentType") == "SUBCELLULAR LOCATION":
                     for location in comment.get("subcellularLocations", []):
-                        if "location" in location and "value" in location["location"]:
+                        if "location" in location and ("value" in location["location"]):
                             result.append(location["location"]["value"])
             return result
 
         elif extract_path == "features[?(@.type=='VARIANT')]":
-            # Extract variant features (correct type is "Natural variant")
+            # Extract variant features
             result = []
             for feature in data.get("features", []):
                 if feature.get("type") == "Natural variant":
                     result.append(feature)
             return result
 
-        elif (
-            extract_path
-            == "features[?(@.type=='MODIFIED RESIDUE' || @.type=='SIGNAL')]"
+        elif extract_path == (
+            "features[?(@.type=='MODIFIED RESIDUE' || " "@.type=='SIGNAL')]"
         ):
-            # Extract PTM and signal features (correct types are "Modified residue" and "Signal")
+            # Extract PTM and signal features
             result = []
             for feature in data.get("features", []):
                 if feature.get("type") in ["Modified residue", "Signal"]:
                     result.append(feature)
             return result
 
-        elif (
-            extract_path
-            == "comments[?(@.commentType=='ALTERNATIVE PRODUCTS')].isoforms[*].isoformIds[*]"
+        elif extract_path == (
+            "comments[?(@.commentType=="
+            "'ALTERNATIVE PRODUCTS')].isoforms[*].isoformIds[*]"
         ):
             # Extract isoform IDs
             result = []
@@ -97,17 +97,220 @@ class UniProtRESTTool(BaseTool):
             return {"error": "jsonpath_ng library is required for data extraction"}
         except Exception as e:
             return {
-                "error": f"Failed to extract UniProt fields using JSONPath '{extract_path}': {e}"
+                "error": (
+                    f"Failed to extract UniProt fields using "
+                    f"JSONPath '{extract_path}': {e}"
+                )
             }
 
+    def _handle_search(self, arguments: Dict[str, Any]) -> Any:
+        """Handle search queries with flexible parameters"""
+        query = arguments.get("query", "")
+        organism = arguments.get("organism", "")
+        limit = min(arguments.get("limit", 25), 500)
+        fields = arguments.get("fields")
+
+        # Build query string
+        query_parts = [query]
+        if organism:
+            # Support common organism names
+            organism_map = {
+                "human": "9606",
+                "mouse": "10090",
+                "rat": "10116",
+                "yeast": "559292",
+            }
+            taxon_id = organism_map.get(organism.lower(), organism)
+            query_parts.append(f"organism_id:{taxon_id}")
+
+        full_query = " AND ".join(query_parts)
+
+        # Build parameters
+        params = {"query": full_query, "size": str(limit), "format": "json"}
+
+        # Add fields parameter if specified
+        if fields and isinstance(fields, list):
+            params["fields"] = ",".join(fields)
+
+        url = "https://rest.uniprot.org/uniprotkb/search"
+
+        try:
+            resp = requests.get(url, params=params, timeout=self.timeout)
+            resp.raise_for_status()
+            data = resp.json()
+
+            # Extract results
+            results = data.get("results", [])
+            formatted_results = []
+
+            for entry in results:
+                formatted_entry = {
+                    "accession": entry.get("primaryAccession", ""),
+                    "id": entry.get("uniProtkbId", ""),
+                    "protein_name": "",
+                    "gene_names": [],
+                    "organism": "",
+                    "length": 0,
+                }
+
+                # Extract protein name
+                protein_desc = entry.get("proteinDescription", {})
+                rec_name = protein_desc.get("recommendedName", {})
+                if rec_name:
+                    full_name = rec_name.get("fullName", {})
+                    if full_name:
+                        formatted_entry["protein_name"] = full_name.get("value", "")
+
+                # Extract gene names
+                genes = entry.get("genes", [])
+                for gene in genes:
+                    gene_name = gene.get("geneName", {})
+                    if gene_name:
+                        formatted_entry["gene_names"].append(gene_name.get("value", ""))
+
+                # Extract organism
+                organism_info = entry.get("organism", {})
+                formatted_entry["organism"] = organism_info.get("scientificName", "")
+
+                # Extract sequence length
+                sequence = entry.get("sequence", {})
+                formatted_entry["length"] = sequence.get("length", 0)
+
+                formatted_results.append(formatted_entry)
+
+            return {
+                "total_results": data.get("resultsFound", len(results)),
+                "returned": len(results),
+                "results": formatted_results,
+            }
+
+        except requests.exceptions.Timeout:
+            return {"error": "Request to UniProt API timed out"}
+        except requests.exceptions.RequestException as e:
+            return {"error": f"Request to UniProt API failed: {e}"}
+        except ValueError as e:
+            return {"error": f"Failed to parse JSON response: {e}"}
+
+    def _handle_id_mapping(self, arguments: Dict[str, Any]) -> Any:
+        """Handle ID mapping requests"""
+
+        ids = arguments.get("ids", [])
+        from_db = arguments.get("from_db", "")
+        to_db = arguments.get("to_db", "UniProtKB")
+        max_wait_time = arguments.get("max_wait_time", 30)
+
+        # Normalize IDs to list
+        if isinstance(ids, str):
+            ids = [ids]
+
+        # Normalize database names
+        db_mapping = {
+            "Ensembl": "Ensembl",
+            "Gene_Name": "Gene_Name",
+            "RefSeq_Protein": "RefSeq_Protein_ID",
+            "PDB": "PDB_ID",
+            "EMBL": "EMBL_ID",
+            "UniProtKB": "UniProtKB_AC-ID",
+        }
+        from_db_normalized = db_mapping.get(from_db, from_db)
+        to_db_normalized = db_mapping.get(to_db, to_db)
+
+        # Step 1: Submit mapping job
+        submit_url = "https://rest.uniprot.org/idmapping/run"
+        payload = {"ids": ids, "from": from_db_normalized, "to": to_db_normalized}
+
+        try:
+            resp = requests.post(submit_url, json=payload, timeout=self.timeout)
+            resp.raise_for_status()
+            job_data = resp.json()
+            job_id = job_data.get("jobId")
+
+            if not job_id:
+                return {"error": "Failed to get job ID from UniProt ID mapping"}
+
+            # Step 2: Poll for job completion
+            status_url = f"https://rest.uniprot.org/idmapping/status/{job_id}"
+            results_url = f"https://rest.uniprot.org/idmapping/results/{job_id}"
+
+            start_time = time.time()
+            while time.time() - start_time < max_wait_time:
+                status_resp = requests.get(status_url, timeout=self.timeout)
+                status_data = status_resp.json()
+
+                if status_data.get("status") == "FINISHED":
+                    # Step 3: Retrieve results
+                    results_resp = requests.get(results_url, timeout=self.timeout)
+                    results_data = results_resp.json()
+
+                    # Format results
+                    formatted_results = []
+                    failed = []
+
+                    # Extract mappings
+                    results = results_data.get("results", [])
+                    for result in results:
+                        from_value = result.get("from", "")
+                        to_values = result.get("to", {}).get("results", [])
+
+                        if to_values:
+                            for to_item in to_values:
+                                to_info = to_item.get("to", {})
+                                gene_names = to_info.get("geneNames", [])
+                                gene_name = ""
+                                if gene_names:
+                                    gene_name = gene_names[0].get("value", "")
+
+                                formatted_results.append(
+                                    {
+                                        "from": from_value,
+                                        "to": {
+                                            "accession": to_info.get(
+                                                "primaryAccession", ""
+                                            ),
+                                            "id": to_info.get("uniProtkbId", ""),
+                                            "gene_name": gene_name,
+                                        },
+                                    }
+                                )
+                        else:
+                            failed.append(from_value)
+
+                    return {
+                        "mapped_count": len(formatted_results),
+                        "results": formatted_results,
+                        "failed": list(set(failed)) if failed else [],
+                    }
+                elif status_data.get("status") == "FAILED":
+                    return {"error": "ID mapping job failed"}
+
+                time.sleep(1)  # Wait 1 second before next poll
+
+            return {"error": (f"ID mapping timed out after {max_wait_time} seconds")}
+
+        except requests.exceptions.Timeout:
+            return {"error": "Request to UniProt API timed out"}
+        except requests.exceptions.RequestException as e:
+            return {"error": f"Request to UniProt API failed: {e}"}
+        except ValueError as e:
+            return {"error": f"Failed to parse JSON response: {e}"}
+
     def run(self, arguments: Dict[str, Any]) -> Any:
-        # Build URL
+        # Check if this is a search request
+        search_type = self.tool_config.get("fields", {}).get("search_type")
+        mapping_type = self.tool_config.get("fields", {}).get("mapping_type")
+
+        if search_type == "search":
+            return self._handle_search(arguments)
+        elif mapping_type == "async":
+            return self._handle_id_mapping(arguments)
+
+        # Build URL for standard accession-based queries
         url = self._build_url(arguments)
         try:
             resp = requests.get(url, timeout=self.timeout)
             if resp.status_code != 200:
                 return {
-                    "error": f"UniProt API returned status code: {resp.status_code}",
+                    "error": (f"UniProt API returned status code: {resp.status_code}"),
                     "detail": resp.text,
                 }
             data = resp.json()

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
@@ -188,6 +188,24 @@ class URLToPDFTextTool(BaseTool):
 
         timeout = arguments.get("timeout", 30)
 
+        # First, check if the URL returns HTML or a downloadable file
+        try:
+            resp = requests.head(url, timeout=timeout, allow_redirects=True)
+            content_type = resp.headers.get("Content-Type", "").lower()
+            # If it's not HTML, handle it as a simple text download
+            is_html = "text/html" in content_type or "application/xhtml" in content_type
+            if not is_html:
+                # Download the file directly and return its text content
+                resp = requests.get(url, timeout=timeout, allow_redirects=True)
+                if resp.status_code != 200:
+                    return {"error": f"HTTP {resp.status_code}"}
+                text = resp.text
+                if not text.strip():
+                    return {"error": "File appears to be empty or binary."}
+                return {self.return_key: text.strip()}
+        except requests.exceptions.RequestException as e:
+            return {"error": f"Failed to check content type: {e}"}
+
         # Ensure browsers are installed (auto-install if needed)
         ensure_error = self._ensure_playwright_browsers(
             browsers=("chromium",), with_deps=False

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,11 +113,11 @@ 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:
-        with open(yaml_file_path, "r") as file:
+        with open(yaml_file_path, "r", encoding="utf-8") as file:
             yaml_dict = yaml.safe_load(file)
             return yaml_dict
     except FileNotFoundError:
@@ -130,13 +130,13 @@ 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:
+    with open(file_path, "r", encoding="utf-8") as file:
         data = json.load(file)
     return data
 
@@ -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/web_search_tool.py

@@ -0,0 +1,229 @@
+"""
+Web search tools for ToolUniverse using DDGS (Dux Distributed Global Search).
+
+This module provides web search capabilities using the ddgs library,
+which supports multiple search engines including DuckDuckGo, Google, Bing, etc.
+"""
+
+import time
+from typing import Dict, Any, List
+from ddgs import DDGS
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+
+@register_tool("WebSearchTool")
+class WebSearchTool(BaseTool):
+    """
+    Web search tool using DDGS library.
+
+    This tool performs web searches using the DDGS library which supports
+    multiple search engines including Google, Bing, Brave, Yahoo, DuckDuckGo, etc.
+    """
+
+    def __init__(self, tool_config: Dict[str, Any]):
+        super().__init__(tool_config)
+        # DDGS instance will be created per request to avoid session issues
+
+    def _search_with_ddgs(
+        self,
+        query: str,
+        max_results: int = 10,
+        backend: str = "auto",
+        region: str = "us-en",
+        safesearch: str = "moderate",
+    ) -> List[Dict[str, Any]]:
+        """
+        Perform a web search using DDGS library and return formatted results.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+            backend: Search engine backend (auto, google, bing, brave, etc.)
+            region: Search region (e.g., 'us-en', 'cn-zh')
+            safesearch: Safe search level ('on', 'moderate', 'off')
+
+        Returns:
+            List of search results with title, url, and snippet
+        """
+        try:
+            # Create DDGS instance
+            ddgs = DDGS()
+
+            # Perform search using DDGS
+            search_results = list(
+                ddgs.text(
+                    query=query,
+                    max_results=max_results,
+                    backend=backend,
+                    region=region,
+                    safesearch=safesearch,
+                )
+            )
+
+            # Convert DDGS results to our expected format
+            results = []
+            for i, result in enumerate(search_results):
+                results.append(
+                    {
+                        "title": result.get("title", ""),
+                        "url": result.get("href", ""),
+                        "snippet": result.get("body", ""),
+                        "rank": i + 1,
+                    }
+                )
+
+            return results
+
+        except Exception as e:
+            return [
+                {
+                    "title": "Search Error",
+                    "url": "",
+                    "snippet": f"Failed to perform search: {str(e)}",
+                    "rank": 0,
+                }
+            ]
+
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute web search using DDGS.
+
+        Args:
+            arguments: Dictionary containing:
+                - query: Search query string
+                - max_results: Maximum number of results (default: 10)
+                - search_type: Type of search (default: 'general')
+                - backend: Search engine backend (default: 'auto')
+                - region: Search region (default: 'us-en')
+                - safesearch: Safe search level (default: 'moderate')
+
+        Returns:
+            Dictionary containing search results
+        """
+        try:
+            query = arguments.get("query", "").strip()
+            max_results = int(arguments.get("max_results", 10))
+            search_type = arguments.get("search_type", "general")
+            backend = arguments.get("backend", "auto")
+            region = arguments.get("region", "us-en")
+            safesearch = arguments.get("safesearch", "moderate")
+
+            if not query:
+                return {
+                    "status": "error",
+                    "error": "Query parameter is required",
+                    "results": [],
+                }
+
+            # Validate max_results
+            max_results = max(1, min(max_results, 50))  # Limit between 1-50
+
+            # Modify query based on search type
+            if search_type == "api_documentation":
+                query = f"{query} API documentation python library"
+            elif search_type == "python_packages":
+                query = f"{query} python package pypi"
+            elif search_type == "github":
+                query = f"{query} site:github.com"
+
+            # Perform search using DDGS
+            results = self._search_with_ddgs(
+                query=query,
+                max_results=max_results,
+                backend=backend,
+                region=region,
+                safesearch=safesearch,
+            )
+
+            # Add rate limiting to be respectful
+            time.sleep(0.5)
+
+            return {
+                "status": "success",
+                "query": query,
+                "search_type": search_type,
+                "total_results": len(results),
+                "results": results,
+            }
+
+        except Exception as e:
+            return {"status": "error", "error": str(e), "results": []}
+
+
+@register_tool("WebAPIDocumentationSearchTool")
+class WebAPIDocumentationSearchTool(WebSearchTool):
+    """
+    Specialized web search tool for API documentation and Python libraries.
+
+    This tool is optimized for finding API documentation, Python packages,
+    and technical resources using DDGS with multiple search engines.
+    """
+
+    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute API documentation focused search.
+
+        Args:
+            arguments: Dictionary containing:
+                - query: Search query string
+                - max_results: Maximum number of results (default: 10)
+                - focus: Focus area ('api_docs', 'python_packages', etc.)
+                - backend: Search engine backend (default: 'auto')
+
+        Returns:
+            Dictionary containing search results
+        """
+        try:
+            query = arguments.get("query", "").strip()
+            focus = arguments.get("focus", "api_docs")
+            backend = arguments.get("backend", "auto")
+
+            if not query:
+                return {
+                    "status": "error",
+                    "error": "Query parameter is required",
+                    "results": [],
+                }
+
+            # Modify query based on focus
+            if focus == "api_docs":
+                enhanced_query = f'"{query}" API documentation official docs'
+            elif focus == "python_packages":
+                enhanced_query = f'"{query}" python package pypi install pip'
+            elif focus == "github_repos":
+                enhanced_query = f'"{query}" github repository source code'
+            else:
+                enhanced_query = f'"{query}" documentation API reference'
+
+            # Use parent class search with enhanced query
+            arguments["query"] = enhanced_query
+            arguments["search_type"] = "api_documentation"
+            arguments["backend"] = backend
+
+            result = super().run(arguments)
+
+            # Add focus-specific metadata
+            if result["status"] == "success":
+                result["focus"] = focus
+                result["enhanced_query"] = enhanced_query
+
+                # Filter results for better relevance
+                if focus == "python_packages":
+                    result["results"] = [
+                        r
+                        for r in result["results"]
+                        if (
+                            "pypi.org" in r.get("url", "")
+                            or "python" in r.get("title", "").lower()
+                        )
+                    ]
+                elif focus == "github_repos":
+                    result["results"] = [
+                        r for r in result["results"] if "github.com" in r.get("url", "")
+                    ]
+
+            return result
+
+        except Exception as e:
+            return {"status": "error", "error": str(e), "results": []}