Fix dataset loading and add intro cards

app.py

@@ -106,6 +106,17 @@ def _resolve_embedding_file(option: str, source_mode: str, example_dataset: str)
     return "embedding_original_large_3.parquet"
 
 
+def _graph_preview_html(mask_density: str, gene_nodes: str, pathway_units: str, genept_dim: str) -> str:
+    return ui.blueprint_div(
+        '<div style="display:grid;grid-template-columns:1fr 1fr;gap:14px 10px">'
+        + ui.mini_stat_html(mask_density, "Mask density")
+        + ui.mini_stat_html(gene_nodes, "Gene nodes")
+        + ui.mini_stat_html(pathway_units, "Pathway units")
+        + ui.mini_stat_html(genept_dim, "GenePT dim")
+        + "</div>"
+    )
+
+
 # ── rail / chrome state machine (presentation only) ─────────────────────
 
 
@@ -422,22 +433,43 @@ def prepare_workspace(
             f"{len(label_names)} classes · {len(gene_branch.pathways) + len(dna_branch.pathways):,} "
             f"branch-specific pathways · GenePT: {html.escape(embedding_file)}{warning_html}"
         )
-        note = ui.esc(
-            f"{len(resolved_rows)} of {len(resolved_rows)} inputs resolved"
-            + (f" · {len(warnings)} warning(s)" if warnings else "")
-            + f" · architecture built {datetime.now().strftime('%H:%M:%S')}"
+        note = (
+            '<div class="actbar-note">'
+            + ui.esc(
+                f"{len(resolved_rows)} of {len(resolved_rows)} inputs resolved"
+                + (f" · {len(warnings)} warning(s)" if warnings else "")
+                + f" · architecture built {datetime.now().strftime('%H:%M:%S')}"
+            )
+            + "</div>"
         )
         run_meta = {
             "source_name": source_name,
             "embedding_file": embedding_file,
             "unmatched_pathway_symbols": unmatched_symbols,
         }
+        mean_density = float(
+            np.mean(
+                [
+                    gene_branch.biological_mask.astype(bool).mean(),
+                    dna_branch.biological_mask.astype(bool).mean(),
+                ]
+            )
+        )
+        genept_dim = gene_branch.embeddings.shape[1] if gene_branch.embeddings is not None else 0
+        graph_preview_html = _graph_preview_html(
+            f"{mean_density * 100:.1f}%",
+            f"{len(gene_branch.hidden_genes) + len(dna_branch.hidden_genes):,}",
+            f"{len(gene_branch.pathways) + len(dna_branch.pathways):,}",
+            f"{genept_dim:,}",
+        )
         progress(1.0, desc="Ready to train")
-        return workspace, summary, architecture, enrichments.head(100), resolved_files, run_meta, note
+        return workspace, summary, architecture, enrichments.head(100), resolved_files, run_meta, note, graph_preview_html
     except Exception as exc:
-        return None, _status(str(exc), error=True), empty, empty, empty, {}, ui.esc(
+        fallback_note = '<div class="actbar-note">' + ui.esc(
             "Choose a source, then build the biological architecture."
-        )
+        ) + "</div>"
+        empty_graph_preview = _graph_preview_html("—", "—", "—", "—")
+        return None, _status(str(exc), error=True), empty, empty, empty, {}, fallback_note, empty_graph_preview
 
 
 def _reveal_symbols(run_meta: dict):
@@ -611,7 +643,8 @@ def train_workspace(
 
         minutes, seconds = divmod(int(elapsed_seconds), 60)
         metrics_html = ui.simple_status_html(
-            "<strong>Training complete.</strong> Best validation checkpoint restored; the "
+            f"<strong>Training complete.</strong> Validation accuracy {metrics['accuracy']:.3f} · "
+            f"elapsed {minutes:02d}:{seconds:02d}. Best validation checkpoint restored; the "
             "downloadable artifact includes architecture, preprocessing, weights and metrics."
         )
         loss_figure = _loss_plot(bundle.history)
@@ -731,19 +764,26 @@ def _resolve_predict_bundle(model_state, artifact_path, use_upload: bool):
     return model_state
 
 
-def refresh_alignment(model_state, artifact_path, use_upload, gene_path, dna_path):
+def _workspace_prediction_frames(workspace: PreparedWorkspace) -> tuple[pd.DataFrame, pd.DataFrame]:
+    return (
+        pd.DataFrame(workspace.gene_expression, columns=workspace.gene_branch.input_genes),
+        pd.DataFrame(workspace.dna_methylation, columns=workspace.dna_branch.input_genes),
+    )
+
+
+def refresh_alignment(model_state, workspace, artifact_path, use_upload, use_prepared, gene_path, dna_path):
     """Presentation-only pre-flight check: mirrors the two structural checks
     ``validate_prediction_frames`` performs (row-count match, required
     columns present) purely to render the alignment table live. The actual
     gating decision on submit still goes through the real, untouched
     ``predict()`` call."""
-    align = {"ok": None, "required": None, "matched": None, "source_label": "Session model"}
+    align = {"ok": None, "required": None, "matched": None, "source_label": "Prepared dataset" if use_prepared else "Session model"}
     try:
         bundle = _resolve_predict_bundle(model_state, artifact_path, use_upload)
     except Exception as exc:
         rows = [[html.escape("Artifact"), "—", "—", f'<span class="error">{html.escape(str(exc))}</span>']]
         table = ui.table_html(["Check", "Artifact", "Uploaded", "Result"], rows, aligns=["left", "left", "left", "right"])
-        return table, gr.update(visible=False), gr.update(interactive=False), align
+        return table, gr.update(visible=False), gr.update(value="Run inference", interactive=False, elem_classes=["actbar-primary-btn"]), align
 
     if use_upload:
         align["source_label"] = "Uploaded artifact" if artifact_path else "Upload artifact"
@@ -753,14 +793,21 @@ def refresh_alignment(model_state, artifact_path, use_upload, gene_path, dna_pat
             [["Trained model available", "—", "—", '<span class="error">Fail</span>']],
             aligns=["left", "left", "left", "right"],
         )
-        return table, gr.update(visible=False), gr.update(interactive=False), align
+        return table, gr.update(visible=False), gr.update(value="Run inference", interactive=False, elem_classes=["actbar-primary-btn"]), align
 
     align["required"] = len(bundle.gene_features) + len(bundle.dna_features)
 
     rows = []
     ok = True
     gene_frame = dna_frame = None
-    if gene_path and dna_path:
+    if use_prepared:
+        if workspace is None:
+            rows.append(["Prepared dataset available", "—", "—", '<span class="error">Fail</span>'])
+            ok = False
+        else:
+            gene_frame, dna_frame = _workspace_prediction_frames(workspace)
+            rows.append(["Prepared dataset available", "—", f"{len(gene_frame):,} samples", _pass_fail(True)])
+    elif gene_path and dna_path:
         try:
             gene_frame = read_csv(gene_path)
             dna_frame = read_csv(dna_path)
@@ -800,7 +847,7 @@ def refresh_alignment(model_state, artifact_path, use_upload, gene_path, dna_pat
     return table, gr.update(visible=strip_visible, value=(
         ui.strip_text_html("Blocking · features missing", f"{missing_total:,} required column(s) are missing from the uploaded files.")
         if strip_visible else ""
-    )), gr.update(interactive=bool(ok)), align
+    )), gr.update(value="Run inference", interactive=bool(ok), elem_classes=["actbar-primary-btn"]), align
 
 
 def _pass_fail(ok: bool) -> str:
@@ -816,14 +863,28 @@ def _list_missing(align: dict):
     return gr.update(visible=True, value=f'<div class="num" style="word-break:break-word">{html.escape(shown)}{more}</div>')
 
 
-def run_prediction(bundle: ModelBundle | None, uploaded_artifact: str | None, use_upload: bool, gene_file: str | None, dna_file: str | None, predict_meta: dict):
+def run_prediction(
+    bundle: ModelBundle | None,
+    workspace: PreparedWorkspace | None,
+    uploaded_artifact: str | None,
+    use_upload: bool,
+    use_prepared: bool,
+    gene_file: str | None,
+    dna_file: str | None,
+    predict_meta: dict,
+):
     predict_meta = dict(predict_meta or {})
     try:
         active_bundle = load_bundle(uploaded_artifact) if (use_upload and uploaded_artifact) else bundle
         if active_bundle is None:
             raise ValueError("Train a model in Phase 2 or upload a BioLM-NET model artifact.")
-        gene_frame = _read_required_upload(gene_file, "a prediction gene-expression CSV")
-        dna_frame = _read_required_upload(dna_file, "a prediction DNA-methylation CSV")
+        if use_prepared:
+            if workspace is None:
+                raise ValueError("Prepare data and priors before scoring the prepared dataset.")
+            gene_frame, dna_frame = _workspace_prediction_frames(workspace)
+        else:
+            gene_frame = _read_required_upload(gene_file, "a prediction gene-expression CSV")
+            dna_frame = _read_required_upload(dna_file, "a prediction DNA-methylation CSV")
         output = predict(gene_frame, dna_frame, active_bundle)
         destination = Path(tempfile.mkdtemp(prefix="biolmnet-prediction-")) / "biolm-net-predictions.csv"
         output.to_csv(destination, index=False)
@@ -923,6 +984,8 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
     predict_meta_state = gr.State({})
     active_page_state = gr.State("data")
     session_id_state = gr.State("")
+    intro_step_state = gr.State(0)
+    intro_dismissed_state = gr.BrowserState(False, storage_key="biolmnet_intro_dismissed")
 
     with gr.Row(elem_classes=["app-shell"]):
         with gr.Column(elem_classes=["rail-col"]):
@@ -943,7 +1006,9 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
                     gr.HTML(ui.footnote_html("Research use only", "ZeroGPU on demand · py 3.12"))
 
         with gr.Column(elem_classes=["workspace-col"]):
-            topbar_html_component = gr.HTML(ui.topbar_html(1, STAGE_TOTAL, STAGE_LABELS[0], "——————", "ZeroGPU idle"))
+            with gr.Row(elem_classes=["topbar-host"]):
+                topbar_html_component = gr.HTML(ui.topbar_html(1, STAGE_TOTAL, STAGE_LABELS[0], "——————", "ZeroGPU idle"))
+                intro_open_button = gr.Button("Introduction", size="sm", variant="secondary", elem_classes=["btn-ghost", "intro-open-btn"])
 
             # ── Data & Priors ────────────────────────────────────────
             with gr.Column(visible=True) as data_page:
@@ -1066,16 +1131,7 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
                         )
 
                         gr.HTML('<div class="mono" style="margin:24px 0 9px">Graph preview</div>')
