tooluniverse 0.2.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

tooluniverse/package_tool.py

@@ -0,0 +1,195 @@
+# package_tool.py
+
+import requests
+import json
+from .base_tool import BaseTool
+from typing import Dict, Any
+from .tool_registry import register_tool
+
+
+@register_tool("PackageTool")
+class PackageTool(BaseTool):
+    """
+    Universal tool to provide information about Python packages.
+    Fetches real-time data from PyPI API with local fallback.
+    """
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        self.package_name = tool_config.get("package_name", "")
+        self.local_info = tool_config.get("local_info", {})
+        self.pypi_timeout = tool_config.get("pypi_timeout", 5)
+
+    def run(self, arguments):
+        """
+        Get comprehensive package information.
+
+        Args:
+            arguments (dict): Optional parameters for customization
+
+        Returns:
+            dict: Package information including name, description, installation, docs, usage
+        """
+        include_examples = arguments.get("include_examples", True)
+        source = arguments.get("source", "auto")  # 'auto', 'pypi', 'local'
+
+        try:
+            if source == "local":
+                return self._get_local_info(include_examples)
+            elif source == "pypi":
+                return self._get_pypi_info(include_examples)
+            else:  # auto - try PyPI first, fallback to local
+                try:
+                    return self._get_pypi_info(include_examples)
+                except Exception as e:
+                    print(f"PyPI fetch failed: {e}, falling back to local info")
+                    return self._get_local_info(include_examples)
+
+        except Exception as e:
+            return {
+                "error": f"Failed to get package information: {str(e)}",
+                "package_name": self.package_name,
+            }
+
+    def _get_pypi_info(self, include_examples: bool = True) -> Dict[str, Any]:
+        """Fetch package information from PyPI API"""
+        url = f"https://pypi.org/pypi/{self.package_name}/json"
+
+        try:
+            response = requests.get(url, timeout=self.pypi_timeout)
+            response.raise_for_status()
+            pypi_data = response.json()
+
+            info = pypi_data.get("info", {})
+
+            # Build response with PyPI data
+            result = {
+                "package_name": info.get("name", self.package_name),
+                "description": info.get("summary", "No description available"),
+                "version": info.get("version", "Unknown"),
+                "author": info.get("author", "Unknown"),
+                "license": info.get("license", "Not specified"),
+                "home_page": info.get("home_page", ""),
+                "documentation": info.get("project_urls", {}).get("Documentation", ""),
+                "repository": info.get("project_urls", {}).get(
+                    "Repository", info.get("project_urls", {}).get("Source", "")
+                ),
+                "python_versions": info.get("classifiers", []),
+                "keywords": (
+                    info.get("keywords", "").split(",") if info.get("keywords") else []
+                ),
+                "installation": {
+                    "pip": f"pip install {self.package_name}",
+                    "conda": f"conda install {self.package_name}",
+                    "pip_upgrade": f"pip install --upgrade {self.package_name}",
+                },
+                "source": "pypi",
+                "last_updated": pypi_data.get("last_serial", "Unknown"),
+            }
+
+            # Merge with local enhanced information
+            local_info = self.local_info
+            if local_info:
+                result["category"] = local_info.get("category", "General")
+                result["import_name"] = local_info.get("import_name", self.package_name)
+                result["popularity"] = local_info.get("popularity", 0)
+
+                # Override with better local descriptions if available
+                if local_info.get("description") and len(
+                    local_info["description"]
+                ) > len(result["description"]):
+                    result["description"] = local_info["description"]
+
+                # Add local documentation if PyPI doesn't have it
+                if not result["documentation"] and local_info.get("documentation"):
+                    result["documentation"] = local_info["documentation"]
+
+                # Add custom installation instructions
+                if local_info.get("installation"):
+                    result["installation"].update(local_info["installation"])
+
+            # Add examples if requested
+            if include_examples:
+                result["usage_example"] = self._get_usage_example()
+                result["quick_start"] = self._get_quick_start_guide()
+
+            return result
+
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"Failed to fetch from PyPI: {str(e)}")
+        except json.JSONDecodeError as e:
+            raise Exception(f"Failed to parse PyPI response: {str(e)}")
+
+    def _get_local_info(self, include_examples: bool = True) -> Dict[str, Any]:
+        """Get package information from local configuration"""
+        if not self.local_info:
+            return {
+                "error": f"No local information available for package '{self.package_name}'",
+                "package_name": self.package_name,
+            }
+
+        result = {
+            "package_name": self.local_info.get("name", self.package_name),
+            "description": self.local_info.get(
+                "description", "No description available"
+            ),
+            "version": self.local_info.get("version", "Check PyPI for latest"),
+            "category": self.local_info.get("category", "General"),
+            "license": self.local_info.get("license", "Not specified"),
+            "documentation": self.local_info.get("documentation", ""),
+            "repository": self.local_info.get("repository", ""),
+            "import_name": self.local_info.get("import_name", self.package_name),
+            "python_versions": self.local_info.get("python_versions", ["3.6+"]),
+            "dependencies": self.local_info.get("dependencies", []),
+            "popularity": self.local_info.get("popularity", 0),
+            "keywords": self.local_info.get("keywords", []),
+            "installation": self._get_installation_instructions(),
+            "source": "local",
+        }
+
+        if include_examples:
+            result["usage_example"] = self._get_usage_example()
+            result["quick_start"] = self._get_quick_start_guide()
+
+        return result
+
+    def _get_installation_instructions(self) -> Dict[str, str]:
+        """Generate installation instructions"""
+        custom_install = self.local_info.get("installation", {})
+
+        instructions = {
+            "pip": custom_install.get("pip", f"pip install {self.package_name}"),
+            "conda": custom_install.get("conda", f"conda install {self.package_name}"),
+            "pip_upgrade": f"pip install --upgrade {self.package_name}",
+        }
+
+        # Add additional installation methods if specified
+        if "additional" in custom_install:
+            instructions.update(custom_install["additional"])
+
+        return instructions
+
+    def _get_usage_example(self) -> str:
+        """Get usage example for the package"""
+        if self.local_info.get("usage_example"):
+            return self.local_info["usage_example"]
+
+        import_name = self.local_info.get("import_name", self.package_name)
+        return f"""# Basic usage example for {self.package_name}
+import {import_name}
+
+# Add your code here - check the documentation for specific usage
+print({import_name}.__version__)"""
+
+    def _get_quick_start_guide(self) -> list:
+        """Get quick start guide steps"""
+        if self.local_info.get("quick_start"):
+            return self.local_info["quick_start"]
+
+        import_name = self.local_info.get("import_name", self.package_name)
+        return [
+            f"1. Install the package: pip install {self.package_name}",
+            f"2. Import in your Python code: import {import_name}",
+            "3. Check the documentation for detailed usage examples",
+            "4. Start with basic examples and gradually explore advanced features",
+        ]

