Deploy BioMCP Explorer

README.md

@@ -1,14 +1,77 @@
 ---
 title: BioMCP Explorer
-emoji: 🏃
-colorFrom: indigo
-colorTo: green
+emoji: 🧬
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.11.0
+sdk_version: "6.11.0"
 app_file: app.py
 pinned: false
-license: mit
-short_description: Exploring BioMCP using 30+ Biomedical API's
+short_description: Explore genes, variants, drugs, trials & more
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# BioMCP Explorer — Gradio App
+
+A feature-rich Gradio web interface for exploring all BioMCP tools and features.
+Search, discover, and analyze biomedical data across 13+ entity types and 30+ upstream APIs.
+
+## Quick Start
+
+### 1. Install BioMCP CLI
+
+```bash
+uv tool install biomcp-cli
+# or: pip install biomcp-cli
+```
+
+### 2. Install Python dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Configure API keys (optional)
+
+Copy `.env.example` to `.env` and fill in your keys. Or enter them in the Settings tab at runtime.
+
+### 4. Launch
+
+```bash
+python app.py
+```
+
+Open http://localhost:7860 in your browser.
+
+## Tabs Overview
+
+| Tab | Purpose |
+|-----|---------|
+| ⚙️ Settings & Health | API keys, health checks, version info |
+| 🔍 Discover | Free-text concept resolution |
+| 🔎 Search | Entity search across 13 types (gene, variant, article, trial, drug, disease, pathway, protein, adverse-event, pgx, gwas, phenotype, cross-entity) |
+| 📋 Get Detail | Focused entity detail with selectable sections |
+| 🔗 Cross-Entity Helpers | 20 pivot commands between related entities |
+| 🧬 Enrichment | g:Profiler gene-set enrichment |
+| 📦 Batch | Parallel get calls for up to 10 IDs |
+| 📊 Study Analytics | Local cBioPortal study analysis (query, cohort, survival, compare, co-occurrence) |
+
+## API Keys
+
+All optional — BioMCP works without them at reduced rate/features:
+
+| Key | Purpose |
+|-----|---------|
+| `NCBI_API_KEY` | Better PubMed/PubTator rate limits |
+| `S2_API_KEY` | Faster Semantic Scholar access |
+| `ONCOKB_TOKEN` | OncoKB variant therapy evidence |
+| `OPENFDA_API_KEY` | Better OpenFDA rate limits |
+| `NCI_API_KEY` | NCI CTS trial search |
+| `DISGENET_API_KEY` | DisGeNET gene-disease scores |
+| `UMLS_API_KEY` | Clinical crosswalk in discover |
+| `ALPHAGENOME_API_KEY` | Variant effect predictions |
+
+## Requirements
+
+- Python 3.11+
+- `biomcp` CLI on PATH
+- Gradio 5.x

app.py

@@ -0,0 +1,68 @@
+"""
+BioMCP Gradio App — Main entry point.
+Assembles all tabs into one cohesive application.
+"""
+
+import gradio as gr
+from core.config import load_env_keys
+from tabs.settings import create_settings_tab
+from tabs.discover import create_discover_tab
+from tabs.search import create_search_tab
+from tabs.get_detail import create_get_tab
+from tabs.helpers import create_helpers_tab
+from tabs.enrichment import create_enrichment_tab
+from tabs.batch import create_batch_tab
+
+DESCRIPTION = """
+# 🧬 BioMCP Explorer
+
+**One interface. Every biomedical entity. Evidence from the sources you trust.**
+
+Explore genes, variants, articles, trials, drugs, diseases, pathways, proteins, adverse events, PGx, GWAS, and phenotypes
+— all powered by [BioMCP](https://biomcp.org/) across 30+ upstream APIs.
+
+> **Tip:** Start with the **⚙️ Settings** tab to configure API keys, then explore any entity tab.
+"""
+
+
+def create_app():
+    with gr.Blocks(title="BioMCP Explorer") as app:
+        gr.Markdown(DESCRIPTION)
+
+        # Session state lives outside tabs so every tab can share it
+        session_keys = gr.State(load_env_keys())
+
+        with gr.Tabs():
+            # Settings tab first — pass session_keys in
+            create_settings_tab(session_keys)
+
+            # All feature tabs, sharing the same session_keys
+            create_discover_tab(session_keys)
+            create_search_tab(session_keys)
+            create_get_tab(session_keys)
+            create_helpers_tab(session_keys)
+            create_enrichment_tab(session_keys)
+            create_batch_tab(session_keys)
+
+    return app
+
+
+if __name__ == "__main__":
+    import os
+    is_hf = os.environ.get("SPACE_ID") is not None
+    app = create_app()
+    app.launch(
+        server_name="0.0.0.0" if is_hf else "127.0.0.1",
+        server_port=7860 if is_hf else 7865,
+        share=False,
+        show_error=True,
+        theme=gr.themes.Soft(
+            primary_hue="blue",
+            secondary_hue="cyan",
+            neutral_hue="slate",
+        ),
+        css="""
+        .gradio-container { max-width: 1400px !important; }
+        footer { display: none !important; }
+        """,
+    )

core/config.py

@@ -0,0 +1,86 @@
+"""
+API key and environment configuration management.
+Keys are stored in session state only — never written to disk.
+"""
+
+import os
+from dotenv import load_dotenv
+
+# All supported API keys with metadata
+API_KEYS = {
+    "NCBI_API_KEY": {
+        "label": "NCBI API Key",
+        "description": "Improves PubTator/PMC OA rate limits (3→10 req/sec)",
+        "url": "https://www.ncbi.nlm.nih.gov/account/settings/",
+        "required": False,
+    },
+    "S2_API_KEY": {
+        "label": "Semantic Scholar API Key",
+        "description": "Dedicated S2 quota (1 req/sec) for article search/TLDR/citations",
+        "url": "https://www.semanticscholar.org/product/api",
+        "required": False,
+    },
+    "ONCOKB_TOKEN": {
+        "label": "OncoKB Token",
+        "description": "Production OncoKB variant therapy & level evidence",
+        "url": "https://www.oncokb.org/account/register",
+        "required": False,
+    },
+    "OPENFDA_API_KEY": {
+        "label": "OpenFDA API Key",
+        "description": "Better OpenFDA rate limits for drug safety/adverse event lookups",
+        "url": "https://open.fda.gov/apis/authentication/",
+        "required": False,
+    },
+    "NCI_API_KEY": {
+        "label": "NCI CTS API Key",
+        "description": "NCI Clinical Trials Search (--source nci)",
+        "url": "https://clinicaltrialsapi.cancer.gov/",
+        "required": False,
+    },
+    "DISGENET_API_KEY": {
+        "label": "DisGeNET API Key",
+        "description": "Scored gene-disease associations in gene/disease lookups",
+        "url": "https://www.disgenet.com/",
+        "required": False,
+    },
+    "UMLS_API_KEY": {
+        "label": "UMLS API Key",
+        "description": "Clinical crosswalk enrichment in discover command",
+        "url": "https://uts.nlm.nih.gov/uts/signup-login",
+        "required": False,
+    },
+    "ALPHAGENOME_API_KEY": {
+        "label": "AlphaGenome API Key",
+        "description": "Variant effect prediction (get variant ... predict)",
+        "url": "https://deepmind.google/science/alphagenome/",
+        "required": False,
+    },
+}
+
+# Additional config env vars
+CONFIG_VARS = {
+    "BIOMCP_STUDY_DIR": {
+        "label": "Study Directory",
+        "description": "Local study root for cBioPortal datasets (leave blank for default)",
+    },
+}
+
+
+def load_env_keys() -> dict[str, str]:
+    """Load API keys from .env file and environment, return as dict."""
+    load_dotenv()
+    keys = {}
+    for key_name in API_KEYS:
+        keys[key_name] = os.environ.get(key_name, "")
+    for key_name in CONFIG_VARS:
+        keys[key_name] = os.environ.get(key_name, "")
+    return keys
+
+
+def build_env_overrides(session_keys: dict[str, str]) -> dict[str, str]:
+    """
+    Build env overrides dict from session keys.
+    Only includes non-empty values.
+    """
+    return {k: v for k, v in session_keys.items() if v}

