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

tooluniverse/remote/expert_feedback/simple_test.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""
+Simple Test for Human Expert System
+"""
+
+from tooluniverse import ToolUniverse
+
+tooluni = ToolUniverse()
+tooluni.load_tools()
+
+# Submit question to expert
+result = tooluni.run(
+    {
+        "name": "expert_consult_human_expert",
+        "arguments": {
+            "question": "What is the recommended dosage of aspirin for elderly patients?",
+            "specialty": "cardiology",
+            "priority": "high",  # normal, high, urgent
+        },
+    }
+)
+print("Request submitted. Result:")
+print(result)

tooluniverse/remote/expert_feedback/start_web_interface.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+Start Web Interface Only
+
+This script starts only the web interface for expert consultations using the
+@register_mcp_tool system (human_expert_mcp_tools.py).
+The MCP server must be running separately.
+"""
+
+import subprocess
+import sys
+import requests
+from pathlib import Path
+import os
+import socket
+
+
+def get_random_port():
+    """Get a random available port"""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+def detect_mcp_server_port():
+    """Ask user for MCP server connection details"""
+    print("📝 Please provide the MCP server connection details:")
+
+    while True:
+        try:
+            address = input("Enter server IP address (default: localhost): ").strip()
+            if not address:
+                address = "localhost"
+
+            port_input = input("Enter server port (default: 9877): ").strip()
+            if not port_input:
+                port = 9876
+            else:
+                port = int(port_input)
+
+            # Validate port range
+            if not (1 <= port <= 65535):
+                print("❌ Port must be between 1 and 65535. Please try again.")
+                continue
+
+            # Test the connection
+            print(f"🔍 Testing connection to {address}:{port}...")
+            if check_mcp_server_on_port(port, address):
+                print(f"✅ Successfully connected to {address}:{port}")
+                # Set the environment variable for this session
+                os.environ["EXPERT_FEEDBACK_MCP_SERVER_URL"] = (
+                    f"http://{address}:{port}"
+                )
+                return port
+            else:
+                print(f"❌ Could not connect to {address}:{port}")
+                print("💡 Make sure the MCP server is running and accessible")
+                print("   Server logs should show something like:")
+                print("   'INFO: Uvicorn running on http://0.0.0.0:9876'")
+                retry = input("Would you like to try again? (y/N): ").strip().lower()
+                if retry != "y":
+                    break
+
+        except ValueError:
+            print("❌ Invalid port number. Please enter a valid integer.")
+        except KeyboardInterrupt:
+            print("\n👋 Cancelled by user")
+            return None
+
+    # Try common ports that the system might use
+    print("🔍 Trying common ports...")
+    common_ports = [8000, 8001] + [52340 + i for i in range(20)]
+
+    for port in common_ports:
+        if check_mcp_server_on_port(port):
+            print(f"✅ Found MCP server running on port {port}")
+            return port
+
+    return None
+
+
+def check_mcp_server_on_port(port, address="localhost"):
+    """Check if MCP server is running on specific port and address"""
+    try:
+        # Try different possible endpoints
+        endpoints_to_try = [
+            f"http://{address}:{port}/tools/get_expert_status",
+            f"http://{address}:{port}/mcp",
+            f"http://{address}:{port}/tools",
+            f"http://{address}:{port}/",
+            f"http://{address}:{port}/docs",
+            f"http://{address}:{port}/health",
+        ]
+
+        for endpoint in endpoints_to_try:
+            try:
+                if "/tools/get_expert_status" in endpoint:
+                    response = requests.post(endpoint, json={}, timeout=2)
+                else:
+                    response = requests.get(endpoint, timeout=2)
+
+                # Accept various response codes that indicate server is running
+                if response.status_code in [200, 404, 405, 406, 422, 500]:
+                    print(
+                        f"✅ Server detected at {endpoint} (status: {response.status_code})"
+                    )
+                    return True
+
+            except requests.exceptions.RequestException:
+                continue
+
+    except Exception as e:
+        print(f"⚠️  Connection test error: {e}")
+
+    return False
+
+
+def check_mcp_server():
+    """Check if MCP server is running and return port"""
+    print("🔍 Detecting MCP server...")
+    port = detect_mcp_server_port()
+    if port:
+        print(f"✅ MCP Server detected on port {port}")
+        return port
+    return None
+
+
+def main():
+    print("🌐 Starting Human Expert Web Interface")
+    print("=" * 50)
+
+    # Check if MCP server is running
+    mcp_port = check_mcp_server()
+    if not mcp_port:
+        print("❌ Second generation MCP Server not detected!")
+        print("📡 Please start the MCP server first:")
+        print("   python human_expert_mcp_tools.py --start-server")
+        print()
+        print("💡 This script only supports the modern @register_mcp_tool system.")
+        print()
+        choice = input("Continue anyway? (y/N): ").strip().lower()
+        if choice != "y":
+            return 1
+
+    # Check for the second generation script
+    modern_script = Path(__file__).parent / "human_expert_mcp_tools.py"
+
+    if not modern_script.exists():
+        print("❌ MCP tools script not found!")
+        print(f"   Looking for: {modern_script}")
+        print("   Make sure human_expert_mcp_tools.py exists in this directory.")
+        return 1
+
+    print("🚀 Using @register_mcp_tool system")
+    if mcp_port:
+        print(f"🔌 MCP Server: localhost:{mcp_port}")
+
+    print("🌐 Starting web interface...")
+    print("🖥️  Browser should open automatically")
+    print("\nPress Ctrl+C to stop")
+    print("=" * 60)
+
+    try:
+        # Check Flask availability
+        try:
+            pass
+
+            print("✅ Flask is available")
+        except ImportError:
+            print("❌ Flask not found. Install with: pip install flask")
+            return 1
+
+        # Start web interface
+        subprocess.run(
+            [sys.executable, str(modern_script), "--web-only", "--no-browser"]
+        )
+        return 0
+
+    except KeyboardInterrupt:
+        print("\n👋 Web Interface stopped")
+        return 0
+    except Exception as e:
+        print(f"❌ Error starting web interface: {str(e)}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tooluniverse/remote/immune_compass/compass_tool.py

@@ -0,0 +1,327 @@
+"""
+COMPASS Prediction Tool - MCP Server
+
+This module provides an MCP (Model Context Protocol) server for running immune checkpoint
+inhibitor (ICI) response predictions using the COMPASS (COMprehensive Pathway Analysis
+for Single-cell Sequencing) model. The tool processes tumor gene expression data to
+predict patient responsiveness to immunotherapy.
+
+The COMPASS model analyzes gene expression profiles to identify key immune cell
+populations and pathways that contribute to treatment response prediction.
+"""
+
+import os
+import sys
+import torch
+import pandas as pd
+import asyncio
+import uuid
+from fastmcp import FastMCP
+from typing import List, Tuple, Optional
+
+sys.path.insert(
+    0, f'{os.getenv("COMPASS_MODEL_PATH")}/immune-compass/COMPASS'
+)  # noqa: E402
+
+from compass import loadcompass  # noqa: E402
+
+# Initialize MCP Server for COMPASS predictions
+server = FastMCP("COMPASS Prediction SMCP Server")
+
+
+class CompassTool:
+    """
+    A comprehensive tool for running immune checkpoint inhibitor (ICI) response predictions
+    using the COMPASS model.
+
+    This class provides functionality to:
+    - Load pre-trained COMPASS model checkpoints
+    - Process gene expression data (TPM format)
+    - Predict ICI treatment response
+    - Extract key immune cell populations contributing to predictions
+
+    The COMPASS model is trained to identify immune cell concepts and pathways
+    that are predictive of patient response to checkpoint inhibitor therapy.
+    """
+
+    def __init__(
+        self,
+        root_path: Optional[str] = None,
+        ckp_path: str = "pft_leave_IMVigor210.pt",
+        device: str = "cpu",
+    ):
+        """
+        Initializes the COMPASS tool by loading the pre-trained model checkpoint.
+
+        Args:
+            root_path (str, optional): Path to the directory containing model checkpoints.
+                                     If None, uses COMPASS_MODEL_PATH/immune-compass/checkpoint.
+            ckp_path (str): Name of the checkpoint file to load.
+                           Defaults to "pft_leave_IMVigor210.pt" (IMVigor210 cohort).
+            device (str): Device for model inference ("cuda" or "cpu"). Defaults to "cuda".
+
+        Raises:
+            FileNotFoundError: If the specified checkpoint file cannot be found.
+            Exception: If model loading fails due to compatibility or corruption issues.
+        """
+        # Construct model checkpoint path
+        if root_path is None:
+            compass_model_path = os.getenv("COMPASS_MODEL_PATH")
+            if compass_model_path is None:
+                raise ValueError("COMPASS_MODEL_PATH environment variable is not set")
+            if not os.path.exists(
+                os.path.join(compass_model_path, "immune-compass", "checkpoint")
+            ):
+                checkpoint_path = os.path.join(
+                    compass_model_path, "immune-compass", "checkpoint"
+                )
+                raise FileNotFoundError(
+                    f"COMPASS model checkpoint not found at {checkpoint_path}. Please check your COMPASS_MODEL_PATH."
+                )
+            root_path = os.path.join(compass_model_path, "immune-compass", "checkpoint")
+
+        self.model_path = os.path.join(root_path, ckp_path)
+        self.device = device
+
+        # Load the pre-trained COMPASS model
+        print(f"🛠️  Initializing COMPASS tool from checkpoint: {self.model_path}...")
+        self.finetuner = loadcompass(
+            self.model_path, weights_only=False, map_location=torch.device(self.device)
+        )
+
+        # Configure device settings for CPU inference if needed
+        if self.device == "cpu":
+            self.finetuner.device = "cpu"
+
+        # Display model parameter count for transparency
+        self.finetuner.count_parameters()
+        print(
+            "[COMPASS] Tool initialized successfully (model loaded and ready for predictions)."
+        )
+
+    def _get_top_columns_per_row(
+        self,
+        df: pd.DataFrame,
+        top_n: int = 44,
+        exclude: Optional[List[str]] = None,
+    ) -> List[List[Tuple[str, float]]]:
+        """
+        Extracts the top-scoring immune cell concepts for each sample from COMPASS output.
+
+        This method processes the COMPASS cell concept matrix to identify the most
+        influential immune cell populations contributing to the prediction for each sample.
+
+        Args:
+            df (pd.DataFrame): DataFrame containing cell concept scores from COMPASS analysis.
+                              Rows represent samples, columns represent immune cell concepts.
+            top_n (int): Maximum number of top concepts to return per sample. Defaults to 44.
+            exclude (List[str]): List of column names to exclude from results.
+                               Defaults to ['CANCER', 'Reference'].
+
+        Returns:
+            List[List[Tuple[str, float]]]: For each sample, a list of tuples containing
+                                         (concept_name, concept_score) sorted by score descending.
+        """
+        # Set default excludes safely to avoid mutable default argument
+        if exclude is None:
+            exclude = ["CANCER", "Reference"]
+        # Sort concepts by score (descending) for each sample
+        sorted_concepts_indices = [
+            row.sort_values(ascending=False).index[:top_n] for _, row in df.iterrows()
+        ]
+
+        results = []
+        for i, (_, row) in enumerate(df.iterrows()):
+            row_concepts = []
+            for col in sorted_concepts_indices[i]:
+                # Skip excluded columns (e.g., metadata columns)
+                if col not in exclude:
+                    row_concepts.append((col, row[col]))
+            results.append(row_concepts)
+        return results
+
+    def predict(
+        self,
+        gene_expression_data_path: str,
+        threshold: float = 0.5,
+        batch_size: int = 128,
+    ) -> Tuple[bool, List[Tuple[str, float]]]:
+        """
+        Performs immune checkpoint inhibitor response prediction on gene expression data.
+
+        This method processes single-sample tumor gene expression data (in TPM format)
+        through the COMPASS model to predict treatment response and identify key
+        immune cell populations contributing to the prediction.
+
+        Args:
+            gene_expression_data_path (str): Path to the TPM expression data file.
+                                                   to their expression levels in Transcripts Per Million (TPM).
+            threshold (float): Prediction probability threshold for classifying samples as responders.
+                             Values ≥ threshold are classified as responders. Defaults to 0.5.
+            batch_size (int): Batch size for model inference. Larger values may improve speed
+                            but require more memory. Defaults to 128.
+
+        Returns:
+            Tuple[bool, List[Tuple[str, float]]]: A tuple containing:
+                - bool: True if predicted as responder (probability ≥ threshold), False otherwise
+                - List[Tuple[str, float]]: Top immune cell concepts ranked by importance,
+                  where each tuple contains (concept_name, concept_score)
+
+        Raises:
+            ValueError: If gene_expression_data is empty or contains invalid values.
+            RuntimeError: If model inference fails.
+        """
+        # Convert gene expression dictionary to DataFrame format expected by COMPASS
+        df_tpm = pd.read_pickle(gene_expression_data_path)
+        df_tpm.index.name = "Index"  # Required by COMPASS for gene indexing
+
+        # Extract immune cell concepts and generate predictions using COMPASS model
+        # dfct contains cell concept scores, dfpred contains response probabilities
+        _, _, dfct = self.finetuner.extract(
+            df_tpm, batch_size=batch_size, with_gene_level=True
+        )
+        _, dfpred = self.finetuner.predict(df_tpm)
+
+        # Extract and rank the most influential immune cell concepts
+        sorted_cell_concepts = self._get_top_columns_per_row(dfct)
+
+        # Classify sample as responder based on prediction probability threshold
+        # dfpred.iloc[:, 1] contains the responder probability (column 1)
+        responder = dfpred.iloc[:, 1].max() >= threshold
+
+        return responder, sorted_cell_concepts[0] if sorted_cell_concepts else []
+
+
+@server.tool()
+async def run_compass_prediction(
+    gene_expression_data_path: str,
+    threshold: float = 0.5,
+    root_path: Optional[str] = None,
+):
+    """
+    MCP Tool: Predicts immune checkpoint inhibitor (ICI) response using COMPASS model.
+
+    This tool analyzes single-sample tumor gene expression data to predict patient
+    responsiveness to immune checkpoint inhibitor therapy. The COMPASS model leverages
+    immune cell concept analysis to provide both a binary prediction and interpretable
+    insights into the immune microenvironment factors driving the prediction.
+
+    Clinical Context:
+    - Designed for precision oncology applications
+    - Helps identify patients likely to benefit from ICI therapy
+    - Provides mechanistic insights through immune cell population analysis
+    - Based on validated cohorts including IMVigor210 (urothelial carcinoma)
+
+    Args:
+        gene_expression_data_path (str): Path to the TPM expression data file.
+                                               Keys should be standard gene symbols (e.g., "CD274", "PDCD1", "CTLA4")
+                                               Values should be normalized expression in TPM (Transcripts Per Million).
+                                               Minimum ~100 genes recommended for reliable predictions.
+        threshold (float): Probability threshold for responder classification (0.0-1.0).
+                         Values ≥ threshold classify sample as likely responder.
+                         Default 0.5 provides balanced sensitivity/specificity.
+                         Consider lower thresholds (~0.3) for higher sensitivity.
+
+    Returns:
+        dict: Structured prediction results containing:
+            - 'prediction' (dict): Core prediction results with:
+                * 'is_responder' (bool): True if predicted responder (probability ≥ threshold)
+                * 'top_concepts' (list): Ranked immune cell concepts as dicts with:
+                    - 'concept' (str): Name of immune cell population/concept
+                    - 'score' (float): Importance score for this concept
+            - 'context_info' (list): Human-readable analysis summary and status messages
+            - 'error' (str, optional): Error description if prediction failed
+    """
+    # Generate unique request ID for tracking and logging
+    request_id = str(uuid.uuid4())[:8]
+    print(f"[{request_id}] Received COMPASS ICI response prediction request")
+
+    # Initialize global COMPASS tool instance for MCP server
+    # This instance will be used by the MCP tool function to serve predictions
+    try:
+        compass_tool = CompassTool(root_path=root_path)
+        print("✅ COMPASS Prediction tool instance created and ready for MCP server")
+    except Exception as e:
+        print(f"❌ Error creating COMPASS Prediction tool: {str(e)}")
+        print(
+            "Please ensure COMPASS_MODEL_PATH is correctly set and model checkpoint exists."
+        )
+        raise e
+
+    try:
+        # Brief async pause to allow for proper request handling
+        await asyncio.sleep(0.1)
+
+        # Validate input parameters
+        if (
+            not isinstance(gene_expression_data_path, str)
+            or not gene_expression_data_path
+        ):
+            raise ValueError(
+                "Input 'gene_expression_data' must be a non-empty dictionary mapping gene symbols to TPM values."
+            )
+
+        if not (0.0 <= threshold <= 1.0):
+            raise ValueError(f"Threshold must be between 0.0 and 1.0, got {threshold}")
+
+        print(
+            f"[{request_id}] Processing {len(gene_expression_data_path)} genes with threshold {threshold}"
+        )
+
+        # Execute COMPASS model prediction
+        is_responder, top_concepts = compass_tool.predict(
+            gene_expression_data_path, threshold=threshold
+        )
+
+        # Convert concept tuples to JSON-serializable format
+        serializable_concepts = [
+            {"concept": concept, "score": float(score)}
+            for concept, score in top_concepts
+        ]
+
+        # Log successful completion
+        response_status = "RESPONDER" if is_responder else "NON-RESPONDER"
+        print(
+            f"[{request_id}] ✅ COMPASS prediction completed: {response_status} ({len(serializable_concepts)} concepts)"
+        )
+
+        return {
+            "prediction": {
+                "is_responder": is_responder,
+                "top_concepts": serializable_concepts,
+            },
+            "context_info": [
+                "COMPASS prediction completed successfully.",
+                f"Sample classified as: {'RESPONDER' if is_responder else 'NON-RESPONDER'}",
+                f"Analysis based on {len(gene_expression_data_path)} input genes.",
+                f"Top {len(serializable_concepts)} immune cell concepts identified.",
+            ],
+        }
+
+    except (ValueError, FileNotFoundError) as e:
+        error_message = f"COMPASS prediction validation error: {str(e)}"
+        print(f"[{request_id}] {error_message}")
+        return {
+            "error": error_message,
+            "context_info": ["Please check input data format and model availability."],
+        }
+    except Exception as e:
+        error_message = f"Unexpected error during COMPASS prediction: {str(e)}"
+        print(f"[{request_id}] {error_message}")
+        return {
+            "error": error_message,
+            "context_info": ["Internal server error occurred during prediction."],
+        }
+
+
+if __name__ == "__main__":
+    print("Starting MCP server for COMPASS Immune Response Prediction Tool...")
+    print("Model: COMPASS (COMprehensive Pathway Analysis for Single-cell Sequencing)")
+    print("Application: Immune Checkpoint Inhibitor Response Prediction")
+    print("Server: FastMCP with streamable HTTP transport")
+    print("Port: 7003 (configured to avoid conflicts with other biomedical tools)")
+
+    # Launch the MCP server with COMPASS prediction capabilities
+    server.run(
+        transport="streamable-http", host="0.0.0.0", port=7003, stateless_http=True
+    )