tooluniverse/pubchem_tool.py

@@ -0,0 +1,158 @@
+# pubchem_tool.py
+
+import requests
+import re
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+# Base URL for PubChem PUG-REST
+PUBCHEM_BASE_URL = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
+
+# Base URL for PubChem PUG-View
+PUBCHEM_PUGVIEW_URL = "https://pubchem.ncbi.nlm.nih.gov/rest/pug_view"
+
+
+@register_tool("PubChemRESTTool")
+class PubChemRESTTool(BaseTool):
+    """
+    Generic PubChem PUG-REST tool class.
+    Directly concatenates URL from the fields.endpoint template and sends requests to PubChem PUG-REST.
+    """
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        # Read endpoint template directly from fields config
+        self.endpoint_template = tool_config["fields"]["endpoint"]
+        # input_description and output_description might not be used, but kept for LLM reference
+        self.input_description = tool_config["fields"].get("input_description", "")
+        self.output_description = tool_config["fields"].get("output_description", "")
+        # If property_list exists, it will be used to replace {property_list} placeholder
+        self.property_list = tool_config["fields"].get("property_list", None)
+        # Parameter schema (properties may include required field)
+        self.param_schema = tool_config["parameter"]["properties"]
+        self.use_pugview = tool_config["fields"].get("use_pugview", False)
+        self.output_format = tool_config["fields"].get("return_format", None)
+
+    def _build_url(self, arguments: dict) -> str:
+        """
+        Use regex to replace all {placeholder} in endpoint_template to generate complete URL path.
+        For example endpoint_template="/compound/cid/{cid}/property/{property_list}/JSON"
+        arguments={"cid":2244}, property_list=["MolecularWeight","IUPACName"]
+        → "/compound/cid/2244/property/MolecularWeight,IUPACName/JSON"
+        Finally returns "https://pubchem.ncbi.nlm.nih.gov/rest/pug" + concatenated path.
+        """
+        url_path = self.endpoint_template
+
+        # First replace property_list (if exists and endpoint_template contains this placeholder)
+        if self.property_list and "{property_list}" in url_path:
+            prop_str = ",".join(self.property_list)
+            url_path = url_path.replace("{property_list}", prop_str)
+
+        # Find all placeholders {xxx} in template
+        placeholders = re.findall(r"\{([^{}]+)\}", url_path)
+        for ph in placeholders:
+            if ph not in arguments:
+                # If a placeholder cannot find corresponding value in arguments, report error
+                raise ValueError(
+                    f"Missing required parameter '{ph}' to replace placeholder in URL."
+                )
+            val = arguments[ph]
+            # If input value is a list, join with commas
+            if isinstance(val, list):
+                val_str = ",".join(map(str, val))
+            else:
+                val_str = str(val)
+            url_path = url_path.replace(f"{{{ph}}}", val_str)
+
+        # Handle xref_types parameter
+        if "xref_types" in arguments:
+            xref_list = ",".join(arguments["xref_types"])
+            url_path = url_path.replace("{xref_list}", xref_list)
+
+        # Finally combine into complete URL
+        if self.use_pugview:
+            full_url = PUBCHEM_PUGVIEW_URL + url_path
+        else:
+            full_url = PUBCHEM_BASE_URL + url_path
+
+        # Handle special parameters
+        if "threshold" in arguments:
+            # Convert 0-1 threshold to 0-100 integer
+            threshold = float(arguments["threshold"])
+            if 0 <= threshold <= 1:
+                threshold = int(threshold * 100)
+            # Add threshold parameter to URL
+            if "?" in full_url:
+                full_url += f"&Threshold={threshold}"
+            else:
+                full_url += f"?Threshold={threshold}"
+
+        return full_url
+
+    def run(self, arguments: dict):
+        # 1. Validate required parameters
+        for key, prop in self.param_schema.items():
+            if prop.get("required", False) and key not in arguments:
+                return {"error": f"Parameter '{key}' is required."}
+
+        # 2. Build URL
+        try:
+            url = self._build_url(arguments)
+        except ValueError as e:
+            return {"error": str(e)}
+
+        # 3. Send HTTP GET request
+        try:
+            # Increase timeout to 30 seconds and add MaxRecords parameter to limit results
+            if "fastsubstructure" in url or "fastsimilarity" in url:
+                if "?" in url:
+                    url += "&MaxRecords=10"
+                else:
+                    url += "?MaxRecords=10"
+
+            resp = requests.get(url, timeout=30)
+        except requests.Timeout:
+            return {
+                "error": "Request to PubChem PUG-REST timed out, try reducing query scope or retry later."
+            }
+        except Exception as e:
+            return {"error": f"Failed to request PubChem PUG-REST: {str(e)}"}
+
+        # 4. Check HTTP status code
+        if resp.status_code != 200:
+            error_detail = resp.text
+            try:
+                error_json = resp.json()
+                if "Fault" in error_json:
+                    error_detail = error_json["Fault"].get("Message", error_detail)
+            except Exception:
+                pass
+            return {
+                "error": f"PubChem API returned HTTP {resp.status_code}",
+                "detail": error_detail,
+            }
+
+        # 5. Determine return type based on URL suffix
+        #    Look at the text after the last slash in endpoint_template, like "JSON","PNG","XML","TXT","CSV"
+        if self.output_format:
+            out_fmt = self.output_format
+        else:
+            out_fmt = self.endpoint_template.strip("/").split("/")[-1].upper()
+
+        if out_fmt == "JSON":
+            try:
+                return resp.json()
+            except ValueError:
+                return {
+                    "error": "Response content cannot be parsed as JSON.",
+                    "content": resp.text,
+                }
+        elif out_fmt in ["XML", "TXT", "CSV", "SDF"]:
+            # These are all text formats
+            return resp.text
+        elif out_fmt in ["PNG", "SVG"]:
+            # Return binary image
+            return resp.content
+        else:
+            # Return text for other cases
+            return resp.text

