tooluniverse 0.1.4__py3-none-any.whl → 1.0.0__py3-none-any.whl

tooluniverse/humanbase_tool.py

@@ -0,0 +1,389 @@
+import networkx as nx
+import requests
+import urllib.parse
+from .base_tool import BaseTool
+from .tool_registry import register_tool
+
+
+@register_tool("HumanBaseTool")
+class HumanBaseTool(BaseTool):
+    """
+    Tool to retrieve protein-protein interactions and biological processes from HumanBase.
+    """
+
+    def __init__(self, tool_config):
+        super().__init__(tool_config)
+
+    def run(self, arguments):
+        """Main entry point for the tool."""
+        gene_list = arguments.get("gene_list")
+        tissue = arguments.get("tissue", "brain")
+        max_node = arguments.get("max_node", 10)
+        interaction = arguments.get("interaction", None)
+        string_mode = arguments.get("string_mode", True)
+
+        graph, bp_collection = self.humanbase_ppi_retrieve(
+            gene_list, tissue, max_node, interaction
+        )
+
+        if string_mode:
+            return self._convert_to_string(graph, bp_collection, gene_list, tissue)
+        else:
+            return graph, bp_collection
+
+    def get_official_gene_name(self, gene_name):
+        """
+        Retrieve the official gene symbol (same as EnrichrTool method)
+
+        Parameters:
+            gene_name (str): The gene name or synonym to query.
+
+        Returns:
+            str: The official gene symbol.
+        """
+        """
+        Retrieve the official gene symbol for a given gene name or synonym using the MyGene.info API.
+
+        Parameters:
+            gene_name (str): The gene name or synonym to query.
+
+        Returns:
+            str: The official gene symbol if found; otherwise, raises an Exception.
+        """
+        # URL-encode the gene_name to handle special characters
+        encoded_gene_name = urllib.parse.quote(gene_name)
+        url = f"https://mygene.info/v3/query?q={encoded_gene_name}&fields=symbol,alias&species=human"
+
+        response = requests.get(url)
+        if response.status_code != 200:
+            return f"Error querying MyGene.info API: {response.status_code}"
+
+        data = response.json()
+        hits = data.get("hits", [])
+        if not hits:
+            return f"No data found for: {gene_name}. Please check the gene name and try again."
+
+        # Attempt to find an exact match in the official symbol or among aliases.
+        for hit in hits:
+            symbol = hit.get("symbol", "")
+            if symbol.upper() == gene_name.upper():
+                print(
+                    f"[humanbase_tool] Using the official gene name: '{symbol}' instead of {gene_name}",
+                    flush=True,
+                )
+                return symbol
+            aliases = hit.get("alias", [])
+            if any(gene_name.upper() == alias.upper() for alias in aliases):
+                print(
+                    f"[humanbase_tool] Using the official gene name: '{symbol}' instead of {gene_name}",
+                    flush=True,
+                )
+                return symbol
+
+        # If no exact match is found, return the symbol of the top hit.
+        top_hit = hits[0]
+        symbol = top_hit.get("symbol", None)
+        if symbol:
+            print(
+                f"[humanbase_tool] Using the official gene name: '{symbol}' instead of {gene_name}",
+                flush=True,
+            )
+            return symbol
+        else:
+            return f"No official gene symbol found for: {gene_name}. Please ensure it is correct."
+
+    def get_entrez_ids(self, gene_names):
+        """
+        Convert gene names to Entrez IDs using NCBI Entrez API.
+
+        Parameters:
+            gene_names (list): List of gene names to convert.
+
+        Returns:
+            list: List of Entrez IDs corresponding to the gene names.
+        """
+        # Define the NCBI Entrez API URL for querying gene information
+        url = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi"
+
+        # Initialize a list to store Entrez IDs
+        entrez_ids = []
+        gene_names = [self.get_official_gene_name(gene) for gene in gene_names]
+
+        # Loop over each gene name in the input list
+        for gene in gene_names:
+            # Define the parameters for the API request
+            params = {
+                "db": "gene",  # Specify the database to search in (gene)
+                "term": gene
+                + "[gene] AND Homo sapiens[orgn]",  # Query term with organism filter
+                "retmode": "xml",  # Request the output in XML format
+                "retmax": "1",  # We only want the first result
+            }
+
+            # Send the request to the Entrez API
+            response = requests.get(url, params=params)
+
+            # Check if the response was successful
+            if response.status_code == 200:
+                # Parse the XML response
+                xml_data = response.text
+
+                # Find the Entrez Gene ID in the XML response
+                start_idx = xml_data.find("<Id>")
+                end_idx = xml_data.find("</Id>")
+
+                if start_idx != -1 and end_idx != -1:
+                    # Extract and append the Entrez Gene ID to the list
+                    entrez_id = xml_data[start_idx + 4 : end_idx]
+                    entrez_ids.append(entrez_id)
+                else:
+                    # If no Entrez ID is found, append None
+                    entrez_ids.append(None)
+            else:
+                # Handle any errors in the API request
+                return f"Error fetching data for gene: {gene}. Please check whether the gene uses official gene name."
+
+        return entrez_ids
+
+    def humanbase_ppi_retrieve(self, genes, tissue, max_node=10, interaction=None):
+        """
+        Retrieve protein-protein interactions and biological processes from HumanBase.
+
+        Parameters:
+            genes (list): List of gene names to analyze.
+            tissue (str): Tissue type for tissue-specific interactions.
+            max_node (int): Maximum number of nodes to retrieve.
+            interaction (str): Specific interaction type to filter by.
+
+        Returns:
+            tuple: (NetworkX Graph of interactions, list of biological processes)
+        """
+        genes = self.get_entrez_ids(genes)
+
+        tissue = tissue.replace(" ", "-").replace("_", "-").lower()
+        interaction_types = [
+            "co-expression",
+            "interaction",
+            "tf-binding",
+            "gsea-microrna-targets",
+            "gsea-perturbations",
+        ]
+
+        if not interaction or interaction not in interaction_types:
+            interaction = "&datatypes=".join(interaction_types)
+
+        gene_id = "&entrez=".join(genes)
+        G = nx.Graph()
+        bp_collection = None
+
+        network_url = f"https://hb.flatironinstitute.org/api/integrations/{tissue}/network/?datatypes={interaction}&entrez={gene_id}&node_size={max_node}"
+        edge_type_url = "https://hb.flatironinstitute.org/api/integrations/{tissue}/evidence/?limit=20&source={source}&target={target}"
+
+        # Retrieve tissue-specific PPI
+        try:
+            response = requests.get(network_url)
+            response.raise_for_status()
+            data = response.json()
+
+            if "genes" in data.keys():
+                G.add_nodes_from(
+                    [
+                        (
+                            g["standard_name"],
+                            {"entrez": g["entrez"], "description": g["description"]},
+                        )
+                        for g in data["genes"]
+                    ]
+                )
+
+            if "edges" in data.keys():
+                for e in data["edges"]:
+                    source = data["genes"][e["source"]]["standard_name"]
+                    target = data["genes"][e["target"]]["standard_name"]
+                    weight = e["weight"]
+
+                    edge_response = requests.get(
+                        edge_type_url.format(
+                            tissue=tissue,
+                            source=G.nodes[source]["entrez"],
+                            target=G.nodes[target]["entrez"],
+                        )
+                    )
+                    edge_response.raise_for_status()
+                    edge_data = edge_response.json()
+                    edge_info = {
+                        t["title"]: t["weight"] for t in edge_data["datatypes"]
+                    }
+
+                    G.add_edge(source, target, weight=weight, interaction=edge_info)
+
+        except requests.exceptions.RequestException as exc:
+            print(f"Error retrieving PPI data: {exc}")
+
+        # Check gene ontology (biological process) graph involved
+        bp_url = f"https://hb.flatironinstitute.org/api/terms/annotated/?database=gene-ontology-bp&entrez={gene_id}&max_term_size=20"
+
+        try:
+            response = requests.get(bp_url)
+            response.raise_for_status()
+            data = response.json()
+
+            if len(data) > 0:
+                # Grab the top 20 common pathways
+                bp_collection = [bp_entity["title"] for bp_entity in data]
+            else:
+                print(f"[{genes}] No Gene Ontology Process recorded.")
+
+        except requests.exceptions.RequestException as exc:
+            print(f"Error retrieving biological process data: {exc}")
+
+        return G, bp_collection
+
+    def _convert_to_string(self, graph, bp_collection, original_genes, tissue):
+        """
+        Convert NetworkX graph and biological processes to string representation.
+
+        Parameters:
+            graph (networkx.Graph): The network graph.
+            bp_collection (list): List of biological processes.
+            original_genes (list): Original gene list provided by user.
+            tissue (str): Tissue type used for analysis.
+
+        Returns:
+            str: Comprehensive string representation of the network data.
+        """
+        output = []
+
+        # Header information
+        output.append("🧬 HUMANBASE PROTEIN-PROTEIN INTERACTION NETWORK")
+        output.append("=" * 50)
+        output.append(f"Query Genes: {', '.join(original_genes)}")
+        output.append(f"Tissue: {tissue.capitalize()}")
+        output.append(f"Analysis Date: {self._get_current_timestamp()}")
+        output.append("")
+
+        # Network summary
+        num_nodes = graph.number_of_nodes()
+        num_edges = graph.number_of_edges()
+
+        output.append("📊 NETWORK SUMMARY")
+        output.append("-" * 20)
+        output.append(f"Total Proteins: {num_nodes}")
+        output.append(f"Total Interactions: {num_edges}")
+
+        if num_nodes > 0:
+            density = nx.density(graph)
+            output.append(f"Network Density: {density:.3f}")
+
+        output.append("")
+
+        # Node information
+        if num_nodes > 0:
+            output.append("🔗 PROTEIN NODES")
+            output.append("-" * 15)
+            for i, (node, data) in enumerate(graph.nodes(data=True), 1):
+                entrez_id = data.get("entrez", "N/A")
+                description = data.get("description", "No description available")
+                degree = graph.degree(node)
+                output.append(f"{i:2d}. {node} (Entrez: {entrez_id})")
+                output.append(f"    Description: {description}")
+                output.append(f"    Connections: {degree}")
+                output.append("")
+
+        # Edge information
+        if num_edges > 0:
+            output.append("⚡ PROTEIN INTERACTIONS")
+            output.append("-" * 22)
+            for i, (source, target, data) in enumerate(graph.edges(data=True), 1):
+                weight = data.get("weight", "N/A")
+                interaction_info = data.get("interaction", {})
+
+                output.append(f"{i:2d}. {source} ↔ {target}")
+                output.append(f"    Weight: {weight}")
+
+                if interaction_info:
+                    output.append("    Evidence Types:")
+                    for evidence_type, evidence_weight in interaction_info.items():
+                        output.append(f"      • {evidence_type}: {evidence_weight}")
+                else:
+                    output.append(
+                        "    Evidence Types: No detailed information available"
+                    )
+                output.append("")
+
+        # Biological processes
+        if bp_collection:
+            output.append("🧬 ASSOCIATED BIOLOGICAL PROCESSES")
+            output.append("-" * 35)
+            output.append(f"Total Processes: {len(bp_collection)}")
+            output.append("")
+
+            for i, process in enumerate(bp_collection, 1):
+                output.append(f"{i:2d}. {process}")
+            output.append("")
+        else:
+            output.append("🧬 ASSOCIATED BIOLOGICAL PROCESSES")
+            output.append("-" * 35)
+            output.append("No biological processes found for this gene set.")
+            output.append("")
+
+        # Network analysis summary
+        if num_nodes > 1:
+            output.append("📈 NETWORK ANALYSIS")
+            output.append("-" * 18)
+
+            # Most connected proteins
+            if num_nodes > 0:
+                degrees = [(node, graph.degree(node)) for node in graph.nodes()]
+                degrees.sort(key=lambda x: x[1], reverse=True)
+
+                output.append("Most Connected Proteins:")
+                for i, (node, degree) in enumerate(degrees[:5], 1):
+                    output.append(f"  {i}. {node}: {degree} connections")
+                output.append("")
+
+            # Connectivity
+            is_connected = nx.is_connected(graph)
+            output.append(
+                f"Network Connectivity: {'Fully connected' if is_connected else 'Disconnected components'}"
+            )
+
+            if is_connected and num_nodes > 1:
+                try:
+                    diameter = nx.diameter(graph)
+                    avg_path_length = nx.average_shortest_path_length(graph)
+                    output.append(f"Network Diameter: {diameter}")
+                    output.append(f"Average Path Length: {avg_path_length:.2f}")
+                except Exception:
+                    pass
+
+            # Clustering
+            try:
+                clustering = nx.average_clustering(graph)
+                output.append(f"Average Clustering: {clustering:.3f}")
+            except Exception:
+                pass
+
+            output.append("")
+
+        # Footer
+        output.append("📝 NOTES")
+        output.append("-" * 8)
+        output.append(
+            "• Interaction weights represent confidence scores from HumanBase"
+        )
+        output.append("• Evidence types indicate the source of interaction data")
+        output.append(
+            "• Biological processes are derived from Gene Ontology annotations"
+        )
+        output.append(
+            "• Network analysis metrics help understand protein relationship patterns"
+        )
+
+        return "\n".join(output)
+
+    def _get_current_timestamp(self):
+        """Get current timestamp for the report."""
+        from datetime import datetime
+
+        return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

