UI overhaul: architecture diagram, dark-readable theme, formatted Ki cards

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+architecture.png filter=lfs diff=lfs merge=lfs -text

app.py

@@ -1,7 +1,7 @@
-"""SugarKi frontend — public UI for sugar-chemistry Ki prediction.
+"""SugarKi public UI — sugar-chemistry Ki predictor (frontend, MWBC/sugarki).
 
-Lightweight Gradio interface that calls the SugarKi backend Space via
-gradio_client. No model weights here; pure UI.
+Pretty Gradio interface that calls the SugarKi backend Space (private,
+ZeroGPU). No model weights here — just the UI.
 """
 from __future__ import annotations
 
@@ -9,16 +9,15 @@ import os
 from gradio_client import Client
 import gradio as gr
 
-# Backend Space (private; requires HF_TOKEN with read access to umesh1608)
 BACKEND = os.environ.get("SUGARKI_BACKEND", "Umesh1608/sugarki-backend")
 HF_TOKEN = os.environ.get("HF_TOKEN")
 
 if not HF_TOKEN:
     print("WARNING: HF_TOKEN not set; backend calls will fail if backend is private.")
 
-# -----------------------------------------------------------------------
-# Curated example library — common sugar inhibitors and enzymes
-# -----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+# Curated example library
+# ----------------------------------------------------------------------
 
 SUGAR_INHIBITORS = {
     "D-mannitol":            "OCC(O)C(O)C(O)C(O)CO",
@@ -51,12 +50,11 @@ EXAMPLES = [
     [EXAMPLE_MDH_WT, "D-mannitol", "substrate", "OCC(=O)C(O)C(O)C(O)CO"],
 ]
 
-# -----------------------------------------------------------------------
-# Backend client (lazy)
-# -----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+# Backend client
+# ----------------------------------------------------------------------
 
 _client = None
-
 def _backend():
     global _client
     if _client is None:
@@ -69,76 +67,178 @@ def _backend():
 
 def predict(sequence, inhibitor_choice, inhibitor_custom, inh_type, substrate_smiles):
     if not sequence or not sequence.strip():
-        return "**Error:** Please paste an enzyme sequence.", None, None
+        return "### ⚠️ Please paste an enzyme sequence", None, "", None
 
-    # Resolve inhibitor SMILES
-    if inhibitor_choice == "Custom (paste SMILES)":
-        smiles = (inhibitor_custom or "").strip()
-        if not smiles:
-            return "**Error:** Custom SMILES cannot be empty.", None, None
-    else:
-        smiles = SUGAR_INHIBITORS.get(inhibitor_choice, "")
-        if not smiles:
-            return f"**Error:** Unknown inhibitor `{inhibitor_choice}`.", None, None
+    smiles = (
+        inhibitor_custom.strip()
+        if inhibitor_choice == "Custom (paste SMILES)"
+        else SUGAR_INHIBITORS.get(inhibitor_choice, "")
+    )
+    if not smiles:
+        return "### ⚠️ Inhibitor SMILES is empty", None, "", None
 
     try:
         result = _backend().predict(
-            sequence.strip(),
-            smiles,
-            inh_type,
+            sequence.strip(), smiles, inh_type,
             substrate_smiles.strip() if substrate_smiles else "",
             api_name="/predict_ki",
         )
     except Exception as e:
-        return f"**Backend error:** {e}", None, None
+        return f"### ❌ Backend error\n```\n{e}\n```", None, "", None
 
-    if isinstance(result, dict) and "error" in result:
-        return f"**Error:** {result['error']}", None, None
+    if isinstance(result, dict) and result.get("error"):
+        msg = result.get("error_message", str(result))
+        return f"### ❌ Prediction error\n```\n{msg}\n```", None, "", result
 
-    # Format
+    # Headline card
     ki_mm = result.get("Ki_mM")
     ki_um = result.get("Ki_uM")
     log_ki = result.get("log10_Ki_mM")
-    inh_used = result.get("inh_type_used")
-    his_stripped = result.get("his_tag_stripped", False)
-    notes = result.get("notes", "")
+    inh_used = result.get("inh_type_used", "?")
+    his_stripped = "✓ stripped" if result.get("his_tag_stripped") else "—"
+    sigma = result.get("ensemble_std_log10", "?")
+
+    # Format Ki nicely with appropriate units
+    if ki_mm is not None:
+        if ki_mm < 0.001:
+            ki_display = f"**{ki_mm * 1e6:.2f} nM**"
+        elif ki_mm < 1:
+            ki_display = f"**{ki_um:.1f} µM**"
+        else:
+            ki_display = f"**{ki_mm:.3f} mM**"
+    else:
+        ki_display = "—"
 
-    summary_md = (
-        f"### Predicted Ki: **{ki_mm:.3f} mM** ({ki_um:,.1f} µM)\n\n"
-        f"- log₁₀(Ki / mM) = **{log_ki:+.3f}**\n"
-        f"- Inhibition mode used: **{inh_used}**\n"
-        f"- His-tag prefix detected and stripped: {'yes' if his_stripped else 'no'}\n"
-        f"- Ensemble σ (across 5 inhibition modes) = {result.get('ensemble_std_log10', '?')}\n\n"
-        f"**Model:** {result.get('model_version', 'SugarKi')}\n\n"
-        f"_{notes}_\n"
-    )
+    summary_md = f"""
+### 🧪 Predicted Ki: {ki_display}
+
+| | |
+|---|---|
+| **Ki (mM)** | {ki_mm:.4f} |
+| **Ki (µM)** | {ki_um:,.1f} |
+| **log₁₀(Ki / mM)** | {log_ki:+.3f} |
+| **Inhibition mode** | `{inh_used}` |
+| **His-tag prefix** | {his_stripped} |
+| **Ensemble σ across 5 modes** | {sigma} |
+
+> **Model:** {result.get('model_version', 'SugarKi')}
+"""
 
     # Per-mode table
-    mode_table = result.get("mode_predictions_mM", {})
-    table_rows = [(k, f"{v:.3f}", f"{v*1000:,.1f}") for k, v in mode_table.items()]
+    mode_mm = result.get("mode_predictions_mM", {})
+    mode_log = result.get("mode_predictions_log10", {})
+
+    mode_rows = []
+    for mode in ["external", "product", "substrate", "product_or_substrate", "unknown"]:
+        if mode in mode_mm:
+            mm = mode_mm[mode]
+            um = mm * 1000
+            log = mode_log.get(mode, 0)
+            highlight = " ⭐" if mode == inh_used else ""
+            mode_rows.append([
+                f"{mode.replace('_', ' ').title()}{highlight}",
+                f"{log:+.3f}",
+                f"{mm:.3f}",
+                f"{um:,.1f}",
+            ])
+
+    notes = result.get("notes", "")
+    notes_md = f"\n\n**ℹ️ Notes:** _{notes}_\n" if notes else ""
 
-    return summary_md, table_rows, result
+    return summary_md, mode_rows, notes_md, result
 
 
-# -----------------------------------------------------------------------
-# UI
-# -----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+# UI — uses theme-aware colors so text stays readable on any background
+# ----------------------------------------------------------------------
 
-with gr.Blocks(title="SugarKi — Ki prediction for sugar-chemistry enzymes",
-               theme=gr.themes.Soft()) as demo:
+CSS = """
+.title-block {
+    text-align: center;
+    padding: 1em 0;
+    margin-bottom: 0.5em;
+}
+.title-block h1 { margin: 0; font-size: 2.2em; }
+.title-block p { margin: 0.3em 0 0; opacity: 0.75; font-size: 1.05em; }
+.ki-card {
+    border: 1px solid var(--border-color-primary);
+    border-radius: 8px;
+    padding: 1em 1.5em;
+    background: var(--background-fill-secondary);
+}
+"""
+
+with gr.Blocks(title="SugarKi — Ki prediction", theme=gr.themes.Default(), css=CSS) as demo:
+
+    # ----- header -----
     gr.HTML(
         """