tooluniverse/pubtator_tool.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import requests
+
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+# Official REST root  (cf. NIH “entity autocomplete” & “search” examples)
+BASE_URL = "https://www.ncbi.nlm.nih.gov/research/pubtator3-api"
+CONFIG_FILE = Path(__file__).with_name("pubtator_tool_config.json")
+
+
+@register_tool("PubTatorTool")
+class PubTatorTool(BaseTool):
+    """Generic wrapper around a single PubTator 3 endpoint supporting JSON-defined configs."""
+
+    def __init__(self, tool_config: Dict[str, Any]):
+        super().__init__(tool_config)
+        self._method: str = tool_config.get("method", "GET").upper()
+        self._path: str = tool_config["endpoint_path"]
+        self._param_map: Dict[str, str] = tool_config.get("param_map", {})
+        self._body_param: Optional[str] = tool_config.get("body_param")
+        self._id_in_path_key: Optional[str] = tool_config.get("id_in_path")
+
+        fields = tool_config.get("fields", {})
+        if "body_param" in fields:
+            self._body_param = fields["body_param"]
+        self._tool_subtype: str = fields.get("tool_subtype", "")
+
+    # ------------------------------------------------------------------ public API --------------
+    def run(self, arguments: Dict[str, Any]):
+        args = arguments.copy()
+        # Special case for PubTatorRelation: combine parameters into a single "text" parameter and use "/search/" endpoint.
+        if self._tool_subtype == "PubTatorRelation":
+            subject = args.pop("subject_id", None)
+            obj = args.pop("object", None)
+            rel_type = args.pop("relation_type", None)
+            if not subject or not obj:
+                raise ValueError(
+                    "Missing required parameters 'subject_id' or 'object' for relation search."
+                )
+            text_value = f"relations:{subject},{obj}"
+            if rel_type:
+                text_value += f",{rel_type}"
+            new_args = {"text": text_value}
+            new_args.update(args)
+            url = f"{BASE_URL.rstrip('/')}/search/"
+            data = None
+            headers: Dict[str, str] = {}
+            response = requests.request(
+                self._method,
+                url,
+                params=self._query_params(new_args),
+                data=data,
+                headers=headers,
+                timeout=30,
+            )
+            response.raise_for_status()
+            ctype = response.headers.get("Content-Type", "").lower()
+            if "json" in ctype:
+                return response.json()
+            if "text" in ctype or "xml" in ctype:
+                return response.text
+            return response.content
+
+        # Special handling for PubTatorAnnotate: override endpoint paths
+        if self._tool_subtype == "PubTatorAnnotate":
+            if self._method == "POST":
+                url = f"{BASE_URL.rstrip('/')}/annotations/annotate"
+            else:
+                url = f"{BASE_URL.rstrip('/')}/annotations/retrieve"
+        else:
+            url = self._compose_url(args)
+
+        # ---------- body handling for POST calls ----------
+        data: Optional[bytes] = None
+        headers: Dict[str, str] = {}
+        if self._method == "POST":
+            if self._body_param:
+                if self._body_param not in args:
+                    raise ValueError(
+                        f"Missing required body parameter '{self._body_param}'."
+                    )
+                data = str(args.pop(self._body_param)).encode("utf-8")
+                headers["Content-Type"] = "text/plain; charset=utf-8"
+            else:
+                data = json.dumps(args).encode()
+                args.clear()
+                headers["Content-Type"] = "application/json"
+
+        # ---------- perform request ----------
+        response = requests.request(
+            self._method,
+            url,
+            params=self._query_params(args) if self._method != "POST" else {},
+            data=data,
+            headers=headers,
+            timeout=30,
+        )
+        if not response.ok:
+            return {
+                "error": f"Request failed with status code {response.status_code}: {response.text}"
+            }
+
+        # ---------- auto-detect & return ----------
+        ctype = response.headers.get("Content-Type", "").lower()
+        if "json" in ctype:
+            result = response.json()
+            # Extra filtering for PubTatorSearch: filter low-score items and facets.
+            if self._tool_subtype == "PubTatorSearch" and isinstance(result, dict):
+                result = self._filter_search_results(result)
+            return result
+        if "text" in ctype or "xml" in ctype:
+            return response.text
+        return response.content
+
+    # ------------------------------------------------------------------ helpers -----------------
+    def _compose_url(self, args: Dict[str, Any]) -> str:
+        """Substitute template vars & build full URL."""
+        path = self._path
+        for placeholder in re.findall(r"{(.*?)}", path):
+            if placeholder not in args:
+                raise ValueError(f"Missing URL placeholder argument '{placeholder}'.")
+            path = path.replace(f"{{{placeholder}}}", str(args.pop(placeholder)))
+
+        if self._id_in_path_key and self._id_in_path_key in args:
+            ids_val = args.pop(self._id_in_path_key)
+            if isinstance(ids_val, (list, tuple)):
+                ids_val = ",".join(map(str, ids_val))
+            path = f"{path}/{ids_val}"
+
+        return f"{BASE_URL.rstrip('/')}/{path.lstrip('/')}"
+
+    def _query_params(self, args: Dict[str, Any]) -> Dict[str, str]:
+        """Translate caller arg names → API param names, drop Nones, serialise lists."""
+        q: Dict[str, str] = {}
+        for user_key, val in args.items():
+            if val is None:
+                continue
+            api_key = self._param_map.get(user_key, user_key)
+            if isinstance(val, (list, tuple)):
+                val = ",".join(map(str, val))
+            q[api_key] = str(val)
+        return q
+
+    def _filter_search_results(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        """Filter PubTatorSearch results by score threshold and remove facet items that only have 'name', 'type', and 'value'."""
+        # Filter result items based on score threshold.
+        threshold = 230  # Adjust threshold as needed
+        if "results" in result and isinstance(result["results"], list):
+            filtered_results = []
+            for item in result["results"]:
+                score = item.get("score")
+                # If there's a numeric score and it's below threshold, skip the item.
+                if isinstance(score, (int, float)) and score < threshold:
+                    continue
+                filtered_results.append(item)
+            result["results"] = filtered_results
+
+        # Also filter facets as before.
+        if "facets" in result and isinstance(result["facets"], dict):
+            del result["facets"]
+        return result

tooluniverse/rcsb_pdb_tool.py

@@ -0,0 +1,38 @@
+from rcsbapi.data import DataQuery
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+
+@register_tool("RCSBTool")
+class RCSBTool(BaseTool):
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        self.name = tool_config.get("name")
+        self.description = tool_config.get("description")
+        self.input_type = tool_config.get("input_type")
+        self.search_fields = tool_config.get("fields", {}).get("search_fields", {})
+        self.return_fields = tool_config.get("fields", {}).get("return_fields", [])
+        self.parameter_schema = tool_config.get("parameter", {}).get("properties", {})
+
+    def validate_params(self, params: dict):
+        for param_name, param_info in self.parameter_schema.items():
+            if param_info.get("required", False) and param_name not in params:
+                raise ValueError(f"Missing required parameter: {param_name}")
+        return True
+
+    def prepare_input_ids(self, params: dict):
+        for param_name in self.search_fields:
+            if param_name in params:
+                val = params[param_name]
+                return val if isinstance(val, list) else [val]
+        raise ValueError("No valid search parameter provided")
+
+    def run(self, params: dict):
+        self.validate_params(params)
+        input_ids = self.prepare_input_ids(params)
+        query = DataQuery(
+            input_type=self.input_type,
+            input_ids=input_ids,
+            return_data_list=self.return_fields,
+        )
+        return query.exec()

tooluniverse/reactome_tool.py

@@ -0,0 +1,108 @@
+# reactome_graph_tool.py
+
+import requests
+import re
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+# Reactome Content Service Base URL
+REACTOME_BASE_URL = "https://reactome.org/ContentService"
+
+
+@register_tool("ReactomeRESTTool")
+class ReactomeRESTTool(BaseTool):
+    """
+    Generic Reactome Content Service REST tool.
+    If there is no "fields.extract_path" in config or its value is empty, returns complete JSON;
+    Otherwise, drills down according to the "dot-separated path" in extract_path and returns corresponding sub-node.
+    """
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+        self.endpoint_template = tool_config["endpoint"]  # e.g. "/data/pathway/{stId}"
+        self.method = tool_config.get("method", "GET").upper()  # Default to GET
+        self.param_schema = tool_config["parameter"][
+            "properties"
+        ]  # Parameter schema (including required)
+        self.required_params = tool_config["parameter"].get(
+            "required", []
+        )  # List of required parameters
+        # If config has fields and it contains extract_path, take it. Otherwise None.
+        self.extract_path = None
+        if "fields" in tool_config and isinstance(tool_config["fields"], dict):
+            ep = tool_config["fields"].get("extract_path", None)
+            if ep is not None and isinstance(ep, str) and ep.strip() != "":
+                # Only effective when extract_path is a non-empty string
+                self.extract_path = ep.strip()
+
+    def _build_url(self, arguments: dict) -> str:
+        """
+        Combines endpoint_template (containing {xxx}) with path parameters from arguments to generate complete URL.
+        For example endpoint_template="/data/pathway/{stId}", arguments={"stId":"R-HSA-73817"}
+        → Returns "https://reactome.org/ContentService/data/pathway/R-HSA-73817"
+        """
+        url_path = self.endpoint_template
+        # Find all {xxx} placeholders and replace with values from arguments
+        for key in re.findall(r"\{([^{}]+)\}", self.endpoint_template):
+            if key not in arguments:
+                raise ValueError(f"Missing path parameter '{key}'")
+            url_path = url_path.replace(f"{{{key}}}", str(arguments[key]))
+        return REACTOME_BASE_URL + url_path
+
+    def run(self, arguments: dict):
+        # 1. Validate required parameters (check from required_params list)
+        for required_param in self.required_params:
+            if required_param not in arguments:
+                return {"error": f"Parameter '{required_param}' is required."}
+
+        # 2. Build URL, replace {xxx} placeholders
+        try:
+            url = self._build_url(arguments)
+        except ValueError as e:
+            return {"error": str(e)}
+
+        # 3. Find remaining arguments besides path parameters as query parameters
+        path_keys = re.findall(r"\{([^{}]+)\}", self.endpoint_template)
+        query_params = {}
+        for k, v in arguments.items():
+            if k not in path_keys:
+                query_params[k] = v
+
+        # 4. Make HTTP request
+        try:
+            if self.method == "GET":
+                resp = requests.get(url, params=query_params, timeout=10)
+            else:
+                # If POST support needed in future, can extend here
+                resp = requests.post(url, json=query_params, timeout=10)
+        except Exception as e:
+            return {"error": f"Failed to request Reactome Content Service: {str(e)}"}
+
+        # 5. Check HTTP status code
+        if resp.status_code != 200:
+            return {
+                "error": f"Reactome API returned HTTP {resp.status_code}",
+                "detail": resp.text,
+            }
+
+        # 6. Parse JSON
+        try:
+            data = resp.json()
+        except ValueError:
+            return {
+                "error": "Unable to parse Reactome returned JSON.",
+                "content": resp.text,
+            }
+
+        # 7. If no extract_path in config, return complete JSON
+        if not self.extract_path:
+            return data
+
+        # 8. Otherwise drill down according to "dot-separated path" in extract_path
+        fragment = data
+        for part in self.extract_path.split("."):
+            if isinstance(fragment, dict) and part in fragment:
+                fragment = fragment[part]
+            else:
+                return {"error": f"Path '{self.extract_path}' not found in JSON."}
+        return fragment