tooluniverse/logging_config.py

@@ -0,0 +1,254 @@
+"""
+Global logging configuration for ToolUniverse
+
+This module provides a centralized logging system based on Python's standard logging module.
+It allows controlling debug output across the entire ToolUniverse project with different
+verbosity levels.
+
+Usage:
+    # Set log level via environment variable
+    export TOOLUNIVERSE_LOG_LEVEL=DEBUG
+
+    # Or set programmatically
+    from tooluniverse.logging_config import setup_logging, get_logger
+    setup_logging('DEBUG')
+
+    # Use in your code
+    logger = get_logger(__name__)
+    logger.info("This is an info message")
+    logger.debug("This is a debug message")
+"""
+
+import logging
+import os
+import sys
+from typing import Optional, Callable
+
+# Define custom log levels
+PROGRESS_LEVEL = 25  # Between INFO(20) and WARNING(30)
+logging.addLevelName(PROGRESS_LEVEL, "PROGRESS")
+
+
+class ToolUniverseFormatter(logging.Formatter):
+    """Custom formatter with colored output and emoji prefixes"""
+
+    # Color codes for different log levels
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "PROGRESS": "\033[34m",  # Blue
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+        "RESET": "\033[0m",  # Reset
+    }
+
+    # Emoji prefixes for different log levels
+    EMOJI_PREFIX = {
+        "DEBUG": "🔧 ",
+        "INFO": "ℹ️  ",
+        "PROGRESS": "⏳ ",
+        "WARNING": "⚠️  ",
+        "ERROR": "❌ ",
+        "CRITICAL": "🚨 ",
+    }
+
+    def format(self, record):
+        # Add emoji prefix
+        emoji = self.EMOJI_PREFIX.get(record.levelname, "")
+
+        # Add color if output is to terminal
+        if hasattr(sys.stderr, "isatty") and sys.stderr.isatty():
+            color = self.COLORS.get(record.levelname, "")
+            reset = self.COLORS["RESET"]
+            record.levelname = f"{color}{record.levelname}{reset}"
+
+        # Format the message
+        formatted = super().format(record)
+        return f"{emoji}{formatted}"
+
+
+class ToolUniverseLogger:
+    """
+    Singleton logger manager for ToolUniverse
+    """
+
+    _instance = None
+    _logger = None
+    _initialized = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not self._initialized:
+            self._setup_logger()
+            self._initialized = True
+
+    def _setup_logger(self):
+        """Setup the main ToolUniverse logger"""
+        self._logger = logging.getLogger("tooluniverse")
+
+        # Remove existing handlers to avoid duplicates
+        for handler in self._logger.handlers[:]:
+            self._logger.removeHandler(handler)
+
+        # Set initial level from environment or default to INFO
+        initial_level = os.getenv("TOOLUNIVERSE_LOG_LEVEL", "INFO").upper()
+        try:
+            level = getattr(logging, initial_level)
+        except AttributeError:
+            level = logging.INFO
+
+        self._logger.setLevel(level)
+
+        # Create console handler
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(level)
+
+        # Create formatter
+        formatter = ToolUniverseFormatter(
+            fmt="%(message)s",  # Simple format since we add emoji prefix
+            datefmt="%H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+
+        # Add handler to logger
+        self._logger.addHandler(handler)
+
+        # Prevent propagation to root logger
+        self._logger.propagate = False
+
+    def get_logger(self, name: Optional[str] = None) -> logging.Logger:
+        """Get a logger instance"""
+        if name:
+            return logging.getLogger(f"tooluniverse.{name}")
+        # Fallback to module logger if not initialized
+        return (
+            self._logger
+            if self._logger is not None
+            else logging.getLogger("tooluniverse")
+        )
+
+    def set_level(self, level: str) -> None:
+        """Set logging level"""
+        try:
+            log_level = getattr(logging, level.upper())
+            if self._logger is None:
+                return
+            self._logger.setLevel(log_level)
+            for handler in self._logger.handlers:
+                handler.setLevel(log_level)
+        except AttributeError:
+            if self._logger is not None:
+                self._logger.warning(
+                    f"Invalid log level: {level}. Valid levels: DEBUG, INFO, WARNING, ERROR, CRITICAL"
+                )
+
+
+# Global logger instance
+_logger_manager = ToolUniverseLogger()
+
+
+def setup_logging(level: Optional[str] = None) -> None:
+    """
+    Setup global logging configuration
+
+    Args:
+        level (str): Log level ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')
+    """
+    if level:
+        _logger_manager.set_level(level)
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Get a logger instance
+
+    Args:
+        name (str, optional): Logger name (usually __name__)
+
+    Returns:
+        logging.Logger: Logger instance
+    """
+    return _logger_manager.get_logger(name)
+
+
+def set_log_level(level: str) -> None:
+    """Set global log level"""
+    _logger_manager.set_level(level)
+
+
+# Convenience functions using the main logger
+_main_logger = get_logger()
+
+
+def debug(msg, *args, **kwargs):
+    """Log debug message"""
+    _main_logger.debug(msg, *args, **kwargs)
+
+
+def info(msg, *args, **kwargs):
+    """Log info message"""
+    _main_logger.info(msg, *args, **kwargs)
+
+
+def progress_log(msg, *args, **kwargs) -> None:
+    """Log progress message"""
+    # Preserve dedicated PROGRESS level without monkey-patching Logger
+    _main_logger.log(PROGRESS_LEVEL, msg, *args, **kwargs)
+
+
+def warning(msg, *args, **kwargs):
+    """Log warning message"""
+    _main_logger.warning(msg, *args, **kwargs)
+
+
+def error(msg, *args, **kwargs):
+    """Log error message"""
+    _main_logger.error(msg, *args, **kwargs)
+
+
+def critical(msg, *args, **kwargs):
+    """Log critical message"""
+    _main_logger.critical(msg, *args, **kwargs)
+
+
+# For backward compatibility
+minimal = info  # Alias minimal to info
+verbose = debug  # Alias verbose to debug
+progress: Callable[..., None] = progress_log  # Alias for convenience
+
+
+def get_hook_logger(name: str = "HookManager") -> logging.Logger:
+    """
+    Get a logger specifically configured for hook operations.
+
+    Args:
+        name (str): Name of the logger. Defaults to 'HookManager'
+
+    Returns:
+        logging.Logger: Configured logger for hook operations
+    """
+    return get_logger(name)
+
+
+def log_hook_execution(
+    hook_name: str, tool_name: str, execution_time: float, success: bool
+):
+    """
+    Log hook execution details for monitoring and debugging.
+
+    Args:
+        hook_name (str): Name of the hook that was executed
+        tool_name (str): Name of the tool the hook was applied to
+        execution_time (float): Time taken to execute the hook in seconds
+        success (bool): Whether the hook execution was successful
+    """
+    logger = get_hook_logger()
+    status = "SUCCESS" if success else "FAILED"
+    logger.info(
+        f"Hook {hook_name} for tool {tool_name}: {status} ({execution_time:.2f}s)"
+    )