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

tooluniverse/extended_hooks.py

@@ -0,0 +1,444 @@
+"""
+Extended Hook Types for ToolUniverse
+
+This module demonstrates how to extend the hook system with additional
+hook types beyond summarization. It shows the pattern for creating
+new hook types while maintaining compatibility with the existing system.
+"""
+
+import re
+import json
+from typing import Dict, Any, List
+from .output_hook import OutputHook
+
+
+class FilteringHook(OutputHook):
+    """
+    Hook for filtering sensitive or unwanted content from tool outputs.
+
+    This hook can be used to:
+    - Remove sensitive information (emails, phones, SSNs)
+    - Filter inappropriate content
+    - Sanitize data before display
+
+    Args:
+        config (Dict[str, Any]): Hook configuration containing filter settings
+        tooluniverse: Optional ToolUniverse instance (not used for filtering)
+    """
+
+    def __init__(self, config: Dict[str, Any], tooluniverse=None):
+        """
+        Initialize the filtering hook with configuration.
+
+        Args:
+            config (Dict[str, Any]): Hook configuration
+            tooluniverse: ToolUniverse instance (optional, not used)
+        """
+        super().__init__(config)
+        hook_config = config.get("hook_config", {})
+
+        # Filter configuration
+        self.filter_patterns = hook_config.get("filter_patterns", [])
+        self.replacement_text = hook_config.get("replacement_text", "[REDACTED]")
+        self.preserve_structure = hook_config.get("preserve_structure", True)
+        self.log_filtered_items = hook_config.get("log_filtered_items", False)
+
+        # Compile regex patterns for efficiency
+        self.compiled_patterns = []
+        for pattern in self.filter_patterns:
+            try:
+                compiled = re.compile(pattern, re.IGNORECASE)
+                self.compiled_patterns.append(compiled)
+            except re.error as e:
+                print(f"Warning: Invalid regex pattern '{pattern}': {e}")
+
+    def process(
+        self,
+        result: Any,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """
+        Apply filtering to the tool output.
+
+        Args:
+            result (Any): The tool output to filter
+            tool_name (str): Name of the tool that produced the output
+            arguments (Dict[str, Any]): Arguments passed to the tool
+            context (Dict[str, Any]): Additional context information
+
+        Returns:
+            Any: The filtered output, or original output if filtering fails
+        """
+        try:
+            if not self.compiled_patterns:
+                return result
+
+            output_str = result if isinstance(result, str) else str(result)
+            filtered_output = output_str
+            filtered_count = 0
+
+            # Apply each filter pattern
+            for pattern in self.compiled_patterns:
+                matches = pattern.findall(filtered_output)
+                if matches:
+                    filtered_count += len(matches)
+                    if self.log_filtered_items:
+                        print(
+                            f"🔒 Filtered {len(matches)} items matching pattern: {pattern.pattern}"
+                        )
+
+                    filtered_output = pattern.sub(
+                        self.replacement_text, filtered_output
+                    )
+
+            if filtered_count > 0:
+                print(
+                    f"🔒 FilteringHook: Filtered {filtered_count} sensitive items from {tool_name} output"
+                )
+
+            return filtered_output
+
+        except Exception as e:
+            print(f"Error in filtering hook: {str(e)}")
+            return result
+
+
+class FormattingHook(OutputHook):
+    """
+    Hook for formatting and beautifying tool outputs.
+
+    This hook can be used to:
+    - Pretty-print JSON/XML outputs
+    - Format text with proper indentation
+    - Standardize output formats
+
+    Args:
+        config (Dict[str, Any]): Hook configuration containing formatting settings
+        tooluniverse: Optional ToolUniverse instance (not used for formatting)
+    """
+
+    def __init__(self, config: Dict[str, Any], tooluniverse=None):
+        """
+        Initialize the formatting hook with configuration.
+
+        Args:
+            config (Dict[str, Any]): Hook configuration
+            tooluniverse: ToolUniverse instance (optional, not used)
+        """
+        super().__init__(config)
+        hook_config = config.get("hook_config", {})
+
+        # Formatting configuration
+        self.indent_size = hook_config.get("indent_size", 2)
+        self.sort_keys = hook_config.get("sort_keys", True)
+        self.ensure_ascii = hook_config.get("ensure_ascii", False)
+        self.max_line_length = hook_config.get("max_line_length", 100)
+        self.pretty_print = hook_config.get("pretty_print", True)
+
+    def process(
+        self,
+        result: Any,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """
+        Apply formatting to the tool output.
+
+        Args:
+            result (Any): The tool output to format
+            tool_name (str): Name of the tool that produced the output
+            arguments (Dict[str, Any]): Arguments passed to the tool
+            context (Dict[str, Any]): Additional context information
+
+        Returns:
+            Any: The formatted output, or original output if formatting fails
+        """
+        try:
+            if isinstance(result, dict):
+                return self._format_json(result)
+            elif isinstance(result, str):
+                return self._format_text(result)
+            elif isinstance(result, list):
+                return self._format_list(result)
+            else:
+                return result
+
+        except Exception as e:
+            print(f"Error in formatting hook: {str(e)}")
+            return result
+
+    def _format_json(self, data: Dict[str, Any]) -> str:
+        """Format JSON data with pretty printing."""
+        if self.pretty_print:
+            return json.dumps(
+                data,
+                indent=self.indent_size,
+                sort_keys=self.sort_keys,
+                ensure_ascii=self.ensure_ascii,
+            )
+        return json.dumps(data, ensure_ascii=self.ensure_ascii)
+
+    def _format_text(self, text: str) -> str:
+        """Format plain text with line wrapping."""
+        if len(text) <= self.max_line_length:
+            return text
+
+        # Simple line wrapping
+        lines = []
+        current_line = ""
+
+        for word in text.split():
+            if len(current_line + " " + word) <= self.max_line_length:
+                current_line += (" " + word) if current_line else word
+            else:
+                if current_line:
+                    lines.append(current_line)
+                current_line = word
+
+        if current_line:
+            lines.append(current_line)
+
+        return "\n".join(lines)
+
+    def _format_list(self, data: List[Any]) -> str:
+        """Format list data."""
+        if self.pretty_print:
+            formatted_items = []
+            for i, item in enumerate(data):
+                if isinstance(item, dict):
+                    formatted_items.append(f"{i+1}. {self._format_json(item)}")
+                else:
+                    formatted_items.append(f"{i+1}. {str(item)}")
+            return "\n".join(formatted_items)
+        return str(data)
+
+
+class ValidationHook(OutputHook):
+    """
+    Hook for validating tool outputs against schemas or rules.
+
+    This hook can be used to:
+    - Validate JSON against schemas
+    - Check required fields
+    - Ensure data quality
+
+    Args:
+        config (Dict[str, Any]): Hook configuration containing validation settings
+        tooluniverse: Optional ToolUniverse instance (not used for validation)
+    """
+
+    def __init__(self, config: Dict[str, Any], tooluniverse=None):
+        """
+        Initialize the validation hook with configuration.
+
+        Args:
+            config (Dict[str, Any]): Hook configuration
+            tooluniverse: ToolUniverse instance (optional, not used)
+        """
+        super().__init__(config)
+        hook_config = config.get("hook_config", {})
+
+        # Validation configuration
+        self.validation_schema = hook_config.get("validation_schema", None)
+        self.strict_mode = hook_config.get("strict_mode", True)
+        self.error_action = hook_config.get("error_action", "warn")  # warn, fix, fail
+        self.required_fields = hook_config.get("required_fields", [])
+
+    def process(
+        self,
+        result: Any,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """
+        Apply validation to the tool output.
+
+        Args:
+            result (Any): The tool output to validate
+            tool_name (str): Name of the tool that produced the output
+            arguments (Dict[str, Any]): Arguments passed to the tool
+            context (Dict[str, Any]): Additional context information
+
+        Returns:
+            Any: The validated output, or original output if validation fails
+        """
+        try:
+            validation_result = self._validate_output(result)
+
+            if validation_result["valid"]:
+                if validation_result["warnings"]:
+                    print(
+                        f"✅ ValidationHook: {tool_name} output validated with warnings"
+                    )
+                else:
+                    print(
+                        f"✅ ValidationHook: {tool_name} output validated successfully"
+                    )
+                return result
+            else:
+                if self.error_action == "fail":
+                    print(f"❌ ValidationHook: {tool_name} output validation failed")
+                    return result
+                elif self.error_action == "fix":
+                    fixed_result = self._fix_output(result, validation_result["errors"])
+                    print(
+                        f"🔧 ValidationHook: Fixed {tool_name} output based on validation errors"
+                    )
+                    return fixed_result
+                else:  # warn
+                    print(f"⚠️ ValidationHook: {tool_name} output has validation issues")
+                    return result
+
+        except Exception as e:
+            print(f"Error in validation hook: {str(e)}")
+            return result
+
+    def _validate_output(self, result: Any) -> Dict[str, Any]:
+        """Validate the output against configured rules."""
+        validation_result = {"valid": True, "errors": [], "warnings": []}
+
+        # Check required fields for dict outputs
+        if isinstance(result, dict) and self.required_fields:
+            for field in self.required_fields:
+                if field not in result:
+                    validation_result["errors"].append(
+                        f"Missing required field: {field}"
+                    )
+                    validation_result["valid"] = False
+
+        # Add schema validation here if needed
+        # This would integrate with jsonschema or similar libraries
+
+        return validation_result
+
+    def _fix_output(self, result: Any, errors: List[str]) -> Any:
+        """Attempt to fix validation errors."""
+        # Simple fixes for common issues
+        if isinstance(result, dict):
+            fixed_result = result.copy()
+
+            for error in errors:
+                if "Missing required field" in error:
+                    field_name = error.split(": ")[1]
+                    fixed_result[field_name] = None  # Add missing field with None value
+
+            return fixed_result
+
+        return result
+
+
+class LoggingHook(OutputHook):
+    """
+    Hook for logging tool outputs and execution details.
+
+    This hook can be used to:
+    - Log all tool outputs
+    - Track execution metrics
+    - Audit tool usage
+
+    Args:
+        config (Dict[str, Any]): Hook configuration containing logging settings
+        tooluniverse: Optional ToolUniverse instance (not used for logging)
+    """
+
+    def __init__(self, config: Dict[str, Any], tooluniverse=None):
+        """
+        Initialize the logging hook with configuration.
+
+        Args:
+            config (Dict[str, Any]): Hook configuration
+            tooluniverse: ToolUniverse instance (optional, not used)
+        """
+        super().__init__(config)
+        hook_config = config.get("hook_config", {})
+
+        # Logging configuration
+        self.log_level = hook_config.get("log_level", "INFO")
+        self.log_format = hook_config.get(
+            "log_format", "detailed"
+        )  # simple, detailed, json
+        self.log_file = hook_config.get("log_file", None)
+        self.max_log_size = hook_config.get("max_log_size", 1000)  # characters
+
+    def process(
+        self,
+        result: Any,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """
+        Log the tool output and execution details.
+
+        Args:
+            result (Any): The tool output to log
+            tool_name (str): Name of the tool that produced the output
+            arguments (Dict[str, Any]): Arguments passed to the tool
+            context (Dict[str, Any]): Additional context information
+
+        Returns:
+            Any: The original output (logging doesn't modify the output)
+        """
+        try:
+            log_entry = self._create_log_entry(result, tool_name, arguments, context)
+            self._write_log(log_entry)
+
+        except Exception as e:
+            print(f"Error in logging hook: {str(e)}")
+
+        # Logging hook always returns the original result unchanged
+        return result
+
+    def _create_log_entry(
+        self,
+        result: Any,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> str:
+        """Create a log entry for the tool execution."""
+        if self.log_format == "simple":
+            return f"Tool: {tool_name} | Args: {arguments} | Output length: {len(str(result))}"
+        elif self.log_format == "json":
+            return json.dumps(
+                {
+                    "tool_name": tool_name,
+                    "arguments": arguments,
+                    "output_length": len(str(result)),
+                    "timestamp": context.get("execution_time", "unknown"),
+                    "output_preview": str(result)[: self.max_log_size],
+                }
+            )
+        else:  # detailed
+            return f"""
+Tool Execution Log:
+==================
+Tool: {tool_name}
+Arguments: {arguments}
+Execution Time: {context.get('execution_time', 'unknown')}
+Output Length: {len(str(result))} characters
+Output Preview: {str(result)[:self.max_log_size]}{'...' if len(str(result)) > self.max_log_size else ''}
+==================
+"""
+
+    def _write_log(self, log_entry: str):
+        """Write the log entry to the configured destination."""
+        if self.log_file:
+            with open(self.log_file, "a", encoding="utf-8") as f:
+                f.write(log_entry + "\n")
+        else:
+            print(f"📝 Log: {log_entry}")
+
+
+# Hook type registry for easy extension
+HOOK_TYPE_REGISTRY = {
+    "SummarizationHook": "SummarizationHook",  # Import from parent module
+    "FilteringHook": FilteringHook,
+    "FormattingHook": FormattingHook,
+    "ValidationHook": ValidationHook,
+    "LoggingHook": LoggingHook,
+}

tooluniverse/gene_ontology_tool.py

@@ -0,0 +1,194 @@
+import requests
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+
+@register_tool("GeneOntologyTool")
+class GeneOntologyTool(BaseTool):
+    """
+    A general-purpose tool for calling the Gene Ontology (GO) API.
+    It is configured via a dictionary that defines the specific API endpoint.
+    """
+
+    def __init__(self, tool_config: Dict):
+        """
+        Initializes the tool with a configuration.
+
+        Args:
+            tool_config (Dict): A dictionary containing 'fields' with an 'endpoint'.
+        """
+        super().__init__(tool_config)
+        self.endpoint = tool_config["fields"]["endpoint"]
+        self.extract_path = tool_config["fields"].get("extract_path")
+        self.timeout = 20
+
+    def _build_url(self, args: Dict[str, Any]) -> str:
+        """Builds the request URL from arguments."""
+        url = self.endpoint
+        for key, value in args.items():
+            url = url.replace(f"{{{key}}}", quote(str(value)))
+        return url
+
+    def _extract_data(self, data: Dict, extract_path: str) -> Any:
+        """Extract specific data from the GO API response using custom paths."""
+
+        if extract_path == "response.docs[0]":
+            # Extract single document from GOlr response
+            response = data.get("response", {})
+            docs = response.get("docs", [])
+            if docs:
+                return docs[0]
+            else:
+                return {"error": "No GO term found"}
+
+        elif extract_path == "response.docs":
+            # Extract all documents from GOlr response
+            response = data.get("response", {})
+            docs = response.get("docs", [])
+            return docs
+
+        elif extract_path == "associations[*].subject":
+            # Extract gene/protein information from Biolink associations
+            result = []
+            # Handle both dict with associations and direct list from Biolink API
+            if isinstance(data, list):
+                # Direct list of associations from Biolink API
+                associations = data
+            else:
+                # Dictionary response with associations key
+                associations = data.get("associations", [])
+
+            for assoc in associations:
+                subject = assoc.get("subject", {})
+                result.append(subject)
+            return result
+
+        # For simple paths, try direct access
+        try:
+            if "." in extract_path:
+                keys = extract_path.split(".")
+                result = data
+                for key in keys:
+                    if "[" in key and "]" in key:
+                        # Handle array indexing like "docs[0]"
+                        array_key = key.split("[")[0]
+                        index_str = key.split("[")[1].split("]")[0]
+                        result = result.get(array_key, [])
+                        if index_str.isdigit():
+                            index = int(index_str)
+                            if index < len(result):
+                                result = result[index]
+                            else:
+                                return {"error": f"Index {index} out of range"}
+                        else:
+                            return {"error": f"Invalid array index: {index_str}"}
+                    else:
+                        result = result.get(key, {})
+                return result
+            else:
+                return data.get(extract_path)
+        except Exception as e:
+            return {"error": f"Failed to extract data using path '{extract_path}': {e}"}
+
+    def run(self, arguments: Any = None) -> Any:
+        """
+        Executes the API call and returns the data.
+
+        Args:
+            arguments (Dict[str, Any]): Parameters for the API call.
+
+        Returns:
+            Any: The JSON data from the API or an error dictionary.
+        """
+        # Normalize arguments
+        if arguments is None:
+            arguments = {}
+        if not isinstance(arguments, dict):
+            return {"error": "Invalid arguments type; expected a mapping/dict."}
+
+        # Handle different endpoint formats
+        if "?" in self.endpoint:
+            # This is a complete URL with query parameters (GOlr format)
+            url = self.endpoint
+            for key, value in arguments.items():
+                url = url.replace(f"{{{key}}}", quote(str(value)))
+            params = {}
+        else:
+            # This is a template URL (Biolink format)
+            url_args = arguments.copy()
+            params = {}
+
+            # Move query parameters to params dict for Biolink API
+            if "taxon" in arguments:
+                params["taxon"] = url_args.pop("taxon")
+            if "rows" in arguments:
+                params["rows"] = url_args.pop("rows")
+            if "start" in arguments:
+                params["start"] = url_args.pop("start")
+
+            # Build URL with remaining arguments
+            url = self._build_url(url_args)
+
+        try:
+            resp = requests.get(
+                url,
+                params=params,
+                timeout=self.timeout,
+                headers={"Accept": "application/json"},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                return {
+                    "error": "The requested resource was not found (404 Not Found)."
+                }
+            return {
+                "error": f"GO API request failed with HTTP status: {e.response.status_code}",
+                "detail": e.response.text,
+            }
+        except requests.exceptions.RequestException as e:
+            return {
+                "error": f"A network error occurred while requesting the GO API: {e}"
+            }
+        except ValueError:
+            return {
+                "error": "Failed to parse GO API response, which may not be valid JSON.",
+                "content": resp.text,
+            }
+
+        # If extract_path is configured, extract the corresponding subset
+        if self.extract_path:
+            result = self._extract_data(data, self.extract_path)
+
+            # Handle empty results
+            if isinstance(result, list) and len(result) == 0:
+                return {"error": f"No data found for path: {self.extract_path}"}
+            elif isinstance(result, dict) and "error" in result:
+                return result
+
+            return result
+
+        return data
+
+    # Method bindings for backward compatibility and convenience
+    def search_terms(self, query: str) -> Any:
+        return self.run({"query": query})
+
+    def get_term_details(self, id: str) -> Any:
+        return self.run({"id": id})
+
+    def get_genes_for_term(
+        self, id: str, taxon: Optional[str] = None, rows: Optional[int] = None
+    ) -> Any:
+        args = {"id": id}
+        if taxon:
+            args["taxon"] = taxon
+        if rows:
+            args["rows"] = rows
+        return self.run(args)
+
+    def get_terms_for_gene(self, id: str) -> Any:
+        return self.run({"id": id})