-        <div style='text-align:center;margin-bottom:0.5em'>
-          <h1 style='margin-bottom:0'>🧪 SugarKi</h1>
-          <p style='color:#666;margin-top:0'>
-            Sugar-chemistry Ki predictor — family-specialized for polyol DHs,
-            sugar kinases, glycosidases, sugar phosphatases, aldolases,
-            isomerases, and phosphomutases.
+        <div class='title-block'>
+          <h1>🧪 SugarKi</h1>
+          <p>
+            Family-specialized Ki prediction for sugar-chemistry enzymes —
+            polyol DHs, sugar kinases, glycosidases, sugar phosphatases,
+            aldolases, isomerases, phosphomutases.
           </p>
         </div>
         """
     )
 
+    # ----- architecture diagram -----
+    with gr.Accordion("📐 How does SugarKi work?", open=True):
+        gr.Markdown(
+            """
+            SugarKi takes an **enzyme sequence** and an **inhibitor SMILES** and predicts the
+            inhibition constant **Ki** specifically for sugar-chemistry enzymes — where current
+            SOTA models like CatPred fail catastrophically (R² = −0.95 on monosaccharide
+            inhibitors).
+
+            ### Pipeline (~30 seconds end-to-end on ZeroGPU A100)
+
+            ```
+            Enzyme sequence ──► ESMFold ─────────► 3D backbone PDB
+                                                       │
+                                                       ▼
+                                                  P2Rank ──► binding pocket residues
+                                                       │
+            Inhibitor SMILES ──► ChEBIFormer ──┐        │
+            Substrate SMILES ──► ChEBIFormer ──┼──┐     │
+                                                ▼   ▼   ▼
+                                       ┌─────────────────────────┐
+                                       │  ESM-2 + LoRA (rank 16) │
+                                       │  + GVP-GNN structure    │
+                                       │  + pocket-aware pool    │
+                                       │  + mechanism aux head   │
+                                       │   = SugarKi-Specialist  │
+                                       └────────────┬────────────┘
+                                                    ▼
+                                            log₁₀(Ki / mM) → Ki value
+            ```
+
+            **Inputs**
+
+            - `Enzyme sequence` — paste any sugar-family enzyme (His-tag auto-stripped). Best for EC 1.1.1.x, 2.7.1.x, 3.1.3.x, 3.2.1.x, 4.1.2.x, 5.3.1.x, 5.4.2.x.
+            - `Inhibitor SMILES` — SMILES of the small molecule whose Ki you want.
+            - `Inhibition type` — choose `product` for product inhibition (e.g., mannitol on mannitol DH), `substrate` for substrate-mode at high [S], or `auto` for an ensemble across all 5 modes.
+            - `Substrate SMILES` (optional) — native substrate, helps disambiguate product-inhibition cases.
+
+            ### Validation
+
+            - WT MDH-006 (mannitol DH) + D-mannitol → predicted **11.78 mM** in substrate mode vs literature **12 mM** (1.8% error).
+            - Sugar-Ki test set R² = **0.702** vs CatPred 0.243 / SELFprot 0.623.
+            - Typical MAE ≈ 0.6 log units; relative ranking is more reliable than absolute Ki values.
+            """
+        )
+        gr.Image(
+            value="architecture.png",
+            label="SugarKi specialist architecture (Plan E2)",
+            show_label=True,
+            interactive=False,
+            container=True,
+            height=400,
+        )
+
+    # ----- input + output -----
     with gr.Row():
         with gr.Column(scale=3):
             seq_in = gr.Textbox(
@@ -146,6 +246,7 @@ with gr.Blocks(title="SugarKi — Ki prediction for sugar-chemistry enzymes",
                 placeholder="MGSSHHHHHH... or just the catalytic domain (30–1000 aa)",
                 lines=10,
                 value=EXAMPLE_MDH_WT,
+                show_copy_button=True,
             )
             with gr.Row():
                 inh_choice = gr.Dropdown(
@@ -158,7 +259,7 @@ with gr.Blocks(title="SugarKi — Ki prediction for sugar-chemistry enzymes",
                      "product_or_substrate", "unknown"],
                     value="auto",
                     label="Inhibition type",
-                    info="`product` for product inhibition; `substrate` for substrate inhibition at high [S]; `auto` averages all 5",
+                    info="`product` for product inhibition; `substrate` for substrate inhibition at high [S]",
                 )
             inh_custom = gr.Textbox(
                 label="Custom inhibitor SMILES (only used if inhibitor = 'Custom (paste SMILES)')",
@@ -168,60 +269,56 @@ with gr.Blocks(title="SugarKi — Ki prediction for sugar-chemistry enzymes",
                 label="Native substrate SMILES (optional, helps product-inhibition prediction)",
                 value="",
             )
-            btn = gr.Button("Predict Ki", variant="primary", size="lg")
+            btn = gr.Button("🧬 Predict Ki", variant="primary", size="lg")
 
         with gr.Column(scale=2):
-            summary_out = gr.Markdown(label="Result")
+            summary_out = gr.Markdown(elem_classes=["ki-card"])
             mode_table = gr.Dataframe(
-                headers=["Inhibition mode", "Ki (mM)", "Ki (µM)"],
-                label="Per-mode predictions",
+                headers=["Inhibition mode", "log₁₀(Ki/mM)", "Ki (mM)", "Ki (µM)"],
+                label="Per-mode predictions (across 5 inhibition assumptions)",
                 wrap=True,
+                interactive=False,
             )
-            raw_out = gr.JSON(label="Full response", visible=False)
-            show_raw = gr.Checkbox(label="Show raw JSON", value=False)
-            show_raw.change(lambda x: gr.update(visible=x), show_raw, raw_out)
+            notes_out = gr.Markdown()
+            with gr.Accordion("Raw JSON response", open=False):
+                raw_out = gr.JSON()
 
     btn.click(
         predict,
         inputs=[seq_in, inh_choice, inh_custom, inh_type, sub_smiles],
-        outputs=[summary_out, mode_table, raw_out],
+        outputs=[summary_out, mode_table, notes_out, raw_out],
     )
 
     gr.Examples(
         examples=EXAMPLES,
         inputs=[seq_in, inh_choice, inh_type, sub_smiles],
+        label="Example: MDH-006 WT + D-mannitol (substrate-mode)",
     )
 
+    # ----- footer -----
     gr.Markdown(
         """