-                        graph_preview = gr.HTML(
-                            ui.blueprint_div(
-                                '<div style="display:grid;grid-template-columns:1fr 1fr;gap:14px 10px">'
-                                + ui.mini_stat_html("—", "Mask density")
-                                + ui.mini_stat_html("—", "Gene nodes")
-                                + ui.mini_stat_html("—", "Pathway units")
-                                + ui.mini_stat_html("—", "GenePT dim")
-                                + "</div>"
-                            )
-                        )
+                        graph_preview = gr.HTML(_graph_preview_html("—", "—", "—", "—"))
 
                 with gr.Row(visible=False):
                     architecture_table = gr.Dataframe(interactive=False, wrap=False, value=pd.DataFrame(), headers=[""], column_count=(1, "dynamic"))
@@ -1230,6 +1286,10 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
                 with gr.Row(elem_classes=["stage-grid"], equal_height=False):
                     with gr.Column(scale=6, min_width=0):
                         gr.HTML('<div class="mono sect">Inputs</div>')
+                        prediction_input_mode = gr.Radio(
+                            ["Prepared dataset", "Upload files"], value="Prepared dataset", show_label=False,
+                            container=False, elem_classes=["seg-radio"],
+                        )
                         with gr.Row(elem_classes=["srow-row", "first"], visible=True) as session_model_row:
                             with gr.Column(min_width=100):
                                 gr.HTML(ui.esc("Trained artifact"))
