feat: Stage 5 — Gradio UI + HuggingFace Spaces deployment

- app.py: Gradio 6.20 Blocks UI with streaming chatbot, 6 example
question buttons (two columns), status bar showing chunk/trial/KG
counts, medical disclaimer footer
- Streaming pattern: status updates shown as italic while waiting,
tokens accumulate in real-time, input locked during generation
- Module-level resource loading: BioLORD collection + KG graph +
trials loaded once at startup (not per request)
- requirements.txt: HF Spaces mirror of pyproject.toml deps
- README.md: HF Spaces metadata header + full setup guide including
offline pipeline run order, architecture diagram, data sources table

Verified: app starts in <5s, serves on localhost:7860, all 510 chunks
/ 112 trials / 220 KG nodes loaded at startup.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,105 @@
+---
+title: Candle Fire
+emoji: 🕯️
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: "6.14.0"
+app_file: app.py
+pinned: false
+---
+
+# 🕯️ Candle-Fire
+
+**ALS Research Intelligence for Physicians**
+
+Candle-fire is a physician-facing tool that synthesizes evidence from ~500 curated ALS research papers and a biomedical knowledge graph. Ask a free-text question about ALS biology, drug targets, or clinical trials — get a structured, cited answer in under 30 seconds.
+
+## What It Does
+
+- **Two-layer retrieval**: Knowledge graph expansion (BioLORD-2023-C embeddings + NetworkX) → RAG over ~500 ALS papers
+- **Citation-weighted ranking**: Highly-cited papers surface first
+- **Structured synthesis**: Claude Sonnet produces mechanism summaries, entity tables, evidence strength assessments, and trial links
+- **Biomedical synonyms**: BioLORD understands that "TDP-43" = "TARDBP" = "TAR DNA-binding protein 43"
+
+## Setup
+
+### Prerequisites
+
+```bash
+# Python 3.11+, uv package manager
+pip install uv
+uv sync
+```
+
+### Environment variables
+
+```bash
+cp .env.example .env
+# Fill in:
+#   ANTHROPIC_API_KEY — required
+#   ENTREZ_EMAIL      — required for PubMed ingestion
+#   NCBI_API_KEY      — optional, raises rate limit 3→10 req/s
+```
+
+### Run the offline pipeline (once)
+
+Build the knowledge assets before launching the app. Each step is resumable.
+
+```bash
+# 1. Ingest ~500 ALS papers from PubMed + PMC full text + citation counts (~15 min)
+uv run python scripts/ingest_papers.py
+
+# 2. Ingest ALS clinical trials from ClinicalTrials.gov (< 1 min, run in parallel)
+uv run python scripts/ingest_trials.py
+
+# 3. Extract biomedical entities using Claude Sonnet (~$1.50, ~50 min, resumable)
+uv run python scripts/extract_entities.py
+
+# 4. Build the knowledge graph (~5 sec)
+uv run python scripts/build_graph.py
+
+# 5. Build the ChromaDB vector index with BioLORD embeddings (~10 min, one-time model download)
+uv run python scripts/build_index.py
+```
+
+### Launch
+
+```bash
+# Web UI
+uv run python app.py
+
+# CLI
+uv run python main.py "What is the evidence for tofersen targeting SOD1?"
+```
+
+## Architecture
+
+```
+Physician query
+  → agents/research_agent.py
+      1. Claude: extract query entities → ["SOD1", "tofersen"]
+      2. graph/query.py: KG expansion → ["SOD1", "TARDBP", "antisense oligonucleotide", ...]
+      3. rag/retriever.py: BioLORD semantic search + entity search → top 15 papers
+         (re-ranked by: similarity × log(citation_count + 2))
+      4. graph/query.py: find linked clinical trials
+      5. Claude Sonnet (streaming): synthesize research landscape
+  → Gradio UI (streaming response with citations)
+```
+
+**Embedding model**: `FremyCompany/BioLORD-2023-C` — anchored to UMLS/SNOMED CT/MeSH ontologies, natively resolves biomedical synonyms.
+
+**Knowledge graph**: NetworkX DiGraph with Gene/Protein/Compound/Pathway/Phenotype/Mechanism/ClinicalTrial nodes. 1-hop BFS expansion before RAG retrieval.
+
+## Data Sources
+
+| Source | Content | Volume |
+|---|---|---|
+| PubMed Entrez | ALS paper abstracts + metadata | ~500 papers (2018–2024) |
+| PubMed Central | Full text for Open Access papers | ~50% coverage |
+| Semantic Scholar | Citation counts per paper | All papers |
+| ClinicalTrials.gov v2 | Active ALS recruiting trials | ~112 trials |
+
+## Disclaimer
+
+Research synthesis tool. Always verify claims with primary sources before applying to patient care. Not a substitute for clinical judgment.

app.py