core/formatter.py

@@ -0,0 +1,32 @@
+"""
+Formatting helpers: convert biomcp output into Gradio-friendly display.
+"""
+
+import json
+import re
+
+
+def _strip_suggested_commands(md: str) -> str:
+    """Remove the '## Suggested Commands' section from markdown output."""
+    return re.split(r"\n##\s+Suggested Commands", md, maxsplit=1)[0].rstrip()
+
+
+def format_result(result: dict) -> tuple[str, str]:
+    """
+    Format a runner result into (markdown_display, json_display).
+    Returns two strings suitable for gr.Markdown and gr.Code components.
+    """
+    if not result["success"]:
+        error_md = f"⚠️ **Error:** {result['error']}"
+        return error_md, json.dumps({"error": result["error"]}, indent=2)
+
+    # Markdown display
+    md = _strip_suggested_commands(result["markdown"])
+
+    # JSON display
+    if result["data"] is not None:
+        json_str = json.dumps(result["data"], indent=2, default=str)
+    else:
+        json_str = ""
+
+    return md, json_str

core/runner.py

@@ -0,0 +1,246 @@
+"""
+Subprocess wrapper for the biomcp CLI.
+Runs biomcp commands and returns structured (JSON) or markdown output.
+"""
+
+import json
+import os
+import subprocess
+import shutil
+import sys
+from typing import Optional
+
+
+def find_biomcp() -> str:
+    """Locate the biomcp binary on PATH or common install locations."""
+    path = shutil.which("biomcp")
+    if path:
+        return path
+
+    # Check Python Scripts directory (pip install location)
+    candidates = [
+        os.path.join(os.path.dirname(sys.executable), "Scripts", "biomcp.exe"),
+        os.path.join(os.path.dirname(sys.executable), "Scripts", "biomcp"),
+        os.path.join(os.path.dirname(sys.executable), "biomcp.exe"),
+        os.path.join(os.path.dirname(sys.executable), "biomcp"),
+    ]
+    # Also check the Python that `py` launcher uses
+    for base in [
+        os.path.expanduser("~/.local/bin"),
+        os.path.expandvars(r"%LOCALAPPDATA%\Python\pythoncore-3.14-64\Scripts"),
+        os.path.expandvars(r"%LOCALAPPDATA%\Python\pythoncore-3.13-64\Scripts"),
+        os.path.expandvars(r"%LOCALAPPDATA%\Python\pythoncore-3.12-64\Scripts"),
+    ]:
+        candidates.append(os.path.join(base, "biomcp.exe"))
+        candidates.append(os.path.join(base, "biomcp"))
+
+    for c in candidates:
+        if os.path.isfile(c):
+            return c
+
+    raise FileNotFoundError(
+        "biomcp not found on PATH. Install with: pip install biomcp-cli"
+    )
+
+
+def run(
+    args: list[str],
+    *,
+    json_mode: bool = True,
+    no_cache: bool = False,
+    env_overrides: Optional[dict[str, str]] = None,
+    timeout: int = 120,
+) -> dict:
+    """
+    Execute a biomcp CLI command.
+
+    Returns dict with keys:
+      - success: bool
+      - command: str (the full command string)
+      - markdown: str (raw stdout, always present)
+      - data: dict | list | None (parsed JSON when json_mode=True)
+      - error: str | None
+    """
+    import os
+
+    biomcp = find_biomcp()
+
+    cmd = [biomcp]
+    if json_mode:
+        cmd.append("--json")
+    if no_cache:
+        cmd.append("--no-cache")
+    cmd.extend(args)
+
+    env = os.environ.copy()
+    if env_overrides:
+        for k, v in env_overrides.items():
+            if v:  # only set non-empty values
+                env[k] = v
+
+    command_str = " ".join(cmd)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+
+        stdout = result.stdout.strip()
+        stderr = result.stderr.strip()
+
+        if result.returncode != 0:
+            error_msg = stderr or stdout or f"Command exited with code {result.returncode}"
+            return {
+                "success": False,
+                "command": command_str,
+                "markdown": error_msg,
+                "data": None,
+                "error": error_msg,
+            }
+
+        # Try parsing JSON
+        data = None
+        if json_mode and stdout:
+            try:
+                data = json.loads(stdout)
+            except json.JSONDecodeError:
+                pass
+
+        # For markdown display: if we got JSON, pretty-print it; otherwise use raw stdout
+        if data is not None:
+            markdown = _json_to_markdown(data)
+        else:
+            markdown = stdout
+
+        return {
+            "success": True,
+            "command": command_str,
+            "markdown": markdown,
+            "data": data,
+            "error": None,
+        }
+
+    except subprocess.TimeoutExpired:
+        return {
+            "success": False,
+            "command": command_str,
+            "markdown": "",
+            "data": None,
+            "error": f"Command timed out after {timeout}s",
+        }
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "command": command_str,
+            "markdown": "",
+            "data": None,
+            "error": "biomcp binary not found. Install with: uv tool install biomcp-cli",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "command": command_str,
+            "markdown": "",
+            "data": None,
+            "error": str(e),
+        }
+
+
+def run_markdown(
+    args: list[str],
+    *,
+    no_cache: bool = False,
+    env_overrides: Optional[dict[str, str]] = None,
+    timeout: int = 120,
+) -> dict:
+    """Run command in markdown mode (no --json flag)."""
+    return run(
+        args,
+        json_mode=False,
+        no_cache=no_cache,
+        env_overrides=env_overrides,
+        timeout=timeout,
+    )
+
+
+def _is_small_dict(d: dict) -> bool:
+    """Check if a dict is simple enough to render inline."""
+    return (len(d) <= 4
+            and all(isinstance(v, (str, int, float, bool, type(None))) for v in d.values()))
+
+
+def _json_to_markdown(data, level=1) -> str:
+    """Convert structured JSON response to readable markdown."""
+    if isinstance(data, str):
+        return data
+    if isinstance(data, (int, float, bool)):
+        return str(data)
+    if data is None:
+        return ""
+    if isinstance(data, list):
+        if not data:
+            return ""
+        # List of simple values
+        if all(isinstance(v, (str, int, float, bool)) for v in data):
+            return ", ".join(str(v) for v in data)
+        # List of small dicts — render as compact table-like rows
+        if all(isinstance(v, dict) and _is_small_dict(v) for v in data):
+            rows = []
+            for item in data[:15]:
+                parts = [f"{v}" for v in item.values() if v is not None and v != ""]
+                rows.append(" · ".join(parts))
+            result = "\n".join(f"- {r}" for r in rows)
+            if len(data) > 15:
+                result += f"\n- *(+{len(data) - 15} more)*"
+            return result
+        # List of larger dicts — render each as a block
+        parts = []
+        for i, item in enumerate(data, 1):
+            if isinstance(item, dict):
+                label = (item.get("label") or item.get("name") or item.get("title")
+                         or item.get("primary_id") or item.get("id") or f"Item {i}")
+                hdr = "#" * min(level + 1, 5)
+                parts.append(f"{hdr} {i}. {label}")
+                parts.append(_format_dict(item, level + 1))
+            else:
+                parts.append(f"- {item}")
+        return "\n\n".join(parts)
+    if isinstance(data, dict):
+        return _format_dict(data, level)
+    return str(data)
+
+
+def _format_dict(d: dict, level: int = 1) -> str:
+    """Format a dict as readable markdown key-value pairs."""
+    lines = []
+    skip = {"_meta", "_links"}
+    for key, value in d.items():
+        if key in skip or key.startswith("_"):
+            continue
+        nice_key = key.replace("_", " ").replace("-", " ").title()
+        if value is None or value == "" or value == []:
+            continue
+        if isinstance(value, (str, int, float, bool)):
+            lines.append(f"**{nice_key}:** {value}")
+        elif isinstance(value, list):
+            if all(isinstance(v, (str, int, float)) for v in value):
+                shown = ", ".join(str(v) for v in value[:8])
+                more = f" *(+{len(value) - 8} more)*" if len(value) > 8 else ""
+                lines.append(f"**{nice_key}:** {shown}{more}")
+            elif all(isinstance(v, dict) and _is_small_dict(v) for v in value):
+                hdr = "#" * min(level + 1, 5)
+                lines.append(f"\n{hdr} {nice_key}\n")
+                lines.append(_json_to_markdown(value, level + 1))
+            else:
+                hdr = "#" * min(level + 1, 5)
+                lines.append(f"\n{hdr} {nice_key}\n")
+                lines.append(_json_to_markdown(value, level + 1))
+        elif isinstance(value, dict):
+            hdr = "#" * min(level + 1, 5)
+            lines.append(f"\n{hdr} {nice_key}\n")
+            lines.append(_format_dict(value, level + 1))
+    return "\n\n".join(lines)

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=5.0
+python-dotenv