@@ -1240,12 +1300,17 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
                                 gr.HTML(ui.esc("Trained artifact"))
                             with gr.Column():
                                 prediction_artifact = gr.File(label="", show_label=False, file_types=[".zip"], type="filepath", elem_classes=["file-slot"])
-                        with gr.Row(elem_classes=["srow-row"]):
+                        with gr.Row(elem_classes=["srow-row"]) as prepared_dataset_row:
+                            with gr.Column(min_width=100):
+                                gr.HTML(ui.esc("Prediction cohort"))
+                            with gr.Column():
+                                gr.HTML('<div class="num" style="opacity:.65">Use the dataset prepared in Data &amp; Priors.</div>')
+                        with gr.Row(elem_classes=["srow-row"], visible=False) as prediction_gene_row:
                             with gr.Column(min_width=100):
                                 gr.HTML(ui.esc("Gene expression"))
                             with gr.Column():
                                 prediction_gene = gr.File(label="", show_label=False, file_types=[".csv"], type="filepath", elem_classes=["file-slot"])
-                        with gr.Row(elem_classes=["srow-row", "last"]):
+                        with gr.Row(elem_classes=["srow-row", "last"], visible=False) as prediction_dna_row:
                             with gr.Column(min_width=100):
                                 gr.HTML(ui.esc("DNA methylation"))
                             with gr.Column():
@@ -1307,6 +1372,40 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
                         "drawing biological or clinical conclusions.</div>"
                     )
 
+    with gr.Group(elem_id="intro", visible=True) as intro_group:
+        intro_cards = []
+        intro_next_buttons = []
+        intro_back_buttons = []
+        intro_skip_buttons = []
+        intro_start_buttons = []
+        with gr.Column(elem_classes=["intro-card"]):
+            for index, (_, _, _, _, note) in enumerate(ui.INTRO_CARDS):
+                with gr.Column(visible=index == 0, elem_classes=["intro-card-page"]) as intro_card:
+                    gr.HTML(ui.intro_card_html(index))
+                    with gr.Row(elem_classes=["intro-card-foot"]):
+                        if index == 0:
+                            intro_dont_show = gr.Checkbox(value=False, label="Don't show again", container=False)
+                        else:
+                            gr.HTML(f'<span class="mono" style="font-size:9.5px">{ui.esc(note)}</span>')
+                        with gr.Row(elem_classes=["intro-card-actions"]):
+                            gr.HTML(ui.intro_dots_html(index))
+                            if index == 0:
+                                skip_btn = gr.Button("Skip", size="sm", variant="secondary", elem_classes=["btn-ghost"])
+                                next_btn = gr.Button("Next", size="sm", variant="primary")
+                                intro_skip_buttons.append(skip_btn)
+                                intro_next_buttons.append(next_btn)
+                            elif index < len(ui.INTRO_CARDS) - 1:
+                                back_btn = gr.Button("Back", size="sm", variant="secondary", elem_classes=["btn-ghost"])
+                                next_btn = gr.Button("Next", size="sm", variant="primary")
+                                intro_back_buttons.append(back_btn)
+                                intro_next_buttons.append(next_btn)
+                            else:
+                                back_btn = gr.Button("Back", size="sm", variant="secondary", elem_classes=["btn-ghost"])
+                                start_btn = gr.Button("Start with the BRCA example", size="sm", variant="primary")
+                                intro_back_buttons.append(back_btn)
+                                intro_start_buttons.append(start_btn)
+                intro_cards.append(intro_card)
+
     # ═════════════════════════════════════════════════════════════════
     # Wiring
     # ═════════════════════════════════════════════════════════════════
@@ -1326,18 +1425,76 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
             _nav(key), inputs=chrome_inputs_tail, outputs=[active_page_state, *page_columns, *chrome_outputs]
         )
 
+    def _intro_updates(index: int, visible: bool = True):
+        index = max(0, min(len(ui.INTRO_CARDS) - 1, int(index)))
+        cards = [gr.update(visible=i == index) for i in range(len(ui.INTRO_CARDS))]
+        return index, gr.update(visible=visible), *cards
+
+    def _intro_load(dismissed):
+        return secrets.token_hex(3), *_intro_updates(0, visible=not bool(dismissed))
+
+    def _intro_close(dont_show):
+        return 0, gr.update(visible=False), bool(dont_show)
+
+    def _intro_start_brca(dont_show):
+        return (
+            0,
+            gr.update(visible=False),
+            bool(dont_show),
+            "BioLM-NET examples",
+            "BRCA",
+            *_source_visibility("BioLM-NET examples"),
+        )
+
+    intro_outputs = [intro_step_state, intro_group, *intro_cards]
+
     demo.load(
-        lambda: secrets.token_hex(3), outputs=[session_id_state]
+        _intro_load, inputs=[intro_dismissed_state], outputs=[session_id_state, *intro_outputs]
     ).then(
         lambda sid, *rest: _refresh_chrome("data", *rest, sid), inputs=[session_id_state, *chrome_inputs_tail[:-1]], outputs=chrome_outputs
     )
 