@@ -1,2 +1,174 @@
-"""Gradio web UI for candle-fire."""
-# Stage 5 implementation
+"""Gradio web UI for candle-fire — physician-facing ALS research intelligence."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import anthropic
+import gradio as gr
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from agents.research_agent import stream_research_agent
+from config import CHROMA_COLLECTION, CHROMA_DIR, GRAPH_PICKLE_PATH, TRIALS_PATH
+from logging_config import get_logger
+from rag.indexer import load_collection
+
+_logger = get_logger("app")
+
+# ── Load resources once at startup ───────────────────────────────────────────
+
+def _load_graph():
+    try:
+        from graph.serializer import load_graph
+        G = load_graph(GRAPH_PICKLE_PATH)
+        _logger.info(f"KG loaded: {G.number_of_nodes()} nodes")
+        return G
+    except FileNotFoundError:
+        _logger.warning("KG not found — running RAG-only mode")
+        return None
+
+
+def _load_trials() -> list[dict]:
+    if not TRIALS_PATH.exists():
+        return []
+    with open(TRIALS_PATH, encoding="utf-8") as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+_collection = load_collection(CHROMA_DIR, CHROMA_COLLECTION)
+_graph = _load_graph()
+_trials = _load_trials()
+_client = anthropic.Anthropic()
+
+_n_chunks = _collection.count()
+_n_trials = len(_trials)
+_kg_nodes = _graph.number_of_nodes() if _graph else 0
+
+# ── Example questions ─────────────────────────────────────────────────────────
+
+_EXAMPLES = [
+    "What is the evidence for tofersen targeting SOD1 in ALS?",
+    "What mechanisms link TDP-43 aggregation to motor neuron death?",
+    "What compounds target glutamate excitotoxicity in ALS?",
+    "What is the role of C9orf72 repeat expansion in neurodegeneration?",
+    "How does riluzole work and what is the clinical evidence?",
+    "What biomarkers track ALS disease progression?",
+]
+
+# ── Streaming respond function ────────────────────────────────────────────────
+
+def respond(message: str, history: list[dict]):
+    if not message.strip():
+        yield history, gr.update(value="", interactive=True)
+        return
+
+    history = history + [{"role": "user", "content": message}]
+    history = history + [{"role": "assistant", "content": ""}]
+    yield history, gr.update(value="", interactive=False)
+
+    response_text = ""
+
+    for event_type, content in stream_research_agent(
+        _client, message, _collection, _trials, graph=_graph
+    ):
+        if event_type == "status":
+            if not response_text:
+                history[-1]["content"] = f"*{content}*"
+                yield history, gr.update()
+        elif event_type == "token":
+            response_text += content
+            history[-1]["content"] = response_text
+            yield history, gr.update()
+        elif event_type == "done":
+            history[-1]["content"] = response_text or content
+            yield history, gr.update(interactive=True)
+            return
+
+    yield history, gr.update(interactive=True)
+
+
+# ── UI ────────────────────────────────────────────────────────────────────────
+
+_CSS = """
+.container { max-width: 900px; margin: 0 auto; }
+.disclaimer { font-size: 0.78rem; color: #888; text-align: center; margin-top: 6px; }
+.status-bar { font-size: 0.82rem; color: #666; text-align: center; margin-bottom: 8px; }
+footer { display: none !important; }
+"""
+
+_TITLE_MD = """# 🕯️ Candle-Fire
+### ALS Research Intelligence for Physicians
+Ask a free-text question about ALS biology, drug targets, or clinical trials.
+Answers are synthesized from ~500 curated ALS papers and enriched by a biomedical knowledge graph.
+"""
+
+_DISCLAIMER_MD = """<div class="disclaimer">
+⚕️ Research synthesis tool — not a substitute for clinical judgment.
+Always verify claims with primary sources before applying to patient care.
+</div>"""
+
+
+with gr.Blocks(title="Candle-Fire — ALS Research Intelligence") as demo:
+
+    with gr.Column(elem_classes="container"):
+
+        gr.Markdown(_TITLE_MD)
+
+        gr.HTML(
+            f'<div class="status-bar">'
+            f'{_n_chunks} paper chunks &nbsp;·&nbsp; '
+            f'{_n_trials} clinical trials &nbsp;·&nbsp; '
+            f'{_kg_nodes} knowledge graph nodes'
+            f'</div>'
+        )
+
+        chatbot = gr.Chatbot(
+            value=[],
+            height=520,
+            show_label=False,
+            sanitize_html=False,
+            avatar_images=(None, "https://api.dicebear.com/7.x/icons/svg?seed=candle&icon=flame"),
+            placeholder="Ask a question about ALS research to get started.",
+        )
+
+        with gr.Row():
+            msg_box = gr.Textbox(
+                placeholder="e.g. What is the evidence for tofersen targeting SOD1?",
+                show_label=False,
+                scale=9,
+                autofocus=True,
+                lines=1,
+            )
+            send_btn = gr.Button("Ask", scale=1, variant="primary", min_width=80)
+
+        gr.Markdown("**Example questions** — click to populate:")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                for ex in _EXAMPLES[:3]:
+                    btn = gr.Button(ex, size="sm", variant="secondary")
+                    btn.click(fn=lambda t=ex: t, outputs=[msg_box])
+            with gr.Column(scale=1):
+                for ex in _EXAMPLES[3:]:
+                    btn = gr.Button(ex, size="sm", variant="secondary")
+                    btn.click(fn=lambda t=ex: t, outputs=[msg_box])
+
+        gr.HTML(_DISCLAIMER_MD)
+
+    submit_kwargs = dict(
+        fn=respond,
+        inputs=[msg_box, chatbot],
+        outputs=[chatbot, msg_box],
+    )
+    msg_box.submit(**submit_kwargs)
+    send_btn.click(**submit_kwargs)
+
+
+if __name__ == "__main__":
+    demo.launch(
+        share=False,
+        css=_CSS,
+        theme=gr.themes.Soft(),
+    )

requirements.txt

@@ -0,0 +1,10 @@
+anthropic>=0.50.0
+gradio>=6.14.0,<7.0.0
+chromadb>=0.5.0
+networkx>=3.3
+biopython>=1.84
+httpx>=0.27.0
+python-dotenv>=1.2.2
+rich>=13.0.0
+sentence-transformers>=3.0.0
+openai>=2.44.0