Upload app.py

app.py

@@ -0,0 +1,774 @@
+"""
+app.py — Topic Modelling Agentic AI | Gradio UI
+═══════════════════════════════════════════════════
+Version:  3.0.0 | April 2026
+Stack:    Gradio 5.x + LangGraph + Mistral + BERTopic
+Deploy:   HuggingFace Spaces (sdk: gradio)
+Rules:    Zero gr.HTML(). All UI via native Gradio components.
+          See GRADIO_UI_GUIDELINES_v2.docx for full standards.
+
+ARCHITECTURE — 20 Blocks in 5 Sections
+─────────────────────────────────────────
+  Section 1: Setup        (B1–B3)   Imports, agent, theme
+  Section 2: Helpers      (B4–B10)  Pure Python functions, no UI
+  Section 3: UI Layout    (B11–B17) gr.Blocks with native components
+  Section 4: Event Wiring (B18–B19) Connect UI to functions
+  Section 5: Launch       (B20)     Start server
+
+BLOCK COMMUNICATION MAP
+─────────────────────────
+  B6 (respond)  ←→ B2 (agent)   : invokes agent for chat
+  B6 (respond)  → B4 (output)   : scans for download files
+  B7 (chart)    → B17a (display) : loads Plotly JSON → gr.Plot
+  B8 (table)    → B16 (review)  : builds rows → gr.Dataframe
+  B9 (papers)   ← B16 (review)  : triggered by row click
+  B10 (submit)  → B2 (agent)    : sends review edits to agent
+  B18 (wiring)  → B5,B7,B8      : refreshes progress, charts, table
+"""
+import os
+import glob
+import json
+
+import plotly.io as pio
+import gradio as gr
+from langchain_mistralai import ChatMistralAI
+from langgraph.prebuilt import create_react_agent
+from langgraph.checkpoint.memory import MemorySaver
+from agent import SYSTEM_PROMPT, get_local_tools
+
+print(">>> app.py: imports complete")
+
+
+# ╔═══════════════════════════════════════════════════════════════╗
+# ║  SECTION 1 — SETUP                                          ║
+# ║  One-time initialization: agent creation and visual theme.   ║
+# ║  Nothing here renders UI — it prepares the backend brain     ║
+# ║  and the visual identity for the entire application.         ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+
+# ── B2: Agent setup ─────────────────────────────────────────────
+# PURPOSE:  Create the LangGraph ReAct agent that powers all chat.
+#           Connects Mistral LLM to BERTopic tools with memory so
+#           the agent remembers context across conversation turns.
+# PRODUCES: `agent` — used by B6 (respond) and B10 (_submit_review)
+# IMPORTS:  SYSTEM_PROMPT, get_local_tools from agent.py
+# NOTE:     MemorySaver keeps conversation in RAM (resets on restart).
+#           For persistent memory, swap to SQLite checkpointer.
+# ────────────────────────────────────────────────────────────────
+llm = ChatMistralAI(model="mistral-small-latest", temperature=0, timeout=300)
+tools = get_local_tools()
+agent = create_react_agent(
+    model=llm, tools=tools, prompt=SYSTEM_PROMPT, checkpointer=MemorySaver()
+)
+print(f">>> app.py: agent ready ({len(tools)} tools)")
+
+_msg_count = 0                    # Global message counter (shared across users)
+_uploaded = {"path": ""}          # Last uploaded CSV path (shared session)
+# ── end B2: Agent setup ────────────────────────────────────────
+
+
+# ── B3: Theme ───────────────────────────────────────────────────
+# PURPOSE:  Define the visual identity of the entire application.
+#           Replaces ALL custom CSS that was previously in HEADER_HTML:
+#           - DM Sans font (was @import url in <style> block)
+#           - Slate color palette (was hardcoded hex in inline styles)
+#           - Soft rounded corners and spacing
+# USED BY:  B20 (demo.launch) — Gradio 6 moved theme from gr.Blocks
+#           to launch(). The theme object is created here but applied
+#           in B20 via demo.launch(theme=theme).
+# REPLACES: Old HEADER_HTML lines 33-38 (<style> block with CSS)
+# ────────────────────────────────────────────────────────────────
+theme = gr.themes.Soft(
+    primary_hue="slate",
+    font=gr.themes.GoogleFont("DM Sans"),
+    font_mono=gr.themes.GoogleFont("JetBrains Mono"),
+)
+# ── end B3: Theme ───────���──────────────────────────────────────
+
+
+# ╔═══════════════════════════════════════════════════════════════╗
+# ║  SECTION 2 — HELPER FUNCTIONS                               ║
+# ║  Pure Python functions that process data and return clean    ║
+# ║  values (strings, lists, figures). NONE of these functions   ║
+# ║  return HTML strings. They feed data to UI components in     ║
+# ║  Section 3 via event handlers in Section 4.                  ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+
+# ── B4: _latest_output() ───────────────────────────────────────
+# PURPOSE:  Scan /tmp for all rq4_* output files generated by the
+#           BERTopic agent pipeline (CSVs, JSONs, chart files).
+#           Sorts them by pipeline phase order so the download
+#           component shows files in logical sequence.
+# RETURNS:  List[str] of filepaths sorted by phase, or None
+# USED BY:  B6 (respond) — attaches to download component after
+#             each agent response
+#           B10 (_submit_review) — refreshes downloads after review
+#           B19 (_auto_load_csv) — refreshes after initial upload
+# ────────────────────────────────────────────────────────────────
+def _latest_output():
+    """Scan /tmp for ALL rq4_* files, sorted by phase order.
+    Returns list of filepaths for gr.File download component."""
+    phase_order = {
+        "summaries": 1, "labels": 2, "themes": 3, "taxonomy": 4,
+        "emb": 0, "intertopic": 5, "bars": 6, "hierarchy": 7,
+        "heatmap": 8, "comparison": 9, "narrative": 10,
+    }
+    files = (
+        glob.glob("/tmp/rq4_*.csv")
+        + glob.glob("/tmp/rq4_*.json")
+        + glob.glob("/tmp/checkpoints/rq4_*.json")
+    )
+    scored = list(map(
+        lambda f: (sum(v * (k in f) for k, v in phase_order.items()), f),
+        files,
+    ))
+    scored.sort(key=lambda x: x[0])
+    return list(map(lambda x: x[1], scored)) or None
+# ── end B4: _latest_output ─────────────────────────────────────
+
+
+# ── B5: _build_progress() ──────────────────────────────────────
+# PURPOSE:  Check which Braun & Clarke phases are complete by
+#           scanning for checkpoint files on disk. Returns a
+#           human-readable emoji string showing pipeline status.
+# RETURNS:  str like "✅ Load → ✅ Codes → ⏳ Themes → ⬜ Report"
+# USED BY:  B14 (phase_progress initial value)
+#           B18 (respond_with_viz) — refreshes after each agent turn
+#           B10 (_submit_review) — refreshes after review submission
+#           B19 (_auto_load_csv) — refreshes after CSV upload
+# REPLACES: Old _build_progress() which returned 24 lines of HTML
+#           with inline-styled <span> elements and color codes.
+#           Now returns pure text with emoji — gr.Markdown renders it.
+# ────────────────────────────────────────────────────────────────
+def _build_progress():
+    """Return emoji progress pipeline. NO HTML — just text + emoji.
+    Displayed in gr.Markdown component (B14)."""
+    checks = [
+        ("Load",   bool(glob.glob("/tmp/checkpoints/rq4_*_summaries.json")
+                        or glob.glob("/tmp/checkpoints/rq4_*_emb.npy"))),
+        ("Codes",  bool(glob.glob("/tmp/checkpoints/rq4_*_labels.json"))),
+        ("Themes", bool(glob.glob("/tmp/checkpoints/rq4_*_themes.json"))),
+        ("Review", bool(glob.glob("/tmp/checkpoints/rq4_*_themes.json"))),
+        ("Names",  bool(glob.glob("/tmp/checkpoints/rq4_*_themes.json"))),
+        ("PAJAIS", bool(glob.glob("/tmp/checkpoints/rq4_*_taxonomy_map.json"))),
+        ("Report", bool(glob.glob("/tmp/rq4_comparison.csv")
+                        or glob.glob("/tmp/rq4_narrative.txt"))),
+    ]
+    return " → ".join(f"{'✅' if done else '⬜'} {name}" for name, done in checks)
+# ── end B5: _build_progress ────────────────────────────────────
+
+
+# ── B6: respond() ──────────────────────────────────────────────
+# PURPOSE:  Core chat handler. This is the brain of the app.
+#           1. Stores uploaded CSV file path (if new upload)
+#           2. Appends file location + phase context to user message
+#              so the agent knows what data is available
+#           3. Yields a "thinking..." bubble immediately (user sees
+#              instant feedback while agent processes)
+#           4. Invokes the LangGraph agent (Mistral decides which
+#              BERTopic tools to call)
+#           5. Replaces thinking bubble with actual agent response
+#           6. Attaches latest output files to download component
+# INPUTS:   message (str), chat_history (list[dict]), uploaded_file (str|None)
+# YIELDS:   Tuple of (chat_history, empty_string, download_files)
+#           — yields TWICE: first with progress bubble, then with final response
+# TALKS TO: B2 (agent.invoke) — sends message, gets response
+#           B4 (_latest_output) — gets download file list
+# USED BY:  B18 (respond_with_viz wraps this)
+#           B19 (_auto_load_csv wraps this)
+# NOTE:     Uses single thread_id="session" so agent remembers
+#           previous turns (loaded CSV path, current phase, etc.)
+# ────────────────────────────────────────────────────────────────
+def respond(message, chat_history, uploaded_file):
+    """Handle one chat turn with the LangGraph agent.
+    Yields twice: progress bubble → final response."""
+    global _msg_count
+    _msg_count += 1
+
+    # Store file path — uses `or` short-circuit instead of if/else
+    _uploaded["path"] = uploaded_file or _uploaded.get("path", "")
+
+    # Tell agent where the CSV is (prevents hallucinated filepaths)
+    file_note = (
+        f"\n[CSV file at: {_uploaded['path']}]" * bool(_uploaded["path"])
+    ) or "\n[No CSV uploaded yet — ask user to upload a file first]"
+
+    # Tell agent what phase we're in based on existing checkpoint files
+    phase_context = (
+        "\n[Phase context: labels exist]"
+        * bool(glob.glob("/tmp/checkpoints/rq4_*_labels.json"))
+        or "\n[Phase context: embeddings exist]"
+        * bool(glob.glob("/tmp/checkpoints/rq4_*_emb.npy"))
+        or "\n[Phase context: fresh start]"
+    )
+
+    text = ((message or "").strip() or "Analyze my Scopus CSV") + file_note + phase_context
+    print(f"\n{'='*60}\n>>> MSG #{_msg_count}: '{text[:120]}'\n{'='*60}")
+
+    # YIELD 1: Show "thinking" bubble immediately
+    chat_history = chat_history + [
+        {"role": "user", "content": (message or "").strip()},
+        {"role": "assistant", "content": "🔬 **Working...**  _Agent is thinking..._"},
+    ]
+    yield chat_history, "", _latest_output()
+
+    # Invoke agent — Mistral brain decides which tools to call
+    result = agent.invoke(
+        {"messages": [("human", text)]},
+        config={"configurable": {"thread_id": "session"}},
+    )
+    response = result["messages"][-1].content
+    print(f">>> Response ({len(response)} chars)")
+
+    # YIELD 2: Replace thinking bubble with actual response
+    chat_history[-1] = {"role": "assistant", "content": response}
+    gr.Info(f"Agent responded ({len(response)} chars)")
+    yield chat_history, "", _latest_output()
+# ── end B6: respond ────────────────────────────────────────────
+
+
+# ── B7: _load_chart() ──────────────────────────────────────────
+# PURPOSE:  Load a BERTopic visualization chart from a saved Plotly
+#           JSON file on disk and return the figure object.
+#           The gr.Plot component in B17a renders this directly —
+#           no iframe, no HTML escaping, no srcdoc hack.
+# INPUT:    chart_name (str) — filename like "rq4_intertopic.json"
+# RETURNS:  plotly.graph_objects.Figure or None
+# USED BY:  B17a (chart_selector.change event)
+#           B18 (respond_with_viz) — auto-shows latest chart
+# REPLACES: Old _load_chart() which used html.escape() + iframe
+#           srcdoc to embed HTML files. That was 8 lines of hack.
+# REQUIRES: BERTopic tools in tools.py must save charts as Plotly
+#           JSON via pio.to_json(fig) instead of fig.write_html().
+# ────────────────────────────────────────────────────────────────
+def _load_chart(chart_name):
+    """Load Plotly chart from JSON file. Returns figure for gr.Plot.
+    No HTML, no iframe — just a native Plotly figure object."""
+    path = f"/tmp/{chart_name}"
+    (not os.path.exists(path)) and (not None)  # guard
+    return pio.from_json(open(path).read()) * bool(os.path.exists(path)) or None
+
+def _get_chart_choices():
+    """Find all rq4_*.json chart files in /tmp."""
+    files = sorted(glob.glob("/tmp/rq4_*.json"))
+    return list(map(os.path.basename, files))
+# ── end B7: _load_chart ──────────────────────────────────��────
+
+
+# ── B8: _load_review_table() ───────────────────────────────────
+# PURPOSE:  Load the latest BERTopic phase data (taxonomy, themes,
+#           labels, or summaries — whichever is most recent) and
+#           build a review table for the researcher to approve,
+#           rename, or annotate topics.
+# RETURNS:  List[List] with 8 columns matching the Dataframe schema:
+#           [#, Label, Evidence, Sentences, Papers, Approve, Rename, Reasoning]
+#           - Column 5 (Approve) is bool (True/False) → renders as checkbox
+#           - Columns 0-4 are read-only (enforced by static_columns in B16)
+#           - Columns 5-7 are editable by the researcher
+# USED BY:  B16 (initial table value)
+#           B10 (_submit_review) — reloads after agent processes review
+#           B18 (respond_with_viz) — refreshes after each agent turn
+# REPLACES: Old version which returned "yes"/"no" strings for Approve.
+#           Now returns True/False so gr.Dataframe renders checkboxes.
+# ────────────────────────────────────────────────────────────────
+def _load_review_table():
+    """Build review table from latest checkpoint JSON.
+    Approve column is bool (renders as checkbox in gr.Dataframe).
+    Priority: taxonomy_map > themes > labels > summaries."""
+    taxonomy_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_taxonomy_map.json"))
+    theme_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_themes.json"))
+    label_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_labels.json"))
+    summary_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_summaries.json"))
+
+    # Pick most advanced checkpoint available
+    path = (
+        (taxonomy_files and taxonomy_files[-1])
+        or (theme_files and theme_files[-1])
+        or (label_files and label_files[-1])
+        or (summary_files and summary_files[-1])
+        or ""
+    )
+    is_taxonomy = bool(taxonomy_files and taxonomy_files[-1] == path)
+    data = (os.path.exists(path) and json.load(open(path))) or []
+
+    # For taxonomy: merge with themes to get sentence/paper counts
+    theme_lookup = {}
+    (is_taxonomy and theme_files) and theme_lookup.update(
+        {t.get("label", ""): t for t in json.load(open(theme_files[-1]))}
+    )
+
+    rows = list(map(
+        lambda pair: [
+            pair[0],                                                          # #
+            pair[1].get("label", pair[1].get("top_words", ""))[:60],         # Label
+            # Evidence: PAJAIS mapping for taxonomy, nearest sentence otherwise
+            (
+                is_taxonomy
+                and f"→ {pair[1].get('pajais_match', '?')} | {pair[1].get('reasoning', '')}"[:120]
+            ) or (
+                (pair[1].get("nearest", [{}])[0].get("sentence", "")[:120] + "...")
+                * bool(pair[1].get("nearest"))
+            ),
+            # Sentence/paper counts
+            theme_lookup.get(pair[1].get("label", ""), pair[1]).get(
+                "sentence_count", pair[1].get("sentence_count", 0)),
+            theme_lookup.get(pair[1].get("label", ""), pair[1]).get(
+                "paper_count", pair[1].get("paper_count", 0)),
+            True,                                                             # Approve (bool → checkbox)
+            "",                                                               # Rename To
+            "",                                                               # Reasoning
+        ],
+        enumerate(data),
+    ))
+    return rows or [[0, "No data yet", "", 0, 0, False, "", ""]]
+# ── end B8: _load_review_table ─────────────────────────────────
+
+
+# ── B9: _show_papers_by_select() ───────────────────────────────
+# PURPOSE:  When the researcher clicks any row in the review table,
+#           this function fires and shows the papers belonging to
+#           that topic. Eliminates the old workflow of typing a
+#           Topic # into a separate input and clicking "Show Papers".
+# INPUT:    gr.SelectData event — contains .index (row, col) and .value
+# RETURNS:  str — formatted paper list for gr.Textbox (paper_list)
+# TRIGGERED BY: review_table.select() event in B16
+# REPLACES: Old _show_papers(topic_id) + topic_num (gr.Number) +
+#           view_papers_btn (gr.Button) — all three components removed.
+# NOTE:     Uses column 0 value (the # column) as topic_id, NOT the
+#           row index, because filtering/sorting may reorder rows.
+# ────────────────────────────────────────────────────────────────
+def _show_papers_by_select(table_data, evt: gr.SelectData):
+    """Show papers for clicked row. Uses column 0 as topic_id.
+    Triggered by review_table.select() — no separate Topic # input needed."""
+    row_idx = evt.index[0]
+
+    # Get topic_id from column 0 of the clicked row (not row index)
+    topic_id = int(table_data.iloc[row_idx, 0]) if hasattr(table_data, 'iloc') else int(table_data[row_idx][0])
+
+    # Load paper data from checkpoint files
+    label_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_labels.json"))
+    summary_files = sorted(glob.glob("/tmp/checkpoints/rq4_*_summaries.json"))
+    all_files = label_files or summary_files
+
+    lines = []
+    for f in all_files:
+        source = os.path.basename(f).split("_")[1]
+        data = json.load(open(f))
+        for t in data:
+            (t.get("topic_id") == topic_id) and lines.append(
+                f"═══ {source.upper()} — Topic {topic_id}: "
+                f"{t.get('label', t.get('top_words', '')[:50])} ═══\n"
+                f"{t.get('sentence_count', 0)} sentences from {t.get('paper_count', 0)} papers\n"
+                f"AI Reasoning: {t.get('reasoning', 'not yet labeled')}\n\n"
+                f"── 5 NEAREST CENTROID SENTENCES (evidence) ──\n"
+                + "\n".join(
+                    f"  {i+1}. \"{t['nearest'][i]['sentence'][:200]}\"\n"
+                    f"     Paper: {t['nearest'][i].get('title', '')[:100]}"
+                    for i in range(min(5, len(t.get('nearest', []))))
+                )
+                + "\n\n── ALL PAPER TITLES ──\n"
+                + "\n".join(
+                    f"  {i+1}. {title}"
+                    for i, title in enumerate(t.get('paper_titles', []))
+                )
+            )
+    return "\n\n".join(lines) or f"Topic {topic_id} not found."
+# ── end B9: _show_papers_by_select ─────────────────────────────
+
+
+# ── B10: _submit_review() ──────────────────────────────────────
+# PURPOSE:  When the researcher finishes editing the review table
+#           (checking Approve boxes, typing Rename values, adding
+#           Reasoning notes) and clicks "Submit Review", this
+#           function converts those edits into a natural language
+#           message and sends it to the agent for processing.
+# INPUTS:   table_data (DataFrame from gr.Dataframe), chat_history (list)
+# YIELDS:   Tuple of (chat, download, chart_choices, chart_fig,
+#           review_rows, progress_str) — yields twice (progress → final)
+# TALKS TO: B2 (agent.invoke) — sends review decisions
+#           B4 (_latest_output) — refreshes downloads
+#           B5 (_build_progress) — refreshes pipeline status
+#           B7 (_get_chart_choices) — refreshes chart dropdown
+#           B8 (_load_review_table) — reloads table with updated data
+# NOTE:     Column 5 (Approve) is now bool. True = approve, False = reject.
+# ────────────────────────────────────────────────────────────────
+def _submit_review(table_data, chat_history):
+    """Convert review table edits into agent message.
+    Approve column is bool (checkbox), not string."""
+    rows = table_data.values.tolist()
+    lines = list(map(
+        lambda r: (
+            f"Topic {int(r[0])}: "
+            + (f"RENAME to '{r[6]}'" * bool(str(r[6]).strip()))
+            + (f"APPROVE '{r[1]}'" * (not bool(str(r[6]).strip())) * bool(r[5]))
+            + (f"REJECT" * (not r[5]))
+            + (f" — reason: {r[7]}" * bool(str(r[7]).strip()))
+        ),
+        rows,
+    ))
+    review_msg = "Review decisions:\n" + "\n".join(lines)
+    print(f">>> Review submitted: {review_msg[:200]}")
+
+    # YIELD 1: Show processing bubble
+    chat_history = chat_history + [
+        {"role": "user", "content": review_msg},
+        {"role": "assistant", "content": "🔬 **Processing review decisions...**"},
+    ]
+    gr.Info("Review submitted to agent")
+    yield (chat_history, _latest_output(), gr.update(),
+           gr.update(), gr.update(), _build_progress())
+
+    # Invoke agent with review decisions
+    result = agent.invoke(
+        {"messages": [("human", review_msg)]},
+        config={"configurable": {"thread_id": "session"}},
+    )
+    response = result["messages"][-1].content
+
+    # YIELD 2: Final response + refreshed table/charts
+    chat_history[-1] = {"role": "assistant", "content": response}
+    gr.Info("Review processed — table updated")
+    yield (
+        chat_history,
+        _latest_output(),
+        gr.update(choices=_get_chart_choices()),
+        gr.update(),
+        gr.update(value=_load_review_table()),
+        _build_progress(),
+    )
+# ── end B10: _submit_review ────────────────────────────────────
+
+
+# ╔═══════════════════════════════════════���═══════════════════════╗
+# ║  SECTION 3 — UI LAYOUT                                      ║
+# ║  All visual components defined here using ONLY native Gradio ║
+# ║  widgets. Zero gr.HTML() calls. Theming via B3.              ║
+# ║  Layout: Header → Upload → Progress → Chat → Results tabs   ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+print(">>> Building UI...")
+
+
+# ── B11: gr.Blocks container ───────────────────────────────────
+# PURPOSE:  Root container for the entire application UI.
+#           Enables full browser width via fill_width.
+# CONTAINS: All UI blocks B12 through B17b
+# CONFIG:   title — browser tab title (stays on Blocks in Gradio 6)
+#           fill_width — removes side padding, uses full browser width
+# NOTE:     In Gradio 6.0, theme/css/footer_links moved from
+#           gr.Blocks() to demo.launch(). See B20 for those params.
+# ────────────────────────────────────────────────────────────────
+with gr.Blocks(
+    title="Topic Modelling — Agentic AI",
+    fill_width=True,
+) as demo:
+
+
+    # ── B12: Header ────────────────────────────────────────────
+    # PURPOSE:  Application title and subtitle. Single gr.Markdown
+    #           call replaces 15 lines of HEADER_HTML that included
+    #           a gradient background div, font imports, and inline CSS.
+    # REPLACES: Old HEADER_HTML constant (lines 32-47 of old app.py)
+    # ───────────────────────────────────────────────────────────
+    gr.Markdown(
+        "# 🔬 Topic Modelling — Agentic AI\n"
+        "*Mistral · Cosine Clustering · 384d · B&C Thematic Analysis*"
+    )
+    # ── end B12: Header ────────────────────────────────────────
+
+
+    # ── B13: Data input ────────────────────────────────────────
+    # PURPOSE:  CSV file upload area with inline instructions.
+    #           Researcher uploads their Scopus CSV export here.
+    #           On upload, B19 auto-triggers the first analysis.
+    # COMPONENTS: gr.File (upload) + gr.Markdown (instructions)
+    # EVENTS:  upload.change → B19 (_auto_load_csv)
+    # ───────────────────────────────────────────────────────────
+    gr.Markdown("**① Data input**")
+    with gr.Row():
+        upload = gr.File(label="📂 Upload Scopus CSV", file_types=[".csv"])
+        gr.Markdown("**Upload your CSV** then type `run abstract only` in chat below")
+    # ── end B13: Data input ────────────────────────────────────
+
+
+    # ── B14: Progress pipeline ─────────────────────────────────
+    # PURPOSE:  Visual indicator of which Braun & Clarke analysis
+    #           phases are complete. Updated after every agent action.
+    #           Now uses gr.Markdown with emoji text (was gr.HTML
+    #           with inline-styled colored <span> elements).
+    # COMPONENT: gr.Markdown — displays emoji string from B5
+    # UPDATED BY: B18 (after chat), B10 (after review), B19 (after upload)
+    # REPLACES: Old gr.HTML(value=_build_progress()) with 24 lines of HTML
+    # ───────────────────────────────────────────────────────────
+    phase_progress = gr.Markdown(value=_build_progress())
+    # ── end B14: Progress pipeline ─────────────────────────────
+
+
+    # ── B15: Chatbot + input ───────────────────────────────────
+    # PURPOSE:  Main conversation interface between researcher and
+    #           the LangGraph agent. The chatbot displays message
+    #           history with markdown rendering. The textbox + button
+    #           below it capture user input.
+    # COMPONENTS: gr.Chatbot (display), gr.Textbox (input), gr.Button (send)
+    # EVENTS:  msg.submit → B18, send.click → B18
+    # NOTE:    placeholder text guides the researcher on available commands.
+    #          height=300 keeps chat visible while showing results below.
+    # ───────────────────────────────────────────────────────────
+    gr.Markdown("**② Agent conversation** — follow the prompts below")
+    with gr.Group():
+        chatbot = gr.Chatbot(
+            height=300,
+            show_label=False,
+            placeholder="Upload your Scopus CSV above, then type: run abstract only",
+        )
+        with gr.Row():
+            msg = gr.Textbox(
+                placeholder="run · approve · show topic 4 papers · group 0 1 5 · done",
+                show_label=False, scale=9, lines=1, max_lines=1, container=False,
+            )
+            send = gr.Button("Send", variant="primary", scale=1, min_width=70)
+    # ── end B15: Chatbot + input ───────────────────────────────
+
+
+    # ── B16: Review table tab ──────────────────────────────────
+    # PURPOSE:  Interactive topic review table where the researcher
+    #           approves, renames, or annotates BERTopic-discovered
+    #           topics. This is the core human-in-the-loop interface.
+    #
+    # KEY FEATURES (all native Gradio, no HTML):
+    #   - static_columns=[0,1,2,3,4] — first 5 columns (#, Label,
+    #     Evidence, Sentences, Papers) are READ-ONLY. Prevents
+    #     accidental edits to agent-generated data.
+    #   - datatype "bool" on column 5 — Approve renders as a native
+    #     CHECKBOX. Researcher clicks to toggle, no typing needed.
+    #   - pinned_columns=2 — # and Label columns stay visible when
+    #     scrolling horizontally through wider columns.
+    #   - show_search="filter" — built-in column filtering. Researcher
+    #     can filter by paper count, sentence count, etc.
+    #   - .select() event — clicking any row auto-loads that topic's
+    #     papers in the textbox below. REPLACES the old workflow of
+    #     Topic # input + Show Papers button (both removed).
+    #
+    # COMPONENTS: gr.Dataframe, gr.Button (submit), gr.Textbox (papers)
+    # EVENTS:  review_table.select → B9 (_show_papers_by_select)
+    #          submit_review.click → B10 (_submit_review)
+    # DATA:    Loaded by B8 (_load_review_table)
+    # REPLACES: Old gr.Dataframe (no static_columns, string Approve,
+    #           no search) + topic_num + view_papers_btn
+    # ───────────────────────────────────────────────────────────
+    gr.Markdown("**③ Results** — review table, charts, downloads")
+    with gr.Tabs():
+        with gr.Tab("📋 Review Table"):
+            gr.Markdown(
+                "*Edit Approve / Rename To / Reasoning → click Submit. "
+                "Click any row to see its papers below.*"
+            )
+            review_table = gr.Dataframe(
+                headers=[
+                    "#", "Topic Label", "Top Evidence Sentence",
+                    "Sentences", "Papers", "Approve", "Rename To", "Your Reasoning",
+                ],
+                datatype=[
+                    "number", "str", "str", "number", "number",
+                    "bool", "str", "str",
+                ],
+                interactive=True,
+                column_count=8,
+                # NOTE: These features need Gradio >=5.23. Uncomment when available:
+                # static_columns=[0, 1, 2, 3, 4],
+                # pinned_columns=2,
+                # show_search="filter",
+                # show_row_numbers=True,
+                # show_fullscreen_button=True,
+                # show_copy_button=True,
+                # column_widths=["60px","200px","250px","80px","70px","70px","150px","200px"],
+            )
+            submit_review = gr.Button("✅ Submit Review to Agent", variant="primary")
+
+            # Paper viewer — triggered by clicking any row (replaces Topic # + button)
+            gr.Markdown("---")
+            gr.Markdown("**📄 Papers in selected topic** *(click any row above)*")
+            paper_list = gr.Textbox(
+                label="Papers in selected topic",
+                lines=8, interactive=False,
+            )
+    # ── end B16: Review table tab ──────────────────────────────
+
+
+        # ── B17a: Charts tab ───────────────────────────────────
+        # PURPOSE:  Display BERTopic visualization charts (intertopic
+        #           distance map, bar chart, hierarchy, heatmap).
+        #           Charts are loaded as Plotly figure objects from
+        #           JSON files and rendered natively in gr.Plot.
+        # COMPONENTS: gr.Dropdown (selector), gr.Plot (display)
+        # EVENTS:  chart_selector.change → B7 (_load_chart)
+        # REPLACES: Old iframe + srcdoc hack that used html.escape()
+        #           to embed HTML files. Now uses gr.Plot directly.
+        # ───────────────────────────────────────────────────────
+        with gr.Tab("📊 Charts"):
+            chart_selector = gr.Dropdown(
+                choices=[], label="Select Chart", interactive=True,
+            )
+            chart_display = gr.Plot(label="BERTopic Visualization")
+        # ── end B17a: Charts tab ───────────────────────────────
+
+
+        # ── B17b: Download tab ─────────────────────────────────
+        # PURPOSE:  Multi-file download for all pipeline outputs.
+        #           Shows file descriptions by phase and a gr.File
+        #           component with all generated files.
+        # COMPONENTS: gr.Markdown (descriptions), gr.File (download)
+        # UPDATED BY: B18, B10, B19 — refreshed after each action
+        # ───────────────────────────────────────────────────────
+        with gr.Tab("📥 Download"):
+            gr.Markdown(
+                "**Files by Phase (per run: abstract / title):**\n\n"
+                "**Phase 2 — Discovery:** `summaries.json` · `emb.npy`\n\n"
+                "**Phase 2 — Labeling:** `labels.json`\n\n"
+                "**Phase 2 — Charts:** `intertopic.json` · `bars.json` · "
+                "`hierarchy.json` · `heatmap.json`\n\n"
+                "**Phase 3 — Themes:** `themes.json`\n\n"
+                "**Phase 5.5 — Taxonomy:** `taxonomy_map.json`\n\n"
+                "**Phase 6 — Report:** `comparison.csv` · `narrative.txt`"
+            )
+            download = gr.File(label="All output files", file_count="multiple")
+        # ── end B17b: Download tab ─────────────────────────────
+
+
+    # ╔═══════════════════════════════════════════════════════════╗
+    # ║  SECTION 4 — EVENT WIRING                                ║
+    # ║  Connect UI components to helper functions. This is       ║
+    # ║  where data flows are defined: which function runs when   ║
+    # ║  a button is clicked, a file is uploaded, or a row is     ║
+    # ║  selected. No HTML, no CSS — just Python event binding.   ║
+    # ╚═══════════════════════════════════════════════════════════╝
+
+
+    # ── B18: respond_with_viz() + event bindings ───────────────
+    # PURPOSE:  Wrapper around B6 (respond) that also refreshes
+    #           the chart dropdown, chart display, review table,
+    #           and progress pipeline after each agent response.
+    #           This is the main "after every chat turn, update
+    #           everything" orchestrator.
+    # CALLS:   B6 (respond), B5 (_build_progress), B7 (_load_chart,
+    #          _get_chart_choices), B8 (_load_review_table)
+    # BINDINGS: msg.submit → this function
+    #           send.click → this function
+    # OUTPUTS:  chatbot, msg, download, chart_selector, chart_display,
+    #           review_table, phase_progress (7 components updated)
+    # ───────────────────────────────────────────────────────────
+    chart_selector.change(_load_chart, [chart_selector], [chart_display])
+
+    review_table.select(
+        _show_papers_by_select, [review_table], [paper_list],
+    )
+
+    submit_review.click(
+        _submit_review, [review_table, chatbot],
+        [chatbot, download, chart_selector, chart_display,
+         review_table, phase_progress],
+    )
+
+    def respond_with_viz(message, chat_history, uploaded_file):
+        """Wrap respond() and update charts + table + progress after each turn."""
+        gen = respond(message, chat_history, uploaded_file)
+
+        # First yield (progress bubble)
+        hist, txt, dl = next(gen)
+        yield (hist, txt, dl, gr.update(choices=_get_chart_choices()),
+               gr.update(), gr.update(), _build_progress())
+
+        # Second yield (final response + populate table + charts)
+        hist, txt, dl = next(gen)
+        choices = _get_chart_choices()
+        first_chart = (choices and _load_chart(choices[-1])) or gr.update()
+        table_data = _load_review_table()
+        yield (
+            hist, txt, dl,
+            gr.update(choices=choices, value=(choices and choices[-1]) or None),
+            first_chart,
+            gr.update(value=table_data),
+            _build_progress(),
+        )
+
+    msg.submit(
+        respond_with_viz, [msg, chatbot, upload],
+        [chatbot, msg, download, chart_selector, chart_display,
+         review_table, phase_progress],
+    )
+    send.click(
+        respond_with_viz, [msg, chatbot, upload],
+        [chatbot, msg, download, chart_selector, chart_display,
+         review_table, phase_progress],
+    )
+    # ── end B18: respond_with_viz + event bindings ─────────────
+
+
+    # ── B19: _auto_load_csv() ──────────────────────────────────
+    # PURPOSE:  Automatically triggers analysis when a CSV file is
+    #           uploaded. The researcher doesn't need to type anything —
+    #           just uploading the file starts the pipeline.
+    #           Sends "Analyze my Scopus CSV" as the initial message.
+    # TRIGGERED BY: upload.change event
+    # CALLS:   B6 (respond) with auto-message
+    # OUTPUTS:  chatbot, download, chart_selector, chart_display,
+    #           review_table, phase_progress
+    # ───────────────────────────────────────────────────────────
+    def _auto_load_csv(uploaded_file, chat_history):
+        """Auto-trigger analysis when CSV is uploaded — no typing needed."""
+        gen = respond("Analyze my Scopus CSV", chat_history, uploaded_file)
+
+        # First yield (progress)
+        hist, txt, dl = next(gen)
+        yield (hist, dl, gr.update(), gr.update(),
+               gr.update(), _build_progress())
+
+        # Second yield (final + populate everything)
+        hist, txt, dl = next(gen)
+        choices = _get_chart_choices()
+        first_chart = (choices and _load_chart(choices[-1])) or gr.update()
+        table_data = _load_review_table()
+        yield (
+            hist, dl,
+            gr.update(choices=choices, value=(choices and choices[-1]) or None),
+            first_chart,
+            gr.update(value=table_data),
+            _build_progress(),
+        )
+
+    upload.change(
+        _auto_load_csv, [upload, chatbot],
+        [chatbot, download, chart_selector, chart_display,
+         review_table, phase_progress],
+    )
+    # ── end B19: _auto_load_csv ────────────────────────────────
+
+
+# ╔═══════════════════════════════════════════════════════════════╗
+# ║  SECTION 5 — LAUNCH                                         ║
+# ║  Start the Gradio server. On HuggingFace Spaces this runs   ║
+# ║  automatically. Locally, access at http://localhost:7860     ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+
+# ── B20: Launch ────────────────────────────────────────────────
+# PURPOSE:  Start the web server. In Gradio 6.0, theme/css/footer
+#           params moved here from gr.Blocks().
+# CONFIG:   theme — from B3 (Soft + DM Sans + slate)
+#           footer_links=[] — hides footer natively (no CSS hack)
+#           ssr_mode=False — for HuggingFace Spaces free tier compat
+#           server_name="0.0.0.0" — accessible on network
+# NOTE:     On Spaces, port 7860 is auto-exposed to the internet.
+#           Locally, open http://localhost:7860 in your browser.
+# ────────────────────────────────────────────────────────────────
+print(">>> Launching...")
+demo.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    ssr_mode=False,
+    theme=theme,                    # Gradio 6: moved from gr.Blocks()
+    footer_links=[],                # Gradio 6: hides footer, replaces show_api
+)
+# ── end B20: Launch ────────────────────────────────────────────