+    intro_open_button.click(
+        lambda: _intro_updates(0, True), outputs=intro_outputs, show_progress="hidden"
+    )
+    for index, button in enumerate(intro_next_buttons):
+        button.click(
+            lambda i=index: _intro_updates(i + 1, True), outputs=intro_outputs, show_progress="hidden"
+        )
+    for index, button in enumerate(intro_back_buttons, start=1):
+        button.click(
+            lambda i=index: _intro_updates(i - 1, True), outputs=intro_outputs, show_progress="hidden"
+        )
+    for button in intro_skip_buttons:
+        button.click(
+            _intro_close, inputs=[intro_dont_show],
+            outputs=[intro_step_state, intro_group, intro_dismissed_state],
+            show_progress="hidden",
+        )
+    for button in intro_start_buttons:
+        button.click(
+            _intro_start_brca, inputs=[intro_dont_show],
+            outputs=[
+                intro_step_state, intro_group, intro_dismissed_state,
+                source_mode, example_dataset, example_group, github_group, upload_group,
+            ],
+            show_progress="hidden",
+        )
+
     source_mode.change(
         _source_visibility, inputs=[source_mode], outputs=[example_group, github_group, upload_group]
     )
 
-    def _busy(label):
-        return gr.update(value=label, interactive=False)
+    # The one deliberate loading indicator (a thin animated bar on the busy
+    # button itself — see `.is-busy` in styles.py) is toggled only through
+    # these two helpers, explicitly, on exactly the button that was clicked.
+    # It is never left to Gradio's own per-component pending state, which is
+    # what caused several of these to appear at once for one click.
+    def _busy(label, base_classes):
+        return gr.update(value=label, interactive=False, elem_classes=[*base_classes, "is-busy"])
+
+    def _idle(label, base_classes, interactive=True):
+        return gr.update(value=label, interactive=interactive, elem_classes=list(base_classes))
 
     prepare_inputs = [
         source_mode, example_dataset, github_folder, uploaded_gene, uploaded_dna, uploaded_labels,
@@ -1348,35 +1505,93 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
     def _after_prepare(workspace, run_meta, session_id):
         chrome = _refresh_chrome("data", workspace, None, run_meta, {}, {}, session_id)
         return (
-            gr.update(value="Build biological architecture", interactive=True),
-            gr.update(value="Re-validate inputs", interactive=True),
+            _idle("Build biological architecture", ["actbar-primary-btn"]),
+            _idle("Re-validate inputs", ["actbar-secondary-btn"]),
             *chrome,
         )
 
-    for trigger in (prepare_button, revalidate_button):
-        trigger.click(
-            lambda: (_busy("Building…"), _busy("Building…")), outputs=[prepare_button, revalidate_button],
-            show_progress="hidden",
-        ).then(
-            prepare_workspace, inputs=prepare_inputs,
-            outputs=[
-                workspace_state, preparation_status, architecture_table, enrichment_table,
-                resolved_files_table, run_meta_state, data_actionbar_note,
-            ],
-            show_progress="minimal",
-        ).then(
-            lambda note: f'<div class="actbar-note">{note}</div>', inputs=[data_actionbar_note], outputs=[data_actionbar_note],
-            show_progress="hidden",
-        ).then(
-            _after_prepare, inputs=[workspace_state, run_meta_state, session_id_state],
-            outputs=[prepare_button, revalidate_button, *chrome_outputs],
-            show_progress="hidden",
+    # Only the button actually clicked gets the sweep; its sibling just goes
+    # inert (disabled, unchanged label) — two buttons both sweeping for one
+    # action would itself be the "more than one indicator" problem.
+    def _busy_pair(which: str):
+        if which == "primary":
+            return (
+                _busy("Building…", ["actbar-primary-btn"]),
+                gr.update(interactive=False),
+            )
+        return (
+            gr.update(interactive=False),
+            _busy("Building…", ["actbar-secondary-btn"]),
         )
 
+    prepare_button.click(
+        lambda: _busy_pair("primary"), outputs=[prepare_button, revalidate_button],
+        show_progress="hidden",
+    ).then(
+        prepare_workspace, inputs=prepare_inputs,
+        outputs=[
+            workspace_state, preparation_status, architecture_table, enrichment_table,
+            resolved_files_table, run_meta_state, data_actionbar_note, graph_preview,
+        ],
+        show_progress="hidden",
+    ).then(
+        _after_prepare, inputs=[workspace_state, run_meta_state, session_id_state],
+        outputs=[prepare_button, revalidate_button, *chrome_outputs],
+        show_progress="hidden",
+    )
+
+    revalidate_button.click(
+        lambda: _busy_pair("secondary"), outputs=[prepare_button, revalidate_button],
+        show_progress="hidden",
+    ).then(
+        prepare_workspace, inputs=prepare_inputs,
+        outputs=[
+            workspace_state, preparation_status, architecture_table, enrichment_table,
+            resolved_files_table, run_meta_state, data_actionbar_note, graph_preview,
+        ],
+        show_progress="hidden",
+    ).then(
+        _after_prepare, inputs=[workspace_state, run_meta_state, session_id_state],
+        outputs=[prepare_button, revalidate_button, *chrome_outputs],
+        show_progress="hidden",
+    )
+
     show_symbols_btn.click(_reveal_symbols, inputs=[run_meta_state], outputs=[unmatched_reveal])
     pdi_override_btn.click(lambda: gr.update(visible=True), outputs=[uploaded_pdi])
     ppi_override_btn.click(lambda: gr.update(visible=True), outputs=[uploaded_ppi])
 
+    def _predict_source_toggle(mode):
+        return gr.update(visible=mode == "Session model"), gr.update(visible=mode == "Upload artifact")
+
+    predict_source_mode.change(
+        _predict_source_toggle, inputs=[predict_source_mode], outputs=[session_model_row, artifact_upload_row]
+    )
+
+    def _predict_input_toggle(mode):
+        use_uploads = mode == "Upload files"
+        return (
+            gr.update(visible=not use_uploads),
+            gr.update(visible=use_uploads),
+            gr.update(visible=use_uploads),
+        )
+
+    prediction_input_mode.change(
+        _predict_input_toggle,
+        inputs=[prediction_input_mode],
+        outputs=[prepared_dataset_row, prediction_gene_row, prediction_dna_row],
+    )
+
+    align_inputs = [
+        model_state, workspace_state, prediction_artifact, predict_source_mode,
+        prediction_input_mode, prediction_gene, prediction_dna,
+    ]
+
+    def _align_wrapper(bundle, workspace, artifact_path, model_mode, input_mode, gene_path, dna_path):
+        return refresh_alignment(
+            bundle, workspace, artifact_path, model_mode == "Upload artifact",
+            input_mode == "Prepared dataset", gene_path, dna_path,
+        )
+
     # `train_workspace`'s positional signature intentionally mirrors
     # `estimate_training_duration` exactly for `@spaces.GPU` — session
     # metadata (dataset name, elapsed time, …) is threaded through
@@ -1389,7 +1604,7 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
 
     def _after_train(bundle, run_meta, session_id):
         chrome = _refresh_chrome("train", bundle is not None and True, bundle, run_meta, {}, {}, session_id)
-        return gr.update(value="Train BioLM-NET on ZeroGPU", interactive=True), *chrome
+        return _idle("Train BioLM-NET on ZeroGPU", ["actbar-primary-btn"]), *chrome
 
     validation_predictions_state = gr.State(pd.DataFrame())
     importance_state = gr.State(pd.DataFrame())
@@ -1398,7 +1613,7 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
     run_meta_update_state = gr.State({})
 
     train_button.click(
-        lambda: _busy("Training on ZeroGPU…"), outputs=[train_button],
+        lambda: _busy("Training on ZeroGPU…", ["actbar-primary-btn"]), outputs=[train_button],
         show_progress="hidden",
     ).then(
         train_workspace, inputs=train_inputs,
@@ -1406,7 +1621,7 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
             model_state, training_status, loss_plot, validation_predictions_state, artifact_path_state,
             importance_state, architecture_audit_state, run_meta_update_state, confusion_html_state,
         ],
-        show_progress="minimal",
+        show_progress="hidden",
     ).then(
         lambda old, new: {**(old or {}), **(new or {})},
         inputs=[run_meta_state, run_meta_update_state], outputs=[run_meta_state],
@@ -1415,6 +1630,10 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
         _after_train, inputs=[model_state, run_meta_state, session_id_state],
         outputs=[train_button, *chrome_outputs],
         show_progress="hidden",
+    ).then(
+        _align_wrapper, inputs=align_inputs,
+        outputs=[alignment_table, alignment_strip, predict_button, align_state],
+        show_progress="hidden",
     ).then(
         lambda bundle, artifact_path, run_meta: _export_panel(bundle, artifact_path, run_meta),
         inputs=[model_state, artifact_path_state, run_meta_state],
@@ -1441,30 +1660,22 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
     ).then(
         lambda bundle: gr.update(visible=bundle is not None), inputs=[model_state], outputs=[results_tables_bottom],
         show_progress="hidden",
-    ).then(
-        lambda bundle, run_meta: gr.update(value=_status(
-            f"Training complete · validation accuracy {bundle.metrics['accuracy']:.3f} · elapsed {run_meta.get('elapsed','—')}"
-        )) if bundle else gr.update(),
-        inputs=[model_state, run_meta_state], outputs=[training_status],
-        show_progress="hidden",
     )
-
-    def _predict_source_toggle(mode):
-        return gr.update(visible=mode == "Session model"), gr.update(visible=mode == "Upload artifact")
-
-    predict_source_mode.change(
-        _predict_source_toggle, inputs=[predict_source_mode], outputs=[session_model_row, artifact_upload_row]
-    )
-
-    def _use_upload(mode):
-        return mode == "Upload artifact"
-
-    align_inputs = [model_state, prediction_artifact, predict_source_mode, prediction_gene, prediction_dna]
-
-    def _align_wrapper(bundle, artifact_path, mode, gene_path, dna_path):
-        return refresh_alignment(bundle, artifact_path, mode == "Upload artifact", gene_path, dna_path)
-
-    for control in (predict_source_mode, prediction_artifact, prediction_gene, prediction_dna, model_state):
+    # training_status is NOT re-set here: train_workspace's own return
+    # already carries the final "Training complete · accuracy · elapsed"
+    # message (it has the elapsed time on hand already), so writing it
+    # again from run_meta_state afterwards was a second, redundant paint
+    # of the same component for one click.
+
+    # Deliberately NOT including `model_state` here: it only ever changes as
+    # part of the train/predict chains below, and both of those already call
+    # `_align_wrapper` explicitly as their own finalize step. Adding it here
+    # too would fire alignment twice per click (train_workspace/_predict_
+    # wrapper set model_state -> this listener fires -> the chain's own
+    # explicit call also fires) — the exact "loading bar twice" symptom.
+    # `workspace_state` stays: nothing else re-checks alignment when the
+    # user rebuilds the architecture while already on the Predict page.
+    for control in (predict_source_mode, prediction_input_mode, prediction_artifact, prediction_gene, prediction_dna, workspace_state):
         control.change(
             _align_wrapper, inputs=align_inputs,
             outputs=[alignment_table, alignment_strip, predict_button, align_state],
@@ -1472,22 +1683,29 @@ with gr.Blocks(title="BioLM-NET Workbench", fill_width=True) as demo:
 
     list_missing_btn.click(_list_missing, inputs=[align_state], outputs=[missing_reveal])
 
-    predict_inputs = [model_state, prediction_artifact, predict_source_mode, prediction_gene, prediction_dna, predict_meta_state]
+    predict_inputs = [
+        model_state, workspace_state, prediction_artifact, predict_source_mode,
+        prediction_input_mode, prediction_gene, prediction_dna, predict_meta_state,
+    ]
 
-    def _predict_wrapper(bundle, artifact_path, mode, gene_path, dna_path, predict_meta):
-        return run_prediction(bundle, artifact_path, mode == "Upload artifact", gene_path, dna_path, predict_meta)
+    def _predict_wrapper(bundle, workspace, artifact_path, model_mode, input_mode, gene_path, dna_path, predict_meta):
+        return run_prediction(
+            bundle, workspace, artifact_path, model_mode == "Upload artifact",
+            input_mode == "Prepared dataset", gene_path, dna_path, predict_meta,
+        )
 
     predict_button.click(
-        lambda: _busy("Running inference…"), outputs=[predict_button],
+        lambda: _busy("Running inference…", ["actbar-primary-btn"]), outputs=[predict_button],
         show_progress="hidden",
     ).then(
         _predict_wrapper, inputs=predict_inputs,
         outputs=[model_state, prediction_status, prediction_table, distribution_panel, prediction_download, predict_meta_state],
-        show_progress="minimal",
-    ).then(
-        lambda: gr.update(value="Run inference", interactive=True), outputs=[predict_button],
         show_progress="hidden",
     ).then(
+        # This one call both resets the button's label back to "Run
+        # inference" (out of its transient "Running inference…" busy state)
+        # and sets the correct interactive flag — no separate blind
+        # re-enable step first, which used to write predict_button twice.
         _align_wrapper, inputs=align_inputs, outputs=[alignment_table, alignment_strip, predict_button, align_state],
         show_progress="hidden",
     ).then(

biolmnet/data.py

@@ -57,6 +57,12 @@ def _normalise_columns(frame: pd.DataFrame) -> pd.DataFrame:
     return result
 
 
+def _normalise_embedding_index(frame: pd.DataFrame) -> pd.DataFrame:
+    result = frame.copy()
+    result.index = result.index.astype(str).str.strip()
+    return result[~result.index.duplicated(keep="first")]
+
+
 def read_csv(source: str | Path | BinaryIO) -> pd.DataFrame:
     if hasattr(source, "read"):
         return _normalise_columns(pd.read_csv(source))
@@ -415,8 +421,7 @@ def load_genept_embeddings(filename: str) -> pd.DataFrame:
         repo_type="model",
     )
     frame = pd.read_parquet(path)
-    frame.index = frame.index.astype(str).str.strip()
-    return frame
+    return _normalise_embedding_index(frame)
 
 
 def attach_embeddings_and_pathways(
@@ -426,6 +431,7 @@ def attach_embeddings_and_pathways(
     *,
     precomputed_significant: bool,
 ) -> pd.DataFrame:
+    embedding_frame = _normalise_embedding_index(embedding_frame)
     embedding_index = set(embedding_frame.index.astype(str))
     keep = np.array(
         [gene in embedding_index for gene in branch.hidden_genes], dtype=bool

biolmnet/ui/components.py

@@ -228,6 +228,116 @@ def empty_note_html(message: str) -> str:
     return f'<div class="empty-note">{esc(message)}</div>'
 
 
+# ── introduction cards ────────────────────────────────────────────────────
+
+INTRO_CARDS = [
+    (
+        "Introduction · 01 / 06",
+        "A network wired along known biology",
+        (
+            "BioLM-NET classifies tumour samples from <b>paired gene expression and DNA methylation</b>. "
+            "Instead of connecting every gene to every neuron, it only makes the connections biology supports — "
+            "KEGG pathways, transcription-factor targets, protein interactions — so trained weights can be read "
+            "back as pathways rather than as a black box."
+        ),
+        "This workbench runs the model end to end in five stages. On the bundled BRCA example it takes a few minutes.",
+        "",
+    ),
+    (
+        "Introduction · 02 / 06",
+        "Five stages, in order",
+        (
+            "The rail on the left is the spine of the app. Each stage consumes the previous one's output, so a "
+            "stage stays <b>locked</b> until its prerequisite exists — you cannot export a model you have not trained."
+        ),
+        (
+            '<div class="intro-stage-list">'
+            "<div><em>01</em><span><b>Data &amp; Priors</b> — assemble the masked graph</span></div>"
+            "<div><em>02</em><span><b>Train Model</b> — fit it, watch the epochs</span></div>"
+            "<div><em>03</em><span><b>Export Artifacts</b> — save a reusable bundle</span></div>"
+            "<div><em>04</em><span><b>Predict</b> — score a new cohort</span></div>"
+            "<div><em>05</em><span><b>Results</b> — metrics and pathway attention</span></div>"
+            "</div>"
+        ),
+        "The plate under the rail always says what state the model is in",
+    ),
+    (
+        "Introduction · 03 / 06 · Stage 01",
+        "Data & Priors",
+        (
+            "Point the workbench at paired omics — a bundled example, a GitHub folder, or your own upload — with "
+            "<b>samples in rows and HGNC symbols in columns</b>. The two matrices are aligned on their shared "
+            "samples, and every file is reported with the shape it was read at rather than failing silently."
+        ),
+        (
+            "The priors on the right are the biology that becomes wiring: pathway annotations, the enrichment "
+            "cutoff, the GenePT context and the interaction sources. Defaults follow the paper."
+        ),
+        "Rebuilding clears any trained model",
+    ),
+    (
+        "Introduction · 04 / 06 · Stage 02",
+        "Train Model",
+        (
+            "Hyperparameters sit on the left as a spec sheet. The run panel on the right reports <b>epoch, train "
+            "and validation loss, accuracy and ETA</b> as the fit progresses."
+        ),
+        (
+            "Controls lock for the duration of a run and the primary button reads <b>Training on ZeroGPU</b> "
+            "until it finishes; Cancel stays available. The GPU is allocated on demand, so the first epoch may "
+            "wait for its reservation."
+        ),
+        "Paper defaults are one click away",
+    ),
+    (
+        "Introduction · 05 / 06 · Stages 03–04",
+        "Export, then predict",
+        (
+            "Export writes one bundle carrying the weights, the fitted preprocessing, the mask and the config — "
+            "enough to score new samples later without rebuilding the graph. Its manifest lists what each entry "
+            "reproduces, with a checksum."
+        ),
+        (
+            "Predict scores a new cohort with either the session model or an uploaded bundle. Features are "
+            "<b>aligned to the artifact first</b>; if a required column is missing, inference is blocked and the "
+            "check that failed is named."
+        ),
+        "Bundles are temp files — download before the Space restarts",
+    ),
+    (
+        "Introduction · 06 / 06 · Stage 05",
+        "Reading the results",
+        (
+            "Results collects everything a run produced: validation metrics, the training curve, the confusion "
+            "matrix, an audit of how sparse each layer actually is, and the pathway attention weights — which is "
+            "the part the architecture exists to give you."
+        ),
+        (
+            "Treat it as model output, not as biology. <b>Check cohort composition, preprocessing and class "
+            "balance before drawing conclusions</b>, and remember that attention weights rank pathways within "
+            "this fit rather than proving mechanism."
+        ),
+        "Research use only · not for clinical decisions",
+    ),
+]
+
+
+def intro_card_html(index: int) -> str:
+    step, title, body_1, body_2, _ = INTRO_CARDS[index]
+    return (
+        f'<div class="intro-step">{esc(step)}</div>'
+        f"<h4>{esc(title)}</h4>"
+        f"<p>{body_1}</p>"
+        f"<p>{body_2}</p>"
+    )
+
+
+def intro_dots_html(index: int, total: int = 6) -> str:
+    return '<div class="intro-dots">' + "".join(
+        f'<i class="{"on" if i == index else ""}"></i>' for i in range(total)
+    ) + "</div>"
+
+
 # ── misc ─────────────────────────────────────────────────────────────────
 
 def human_bytes(n: float) -> str:

biolmnet/ui/styles.py

@@ -274,7 +274,25 @@ body, .gradio-container {
 .kv-plain.last { border-bottom: none; }
 
 /* ── topbar / page head / action bar ─────────────────────────────────── */
-.topbar { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 13px 30px; border-bottom: 1px solid var(--color-divider); }
+.topbar-host {
+  position: relative;
+  display: block !important;
+  padding: 0 !important;
+  gap: 0 !important;
+}
+.topbar-host > .block:first-child { width: 100% !important; }
+.topbar { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 13px 132px 13px 30px; border-bottom: 1px solid var(--color-divider); }
+.intro-open-btn {
+  position: absolute !important;
+  right: 30px;
+  top: 8px;
+  z-index: 5;
+}
+.intro-open-btn button {
+  font-size: 11.5px !important;
+  min-height: 28px !important;
+  padding: 0 8px !important;
+}
 .pghd { padding: 26px 30px 0; display: flex; align-items: flex-end; justify-content: space-between; gap: 24px; flex-wrap: wrap; }
 .pghd h2 { font-size: 34px; line-height: 1; color: var(--color-text); }
 .pghd .desc { margin-top: 5px; max-width: 640px; color: var(--color-muted); font-size: 13.5px; line-height: 1.5; }
@@ -510,6 +528,45 @@ body, .gradio-container {
 .gradio-container input[type="range"] { accent-color: var(--color-accent); height: 3px; }
 .gradio-container :focus-visible { outline: 2px solid var(--color-accent) !important; outline-offset: 2px; }
 
+/* Gradio pulses a 2px accent border + animation around every component
+   whose value is currently pending ("generating"), independent of
+   show_progress. One action often updates several visible components at
+   once (a table, a note, a stat panel, …), so this reads as multiple
+   flashing "loading bars" appearing together — we already surface busy
+   state through the triggering button's own label (see app.py's `_busy`
+   helper), so drop Gradio's border/animation entirely rather than have it
+   multiply per output. */
+.gradio-container .generating {
+  animation: none !important;
+  border-color: transparent !important;
+  border-width: 0 !important;
+  background: none !important;
+}
+
+/* The one deliberate loading indicator: a thin animated bar along the
+   bottom edge of whichever action button is currently busy. Toggled
+   explicitly by app.py's `_busy`/`_idle` helpers via the `is-busy` class —
+   never by Gradio's own per-component pending state — so exactly one of
+   these can ever be on screen at a time. */
+/* elem_classes lands directly on the <button> tag for gr.Button (no
+   wrapper div) — cover both that and a wrapper div defensively. */
+.is-busy, .is-busy button {
+  position: relative;
+  overflow: hidden;
+}
+.is-busy::after, .is-busy button::after {
+  content: "";
+  position: absolute;
+  left: 0; bottom: 0; height: 2px; width: 35%;
+  background: currentColor;
+  opacity: .7;
+  animation: workbench-busy-sweep 1.1s ease-in-out infinite;
+}
+@keyframes workbench-busy-sweep {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(285%); }
+}
+
 /* dataframes (.tbl-like) */
 .gradio-container table { color: var(--color-text) !important; font-size: 12.5px !important; }
 .gradio-container thead th {
@@ -526,6 +583,144 @@ body, .gradio-container {
 /* accordion */
 .gradio-container .label-wrap { color: var(--color-text) !important; }
 
+/* ── first-open introduction ─────────────────────────────────────────── */
+#intro {
+  position: fixed !important;
+  inset: 0 !important;
+  z-index: 60 !important;
+  min-height: 100vh !important;
+  display: grid !important;
+  place-items: center !important;
+  padding: 24px !important;
+  background: rgba(29, 31, 32, .6) !important;
+  border: 0 !important;
+}
+#intro[style*="display: none"] {
+  display: none !important;
+}
+#intro > .form,
+#intro .form {
+  display: contents !important;
+}
+.intro-card {
+  position: relative;
+  width: min(556px, calc(100vw - 48px)) !important;
+  background: var(--color-bg) !important;
+  border: 1px solid rgba(29,31,32,.18) !important;
+  padding: 26px 28px 20px !important;
+  box-shadow: 0 18px 44px rgba(0,0,0,.18) !important;
+}
+.intro-card::before,
+.intro-card::after {
+  content: "";
+  position: absolute;
+  top: -6px;
+  bottom: -6px;
+  width: 11px;
+  pointer-events: none;
+  border-color: color-mix(in srgb, var(--color-text) 55%, transparent);
+}
+.intro-card::before {
+  left: -6px;
+  border-left: 1px solid;
+  border-top: 1px solid;
+  border-bottom: 1px solid;
+}
+.intro-card::after {
+  right: -6px;
+  border-right: 1px solid;
+  border-top: 1px solid;
+  border-bottom: 1px solid;
+}
+.intro-card-page {
+  gap: 0 !important;
+}
+.intro-step {
+  font: 500 10px/1.3 var(--font-mono);
+  letter-spacing: .1em;
+  text-transform: uppercase;
+  color: var(--color-accent-700);
+}
+.intro-card h4 {
+  margin: 10px 0 10px;
+  font: 600 27px/1 var(--font-heading);
+  color: var(--color-text);
+}
+.intro-card p {
+  margin: 0 0 10px;
+  font-size: 13.5px;
+  line-height: 1.55;
+  color: color-mix(in srgb, var(--color-text) 74%, transparent) !important;
+}
+.intro-stage-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 8px 0 6px;
+}
+.intro-stage-list div {
+  display: grid;
+  grid-template-columns: 28px minmax(0, 1fr);
+  gap: 8px;
+  align-items: baseline;
+  font-size: 13px;
+}
+.intro-stage-list em {
+  font: 500 10px/1 var(--font-mono);
+  color: var(--color-accent-700);
+  font-style: normal;
+}
+.intro-card-foot {
+  align-items: center !important;
+  justify-content: space-between !important;
+  gap: 12px 16px !important;
+  margin-top: 16px !important;
+  padding-top: 14px !important;
+  border-top: 1px solid var(--color-divider) !important;
+  flex-wrap: wrap !important;
+}
+.intro-card-foot > *:first-child {
+  flex: 1 1 auto !important;
+  min-width: 0 !important;
+  max-width: 100% !important;
+  overflow-wrap: anywhere;
+}
+.intro-card-actions {
+  align-items: center !important;
+  justify-content: flex-end !important;
+  flex: 1 0 220px !important;
+  gap: 12px !important;
+  flex-wrap: nowrap !important;
+  width: auto !important;
+  margin-left: auto !important;
+}
+.intro-card-actions > * {
+  flex: 0 0 auto !important;
+  width: auto !important;
+}
+.intro-card-actions button {
+  min-height: 30px !important;
+  padding: 0 12px !important;
+  font-size: 12.5px !important;
+  white-space: normal !important;
+  line-height: 1.15 !important;
+}
+.intro-dots {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  flex: 0 0 auto;
+}
+.intro-dots i {
+  width: 8px;
+  height: 8px;
+  display: block;
+  background: color-mix(in srgb, var(--color-text) 18%, transparent);
+}
+.intro-dots i.on {
+  background: var(--color-accent);
+}
+
 /* ── responsive ───────────────────────────────────────────────────────── */
 @media (max-width: 1000px) {
   .app-shell { display: block !important; }

tests/test_core.py

@@ -128,6 +128,35 @@ def test_model_forward_probabilistic_shape() -> None:
     )
 
 
+def test_duplicate_embedding_rows_do_not_break_pathway_attachment() -> None:
+    branch = BranchPriors(
+        input_genes=["A", "B"],
+        hidden_genes=["A", "B", "C"],
+        biological_mask=np.ones((2, 3), dtype=np.float32),
+    )
+    embeddings = pd.DataFrame(
+        np.arange(16, dtype=np.float32).reshape(4, 4),
+        index=["A", "B", "B", "C"],
+    )
+    pathway_mapping = pd.DataFrame(
+        {
+            "SYMBOL": ["A", "B", "C"],
+            "PathwayID": ["hsa1", "hsa1", "hsa2"],
+        }
+    )
+
+    attach_embeddings_and_pathways(
+        branch,
+        embeddings,
+        pathway_mapping,
+        precomputed_significant=True,
+    )
+
+    assert branch.embeddings.shape[0] == len(branch.hidden_genes)
+    assert branch.biological_mask.shape[1] == len(branch.hidden_genes)
+    assert branch.pathway_mask.shape[0] == len(branch.hidden_genes)
+
+
 def test_training_artifact_roundtrip(tmp_path) -> None:
     workspace = _tiny_workspace()
     result = train(
@@ -161,6 +190,39 @@ def test_training_artifact_roundtrip(tmp_path) -> None:
     )
 
 
+def test_prediction_can_score_prepared_workspace_without_uploads() -> None:
+    from app import run_prediction
+
+    workspace = _tiny_workspace()
+    result = train(
+        workspace,
+        Hyperparameters(
+            epochs=3,
+            batch_size=8,
+            projection_dim=4,
+            fusion_dim=3,
+            dropout=0.0,
+            early_stopping_patience=3,
+        ),
+    )
+
+    _, status, output, _, download_path, predict_meta = run_prediction(
+        result.bundle,
+        workspace,
+        None,
+        False,
+        True,
+        None,
+        None,
+        {},
+    )
+
+    assert "Predicted 48 samples" in status
+    assert len(output) == len(workspace.labels)
+    assert download_path is not None
+    assert predict_meta["n_samples"] == len(workspace.labels)
+
+
 def test_zerogpu_duration_estimator_is_bounded_and_scales() -> None:
     from app import estimate_training_duration