tabs/batch.py

@@ -0,0 +1,88 @@
+"""
+Batch tab — parallel get calls for up to 10 IDs.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+BATCH_ENTITIES = [
+    "gene", "variant", "article", "trial", "drug",
+    "disease", "pathway", "protein", "adverse-event", "pgx",
+]
+
+
+def create_batch_tab(session_keys):
+    """Build the Batch tab."""
+
+    with gr.Tab("📦 Batch"):
+        gr.Markdown(
+            "## Batch Mode\n"
+            "Run parallel `get` calls for up to 10 entity IDs in one command.\n"
+            "Enter comma-separated IDs."
+        )
+
+        with gr.Row():
+            entity = gr.Dropdown(
+                choices=BATCH_ENTITIES,
+                value="gene",
+                label="Entity Type",
+                scale=1,
+            )
+            ids = gr.Textbox(
+                label="IDs (comma-separated, max 10)",
+                placeholder="e.g., BRAF,TP53 or NCT02576665,NCT03715933",
+                scale=3,
+            )
+
+        with gr.Row():
+            sections = gr.Textbox(
+                label="Sections (comma-separated, optional)",
+                placeholder="e.g., pathways,interactions",
+            )
+            source = gr.Textbox(
+                label="Source (optional)",
+                placeholder="e.g., nci",
+            )
+
+        with gr.Row():
+            no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        # Quick examples
+        gr.Markdown("**Quick examples:**")
+        with gr.Row():
+            ex1 = gr.Button("Genes: BRAF,TP53", size="sm", variant="secondary")
+            ex2 = gr.Button("Trials: NCT02576665,NCT03715933", size="sm", variant="secondary")
+            ex3 = gr.Button("Variants: BRAF V600E, KRAS G12D", size="sm", variant="secondary")
+
+        ex1.click(fn=lambda: ("gene", "BRAF,TP53"), outputs=[entity, ids])
+        ex2.click(fn=lambda: ("trial", "NCT02576665,NCT03715933"), outputs=[entity, ids])
+        ex3.click(fn=lambda: ("variant", "BRAF V600E,KRAS G12D"), outputs=[entity, ids])
+
+        run_btn = gr.Button("📦 Run Batch", variant="primary")
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_batch(ent, id_str, secs, src, skip_cache, keys):
+            if not id_str.strip():
+                raise gr.Error("Please enter at least one ID (comma-separated, max 10).")
+
+            args = ["batch", ent, id_str.strip()]
+            if secs.strip():
+                args.extend(["--sections", secs.strip()])
+            if src.strip():
+                args.extend(["--source", src.strip()])
+
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        run_btn.click(
+            fn=run_batch,
+            inputs=[entity, ids, sections, source, no_cache, session_keys],
+            outputs=[output_md, output_json],
+        )

tabs/discover.py

@@ -0,0 +1,65 @@
+"""
+Discover tab — free-text concept resolution.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+
+def create_discover_tab(session_keys):
+    """Build the Discover tab."""
+
+    with gr.Tab("🔍 Discover"):
+        gr.Markdown(
+            "## Concept Discovery\n"
+            "Start with free text — BioMCP resolves concepts by type and suggests follow-up commands.\n"
+            "Use this when you don't know which entity type to search."
+        )
+
+        with gr.Row():
+            with gr.Column(scale=3):
+                query = gr.Textbox(
+                    label="Query",
+                    placeholder='e.g., "ERBB1", "chest pain", "diabetes", "Keytruda"',
+                    lines=1,
+                )
+            with gr.Column(scale=1):
+                no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        run_btn = gr.Button("🔍 Discover", variant="primary")
+
+        # Quick examples
+        gr.Markdown("**Quick examples:**")
+        with gr.Row():
+            ex1 = gr.Button("ERBB1", size="sm", variant="secondary")
+            ex2 = gr.Button("chest pain", size="sm", variant="secondary")
+            ex3 = gr.Button("diabetes", size="sm", variant="secondary")
+            ex4 = gr.Button("Keytruda", size="sm", variant="secondary")
+            ex5 = gr.Button("BRAF V600E", size="sm", variant="secondary")
+
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_discover(q, skip_cache, keys):
+            if not q.strip():
+                raise gr.Error("Please enter a query to discover.")
+            args = ["discover", q.strip()]
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        run_btn.click(
+            fn=run_discover,
+            inputs=[query, no_cache, session_keys],
+            outputs=[output_md, output_json],
+        )
+
+        # Wire example buttons
+        for btn, text in [(ex1, "ERBB1"), (ex2, "chest pain"), (ex3, "diabetes"),
+                          (ex4, "Keytruda"), (ex5, "BRAF V600E")]:
+            btn.click(fn=lambda t=text: t, outputs=[query])