-        ### About SugarKi
+        ---
 
-        SugarKi is a sugar-chemistry-specialized Ki predictor. Two integrated
-        components: a **specialist** (Plan E2) trained on a curated 5,041-row
-        sugar-Ki benchmark, and a rule-based **router** that dispatches
-        non-sugar queries to CatPred zero-shot.
+        ### How SugarKi compares to existing Ki predictors
 
-        | | Sugar-chemistry Ki | General Ki |
+        | Model | Sugar-chemistry Ki | General Ki |
         |---|---|---|
         | CatPred zero-shot | R² = 0.243 (catastrophic on monosaccharides/polyols) | R² = 0.578 |
         | SELFprot zero-shot | R² = 0.623 | R² = 0.314 |
-        | **SugarKi specialist** | **R² = 0.702** | (route to CatPred) |
-
-        ### Calibration
-
-        On MDH-006 WT (mannitol DH) + D-mannitol — predicted Ki = 11.78 mM in
-        substrate mode vs literature 12 mM (1.8% relative error).
+        | **SugarKi specialist** | **R² = 0.702** | (router falls back to CatPred) |
 
         ### Limitations
 
-        - Test MAE ~0.6 log units; relative ranking more reliable than absolute values
-        - Best on EC families 1.1.1.x / 2.7.1.x / 3.2.1.x / 3.1.3.x / 4.1.2.x / 5.3.1.x / 5.4.2.x
-        - Allosteric inhibition not separately modeled
+        - Test MAE ~0.6 log units; **rankings** more reliable than **absolute** values.
+        - Best on EC families 1.1.1.x / 2.7.1.x / 3.2.1.x / 3.1.3.x / 4.1.2.x / 5.3.1.x / 5.4.2.x.
+        - Allosteric inhibition not separately modeled.
+        - First call cold-starts ~30 s while ESMFold loads; subsequent calls re-use cached structures.
 
         ### Citation
 
-        Paper in preparation. Hosted by [MWBC](https://huggingface.co/MWBC),
-        backed by [Umesh1608/sugarki-backend](https://huggingface.co/spaces/Umesh1608/sugarki-backend).
+        Paper in preparation. Hosted by [MWBC](https://huggingface.co/MWBC), backed by
+        a private SugarKi inference Space ([Umesh1608](https://huggingface.co/Umesh1608)).
         """
     )