feat(trials): facility & geography search + targeted mechanism & explainable evidence tier (#22)

* feat(trials): facility & geography trial search with evidence enrichment

Physicians can now find ALS trials by facility ("trials at Mass General
Hospital") or geography ("trials in NY"), with each result enriched by
surrounding research evidence.

- ingestion: _flatten_trial() parses contactsLocationsModule so each trial
persists a locations list (facility/city/state/country/status/lat/lon) plus
central contact phone/email; TrialSummary gains matching fields.
- trials_query.py (new): search_trials_by_location() (state abbrev→name,
token-substring facility match, recruiting filter) and enrich_trial()
(key papers via the RAG retriever + citation boost, sibling trials for the
same compound, heuristic Strong/Moderate/Emerging evidence tier), plus an
HTML renderer.
- agent: new find_trials_by_location tool wired into RESEARCH_TOOLS and
dispatched in research_agent; prompt guidance added for when to use it.
- app: dedicated "Clinical Trials" tab (facility/state/city/status inputs →
enriched cards); _ensure_data() also fetches trials.jsonl for the Space.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(trials): targeted mechanism + explainable evidence tier

Reverse-index each trial's dominant mechanism class from the offline
landscape (no LLM at query time) and surface it as a "Mechanism" pill.
Feed the mechanism's KG hub node into _kg_paper_count so a compound whose
only extracted target is its own name still gets credit for its
mechanism's literature instead of scoring 0.

Make the evidence tier explain itself: _evidence_tier now returns a
per-factor rationale (points + physician-readable reason) and the KG
node that supplied the paper count, flagging when credit came from the
mechanism vs. the drug target. Rendered as a collapsible "Why <tier>?"
disclosure on each trial card; the agent is told to justify tiers from
evidence.rationale.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

agents/research_agent.py

@@ -26,6 +26,7 @@ from normalization.drug_vocab import build_drug_vocab, suggest_drug_term
 from prompts import SYNTHESIS_SYSTEM
 from rag import retriever as rag_retriever
 from tools import RESEARCH_TOOLS
+import trials_query
 
 _logger = get_logger("agents.research_agent")
 
@@ -135,6 +136,9 @@ def stream_research_agent(
                 if tool_call["name"] == "search_research_landscape":
                     result = _handle_search(tool_call["input"], collection, trials, _graph)
                     is_error = False
+                elif tool_call["name"] == "find_trials_by_location":
+                    result = _handle_trials_by_location(tool_call["input"], trials, collection, _graph)
+                    is_error = False
                 else:
                     result = {"error": f"Unknown tool: {tool_call['name']}"}
                     is_error = True
@@ -453,3 +457,68 @@ def _handle_search(
         "kg_expansion_active": graph is not None,
         "grounding_note": grounding_note,
     }
+
+
+# Cap enrichment work per location query — each trial triggers RAG retrieval, so bound it.
+_LOCATION_ENRICH_CAP = 25
+
+
+def _handle_trials_by_location(
+    tool_input: dict,
+    trials: list[dict],
+    collection: chromadb.Collection | None = None,
+    graph: nx.DiGraph | None = None,
+) -> dict:
+    """Filter trials by facility/geography and enrich each with research evidence."""
+    facility = tool_input.get("facility") or None
+    city = tool_input.get("city") or None
+    state = tool_input.get("state") or None
+    country = tool_input.get("country") or None
+    status = tool_input.get("status") or None
+
+    matches = trials_query.search_trials_by_location(
+        trials, facility=facility, city=city, state=state, country=country, status=status
+    )
+
+    enriched = [
+        trials_query.enrich_trial(t, collection, graph, trials)
+        for t in matches[:_LOCATION_ENRICH_CAP]
+    ]
+
+    where_parts = [p for p in (facility, city, state, country) if p]
+    where = ", ".join(where_parts) or "the requested location"
+
+    _logger.info(
+        "location trial search",
+        extra={"data": {
+            "facility": facility, "city": city, "state": state, "country": country,
+            "status": status, "matches": len(matches), "enriched": len(enriched),
+        }},
+    )
+
+    if not enriched:
+        grounding_note = (
+            f"No ALS clinical trials in this database have a study site matching {where}. "
+            "State that plainly; do not invent trials or sites."
+        )
+    else:
+        grounding_note = (
+            f"{len(matches)} ALS trial(s) have a study site matching {where} "
+            f"(showing {len(enriched)}). Report them grouped by recruiting status (recruiting "
+            "first). For each, give the NCT ID, phase, matched facility/city/state, the targeted "
+            "mechanism (when present), and evidence tier. When you state a tier, justify it briefly "
+            "from evidence.rationale (the scoring factors and points behind it, incl. which KG node "
+            "supplied the paper count). Cite key_papers by PMID only for claims "
+            "their titles support. Mention "
+            "sibling_trials as related trials for the same compound. Do not add trials not listed here."
+        )
+
+    return {
+        "location_query": {
+            "facility": facility, "city": city, "state": state,
+            "country": country, "status": status,
+        },
+        "match_count": len(matches),
+        "trials": enriched,
+        "grounding_note": grounding_note,
+    }

app.py

@@ -56,7 +56,8 @@ def _ensure_data() -> None:
     """
     need_chroma = not (CHROMA_DIR / "chroma.sqlite3").exists()
     need_graph = not GRAPH_PICKLE_PATH.exists()
-    if not need_chroma and not need_graph:
+    need_trials = not TRIALS_PATH.exists()
+    if not need_chroma and not need_graph and not need_trials:
         return
     try:
         from huggingface_hub import hf_hub_download, snapshot_download
@@ -82,6 +83,14 @@ def _ensure_data() -> None:
                 filename="graph/als_graph.pkl", local_dir=str(GRAPH_PICKLE_PATH.parent.parent),
             )
             _logger.info("Graph download complete")
+        if need_trials:
+            _logger.info("Downloading trials from HF dataset...")
+            TRIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+            hf_hub_download(
+                repo_id=_HF_DATASET, repo_type="dataset",
+                filename="trials/trials.jsonl", local_dir=str(TRIALS_PATH.parent.parent),
+            )
+            _logger.info("Trials download complete")
     except Exception as e:
         _logger.warning(f"Failed to download data from HF dataset: {e}")
 
@@ -192,6 +201,32 @@ def _compound_change(label: str):
     )
 
 
+# ── Clinical Trials tab (facility / geography search) ─────────────────────────
+
+import trials_query
+
+_TRIAL_ENRICH_CAP = 25
+_US_STATES = ["All"] + sorted(set(trials_query._STATE_ABBREV.values()))
+
+
+def _search_trials(facility: str, state: str, city: str, status: str) -> str:
+    facility = (facility or "").strip() or None
+    city = (city or "").strip() or None
+    state = None if (not state or state == "All") else state
+
+    if not any([facility, city, state]):
+        return '<div style="color:#888;padding:12px 0;">Enter a facility, state, or city to search.</div>'
+
+    matches = trials_query.search_trials_by_location(
+        _trials, facility=facility, city=city, state=state, status=status
+    )
+    enriched = [
+        trials_query.enrich_trial(t, _collection, _graph, _trials)
+        for t in matches[:_TRIAL_ENRICH_CAP]
+    ]
+    return trials_query.render_trials_html(enriched, len(matches))
+
+
 with gr.Blocks(title="Candle-Fire — ALS Research Intelligence") as demo:
 
     with gr.Tabs():
@@ -307,6 +342,39 @@ with gr.Blocks(title="Candle-Fire — ALS Research Intelligence") as demo:
 
                 gr.HTML(_DISCLAIMER_MD)
 
+        with gr.Tab("🏥 Clinical Trials"):
+            with gr.Column(elem_classes="container"):
+                gr.Markdown(
+                    "### 🏥 Find ALS Trials by Facility or Geography\n"
+                    "Search the trial database by **facility** (e.g. *Mass General Hospital*) or "
+                    "**location** (state / city). Each result is enriched with recruiting status, an "
+                    "evidence-strength tier, key supporting papers, and related trials for the same compound."
+                )
+                with gr.Row():
+                    facility_tb = gr.Textbox(
+                        label="Facility / institution", scale=2,
+                        placeholder="e.g. Mass General Hospital",
+                    )
+                    state_dd = gr.Dropdown(
+                        choices=_US_STATES, value="All", label="State", scale=1,
+                    )
+                    city_tb = gr.Textbox(label="City", scale=1, placeholder="e.g. Boston")
+                    trial_status_dd = gr.Dropdown(
+                        choices=["All", "Recruiting", "Not recruiting"],
+                        value="All", label="Recruitment status", scale=1,
+                    )
+                search_btn = gr.Button("Search trials", variant="primary")
+                trial_results = gr.HTML(
+                    '<div style="color:#888;padding:12px 0;">Enter a facility, state, or city to search.</div>'
+                )
+
+                _trial_search_inputs = [facility_tb, state_dd, city_tb, trial_status_dd]
+                search_btn.click(_search_trials, inputs=_trial_search_inputs, outputs=[trial_results])
+                facility_tb.submit(_search_trials, inputs=_trial_search_inputs, outputs=[trial_results])
+                city_tb.submit(_search_trials, inputs=_trial_search_inputs, outputs=[trial_results])
+
+                gr.HTML(_DISCLAIMER_MD)
+
     submit_kwargs = dict(
         fn=respond,
         inputs=[msg_box, chatbot],

data/tools/find_trials_by_location.json

@@ -0,0 +1,26 @@
+{
+  "type": "object",
+  "properties": {
+    "facility": {
+      "type": "string",
+      "description": "Hospital, institution, or research-site name mentioned in the question (e.g. 'Mass General Hospital', 'Mayo Clinic'). Provide the name as written; partial names are matched."
+    },
+    "city": {
+      "type": "string",
+      "description": "City name mentioned in the question (e.g. 'Boston')."
+    },
+    "state": {
+      "type": "string",
+      "description": "US state mentioned in the question, as a two-letter abbreviation or full name (e.g. 'NY' or 'New York')."
+    },
+    "country": {
+      "type": "string",
+      "description": "Country mentioned in the question (e.g. 'United States'). Only for non-US or explicitly international queries."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Recruiting", "Not recruiting", "All"],
+      "description": "Recruitment filter. Use 'Recruiting' when the physician asks for open/enrolling trials; otherwise 'All'."
+    }
+  }
+}

ingestion/clinicaltrials.py

@@ -87,6 +87,7 @@ def _flatten_trial(study: dict) -> dict:
     sponsor_mod = proto.get("sponsorCollaboratorsModule", {})
     arms_mod = proto.get("armsInterventionsModule", {})
     status_mod = proto.get("statusModule", {})
+    contacts_mod = proto.get("contactsLocationsModule", {})
 
     nct_id = id_mod.get("nctId", "")
     interventions = [
@@ -97,6 +98,26 @@ def _flatten_trial(study: dict) -> dict:
     study_type = design_mod.get("studyType", "")
     is_eap = study_type == "EXPANDED_ACCESS"
 
+    # Site locations — facility, address, per-site recruiting status, and geo point.
+    # Physicians search trials by facility ("Mass General") or place ("in NY"), so this
+    # address data must be persisted in the trials DB (offline; no fetch at query time).
+    locations = [
+        {
+            "facility": (loc.get("facility") or "").strip(),
+            "city": loc.get("city", ""),
+            "state": loc.get("state", ""),
+            "country": loc.get("country", ""),
+            "status": loc.get("status", ""),  # per-site recruiting status
+            "lat": (loc.get("geoPoint") or {}).get("lat"),
+            "lon": (loc.get("geoPoint") or {}).get("lon"),
+        }
+        for loc in contacts_mod.get("locations", [])
+    ]
+
+    central_contacts = contacts_mod.get("centralContacts", [])
+    contact_phone = next((c.get("phone", "") for c in central_contacts if c.get("phone")), "")
+    contact_email = next((c.get("email", "") for c in central_contacts if c.get("email")), "")
+
     return {
         "nct_id": nct_id,
         "title": id_mod.get("briefTitle", ""),
@@ -111,6 +132,9 @@ def _flatten_trial(study: dict) -> dict:
         "start_date": status_mod.get("startDateStruct", {}).get("date", ""),
         "url": f"https://clinicaltrials.gov/study/{nct_id}" if nct_id else "",
         "target_entities": [],
+        "locations": locations,
+        "contact_phone": contact_phone,
+        "contact_email": contact_email,
     }
 
 

models.py

@@ -113,6 +113,11 @@ class TrialSummary:
     sponsor: str = ""
     start_date: str = ""
     url: str = ""
+    # Site locations: {facility, city, state, country, status, lat, lon}. Enables
+    # facility/geography trial search (e.g. "trials at Mass General", "trials in NY").
+    locations: list[dict] = field(default_factory=list)
+    contact_phone: str = ""
+    contact_email: str = ""
 
 
 @dataclass

prompts.py

@@ -98,6 +98,10 @@ Any relevant ALS clinical trials linked to the topic, with NCT ID and status.
 *Research synthesis tool. Always verify with primary sources and current clinical evidence.
 Not a substitute for clinical judgment.*
 
+Tool selection:
+- Use `search_research_landscape` for questions about ALS biology, drug targets, mechanisms, or a compound's evidence — this is the default.
+- Use `find_trials_by_location` when the question names a hospital/research site (e.g. "trials at Mass General Hospital") or a place (state/city/country, e.g. "trials in NY"). Pass the facility/city/state/country you identified and set `status` to "Recruiting" only if the physician asked for open/enrolling trials. When it returns trials, present them grouped by recruiting status (recruiting first); for each give the NCT ID (as a link when a url is provided), phase, the matched facility/city/state, the evidence-strength tier, key supporting papers (cite PMIDs only for claims their titles support), and any sibling_trials as related trials for the same compound.
+
 Guidelines:
 - Begin directly with the structured response — no preamble, no "let me search", no narration of your reasoning steps
 - GROUNDING RULE (non-negotiable): Every factual claim must be directly supported by text in the retrieved excerpt for the PMID you cite. Before citing a PMID, verify the claim actually appears in that paper's excerpt. NEVER cite a PMID because it is topically adjacent — a citation asserts that specific paper supports that specific claim.

tools.py

@@ -34,6 +34,18 @@ SEARCH_LANDSCAPE_TOOL: anthropic.types.ToolParam = {
     "input_schema": _load("search_landscape"),
 }
 
+FIND_TRIALS_BY_LOCATION_TOOL: anthropic.types.ToolParam = {
+    "name": "find_trials_by_location",
+    "description": (
+        "Find ALS clinical trials by the facility/institution or the geography (state, city, "
+        "or country) where they are conducted. Use this when the physician's question names a "
+        "hospital or research site (e.g. 'trials at Mass General Hospital') or a place (e.g. "
+        "'trials in NY'). Returns matching trials enriched with recruiting status, an evidence-"
+        "strength tier, key supporting papers, and related trials for the same compound."
+    ),
+    "input_schema": _load("find_trials_by_location"),
+}
+
 EXTRACT_TRIAL_TARGETS_TOOL: anthropic.types.ToolParam = {
     "name": "extract_trial_targets",
     "description": (
@@ -55,5 +67,5 @@ CLASSIFY_THERAPY_TOOL: anthropic.types.ToolParam = {
 
 EXTRACTION_TOOLS: list[anthropic.types.ToolParam] = [EXTRACT_ENTITIES_TOOL]
 TRIAL_EXTRACTION_TOOLS: list[anthropic.types.ToolParam] = [EXTRACT_TRIAL_TARGETS_TOOL]
-RESEARCH_TOOLS: list[anthropic.types.ToolParam] = [SEARCH_LANDSCAPE_TOOL]
+RESEARCH_TOOLS: list[anthropic.types.ToolParam] = [SEARCH_LANDSCAPE_TOOL, FIND_TRIALS_BY_LOCATION_TOOL]
 LANDSCAPE_TOOLS: list[anthropic.types.ToolParam] = [CLASSIFY_THERAPY_TOOL]

trials_query.py

@@ -0,0 +1,512 @@
+"""Facility / geography trial search + research-evidence enrichment.
+
+Physicians ask "what trials are at Mass General Hospital" or "what trials are in NY".
+This module filters the offline-ingested trials list by facility/city/state/country
+(in-memory — no fetch at query time) and enriches each hit with surrounding research
+evidence: key papers, sibling trials for the same compound, a heuristic evidence-strength
+tier, and recruiting status.
+"""
+from __future__ import annotations
+
+import html
+import json
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+from logging_config import get_logger
+
+if TYPE_CHECKING:
+    import chromadb
+    import networkx as nx
+
+_logger = get_logger("trials_query")
+
+# Site statuses that count as "recruiting / open to enrollment".
+RECRUITING_STATUSES = {
+    "RECRUITING", "NOT_YET_RECRUITING", "ENROLLING_BY_INVITATION", "AVAILABLE",
+}
+
+# Trial status display order — open first, closed/unavailable last (mirrors research_agent).
+_TRIAL_STATUS_RANK = {
+    "AVAILABLE": 0, "RECRUITING": 1, "NOT_YET_RECRUITING": 2, "ENROLLING_BY_INVITATION": 3,
+    "ACTIVE_NOT_RECRUITING": 4, "TEMPORARILY_NOT_AVAILABLE": 5, "COMPLETED": 6,
+    "SUSPENDED": 7, "TERMINATED": 8, "WITHDRAWN": 9, "NO_LONGER_AVAILABLE": 10,
+}
+
+# US state abbreviation → full name. ClinicalTrials.gov stores the full state name, so
+# "NY" must be normalized to "New York" before matching.
+_STATE_ABBREV = {
+    "AL": "Alabama", "AK": "Alaska", "AZ": "Arizona", "AR": "Arkansas", "CA": "California",
+    "CO": "Colorado", "CT": "Connecticut", "DE": "Delaware", "FL": "Florida", "GA": "Georgia",
+    "HI": "Hawaii", "ID": "Idaho", "IL": "Illinois", "IN": "Indiana", "IA": "Iowa",
+    "KS": "Kansas", "KY": "Kentucky", "LA": "Louisiana", "ME": "Maine", "MD": "Maryland",
+    "MA": "Massachusetts", "MI": "Michigan", "MN": "Minnesota", "MS": "Mississippi",
+    "MO": "Missouri", "MT": "Montana", "NE": "Nebraska", "NV": "Nevada", "NH": "New Hampshire",
+    "NJ": "New Jersey", "NM": "New Mexico", "NY": "New York", "NC": "North Carolina",
+    "ND": "North Dakota", "OH": "Ohio", "OK": "Oklahoma", "OR": "Oregon", "PA": "Pennsylvania",
+    "RI": "Rhode Island", "SC": "South Carolina", "SD": "South Dakota", "TN": "Tennessee",
+    "TX": "Texas", "UT": "Utah", "VT": "Vermont", "VA": "Virginia", "WA": "Washington",
+    "WV": "West Virginia", "WI": "Wisconsin", "WY": "Wyoming", "DC": "District of Columbia",
+}
+
+# Generic facility words that carry no discriminating signal on their own.
+_FACILITY_STOPWORDS = {"of", "the", "and", "at", "for"}
+
+
+def _norm_alnum(s: str) -> str:
+    """Lowercase, alphanumeric-only form so 'CNM-Au8', 'CNMAu8', 'cnm_au8' all unify."""
+    return "".join(c for c in s.lower() if c.isalnum())
+
+
+def _tokens(s: str) -> list[str]:
+    """Lowercased alphanumeric word tokens, minus stopwords."""
+    words = "".join(c if c.isalnum() else " " for c in s.lower()).split()
+    return [w for w in words if w not in _FACILITY_STOPWORDS]
+
+
+def _normalize_state(state: str) -> str:
+    """Map a state abbreviation to its full name; pass full names through unchanged."""
+    s = state.strip()
+    return _STATE_ABBREV.get(s.upper(), s)
+
+
+def _facility_matches(query: str, site_facility: str) -> bool:
+    """True if every query token is a substring of some site-facility token.
+
+    Token-level substring matching lets 'Mass General' match 'Massachusetts General
+    Hospital' ('mass' ⊂ 'massachusetts') without a fuzzy library.
+    """
+    q_tokens = _tokens(query)
+    if not q_tokens:
+        return False
+    site_tokens = _tokens(site_facility)
+    return all(any(q in st for st in site_tokens) for q in q_tokens)
+
+
+def _site_matches(
+    site: dict,
+    facility: str | None,
+    city: str | None,
+    state: str | None,
+    country: str | None,
+) -> bool:
+    """True if a single trial site satisfies every provided location filter."""
+    if facility and not _facility_matches(facility, site.get("facility", "")):
+        return False
+    if city and city.strip().lower() not in (site.get("city", "") or "").lower():
+        return False
+    if state:
+        want = _normalize_state(state).lower()
+        if want != (site.get("state", "") or "").lower():
+            return False
+    if country and country.strip().lower() not in (site.get("country", "") or "").lower():
+        return False
+    return True
+
+
+def search_trials_by_location(
+    trials: list[dict],
+    *,
+    facility: str | None = None,
+    city: str | None = None,
+    state: str | None = None,
+    country: str | None = None,
+    status: str | None = None,
+) -> list[dict]:
+    """Return trials with at least one site matching the location filters.
+
+    `status`: "Recruiting" keeps only trials with an open overall status; "Not recruiting"
+    keeps only closed ones; anything else (None / "All") keeps all. Each returned trial is a
+    shallow copy with `matched_sites` attached; recruiting trials are ranked first.
+    """
+    if not any([facility, city, state, country]):
+        return []
+
+    status_filter = (status or "").strip().lower()
+    results: list[dict] = []
+    for trial in trials:
+        matched_sites = [
+            s for s in trial.get("locations", [])
+            if _site_matches(s, facility, city, state, country)
+        ]
+        if not matched_sites:
+            continue
+
+        is_recruiting = trial.get("status", "") in RECRUITING_STATUSES
+        if status_filter == "recruiting" and not is_recruiting:
+            continue
+        if status_filter == "not recruiting" and is_recruiting:
+            continue
+
+        hit = dict(trial)
+        hit["matched_sites"] = matched_sites
+        results.append(hit)
+
+    results.sort(key=lambda t: _TRIAL_STATUS_RANK.get(t.get("status", ""), 99))
+    return results
+
+
+def _find_supporting_papers(
+    trial: dict,
+    collection: "chromadb.Collection | None",
+    top_n: int = 3,
+) -> list[dict]:
+    """Retrieve the top research papers relevant to this trial's compound/target."""
+    if collection is None or collection.count() == 0:
+        return []
+
+    from rag import retriever as rag_retriever
+
+    entities = list(trial.get("target_entities") or [])
+    if entities:
+        results = rag_retriever.search_by_entities(collection, entities)
+    else:
+        # No extracted target — fall back to the trial title + intervention names.
+        iv_names = " ".join(iv.get("name", "") for iv in trial.get("interventions", []))
+        query = f"{trial.get('title', '')} {iv_names}".strip()
+        results = rag_retriever.search(collection, query) if query else []
+
+    results = rag_retriever.apply_citation_boost(results)
+    return [
+        {
+            "pmid": r["pmid"],
+            "title": r["title"],
+            "year": r["year"],
+            "citation_count": r["citation_count"],
+        }
+        for r in results[:top_n]
+    ]
+
+
+def _find_sibling_trials(
+    trial: dict,
+    all_trials: list[dict],
+    top_n: int = 5,
+) -> list[dict]:
+    """Other trials testing the same compound/target (prior + concurrent), excluding self."""
+    self_nct = trial.get("nct_id", "")
+    self_targets = {t.lower() for t in trial.get("target_entities", [])}
+    self_ivs = {_norm_alnum(iv.get("name", "")) for iv in trial.get("interventions", [])}
+    self_ivs.discard("")
+
+    siblings: list[dict] = []
+    for other in all_trials:
+        if other.get("nct_id", "") == self_nct:
+            continue
+        other_targets = {t.lower() for t in other.get("target_entities", [])}
+        other_ivs = {_norm_alnum(iv.get("name", "")) for iv in other.get("interventions", [])}
+        if (self_targets & other_targets) or (self_ivs & other_ivs):
+            siblings.append({
+                "nct_id": other.get("nct_id", ""),
+                "title": other.get("title", ""),
+                "phase": other.get("phase", ""),
+                "status": other.get("status", ""),
+                "url": other.get("url", ""),
+            })
+
+    siblings.sort(key=lambda t: _TRIAL_STATUS_RANK.get(t.get("status", ""), 99))
+    return siblings[:top_n]
+
+
+# ── Targeted mechanism (reverse-indexed from the offline therapy landscape) ───
+# A trial's "targeted mechanism" is the dominant mechanism class of the compound it
+# tests, reused from the already-built landscape.json (no LLM at query time). Only
+# landscape-classified compounds get one; unclassified drugs (e.g. brand-new agents
+# whose only extracted target is their own name) map to "" and show no mechanism.
+
+def _primary_class(therapy: dict) -> str:
+    """A compound's dominant mechanism class: primary role, else highest confidence.
+
+    Mirrors landscape._primary_class. Returns "" when the compound has no mechanism
+    (landscape left it unclassified).
+    """
+    mechs = therapy.get("mechanisms") or []
+    if not mechs:
+        return ""
+    pool = [m for m in mechs if m.get("role") == "primary"] or mechs
+    best = max(pool, key=lambda m: m.get("confidence", 0) or 0)
+    return best.get("class", "") or ""
+
+
+@lru_cache(maxsize=1)
+def _mechanism_index() -> dict[str, str]:
+    """Map NCT ID → targeted-mechanism class name, reverse-indexed from landscape.json.
+
+    Classified compounds take precedence over unclassified ones; compounds with no
+    mechanism are skipped. Returns {} when the landscape artifact is absent.
+    """
+    from config import LANDSCAPE_PATH
+
+    if not LANDSCAPE_PATH.exists():
+        return {}
+    try:
+        landscape = json.loads(LANDSCAPE_PATH.read_text())
+    except Exception:
+        _logger.warning("could not load landscape for mechanism index", exc_info=True)
+        return {}
+
+    index: dict[str, str] = {}
+    # classifications first so a classified compound's mechanism wins over unclassified
+    for group in (landscape.get("classifications", []) + landscape.get("unclassified", [])):
+        therapies = group.get("therapies", [group]) if "therapies" in group else [group]
+        for therapy in therapies:
+            mechanism = _primary_class(therapy)
+            if not mechanism:
+                continue
+            for tr in therapy.get("trials", []):
+                index.setdefault(tr.get("nct_id", ""), mechanism)
+    index.pop("", None)
+    return index
+
+
+def _kg_paper_count(
+    trial: dict, graph: "nx.DiGraph | None", mechanism: str = ""
+) -> tuple[int, str]:
+    """Max supporting-paper count in the KG, and the node label that supplied it.
+
+    Considers this trial's target entities plus its targeted `mechanism` hub node, so a
+    compound whose only extracted target is its own name (no KG node) still gets credit
+    for its mechanism's literature instead of scoring 0. The returned label lets the tier
+    show a physician *which* node the count came from (e.g. the mechanism vs. the target).
+    """
+    if graph is None:
+        return 0, ""
+    from graph.query import _find_node
+
+    # (name, is_mechanism) — mechanism last so a real target wins ties.
+    names = [(n, False) for n in trial.get("target_entities", [])]
+    if mechanism:
+        names.append((mechanism, True))
+
+    best, best_label = 0, ""
+    for name, is_mech in names:
+        for node_id in _find_node(graph, name):
+            count = graph.nodes[node_id].get("paper_count", 0)
+            if count > best:
+                best = count
+                display = graph.nodes[node_id].get("display_name", name)
+                best_label = f"{display} (mechanism)" if is_mech else display
+    return best, best_label
+
+
+def _evidence_tier(
+    trial: dict,
+    key_papers: list[dict],
+    kg_paper_count: int,
+    kg_source: str = "",
+) -> dict:
+    """Heuristic evidence-strength tier from paper count, citations, KG breadth, and phase.
+
+    Strong / Moderate / Emerging — a fully offline signal (no LLM call). Returns a
+    `rationale`: one entry per scoring factor with the points it earned and a physician-
+    readable reason (including *which* KG node supplied the paper count), so the tier can
+    explain itself rather than presenting a bare label.
+    """
+    n_papers = len(key_papers)
+    max_cit = max((p.get("citation_count", 0) for p in key_papers), default=0)
+    phase = (trial.get("phase", "") or "").upper()
+
+    rationale: list[dict] = []
+
+    def factor(label: str, pts: int, detail: str) -> None:
+        rationale.append({"factor": label, "points": pts, "detail": detail})
+
+    if n_papers >= 5:
+        factor("Supporting papers", 2, f"{n_papers} supporting papers in the database (≥5)")
+    elif n_papers >= 2:
+        factor("Supporting papers", 1, f"{n_papers} supporting papers in the database (2–4)")
+    else:
+        factor("Supporting papers", 0, f"{n_papers} supporting paper(s) in the database (<2)")
+
+    if max_cit >= 100:
+        factor("Citation impact", 2, f"top paper cited {max_cit}× (≥100)")
+    elif max_cit >= 20:
+        factor("Citation impact", 1, f"top paper cited {max_cit}× (20–99)")
+    else:
+        factor("Citation impact", 0, f"top paper cited {max_cit}× (<20)")
+
+    if kg_paper_count >= 5:
+        src = f" via {kg_source}" if kg_source else ""
+        factor("KG breadth", 1, f"{kg_paper_count} papers on the target/mechanism node{src} (≥5)")
+    else:
+        src = f" (best: {kg_source})" if kg_source else ""
+        factor("KG breadth", 0, f"{kg_paper_count} papers on the target/mechanism node{src} (<5)")
+
+    is_phase3 = "PHASE3" in phase.replace(" ", "") or "3" in phase
+    if is_phase3:
+        factor("Trial phase", 1, f"reached Phase 3 ({trial.get('phase', '')})")
+    else:
+        factor("Trial phase", 0, f"not yet Phase 3 ({trial.get('phase', '') or 'phase unknown'})")
+
+    points = sum(f["points"] for f in rationale)
+
+    if points >= 4:
+        tier = "Strong"
+    elif points >= 2:
+        tier = "Moderate"
+    else:
+        tier = "Emerging"
+
+    return {
+        "tier": tier,
+        "points": points,
+        "n_papers": n_papers,
+        "max_citations": max_cit,
+        "kg_paper_count": kg_paper_count,
+        "kg_source": kg_source,
+        "rationale": rationale,
+    }
+
+
+def enrich_trial(
+    trial: dict,
+    collection: "chromadb.Collection | None" = None,
+    graph: "nx.DiGraph | None" = None,
+    all_trials: list[dict] | None = None,
+    mechanism_index: dict[str, str] | None = None,
+) -> dict:
+    """Attach research-evidence context to a trial: targeted mechanism, key papers,
+    sibling trials, evidence tier."""
+    index = _mechanism_index() if mechanism_index is None else mechanism_index
+    mechanism = index.get(trial.get("nct_id", ""), "")
+
+    key_papers = _find_supporting_papers(trial, collection)
+    sibling_trials = _find_sibling_trials(trial, all_trials or [])
+    kg_paper_count, kg_source = _kg_paper_count(trial, graph, mechanism)
+    evidence = _evidence_tier(trial, key_papers, kg_paper_count, kg_source)
+
+    return {
+        "nct_id": trial.get("nct_id", ""),
+        "title": trial.get("title", ""),
+        "phase": trial.get("phase", ""),
+        "status": trial.get("status", ""),
+        "is_recruiting": trial.get("status", "") in RECRUITING_STATUSES,
+        "sponsor": trial.get("sponsor", ""),
+        "url": trial.get("url", ""),
+        "target_entities": trial.get("target_entities", []),
+        "mechanism": mechanism,
+        "matched_sites": trial.get("matched_sites", []),
+        "key_papers": key_papers,
+        "sibling_trials": sibling_trials,
+        "evidence": evidence,
+    }
+
+
+# ── HTML rendering for the Clinical Trials tab ────────────────────────────────
+
+def _status_badge(status: str) -> tuple[str, str]:
+    """(color, label) for a ClinicalTrials.gov overall-status value."""
+    s = (status or "").upper()
+    if s in RECRUITING_STATUSES:
+        return "#00B894", "Recruiting" if s == "RECRUITING" else status.replace("_", " ").title()
+    if s == "ACTIVE_NOT_RECRUITING":
+        return "#0984E3", "Active"
+    if s == "COMPLETED":
+        return "#636E72", "Completed"
+    if s in {"TERMINATED", "WITHDRAWN", "SUSPENDED"}:
+        return "#D63031", status.title()
+    return "#B2BEC3", (status or "Unknown").replace("_", " ").title()
+
+
+_TIER_COLOR = {"Strong": "#00B894", "Moderate": "#E17055", "Emerging": "#B2BEC3"}
+
+
+def _pill(text: str, color: str) -> str:
+    return (f'<span style="background:{color};color:#fff;border-radius:10px;'
+            f'padding:1px 8px;font-size:0.72rem;white-space:nowrap;">{html.escape(text)}</span>')
+
+
+def _tier_rationale_html(ev: dict) -> str:
+    """A collapsible 'why this tier' breakdown: each scoring factor, its points, and reason.
+
+    Uses a native <details> disclosure (no JS) so a physician can audit the label without
+    it crowding the card by default.
+    """
+    rationale = ev.get("rationale") or []
+    if not rationale:
+        return ""
+    rows = "".join(
+        f'<li style="margin:1px 0;{"" if f["points"] else "color:#aaa;"}">'
+        f'<b>+{f["points"]}</b> {html.escape(f["factor"])} — {html.escape(f["detail"])}</li>'
+        for f in rationale
+    )
+    total = ev.get("points", sum(f["points"] for f in rationale))
+    summary = (f'Why {html.escape(ev.get("tier", ""))}? ({total} pts — '
+               "≥4 Strong · 2–3 Moderate · &lt;2 Emerging)")
+    return (
+        '<details style="margin-top:4px;font-size:0.8rem;color:#555;">'
+        f'<summary style="cursor:pointer;color:#6C5CE7;">{summary}</summary>'
+        f'<ul style="margin:4px 0 0 18px;list-style:none;padding:0;">{rows}</ul>'
+        '</details>'
+    )
+
+
+def render_trials_html(enriched: list[dict], match_count: int) -> str:
+    """Render enriched location-search results as an HTML card list."""
+    if not enriched:
+        return '<div style="color:#888;padding:12px 0;">No trials found for this location.</div>'
+
+    caption = (f'<div style="font-size:0.85rem;color:#666;margin:6px 0;">'
+               f'{match_count} trial(s) matched — showing {len(enriched)}, recruiting first.</div>')
+
+    cards = []
+    for t in enriched:
+        s_color, s_label = _status_badge(t["status"])
+        ev = t["evidence"]
+        tier_pill = _pill(f'Evidence: {ev["tier"]}', _TIER_COLOR.get(ev["tier"], "#B2BEC3"))
+        mech = t.get("mechanism", "")
+        mech_pill = _pill(f'Mechanism: {mech}', "#6C5CE7") if mech else ""
+        rationale_html = _tier_rationale_html(ev)
+        phase = html.escape((t.get("phase") or "—").replace("PHASE", "Ph"))
+        title = html.escape(t.get("title", "")[:140])
+        nct = html.escape(t.get("nct_id", ""))
+        url = html.escape(t.get("url", ""))
+        nct_link = f'<a href="{url}" target="_blank" rel="noopener">{nct}</a>' if url else nct
+
+        sites = t.get("matched_sites", [])
+        site_bits = []
+        for st in sites[:3]:
+            loc = ", ".join(x for x in (st.get("facility", ""), st.get("city", ""), st.get("state", "")) if x)
+            if loc:
+                site_bits.append(html.escape(loc))
+        sites_html = "<br>".join(site_bits)
+        if len(sites) > 3:
+            sites_html += f'<br><span style="color:#aaa;">+{len(sites) - 3} more site(s)</span>'
+
+        papers = t.get("key_papers", [])
+        if papers:
+            paper_items = "".join(
+                f'<li>{html.escape(p.get("title", "")[:120])} '
+                f'({p.get("year") or "n.d."}) — '
+                f'<a href="https://pubmed.ncbi.nlm.nih.gov/{html.escape(str(p.get("pmid", "")))}/" '
+                f'target="_blank" rel="noopener">PMID {html.escape(str(p.get("pmid", "")))}</a>, '
+                f'{p.get("citation_count", 0)} citations</li>'
+                for p in papers
+            )
+            papers_html = f'<div style="margin-top:6px;font-size:0.82rem;color:#555;"><b>Key papers:</b><ul style="margin:2px 0 0 18px;">{paper_items}</ul></div>'
+        else:
+            papers_html = '<div style="margin-top:6px;font-size:0.82rem;color:#aaa;">No supporting papers found in the database.</div>'
+
+        siblings = t.get("sibling_trials", [])
+        if siblings:
+            sib_links = ", ".join(
+                f'<a href="{html.escape(s.get("url", ""))}" target="_blank" rel="noopener">{html.escape(s.get("nct_id", ""))}</a>'
+                for s in siblings
+            )
+            siblings_html = f'<div style="margin-top:4px;font-size:0.82rem;color:#555;"><b>Related trials (same compound):</b> {sib_links}</div>'
+        else:
+            siblings_html = ""
+
+        cards.append(
+            '<div style="border:1px solid #e3e3e3;border-radius:8px;padding:10px 12px;margin:8px 0;">'
+            f'<div style="display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-bottom:4px;">'
+            f'{_pill(s_label, s_color)}{tier_pill}{mech_pill}'
+            f'<span style="color:#888;font-size:0.78rem;">{phase}</span></div>'
+            f'<div style="font-weight:600;">{nct_link} — {title}</div>'
+            f'{rationale_html}'
+            f'<div style="margin-top:4px;font-size:0.82rem;color:#555;"><b>Site(s):</b><br>{sites_html}</div>'
+            f'{papers_html}{siblings_html}'
+            '</div>'
+        )
+
+    return caption + "".join(cards)