tabs/enrichment.py

@@ -0,0 +1,64 @@
+"""
+Enrichment tab — gene-set enrichment via g:Profiler.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+
+def create_enrichment_tab(session_keys):
+    """Build the Enrichment tab."""
+
+    with gr.Tab("🧬 Enrichment"):
+        gr.Markdown(
+            "## Gene-Set Enrichment\n"
+            "Run g:Profiler gene-set enrichment analysis.\n"
+            "Enter a comma-separated list of gene symbols."
+        )
+
+        genes = gr.Textbox(
+            label="Gene List (comma-separated)",
+            placeholder="e.g., BRAF,KRAS,NRAS,EGFR,PIK3CA",
+            lines=2,
+        )
+
+        with gr.Row():
+            limit = gr.Number(label="Limit", value=10, minimum=1, maximum=100)
+            no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        # Quick examples
+        gr.Markdown("**Quick examples:**")
+        with gr.Row():
+            ex1 = gr.Button("BRAF,KRAS,NRAS", size="sm", variant="secondary")
+            ex2 = gr.Button("TP53,BRCA1,BRCA2,ATM,CHEK2", size="sm", variant="secondary")
+            ex3 = gr.Button("EGFR,ERBB2,ERBB3,ERBB4", size="sm", variant="secondary")
+
+        ex1.click(fn=lambda: "BRAF,KRAS,NRAS", outputs=[genes])
+        ex2.click(fn=lambda: "TP53,BRCA1,BRCA2,ATM,CHEK2", outputs=[genes])
+        ex3.click(fn=lambda: "EGFR,ERBB2,ERBB3,ERBB4", outputs=[genes])
+
+        run_btn = gr.Button("🧬 Run Enrichment", variant="primary")
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_enrich(gene_list, lim, skip_cache, keys):
+            if not gene_list.strip():
+                raise gr.Error("Please enter at least one gene symbol (e.g., BRAF,KRAS,NRAS).")
+
+            clean = gene_list.strip().replace(" ", "")
+            args = ["enrich", clean, "--limit", str(int(lim))]
+
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        run_btn.click(
+            fn=run_enrich,
+            inputs=[genes, limit, no_cache, session_keys],
+            outputs=[output_md, output_json],
+        )

tabs/get_detail.py

@@ -0,0 +1,175 @@
+"""
+Get Detail tab — focused entity detail with selectable sections (progressive disclosure).
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+# Sections available per entity type
+ENTITY_SECTIONS = {
+    "gene": [
+        "pathways", "ontology", "diseases", "protein", "go", "interactions",
+        "civic", "expression", "hpa", "druggability", "clingen", "constraint",
+        "disgenet", "all",
+    ],
+    "variant": ["clinvar", "population", "conservation", "predict", "gwas", "all"],
+    "article": ["fulltext", "tldr", "all"],
+    "trial": ["eligibility", "locations", "outcomes", "all"],
+    "drug": ["label", "targets", "civic", "approvals", "regulatory", "safety", "shortage", "all"],
+    "disease": [
+        "genes", "phenotypes", "variants", "models", "pathways",
+        "prevalence", "civic", "disgenet", "all",
+    ],
+    "pathway": ["genes", "all"],
+    "protein": ["domains", "interactions", "complexes", "all"],
+    "adverse-event": ["reactions", "outcomes", "concomitant", "guidance", "all"],
+    "pgx": ["recommendations", "frequencies", "annotations"],
+}
+
+# Default sections per entity — use "all" for drug/trial to get full detail
+ENTITY_DEFAULTS = {
+    "drug": ["all"],
+    "trial": ["all"],
+}
+
+ENTITY_CHOICES = list(ENTITY_SECTIONS.keys())
+
+GET_EXAMPLES = {
+    "gene": ("BRAF", ["pathways", "hpa"], "Gene detail with pathways + tissue expression"),
+    "variant": ("BRAF V600E", ["clinvar", "population"], "ClinVar significance + population freq"),
+    "article": ("22663011", ["tldr"], "Article summary with TLDR"),
+    "trial": ("NCT02576665", ["all"], "Full trial details"),
+    "drug": ("pembrolizumab", ["all"], "Full drug details"),
+    "disease": ("MONDO:0005105", ["genes", "phenotypes"], "Disease genes + phenotypes"),
+    "pathway": ("hsa05200", ["genes"], "Pathway gene list"),
+    "protein": ("P15056", ["domains", "interactions"], "Protein domains + interactions"),
+    "adverse-event": ("10222779", ["reactions", "outcomes"], "Adverse event details"),
+    "pgx": ("CYP2D6", ["recommendations"], "PGx recommendations"),
+}
+
+
+def create_get_tab(session_keys):
+    """Build the Get Detail tab."""
+
+    with gr.Tab("📋 Get Detail"):
+        gr.Markdown(
+            "## Entity Detail\n"
+            "Retrieve focused detail for a specific entity ID with selectable sections.\n"
+            "**Drug** and **Trial** default to full details (`all` sections). Customize sections as needed."
+        )
+
+        with gr.Row():
+            entity = gr.Dropdown(
+                choices=ENTITY_CHOICES,
+                value="gene",
+                label="Entity Type",
+                scale=1,
+            )
+            entity_id = gr.Textbox(
+                label="Entity ID",
+                placeholder="e.g., BRAF, BRAF V600E, 22663011, NCT02576665",
+                scale=2,
+            )
+
+        sections = gr.CheckboxGroup(
+            choices=ENTITY_SECTIONS["gene"],
+            value=[],
+            label="Sections (leave empty for summary only)",
+        )
+
+        with gr.Row():
+            # Drug-specific region option
+            drug_region = gr.Dropdown(
+                choices=[
+                    ("— Default (US)", ""),
+                    ("🇺🇸 United States (FDA)", "us"),
+                    ("🇪🇺 European Union (EMA)", "eu"),
+                    ("🌐 All Regions (US + EU)", "all"),
+                ],
+                value="",
+                label="Region (drug regulatory/safety/shortage)",
+                visible=False,
+            )
+            no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        # Update sections when entity changes
+        def update_sections(ent):
+            choices = ENTITY_SECTIONS.get(ent, [])
+            defaults = ENTITY_DEFAULTS.get(ent, [])
+            drug_vis = ent == "drug"
+            example = GET_EXAMPLES.get(ent)
+            if example:
+                eid, secs, desc = example
+                hint = f"**Example:** `biomcp get {ent} \"{eid}\" {' '.join(secs)}` — {desc}"
+            else:
+                eid, hint = "", ""
+            return (
+                gr.CheckboxGroup(choices=choices, value=defaults),
+                gr.Dropdown(visible=drug_vis),
+                eid,
+                hint,
+            )
+
+        example_display = gr.Markdown("")
+
+        entity.change(
+            fn=update_sections,
+            inputs=[entity],
+            outputs=[sections, drug_region, entity_id, example_display],
+        )
+
+        # Quick examples
+        gr.Markdown("**Quick examples:**")
+        with gr.Row():
+            ex1 = gr.Button("Gene: BRAF", size="sm", variant="secondary")
+            ex2 = gr.Button("Variant: BRAF V600E", size="sm", variant="secondary")
+            ex3 = gr.Button("Article: 22663011", size="sm", variant="secondary")
+            ex4 = gr.Button("Trial: NCT02576665", size="sm", variant="secondary")
+            ex5 = gr.Button("Drug: pembrolizumab", size="sm", variant="secondary")
+
+        def set_example(ent, eid):
+            secs = ENTITY_SECTIONS.get(ent, [])
+            defaults = ENTITY_DEFAULTS.get(ent, [])
+            return ent, eid, gr.CheckboxGroup(choices=secs, value=defaults)
+
+        ex1.click(fn=lambda: set_example("gene", "BRAF"), outputs=[entity, entity_id, sections])
+        ex2.click(fn=lambda: set_example("variant", "BRAF V600E"), outputs=[entity, entity_id, sections])
+        ex3.click(fn=lambda: set_example("article", "22663011"), outputs=[entity, entity_id, sections])
+        ex4.click(fn=lambda: set_example("trial", "NCT02576665"), outputs=[entity, entity_id, sections])
+        ex5.click(fn=lambda: set_example("drug", "pembrolizumab"), outputs=[entity, entity_id, sections])
+
+        run_btn = gr.Button("📋 Get Details", variant="primary")
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_get(ent, eid, secs, region, skip_cache, keys):
+            if not eid.strip():
+                raise gr.Error("Please enter an entity ID (e.g., BRAF, NCT02576665, pembrolizumab).")
+
+            args = ["get", ent, eid.strip()]
+
+            # Add sections
+            if secs:
+                if "all" in secs:
+                    args.append("all")
+                else:
+                    args.extend(secs)
+
+            # Drug region (only for relevant sections)
+            if ent == "drug" and region and region != "us":
+                args.extend(["--region", region])
+
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        run_btn.click(
+            fn=run_get,
+            inputs=[entity, entity_id, sections, drug_region, no_cache, session_keys],
+            outputs=[output_md, output_json],
+        )

tabs/helpers.py

@@ -0,0 +1,115 @@
+"""
+Cross-Entity Helpers tab — pivot between related entities.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+# All helper commands: (source_entity, helper_verb, id_label, id_placeholder, description)
+HELPERS = [
+    ("variant", "trials", "Variant", "BRAF V600E", "Find trials for a variant"),
+    ("variant", "articles", "Variant", "BRAF V600E", "Find articles about a variant"),
+    ("variant", "oncokb", "Variant", "BRAF V600E", "OncoKB therapy evidence (needs ONCOKB_TOKEN)"),
+    ("drug", "adverse-events", "Drug", "pembrolizumab", "Adverse events for a drug"),
+    ("drug", "trials", "Drug", "pembrolizumab", "Trials for a drug"),
+    ("disease", "trials", "Disease", "melanoma", "Trials for a disease"),
+    ("disease", "drugs", "Disease", "melanoma", "Drugs for a disease"),
+    ("disease", "articles", "Disease", "Lynch syndrome", "Articles about a disease"),
+    ("gene", "trials", "Gene", "BRAF", "Trials involving a gene"),
+    ("gene", "drugs", "Gene", "BRAF", "Drugs targeting a gene"),
+    ("gene", "articles", "Gene", "BRCA1", "Articles about a gene"),
+    ("gene", "pathways", "Gene", "BRAF", "Pathways involving a gene"),
+    ("pathway", "drugs", "Pathway ID", "R-HSA-5673001", "Drugs related to a pathway"),
+    ("pathway", "articles", "Pathway ID", "R-HSA-5673001", "Articles about a pathway"),
+    ("pathway", "trials", "Pathway ID", "R-HSA-5673001", "Trials related to a pathway"),
+    ("protein", "structures", "UniProt ID", "P15056", "Protein structures"),
+    ("article", "entities", "PMID", "22663011", "Named entities from an article"),
+    ("article", "citations", "PMID", "22663011", "Papers that cite this article"),
+    ("article", "references", "PMID", "22663011", "References cited by this article"),
+    ("article", "recommendations", "PMID", "22663011", "Recommended similar articles"),
+]
+
+HELPER_LABELS = [f"{h[0]} {h[1]} — {h[4]}" for h in HELPERS]
+
+
+def create_helpers_tab(session_keys):
+    """Build the Cross-Entity Helpers tab."""
+
+    with gr.Tab("🔗 Cross-Entity Helpers"):
+        gr.Markdown(
+            "## Cross-Entity Pivots\n"
+            "Pivot from one entity to another without rebuilding filters.\n"
+            "Select a helper command, enter the ID, and go."
+        )
+
+        helper_choice = gr.Dropdown(
+            choices=HELPER_LABELS,
+            value=HELPER_LABELS[0],
+            label="Helper Command",
+        )
+
+        with gr.Row():
+            helper_id = gr.Textbox(
+                label="ID / Name",
+                placeholder="BRAF V600E",
+                scale=3,
+            )
+            helper_limit = gr.Number(label="Limit", value=5, minimum=1, maximum=50, scale=1)
+
+        with gr.Row():
+            no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        # Update placeholder when helper changes
+        def update_placeholder(choice):
+            idx = HELPER_LABELS.index(choice) if choice in HELPER_LABELS else 0
+            h = HELPERS[idx]
+            return gr.Textbox(placeholder=f"e.g., {h[3]}", label=h[2])
+
+        helper_choice.change(fn=update_placeholder, inputs=[helper_choice], outputs=[helper_id])
+
+        # Quick examples
+        gr.Markdown("**Quick examples:**")
+        with gr.Row():
+            ex1 = gr.Button('variant trials "BRAF V600E"', size="sm", variant="secondary")
+            ex2 = gr.Button("gene drugs BRAF", size="sm", variant="secondary")
+            ex3 = gr.Button("drug adverse-events pembrolizumab", size="sm", variant="secondary")
+            ex4 = gr.Button("article citations 22663011", size="sm", variant="secondary")
+
+        def set_ex(label, eid):
+            return label, eid
+
+        ex1.click(fn=lambda: set_ex(HELPER_LABELS[0], "BRAF V600E"), outputs=[helper_choice, helper_id])
+        ex2.click(fn=lambda: set_ex(HELPER_LABELS[9], "BRAF"), outputs=[helper_choice, helper_id])
+        ex3.click(fn=lambda: set_ex(HELPER_LABELS[3], "pembrolizumab"), outputs=[helper_choice, helper_id])
+        ex4.click(fn=lambda: set_ex(HELPER_LABELS[17], "22663011"), outputs=[helper_choice, helper_id])
+
+        run_btn = gr.Button("🔗 Run Helper", variant="primary")
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_helper(choice, eid, lim, skip_cache, keys):
+            if not eid.strip():
+                raise gr.Error("Please enter an ID or name (e.g., BRAF V600E, pembrolizumab, 22663011).")
+
+            idx = HELPER_LABELS.index(choice) if choice in HELPER_LABELS else 0
+            h = HELPERS[idx]
+            entity, verb = h[0], h[1]
+
+            args = [entity, verb, eid.strip()]
+            lim = int(lim) if lim else 5
+            args.extend(["--limit", str(lim)])
+
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        run_btn.click(
+            fn=run_helper,
+            inputs=[helper_choice, helper_id, helper_limit, no_cache, session_keys],
+            outputs=[output_md, output_json],
+        )

tabs/search.py

@@ -0,0 +1,360 @@
+"""
+Search tab — entity-based discovery across all 13+ entity types.
+Dynamic forms show/hide filters based on selected entity.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+ENTITY_CHOICES = [
+    "all", "gene", "disease", "variant", "article", "trial",
+    "drug", "pathway", "protein", "adverse-event", "pgx", "gwas", "phenotype",
+]
+
+TRIAL_STATUS = [
+    "", "recruiting", "not yet recruiting", "active, not recruiting",
+    "completed", "terminated", "suspended", "withdrawn",
+]
+
+TRIAL_PHASES = ["", "1", "2", "3", "4"]
+
+VARIANT_SIGNIFICANCE = [
+    "", "pathogenic", "likely_pathogenic", "uncertain_significance",
+    "likely_benign", "benign", "conflicting_interpretations", "risk_factor",
+]
+
+VARIANT_CONSEQUENCE = [
+    "", "missense_variant", "nonsense_variant", "synonymous_variant",
+    "frameshift_variant", "splice_acceptor_variant", "splice_donor_variant",
+    "inframe_deletion", "inframe_insertion", "stop_lost", "start_lost",
+]
+
+ARTICLE_SOURCE = ["", "all", "pubtator", "europepmc", "pubmed"]
+
+TRIAL_SOURCE = ["", "ctgov", "nci"]
+
+DISEASE_SOURCE = ["", "mondo"]
+
+SEARCH_EXAMPLES = {
+    "all": ("--gene BRAF --disease melanoma", "Cross-entity overview for BRAF + melanoma"),
+    "gene": ("-q BRAF", "Search genes matching BRAF"),
+    "disease": ("-q melanoma", "Search diseases matching melanoma"),
+    "variant": ("-g BRAF --hgvsp V600E", "Search BRAF V600E variants"),
+    "article": ("-g BRAF -d melanoma --since 2024-01-01", "BRAF melanoma articles since 2024"),
+    "trial": ("-c melanoma --status recruiting", "Recruiting melanoma trials"),
+    "drug": ("-q pembrolizumab", "Search drug pembrolizumab"),
+    "pathway": ('-q "MAPK signaling"', "Search MAPK signaling pathways"),
+    "protein": ("-q kinase", "Search kinase proteins"),
+    "adverse-event": ("--drug pembrolizumab --serious", "Serious adverse events for pembrolizumab"),
+    "pgx": ("-g CYP2D6", "PGx data for CYP2D6"),
+    "gwas": ('--trait "type 2 diabetes"', "GWAS for type 2 diabetes"),
+    "phenotype": ('"HP:0001250 HP:0001263"', "Phenotype similarity search"),
+}
+
+
+def create_search_tab(session_keys):
+    """Build the Search tab with dynamic entity forms."""
+
+    with gr.Tab("🔎 Search"):
+        gr.Markdown(
+            "## Entity Search\n"
+            "Discovery across 13 biomedical entity types. Select an entity and fill in the relevant filters."
+        )
+
+        with gr.Row():
+            entity = gr.Dropdown(
+                choices=ENTITY_CHOICES,
+                value="gene",
+                label="Entity Type",
+                scale=1,
+            )
+            limit = gr.Number(label="Limit", value=10, minimum=1, maximum=100, scale=1)
+            offset = gr.Number(label="Offset", value=0, minimum=0, scale=1)
+
+        with gr.Row():
+            no_cache = gr.Checkbox(label="Bypass cache", value=False)
+
+        # === All (cross-entity) filters ===
+        with gr.Group(visible=False) as all_group:
+            gr.Markdown("### Cross-Entity Search Filters")
+            with gr.Row():
+                all_gene = gr.Textbox(label="Gene", placeholder="e.g., BRAF")
+                all_disease = gr.Textbox(label="Disease", placeholder="e.g., melanoma")
+                all_keyword = gr.Textbox(label="Keyword", placeholder="e.g., immunotherapy resistance")
+            with gr.Row():
+                all_since = gr.Textbox(label="Since (date)", placeholder="e.g., 2024-01-01")
+                all_counts_only = gr.Checkbox(label="Counts only")
+                all_debug_plan = gr.Checkbox(label="Debug plan")
+
+        # === Gene filters ===
+        with gr.Group(visible=True) as gene_group:
+            gr.Markdown("### Gene Search")
+            gene_query = gr.Textbox(label="Query", placeholder="e.g., BRAF, TP53, EGFR")
+
+        # === Disease filters ===
+        with gr.Group(visible=False) as disease_group:
+            gr.Markdown("### Disease Search")
+            with gr.Row():
+                disease_query = gr.Textbox(label="Query", placeholder="e.g., melanoma, Lynch syndrome")
+                disease_source = gr.Dropdown(choices=DISEASE_SOURCE, value="", label="Source")
+
+        # === Variant filters ===
+        with gr.Group(visible=False) as variant_group:
+            gr.Markdown("### Variant Search")
+            with gr.Row():
+                variant_gene = gr.Textbox(label="Gene (-g)", placeholder="e.g., BRAF")
+                variant_hgvsp = gr.Textbox(label="HGVSp", placeholder="e.g., V600E")
+            with gr.Row():
+                variant_sig = gr.Dropdown(choices=VARIANT_SIGNIFICANCE, value="", label="Significance")
+                variant_consequence = gr.Dropdown(choices=VARIANT_CONSEQUENCE, value="", label="Consequence")
+
+        # === Article filters ===
+        with gr.Group(visible=False) as article_group:
+            gr.Markdown("### Article Search")
+            with gr.Row():
+                article_gene = gr.Textbox(label="Gene (-g)", placeholder="e.g., BRAF")
+                article_disease = gr.Textbox(label="Disease (-d)", placeholder="e.g., melanoma")
+            with gr.Row():
+                article_since = gr.Textbox(label="Since", placeholder="e.g., 2024-01-01")
+                article_source = gr.Dropdown(choices=ARTICLE_SOURCE, value="", label="Source")
+
+        # === Trial filters ===
+        with gr.Group(visible=False) as trial_group:
+            gr.Markdown("### Trial Search")
+            with gr.Row():
+                trial_condition = gr.Textbox(label="Condition (-c)", placeholder="e.g., melanoma")
+                trial_status = gr.Dropdown(choices=TRIAL_STATUS, value="", label="Status")
+                trial_phase = gr.Dropdown(choices=TRIAL_PHASES, value="", label="Phase")
+            with gr.Row():
+                trial_source = gr.Dropdown(choices=TRIAL_SOURCE, value="", label="Source")
+                trial_lat = gr.Textbox(label="Latitude", placeholder="e.g., 42.3601")
+                trial_lon = gr.Textbox(label="Longitude", placeholder="e.g., -71.0589")
+                trial_distance = gr.Textbox(label="Distance (mi)", placeholder="e.g., 50")
+
+        # === Drug filters ===
+        with gr.Group(visible=False) as drug_group:
+            gr.Markdown("### Drug Search")
+            with gr.Row():
+                drug_query = gr.Textbox(label="Query", placeholder="e.g., pembrolizumab, kinase inhibitor")
+                drug_region = gr.Dropdown(
+                    choices=[
+                        ("— Default (US + EU auto)", ""),
+                        ("🇪🇺 EU (European Medicines Agency)", "eu"),
+                    ],
+                    value="",
+                    label="Region",
+                )
+
+        # === Pathway filters ===
+        with gr.Group(visible=False) as pathway_group:
+            gr.Markdown("### Pathway Search")
+            pathway_query = gr.Textbox(label="Query", placeholder='e.g., "MAPK signaling", "Pathways in cancer"')
+
+        # === Protein filters ===
+        with gr.Group(visible=False) as protein_group:
+            gr.Markdown("### Protein Search")
+            with gr.Row():
+                protein_query = gr.Textbox(label="Query", placeholder="e.g., kinase")
+                protein_all_species = gr.Checkbox(label="All species")
+
+        # === Adverse Event filters ===
+        with gr.Group(visible=False) as ae_group:
+            gr.Markdown("### Adverse Event Search")
+            with gr.Row():
+                ae_drug = gr.Textbox(label="Drug", placeholder="e.g., pembrolizumab")
+                ae_serious = gr.Checkbox(label="Serious only")
+            with gr.Row():
+                ae_type = gr.Dropdown(choices=["", "device"], value="", label="Type")
+                ae_manufacturer = gr.Textbox(label="Manufacturer", placeholder="e.g., Medtronic")
+                ae_product_code = gr.Textbox(label="Product code", placeholder="e.g., PQP")
+
+        # === PGx filters ===
+        with gr.Group(visible=False) as pgx_group:
+            gr.Markdown("### PGx Search")
+            with gr.Row():
+                pgx_gene = gr.Textbox(label="Gene (-g)", placeholder="e.g., CYP2D6")
+                pgx_drug = gr.Textbox(label="Drug (-d)", placeholder="e.g., warfarin")
+
+        # === GWAS filters ===
+        with gr.Group(visible=False) as gwas_group:
+            gr.Markdown("### GWAS Search")
+            with gr.Row():
+                gwas_gene = gr.Textbox(label="Gene (-g)", placeholder="e.g., TCF7L2")
+                gwas_trait = gr.Textbox(label="Trait", placeholder='e.g., "type 2 diabetes"')
+
+        # === Phenotype filters ===
+        with gr.Group(visible=False) as phenotype_group:
+            gr.Markdown("### Phenotype Search (Monarch Semsim)")
+            phenotype_terms = gr.Textbox(label="HPO Terms", placeholder="e.g., HP:0001250 HP:0001263")
+
+        # Dynamic visibility
+        entity_groups = {
+            "all": all_group, "gene": gene_group, "disease": disease_group,
+            "variant": variant_group, "article": article_group, "trial": trial_group,
+            "drug": drug_group, "pathway": pathway_group, "protein": protein_group,
+            "adverse-event": ae_group, "pgx": pgx_group, "gwas": gwas_group,
+            "phenotype": phenotype_group,
+        }
+
+        def toggle_visibility(selected):
+            return [gr.Group(visible=(k == selected)) for k in entity_groups]
+
+        entity.change(
+            fn=toggle_visibility,
+            inputs=[entity],
+            outputs=list(entity_groups.values()),
+        )
+
+        # Example button
+        example_display = gr.Markdown("")
+
+        def show_example(ent):
+            if ent in SEARCH_EXAMPLES:
+                hint, desc = SEARCH_EXAMPLES[ent]
+                return f"**Example:** `biomcp search {ent} {hint}` — {desc}"
+            return ""
+
+        entity.change(fn=show_example, inputs=[entity], outputs=[example_display])
+
+        # Run button
+        run_btn = gr.Button("🔎 Search", variant="primary")
+        output_md = gr.Markdown(label="Results")
+        with gr.Accordion("Raw JSON", open=False):
+            output_json = gr.Code(language="json")
+
+        def run_search(
+            ent, lim, off, skip_cache, keys,
+            # all
+            a_gene, a_disease, a_keyword, a_since, a_counts, a_debug,
+            # gene
+            g_query,
+            # disease
+            d_query, d_source,
+            # variant
+            v_gene, v_hgvsp, v_sig, v_cons,
+            # article
+            ar_gene, ar_disease, ar_since, ar_source,
+            # trial
+            t_cond, t_status, t_phase, t_source, t_lat, t_lon, t_dist,
+            # drug
+            dr_query, dr_region,
+            # pathway
+            pw_query,
+            # protein
+            pr_query, pr_all_species,
+            # adverse event
+            ae_d, ae_s, ae_t, ae_m, ae_pc,
+            # pgx
+            pgx_g, pgx_d,
+            # gwas
+            gw_g, gw_t,
+            # phenotype
+            ph_terms,
+        ):
+            args = ["search", ent]
+
+            lim = int(lim) if lim else 10
+            off = int(off) if off else 0
+
+            if ent == "all":
+                if a_gene: args.extend(["--gene", a_gene.strip()])
+                if a_disease: args.extend(["--disease", a_disease.strip()])
+                if a_keyword: args.extend(["--keyword", a_keyword.strip()])
+                if a_since: args.extend(["--since", a_since.strip()])
+                if a_counts: args.append("--counts-only")
+                if a_debug: args.append("--debug-plan")
+            elif ent == "gene":
+                if g_query: args.extend(["-q", g_query.strip()])
+            elif ent == "disease":
+                if d_query: args.extend(["-q", d_query.strip()])
+                if d_source: args.extend(["--source", d_source])
+            elif ent == "variant":
+                if v_gene: args.extend(["-g", v_gene.strip()])
+                if v_hgvsp: args.extend(["--hgvsp", v_hgvsp.strip()])
+                if v_sig: args.extend(["--significance", v_sig])
+                if v_cons: args.extend(["--consequence", v_cons])
+            elif ent == "article":
+                if ar_gene: args.extend(["-g", ar_gene.strip()])
+                if ar_disease: args.extend(["-d", ar_disease.strip()])
+                if ar_since: args.extend(["--since", ar_since.strip()])
+                if ar_source: args.extend(["--source", ar_source])
+            elif ent == "trial":
+                if t_cond: args.extend(["-c", t_cond.strip()])
+                if t_status: args.extend(["--status", t_status])
+                if t_phase: args.extend(["--phase", t_phase])
+                if t_source: args.extend(["--source", t_source])
+                if t_lat: args.extend(["--lat", t_lat.strip()])
+                if t_lon: args.extend(["--lon", t_lon.strip()])
+                if t_dist: args.extend(["--distance", t_dist.strip()])
+            elif ent == "drug":
+                if dr_query: args.extend(["-q", dr_query.strip()])
+                if dr_region: args.extend(["--region", dr_region])
+            elif ent == "pathway":
+                if pw_query: args.extend(["-q", pw_query.strip()])
+            elif ent == "protein":
+                if pr_query: args.extend(["-q", pr_query.strip()])
+                if pr_all_species: args.append("--all-species")
+            elif ent == "adverse-event":
+                if ae_d: args.extend(["--drug", ae_d.strip()])
+                if ae_s: args.append("--serious")
+                if ae_t: args.extend(["--type", ae_t])
+                if ae_m: args.extend(["--manufacturer", ae_m.strip()])
+                if ae_pc: args.extend(["--product-code", ae_pc.strip()])
+            elif ent == "pgx":
+                if pgx_g: args.extend(["-g", pgx_g.strip()])
+                if pgx_d: args.extend(["-d", pgx_d.strip()])
+            elif ent == "gwas":
+                if gw_g: args.extend(["-g", gw_g.strip()])
+                if gw_t: args.extend(["--trait", gw_t.strip()])
+            elif ent == "phenotype":
+                if ph_terms: args.append(ph_terms.strip())
+
+            # Add limit/offset
+            args.extend(["--limit", str(lim)])
+            if off > 0:
+                args.extend(["--offset", str(off)])
+
+            env = config.build_env_overrides(keys)
+            result = runner.run(args, json_mode=True, no_cache=skip_cache, env_overrides=env)
+            if not result["success"]:
+                raise gr.Error(f"BioMCP error: {result['error']}")
+            md, js = format_result(result)
+            return md, js
+
+        all_inputs = [
+            entity, limit, offset, no_cache, session_keys,
+            # all
+            all_gene, all_disease, all_keyword, all_since, all_counts_only, all_debug_plan,
+            # gene
+            gene_query,
+            # disease
+            disease_query, disease_source,
+            # variant
+            variant_gene, variant_hgvsp, variant_sig, variant_consequence,
+            # article
+            article_gene, article_disease, article_since, article_source,
+            # trial
+            trial_condition, trial_status, trial_phase, trial_source,
+            trial_lat, trial_lon, trial_distance,
+            # drug
+            drug_query, drug_region,
+            # pathway
+            pathway_query,
+            # protein
+            protein_query, protein_all_species,
+            # adverse-event
+            ae_drug, ae_serious, ae_type, ae_manufacturer, ae_product_code,
+            # pgx
+            pgx_gene, pgx_drug,
+            # gwas
+            gwas_gene, gwas_trait,
+            # phenotype
+            phenotype_terms,
+        ]
+
+        run_btn.click(
+            fn=run_search,
+            inputs=all_inputs,
+            outputs=[output_md, output_json],
+        )

tabs/settings.py

@@ -0,0 +1,99 @@
+"""
+Settings & Health tab — API key management, health checks, and version info.
+"""
+
+import gradio as gr
+from core import config, runner
+from core.formatter import format_result
+
+
+def create_settings_tab(session_keys):
+    """Build the Settings & Health tab."""
+
+    with gr.Tab("⚙️ Settings & Health"):
+        gr.Markdown("## API Key Configuration\nKeys are stored in session only — never written to disk.")
+
+        key_inputs = {}
+
+        with gr.Row():
+            with gr.Column():
+                for key_name, meta in list(config.API_KEYS.items())[:4]:
+                    key_inputs[key_name] = gr.Textbox(
+                        label=f"{meta['label']}",
+                        info=f"{meta['description']} — [Get key]({meta['url']})",
+                        type="password",
+                        value="",
+                        placeholder="Paste key here...",
+                    )
+            with gr.Column():
+                for key_name, meta in list(config.API_KEYS.items())[4:]:
+                    key_inputs[key_name] = gr.Textbox(
+                        label=f"{meta['label']}",
+                        info=f"{meta['description']} — [Get key]({meta['url']})",
+                        type="password",
+                        value="",
+                        placeholder="Paste key here...",
+                    )
+
+        gr.Markdown("### Additional Configuration")
+        config_inputs = {}
+        for var_name, meta in config.CONFIG_VARS.items():
+            config_inputs[var_name] = gr.Textbox(
+                label=meta["label"],
+                info=meta["description"],
+                value="",
+                placeholder="Leave blank for default",
+            )
+
+        save_btn = gr.Button("💾 Save Keys to Session", variant="primary")
+        save_status = gr.Markdown("")
+
+        gr.Markdown("---")
+        gr.Markdown("## System Checks")
+
+        with gr.Row():
+            health_btn = gr.Button("🏥 Health Check", variant="secondary")
+            version_btn = gr.Button("ℹ️ Version Info", variant="secondary")
+
+        check_output_md = gr.Markdown("")
+        with gr.Accordion("Raw JSON", open=False):
+            check_output_json = gr.Code(language="json")
+
+        def save_keys(*values):
+            all_keys = list(config.API_KEYS.keys()) + list(config.CONFIG_VARS.keys())
+            keys = {}
+            for name, val in zip(all_keys, values):
+                keys[name] = val.strip() if val else ""
+            filled = sum(1 for v in keys.values() if v)
+            return keys, f"**Saved {filled} key(s) to session.** These will be used for all commands."
+
+        all_key_components = list(key_inputs.values()) + list(config_inputs.values())
+        save_btn.click(
+            fn=save_keys,
+            inputs=all_key_components,
+            outputs=[session_keys, save_status],
+        )
+
+        def run_health(keys):
+            env = config.build_env_overrides(keys)
+            result = runner.run_markdown(["health", "--apis-only"], env_overrides=env, timeout=30)
+            md, js = format_result(result)
+            return md, js
+
+        health_btn.click(
+            fn=run_health,
+            inputs=[session_keys],
+            outputs=[check_output_md, check_output_json],
+        )
+
+        def run_version(keys):
+            env = config.build_env_overrides(keys)
+            result = runner.run_markdown(["version"], env_overrides=env, timeout=10)
+            md, js = format_result(result)
+            return md, js
+
+        version_btn.click(
+            fn=run_version,
+            inputs=[session_keys],
+            outputs=[check_output_md, check_output_json],
+        )