update feature

app.py

@@ -9,7 +9,6 @@ Pipeline:
   (4) Tab 2 – Condition Screening: pick one condition to vary, fix the rest → plot
 """
 
-import re
 import sys
 import warnings
 from pathlib import Path
@@ -20,11 +19,23 @@ import matplotlib
 matplotlib.use("Agg")
 import matplotlib.pyplot as plt
 import joblib
-import torch
 import gradio as gr
 import spaces
 from huggingface_hub import snapshot_download
 
+from examples import EXAMPLES, feature_path, find_example_by_seq
+
+# Only surface examples that actually have a pre-computed T5 feature cached
+# in assets/ — an entry added via preprocess/add_example.py but not yet run
+# through preprocess/extract_example_feat.py would otherwise show up in the
+# picker and silently fall back to a slow/GPU extraction on first click.
+AVAILABLE_EXAMPLES = [example for example in EXAMPLES if feature_path(example["id"]).exists()]
+from t5_utils import (
+    T5_REPO_ID,
+    extract_t5_feature as _extract_t5_feature_core,
+    read_feature_h5,
+)
+
 warnings.filterwarnings("ignore")
 
 # ── Paths ─────────────────────────────────────────────────────────────────────
@@ -36,7 +47,6 @@ BASE_DIR = Path(__file__).parent
 # at module import (app startup, plain CPU context) — before any @spaces.GPU
 # call — so extract_t5_feature() never blocks on a network download while
 # holding a ZeroGPU allocation (which has a short time budget).
-T5_REPO_ID = "Rostlab/prot_t5_xl_half_uniref50-enc"
 snapshot_download(T5_REPO_ID)
 
 # ── Physical constants (from preprocess/misc.py) ──────────────────────────────
@@ -69,23 +79,10 @@ SCREEN_LABELS = {
 VALID_AA = set("ACDEFGHIKLMNPQRSTVWY")
 ALLOW_AA = VALID_AA | set("XBJOUZ")
 
-# α-synuclein (used as built-in example)
-EXAMPLE_SEQ = (
-    "MDVFMKGLSKAKEGVVAAAEKTKQGVAEAAGKTKEGVLYVGSKTKEGVVHGVATVAEKTK"
-    "EQVTNVGGAVVTGVTAVAQKTVEGAGSIAAATGFVKKDQLGKNEEGAPQEGILEDMPVDP"
-    "DNEAYEMPSEEGYQDYEPEA"
-)
-
 # ── Lazy-loaded singletons ────────────────────────────────────────────────────
-_t5_tokenizer = None
-_t5_model = None
 _llps_model = None
 
 
-def get_device() -> str:
-    return "cuda" if torch.cuda.is_available() else "cpu"
-
-
 def load_llps_model():
     global _llps_model
     if _llps_model is None:
@@ -103,78 +100,15 @@ def load_llps_model():
     return _llps_model
 
 
-def load_t5():
-    global _t5_tokenizer, _t5_model
-    if _t5_model is None:
-        from transformers import AutoTokenizer, T5EncoderModel
-        import transformers.utils.import_utils as _hf_utils
-
-        # Rostlab/prot_t5_xl_half_uniref50-enc is only available as .bin (no safetensors).
-        # transformers 5.x blocks torch.load on torch < 2.6 due to CVE-2025-32434.
-        # We bypass that gate for this specific trusted checkpoint from the official
-        # HuggingFace Hub.  The check lives in two places — import_utils AND the
-        # locally-imported name in modeling_utils — so both must be patched.
-        import transformers.modeling_utils as _modeling_utils
-
-        _noop = lambda: None
-        _orig_hf   = _hf_utils.check_torch_load_is_safe
-        _orig_mdl  = _modeling_utils.check_torch_load_is_safe
-
-        _hf_utils.check_torch_load_is_safe    = _noop
-        _modeling_utils.check_torch_load_is_safe = _noop
-
-        try:
-            # Already fetched by the module-level snapshot_download() above, so
-            # ZeroGPU calls never hit the network here — a cold download would
-            # blow past the GPU-allocation time budget and get aborted.
-            # local_files_only=True enforces that guarantee.
-            repo_id = T5_REPO_ID
-            dev = get_device()
-            dtype = torch.float16 if dev == "cuda" else torch.float32
-
-            _t5_tokenizer = AutoTokenizer.from_pretrained(
-                repo_id, do_lower_case=False, local_files_only=True
-            )
-            _t5_model = (
-                T5EncoderModel.from_pretrained(
-                    repo_id, torch_dtype=dtype, local_files_only=True
-                )
-                .to(dev)
-                .eval()
-            )
-            _t5_model.requires_grad_(False)
-        finally:
-            _hf_utils.check_torch_load_is_safe    = _orig_hf   # always restore
-            _modeling_utils.check_torch_load_is_safe = _orig_mdl
-
-    return _t5_tokenizer, _t5_model
-
-
 # ── Feature extraction ────────────────────────────────────────────────────────
+# The actual tokenize/forward/mean-pool logic lives in t5_utils.py, shared
+# with preprocess/extract_example_feat.py so the offline-cached example
+# features in assets/ always match what this would compute live. Only the
+# @spaces.GPU wrapping (ZeroGPU allocation) is app-specific, and cb_extract()
+# below skips calling this entirely when a cached feature is available.
 @spaces.GPU
 def extract_t5_feature(sequence: str) -> np.ndarray:
-    """
-    Return mean-pooled ProtT5-XL embedding for a single sequence.
-    Output shape: (1024,)  — matches the feature dimension LLPSense was trained on.
-    """
-    tok, mdl = load_t5()
-    dev = get_device()
-
-    # Replace ambiguous residues with X (same as original pipeline)
-    clean = re.sub(r"[UZOB]", "X", sequence.strip().upper())
-    spaced = " ".join(list(clean))
-
-    enc = tok([spaced], add_special_tokens=True, padding="longest", return_tensors="pt")
-    input_ids    = enc["input_ids"].to(dev)
-    attention_mask = enc["attention_mask"].to(dev)
-
-    with torch.no_grad():
-        hidden = mdl(input_ids=input_ids, attention_mask=attention_mask).last_hidden_state
-        # Mean-pool over sequence positions (ignoring padding tokens)
-        feat = (hidden * attention_mask[..., None]).sum(dim=1) / \
-               attention_mask.sum(dim=1, keepdim=True)
-
-    return feat[0].float().cpu().numpy()  # (1024,)
+    return _extract_t5_feature_core(sequence)
 
 
 # ── Condition vector builder ──────────────────────────────────────────────────
@@ -344,7 +278,14 @@ def cb_extract(sequence: str):
     yield None, _SPINNER_HTML, None, "", None, ""
 
     try:
-        feat = extract_t5_feature(seq)
+        # Known example sequence with a pre-computed feature? Skip the T5
+        # model/GPU call entirely and load it straight from assets/.
+        example = find_example_by_seq(seq)
+        cached_path = feature_path(example["id"]) if example else None
+        if cached_path and cached_path.exists():
+            feat = read_feature_h5(cached_path)
+        else:
+            feat = extract_t5_feature(seq)
         yield feat, _status_ok(len(seq), feat.shape[0]), None, "", None, ""
     except Exception as e:
         yield None, _status_err(str(e)), None, "", None, ""
@@ -509,14 +450,21 @@ with gr.Blocks(
             label="Amino Acid Sequence (1-letter code)",
             placeholder="Paste your protein sequence here (e.g. MDVFMKGLSK…)",
             lines=5,
-            value=EXAMPLE_SEQ,
+            value=AVAILABLE_EXAMPLES[0]["seq"] if AVAILABLE_EXAMPLES else "",
             elem_id="seq-input",
         )
-        gr.Examples(
-            examples=[[EXAMPLE_SEQ]],
-            inputs=[seq_box],
-            label="Example: α-synuclein (SNCA)",
-        )
+        # Clicking an example fills seq_box; the matching Step-2 extraction
+        # is chained onto it further down (once the Step-3 output components
+        # exist) so selecting an example runs extraction automatically.
+        # Skipped entirely if no example has a cached feature yet.
+        example_picker = None
+        if AVAILABLE_EXAMPLES:
+            with gr.Accordion("🧪 Examples  (We provide preprocessed T5 feature)", open=False):
+                example_picker = gr.Examples(
+                    examples=[[example["seq"]] for example in AVAILABLE_EXAMPLES],
+                    example_labels=[example["name"] for example in AVAILABLE_EXAMPLES],
+                    inputs=[seq_box],
+                )
 
     with gr.Group():
         gr.Markdown("## Step 2 — Extract ProtT5 Feature")
@@ -675,6 +623,18 @@ with gr.Blocks(
         outputs=[feat_state, extract_status, pred_plot, pred_text, screen_plot, screen_text],
     )
 
+    # Selecting a built-in example runs extraction automatically (no manual
+    # Step-2 click needed) — cache-hit examples resolve near-instantly since
+    # cb_extract reads their pre-computed feature from assets/ instead of
+    # calling the T5 model. example_picker is None when no example has a
+    # cached feature yet (see AVAILABLE_EXAMPLES above).
+    if example_picker is not None:
+        example_picker.load_input_event.then(
+            fn=cb_extract,
+            inputs=[seq_box],
+            outputs=[feat_state, extract_status, pred_plot, pred_text, screen_plot, screen_text],
+        )
+
     # ── Footer ────────────────────────────────────────────────────────────────
     gr.Markdown("""
 ---

assets/ascl1.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fec1ca3caebb001a1ec821900f7cb57c3b748ea6754b47a264a45cdbf600e88f
+size 6160

assets/atn1.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd29669387a1dae9268a8e75381ad6899f96908c403b16aa409abe3d7262402a
+size 6157

assets/fbll1.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3be5535f596b4ff93013c21cddd8fcef9e3bcdde5391f42bfb26fb670b7d4157
+size 6157

assets/foxp2.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46cd534b6b9fadac71a887ea7ca9b02eb2616c9a89ee9babbfd09aa467288653
+size 6174

assets/semg2.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:330004af079a2bf62cd36951258c0414da4a1e1f5acc9259e31dc520a0b60975
+size 6180

assets/sgta.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:17d0cacc822200a1f62353f97dfe7bc9be6920abf2c99fd1e504f269cb50ae96
+size 6164

assets/ss18.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dabf03dddeb0e3cc6b45564a1978cd2a7d92befaf5f452dfc1dbbf39b1ab500b
+size 6156

assets/synuclein.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fff3a1909b4c47d3ee84fd3e0601c9ca5dd1ce1cfc66df1f0a1066087beec7c5
+size 6149

assets/ubqln4.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4e81867866cb676c5c6cab266a887711cc96227ce7ebbd06258db7fd413d07b2
+size 6151

assets/ubqln_mut10.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6bac2120b88b2f792579f8ac36da89b2d36a40f8677d48689facca9550df5b2e
+size 6144

assets/ubqln_mut20.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:588896444e29efdd1066719561ced11fcdf9d7149632a356051d55775d55b88c
+size 6146

assets/ubqln_mut30.h5

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:229cfa12dc1810d93e96da3058aba885c9efdaa0970cf852e36f088b8d9ab21c
+size 6152

examples.py

@@ -0,0 +1,214 @@
+"""Built-in example sequences for the LLPSense demo.
+
+Shared by app.py (UI + on-the-fly extraction fallback) and
+preprocess/extract_example_feat.py (offline pre-computation), so both stay
+in sync on which sequences have a cached ProtT5 feature under assets/.
+
+To add another example, just append a dict with a unique "id" here, then
+run `python preprocess/extract_example_feat.py` to populate its cached
+feature in assets/ before deploying.
+"""
+
+from pathlib import Path
+
+ASSETS_DIR = Path(__file__).parent / "assets"
+
+EXAMPLES = [
+    {
+        "id": "synuclein",
+        "name": "α-Synuclein",
+        "seq": (
+            "MDVFMKGLSKAKEGVVAAAEKTKQGVAEAAGKTKEGVLYVGSKTKEGVVHGVATVAEKTK"
+            "EQVTNVGGAVVTGVTAVAQKTVEGAGSIAAATGFVKKDQLGKNEEGAPQEGILEDMPVDP"
+            "DNEAYEMPSEEGYQDYEPEA"
+        ),
+    },
+    {
+        "id": "ubqln4",
+        "name": "UBQLN-4",
+        "seq": (
+            "MAEPSGAETRPPIRVTVKTPKDKEEIVICDRASVKEFKEEISRRFKAQQDQLVLIFAGKI"
+            "LKDGDTLNQHGIKDGLTVHLVIKTPQKAQDPAAATASSPSTPDPASAPSTTPASPATPAQ"
+            "PSTSGSASSDAGSGSRRSSGGGPSPGAGEGSPSATASILSGFGGILGLGSLGLGSANFME"
+            "LQQQMQRQLMSNPEMLSQIMENPLVQDMMSNPDLMRHMIMANPQMQQLMERNPEISHMLN"
+            "NPELMRQTMELARNPAMMQEMMRNQDRALSNLESIPGGYNALRRMYTDIQEPMFSAAREQ"
+            "FGNNPFSSLAGNSDSSSSQPLRTENREPLPNPWSPSPPTSQAPGSGGEGTGGSGTSQVHP"
+            "TVSNPFGINAASLGSGMFNSPEMQALLQQISENPQLMQNVISAPYMRSMMQTLAQNPDFA"
+            "AQMMVNVPLFAGNPQLQEQLRLQLPVFLQQMQNPESLSILTNPRAMQALLQIQQGLQTLQ"
+            "TEAPGLVPSLGSFGISRTPAPSAGSNAGSTPEAPTSSPATPATSSPTGASSAQQQLMQQM"
+            "IQLLAGSGNSQVQTPEVRFQQQLEQLNSMGFINREANLQALIATGGDINAAIERLLGSQL"
+            "S"
+        ),
+    },
+    {
+        "id": 'ascl1',
+        "name": 'ASCL1',
+        "seq": (
+            "MESSAKMESGGAGQQPQPQPQQPFLPPAACFFATAAAAAAAAAAAAAQSAQQQQQQQQQQ"
+            "QQAPQLRPAADGQPSGGGHKSAPKQVKRQRSSSPELMRCKRRLNFSGFGYSLPQQQPAAV"
+            "ARRNERERNRVKLVNLGFATLREHVPNGAANKKMSKVETLRSAVEYIRALQQLLDEHDAV"
+            "SAAFQAGVLSPTISPNYSNDLNSMAGSPVSSYSSDEGSYDPLSPEEQELLDFTNWF"
+        ),
+    },
+    {
+        "id": 'atn1',
+        "name": 'ATN1',
+        "seq": (
+            "MKTRQNKDSMSMRSGRKKEAPGPREELRSRGRASPGGVSTSSSDGKAEKSRQTAKKARVE"
+            "EASTPKVNKQGRSEEISESESEETNAPKKTKTEQELPRPQSPSDLDSLDGRSLNDDGSSD"
+            "PRDIDQDNRSTSPSIYSPGSVENDSDSSSGLSQGPARPYHPPPLFPPSPQPPDSTPRQPE"
+            "ASFEPHPSVTPTGYHAPMEPPTSRMFQAPPGAPPPHPQLYPGGTGGVLSGPPMGPKGGGA"
+            "ASSVGGPNGGKQHPPPTTPISVSSSGASGAPPTKPPTTPVGGGNLPSAPPPANFPHVTPN"
+            "LPPPPALRPLNNASASPPGLGAQPLPGHLPSPHAMGQGMGGLPPGPEKGPTLAPSPHSLP"
+            "PASSSAPAPPMRFPYSSSSSSSAAASSSSSSSSSSASPFPASQALPSYPHSFPPPTSLSV"
+            "SNQPPKYTQPSLPSQAVWSQGPPPPPPYGRLLANSNAHPGPFPPSTGAQSTAHPPVSTHH"
+            "HHHQQQQQQQQQQQQQQQQQQQHHGNSGPPPPGAFPHPLEGGSSHHAHPYAMSPSLGSLR"
+            "PYPPGPAHLPPPHSQVSYSQAGPNGPPVSSSSNSSSSTSQGSYPCSHPSPSQGPQGAPYP"
+            "FPPVPTVTTSSATLSTVIATVASSPAGYKTASPPGPPPYGKRAPSPGAYKTATPPGYKPG"
+            "SPPSFRTGTPPGYRGTSPPAGPGTFKPGSPTVGPGPLPPAGPSGLPSLPPPPAAPASGPP"
+            "LSATQIKQEPAEEYETPESPVPPARSPSPPPKVVDVPSHASQSARFNKHLDRGFNSCARS"
+            "DLYFVPLEGSKLAKKRADLVEKVRREAEQRAREEKEREREREREKEREREKERELERSVK"
+            "LAQEGRAPVECPSLGPVPHRPPFEPGSAVATVPPYLGPDTPALRTLSEYARPHVMSPGNR"
+            "NHPFYVPLGAVDPGLLGYNVPALYSSDPAAREREREARERDLRDRLKPGFEVKPSELEPL"
+            "HGVPGPGLDPFPRHGGLALQPGPPGLHPFPFHPSLGPLERERLALAAGPALRPDMSYAER"
+            "LAAERQHAERVAALGNDPLARLQMLNVTPHHHQHSHIHSHLHLHQQDAIHAASASVHPLI"
+            "DPLASGSHLTRIPYPAGTLPNPLLPHPLHENEVLRHQLFAAPYRDLPASLSAPMSAAHQL"
+            "QAMHAQSAELQRLALEQQQWLHAHHPLHSVPLPAQEDYYSHLKKESDKPL"
+        ),
+    },
+    {
+        "id": 'fbll1',
+        "name": 'FBLL1',
+        "seq": (
+            "MKSAASSRGGGGGGRGGGGWGSWGGGRGGGGGAGKGGGGDGGGQGGKGGFGARARGFGGG"
+            "GRGRGRGGGDGKDRGGGGQRRGGVAKSKSRRRKGAMVVSVEPHRHEGVFIYRGAEDALVT"
+            "LNMVPGQSVYGERRVTVTEGGVKQEYRTWNPFRSKLAAAILGGVDQIHIKPKSKVLYLGA"
+            "ASGTTVSHVSDIIGPDGLVYAVEFSHRAGRDLVNVAKKRTNIIPVLEDARHPLKYRMLIG"
+            "MVDVIFADVAQPDQSRIVALNAHTFLRNGGHFLISIKANCIDSTASAEAVFASEVRKLQQ"
+            "ENLKPQEQLTLEPYERDHAVVVGVYRPLPKSSSK"
+        ),
+    },
+    {
+        "id": 'foxp2',
+        "name": 'FOXP2',
+        "seq": (
+            "MMQESATETISNSSMNQNGMSTLSSQLDAGSRDGRSSGDTSSEVSTVELLHLQQQQALQA"
+            "ARQLLLQQQTSGLKSPKSSDKQRPLQVPVSVAMMTPQVITPQQMQQILQQQVLSPQQLQA"
+            "LLQQQQAVMLQQQQLQEFYKKQQEQLHLQLLQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ"
+            "QQQQQQQQQQQHPGKQAKEQQQQQQQQQQLAAQQLVFQQQLLQMQQLQQQQHLLSLQRQG"
+            "LISIPPGQAALPVQSLPQAGLSPAEIQQLWKEVTGVHSMEDNGIKHGGLDLTTNNSSSTT"
+            "SSNTSKASPPITHHSIVNGQSSVLSARRDSSSHEETGASHTLYGHGVCKWPGCESICEDF"
+            "GQFLKHLNNEHALDDRSTAQCRVQMQVVQQLEIQLSKERERLQAMMTHLHMRPSEPKPSP"
+            "KPLNLVSSVTMSKNMLETSPQSLPQTPTTPTAPVTPITQGPSVITPASVPNVGAIRRRHS"
+            "DKYNIPMSSEIAPNYEFYKNADVRPPFTYATLIRQAIMESSDRQLTLNEIYSWFTRTFAY"
+            "FRRNAATWKNAVRHNLSLHKCFVRVENVKGAVWTVDEVEYQKRRSQKITGSPTLVKNIPT"
+            "SLGYGAALNASLQAALAESSLPLLSNPGLINNASSGLLQAVHEDLNGSLDHIDSNGNSSP"
+            "GCSPQPHIHSIHVKEEPVIAEDEDCPMSLVTTANHSPELEDDREIEEEPLSEDLE"
+        ),
+    },
+    {
+        "id": 'semg2',
+        "name": 'SEMG2',
+        "seq": (
+            "MKSIILFVLSLLLILEKQAAVMGQKGGSKGQLPSGSSQFPHGQKGQHYFGQKDQQHTKSK"
+            "GSFSIQHTYHVDINDHDWTRKSQQYDLNALHKATKSKQHLGGSQQLLNYKQEGRDHDKSK"
+            "GHFHMIVIHHKGGQAHHGTQNPSQDQGNSPSGKGLSSQCSNTEKRLWVHGLSKEQASASG"
+            "AQKGRTQGGSQSSYVLQTEELVVNKQQRETKNSHQNKGHYQNVVDVREEHSSKLQTSLHP"
+            "AHQDRLQHGPKDIFTTQDELLVYNKNQHQTKNLSQDQEHGRKAHKISYPSSRTEERQLHH"
+            "GEKSVQKDVSKGSISIQTEEKIHGKSQNQVTIHSQDQEHGHKENKISYQSSSTEERHLNC"
+            "GEKGIQKGVSKGSISIQTEEQIHGKSQNQVRIPSQAQEYGHKENKISYQSSSTEERRLNS"
+            "GEKDVQKGVSKGSISIQTEEKIHGKSQNQVTIPSQDQEHGHKENKMSYQSSSTEERRLNY"
+            "GGKSTQKDVSQSSISFQIEKLVEGKSQIQTPNPNQDQWSGQNAKGKSGQSADSKQDLLSH"
+            "EQKGRYKQESSESHNIVITEHEVAQDDHLTQQYNEDRNPIST"
+        ),
+    },
+    {
+        "id": 'sgta',
+        "name": 'SGTA',
+        "seq": (
+            "MDNKKRLAYAIIQFLHDQLRHGGLSSDAQESLEVAIQCLETAFGVTVEDSDLALPQTLPE"
+            "IFEAAATGKEMPQDLRSPARTPPSEEDSAEAERLKTEGNEQMKVENFEAAVHFYGKAIEL"
+            "NPANAVYFCNRAAAYSKLGNYAGAVQDCERAICIDPAYSKAYGRMGLALSSLNKHVEAVA"
+            "YYKKALELDPDNETYKSNLKIAELKLREAPSPTGGVGSFDIAGLLNNPGFMSMASNLMNN"
+            "PQIQQLMSGMISGGNNPLGTPGTSPSQNDLASLIQAGQQFAQQMQQQNPELIEQLRSQIR"
+            "SRTPSASNDDQQE"
+        ),
+    },
+    {
+        "id": 'ss18',
+        "name": 'SS18',
+        "seq": (
+            "MSVAFAAPRQRGKGEITPAAIQKMLDDNNHLIQCIMDSQNKGKTSECSQYQQMLHTNLVY"
+            "LATIADSNQNMQSLLPAPPTQNMPMGPGGMNQSGPPPPPRSHNMPSDGMVGGGPPAPHMQ"
+            "NQMNGQMPGPNHMPMQGPGPNQLNMTNSSMNMPSSSHGSMGGYNHSVPSSQSMPVQNQMT"
+            "MSQGQPMGNYGPRPNMSMQPNQGPMMHQQPPSQQYNMPQGGGQHYQGQQPPMGMMGQVNQ"
+            "GNHMMGQRQIPPYRPPQQGPPQQYSGQEDYYGDQYSHGGQGPPEGMNQQYYPDGHNDYGY"
+            "QQPSYPEQGYDRPYEDSSQHYYEGGNSQYGQQQDAYQGPPPQQGYPPQQQQYPGQQGYPG"
+            "QQQGYGPSQGGPGPQYPNYPQGQGQQYGGYRPTQPGPPQPPQQRPYGYDQGQYGNYQQ"
+        ),
+    },
+    {
+        "id": 'ubqln_mut10',
+        "name": 'UBQLN_mut10',
+        "seq": (
+            "MAEPSGAETRPPIRVTVKTPKDKEEIVICDRASVKEFKEEISRRFKAQQDQLVLIFAGKI"
+            "LKDGDTLNQHGIKDGLTVHLVIKTPQKAQDPAAATASSPSTPDPASAPSTTPASPATPAQ"
+            "PSTSGSASSDAGSGSRRSSGGGPSPGAGEGSPSATASILSGFGGILGLGSLGLGSANFME"
+            "LQQQMQRQLMSNPEMLSQICENPLVQDMMSNPDLMRHCCMANPQYQQLCERNPEISHMLN"
+            "NPELMRQTMELARNPAMMQEMMRNQDRALSNCESIPGGYNALRRMYTDIQEPMFSAAREQ"
+            "FGNNPFSSLAGNSDSSSSQPLRTENREPLPNPWSPSPPTSQAPGSGGEGTGGSGTSQVHP"
+            "TVSNPFGINAASLGSGMCNSPEMQALLQQISENCQLMQNVISAPYMRSMMQTLAQNPDFA"
+            "AQMMVNVPLFAGNPQLQEQLRLQLPVFLQQCQNPESLSILTNPRAMQALLQIQQGLQTLQ"
+            "TEAPGLVPSLGSFGISRTPAPSAGSNAGSTPEAPTSSPATPATSSPTGASSAQQQLMQQM"
+            "IQLLAGSGNSQVQTPEVRFQQQLEQLNSCGFINREANLQALIATGGDINAAIERLLGSQL"
+            "S"
+        ),
+    },
+    {
+        "id": 'ubqln_mut20',
+        "name": 'UBQLN_mut20',
+        "seq": (
+            "MAEPSGAETNPNIRVTVKTPKDKEEIVICDIASVKEFKEEISRRFKAQQDQLVLIFAGKD"
+            "LKDGDTLNQHGIKDGETYHLVIKTPQKAQDPAAATASSPSTPDPASAPSTTPASPATPAQ"
+            "PSTSGSASSDAGSGSRRSSGGGPSPGAGEGSPSATASILSGFGGILGLGSLGLGSANFME"
+            "LQQQMQRQLMSNPEMLSQICENPLVQDMMSNPDLMRHCCMANPQYQQLCERNPEISHMLN"
+            "NPELMRQTMELARNPAMMQEMMRNQDRALSNCESIPGGYNALRRMYTDIQEPMFSAAREQ"
+            "FGNNPDSSLAGNSDSSSSQPLRTENREPLPNPWSPSPPTSQAPGSGGEGTGGSGTSQVHP"
+            "TVSNPFGINAASLGSGMCNSPEMQALLQQISENCQLMQNVISAPKMRSMMQTLAQNPDFA"
+            "AQMMVNVPLFAGNPQLQEQLRLQLPVFLQQCQNPESLSIDTNPRAMQALLQIQQGLQTLQ"
+            "TEAPGLVPSLGSFGISRTPAPSAGSNAGSTPEAPTSSPATPATSSPTGASSAQQQLKQQM"
+            "IQLLAGSGNSQVQTPEVRFQQQLEQLNSCGFINREANLQALIATGGDINAAIERLLGSQL"
+            "S"
+        ),
+    },
+    {
+        "id": 'ubqln_mut30',
+        "name": 'UBQLN_mut30',
+        "seq": (
+            "MAEPSGAETNPNIRVTVKTPKDKEEIVICDIASVKEFKEEISRRFKAQQDQLVLIFAGKD"
+            "DKDGDTDNQHGIKDGETYHLVIKTPQKAQDPAAATASSPSTPDPASAPSTTPASPATPAQ"
+            "PSTSGSASSDAGSGSRRSSGGGPSPGAGEGSPSATASILSGFGGILGLGSLGLGSANFME"
+            "LQQQMQRQLMSNPEMLSQPCENLLVQDMMSNPDLMRHCCMANPQYQQLCERNPEISHMLN"
+            "NPELMRQPMELARNPAMMQEMMRNQDRALSNCESIPGGYNADRRDYTDIQEPMFSAAREQ"
+            "FGNNPDSSLAGNSDSSSSQPLRTENREPLPNPWSPSPPTSQAPGSGGEGTGGSGTSQVHP"
+            "TVSNPFGINAASLGSGMCNSPEMQALLQQISENCQLMQNVISAPKMRSMMQTLAQNPDFA"
+            "AQMMVNVPLFAGNPQLQEQLRLQLPVFLQQCQNPESLSIDTNPRAMQALLQIQQGLQTLQ"
+            "TEAPGLVPSLGSFGISRTPAPSAGSNAGSTPEAPTSSPATPATSSPTGASSAQQQLKQQM"
+            "IQLLAGSGNSQVQTPEVRFQQQLEQLNSCGPINREANLQALPATGGDINADIERLLGSQL"
+            "S"
+        ),
+    },
+]
+
+
+def feature_path(example_id: str) -> Path:
+    return ASSETS_DIR / f"{example_id}.h5"
+
+
+def find_example_by_seq(seq: str):
+    """Return the EXAMPLES entry whose sequence matches `seq`, or None."""
+    norm = seq.strip().upper()
+    for example in EXAMPLES:
+        if example["seq"].strip().upper() == norm:
+            return example
+    return None

preprocess/add_example.py

@@ -0,0 +1,173 @@
+"""Add example sequence(s) to examples.py from a raw-data Excel file.
+
+The training-data Excel files (e.g. LLPSense/data/raw/nonPSPex/ASCL1.xlsx)
+carry a "Protein name" column and a sequence column (spelled either
+"Sequence" or "Seqence" across files) alongside condition columns this demo
+doesn't need. Some files hold one protein across several condition rows
+(e.g. ASCL1.xlsx); others hold several distinct proteins, one per row, each
+with its own name/sequence (e.g. UBQLN4_mut.xlsx's UBQLN_mut10/20/30). This
+script groups rows by protein name and appends one EXAMPLES entry per
+distinct (name, sequence) pair found in the file.
+
+Requires pandas + openpyxl (not part of requirements.txt — those are only
+needed to run this offline script, not the deployed app):
+    pip install pandas openpyxl
+
+Usage:
+    python preprocess/add_example.py /path/to/ASCL1.xlsx
+    python preprocess/add_example.py /path/to/ASCL1.xlsx --id ascl1 --name "ASCL1"
+    python preprocess/add_example.py /path/to/UBQLN4_mut.xlsx   # adds all 3 mutants
+
+--id/--name only apply when the file contains a single protein.
+
+After adding, run preprocess/extract_example_feat.py to cache the T5 feature(s).
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from examples import EXAMPLES  # noqa: E402
+
+EXAMPLES_FILE = Path(__file__).resolve().parent.parent / "examples.py"
+VALID_AA = set("ACDEFGHIKLMNPQRSTVWY")
+ALLOW_AA = VALID_AA | set("XBJOUZ")
+
+
+def _find_col(df, *keywords):
+    for col in df.columns:
+        low = col.lower()
+        if all(keyword in low for keyword in keywords):
+            return col
+    return None
+
+
+def slugify(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "_", name.strip().lower()).strip("_")
+    if not slug:
+        raise ValueError(f"Could not derive an id from name: {name!r}")
+    return slug
+
+
+def read_proteins(xlsx_path: Path) -> list[tuple[str, str]]:
+    """Return one (name, sequence) pair per distinct protein in the file.
+
+    Rows are grouped by protein name — a file may repeat the same protein
+    across several condition rows (ASCL1.xlsx: 1 protein, several conditions)
+    or list several distinct proteins one per row (UBQLN4_mut.xlsx: 3
+    mutants). Either shape yields one entry per unique protein name here.
+    """
+    df = pd.read_excel(xlsx_path, engine="openpyxl")
+
+    name_col = _find_col(df, "protein", "name")
+    seq_col = _find_col(df, "seq")
+    if name_col is None or seq_col is None:
+        raise ValueError(
+            f"{xlsx_path} is missing a protein-name or sequence column "
+            f"(found columns: {df.columns.tolist()})"
+        )
+
+    df = df[[name_col, seq_col]].dropna()
+    if df.empty:
+        raise ValueError(f"{xlsx_path} has no rows with both a name and a sequence")
+
+    proteins = []
+    for name, group in df.groupby(name_col, sort=False):
+        seqs = group[seq_col].astype(str).str.strip().str.upper().unique()
+        if len(seqs) != 1:
+            raise ValueError(
+                f"Protein '{name}' in {xlsx_path} has {len(seqs)} distinct "
+                f"sequences across its rows — expected exactly one"
+            )
+        proteins.append((str(name).strip(), seqs[0]))
+    return proteins
+
+
+def format_seq_literal(seq: str, width: int = 60) -> str:
+    lines = [seq[i:i + width] for i in range(0, len(seq), width)]
+    body = "\n".join(f'            "{line}"' for line in lines)
+    return f"(\n{body}\n        )"
+
+
+def append_example(entry: dict) -> None:
+    text = EXAMPLES_FILE.read_text()
+    match = re.search(r"(EXAMPLES\s*=\s*\[)(.*?)(\n\])", text, flags=re.DOTALL)
+    if not match:
+        raise RuntimeError(f"Could not find EXAMPLES list in {EXAMPLES_FILE}")
+
+    # The existing last entry may or may not have a trailing comma (both
+    # forms occur in practice) — normalize to one before appending.
+    body = match.group(2).rstrip()
+    if body and not body.endswith(","):
+        body += ","
+
+    new_block = (
+        "\n    {\n"
+        f'        "id": {entry["id"]!r},\n'
+        f'        "name": {entry["name"]!r},\n'
+        f'        "seq": {format_seq_literal(entry["seq"])},\n'
+        "    },"
+    )
+    updated = text[:match.start(2)] + body + new_block + text[match.end(2):]
+    EXAMPLES_FILE.write_text(updated)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("xlsx_path", type=Path)
+    parser.add_argument(
+        "--id", type=str, default=None,
+        help="override the generated example id (only valid for single-protein files)",
+    )
+    parser.add_argument(
+        "--name", type=str, default=None,
+        help="override the display name (only valid for single-protein files)",
+    )
+    args = parser.parse_args()
+
+    proteins = read_proteins(args.xlsx_path)
+
+    if (args.id or args.name) and len(proteins) > 1:
+        parser.error(
+            f"{args.xlsx_path} contains {len(proteins)} distinct proteins — "
+            "--id/--name can only be used with a single-protein file"
+        )
+
+    # Track ids seen so far in this run too, so two proteins in the same
+    # file that happen to slugify to the same id are still caught.
+    known_ids = {example["id"] for example in EXAMPLES}
+    added = 0
+
+    for name, seq in proteins:
+        example_id = args.id or slugify(name)
+        display_name = args.name or name
+
+        invalid = set(seq) - ALLOW_AA
+        if invalid:
+            print(
+                f"Warning: '{name}' sequence contains unexpected characters: "
+                f"{''.join(sorted(invalid))}",
+                file=sys.stderr,
+            )
+
+        if example_id in known_ids:
+            print(f"'{example_id}' already exists in EXAMPLES — skipping.")
+            continue
+
+        append_example({"id": example_id, "name": display_name, "seq": seq})
+        known_ids.add(example_id)
+        added += 1
+        print(f"Added '{example_id}' ({display_name}, {len(seq)} aa) to {EXAMPLES_FILE}")
+
+    if added:
+        print("Run `python preprocess/extract_example_feat.py` to cache the T5 feature(s).")
+    else:
+        print("No new examples added.")
+
+
+if __name__ == "__main__":
+    main()

preprocess/extract_example_feat.py

@@ -0,0 +1,38 @@
+"""Pre-extract ProtT5-XL features for the built-in example sequences.
+
+Mirrors the offline pre-computation step in the training pipeline
+(LLPSense/preprocess/extract_feat.py): run this once so the Gradio app never
+has to hit the T5 model / GPU for a sequence it already knows about (see
+`examples.find_example_by_seq` and `cb_extract` in app.py). This matters
+most on the ZeroGPU-backed Space, where every GPU call consumes quota.
+
+Usage:
+    python preprocess/extract_example_feat.py
+"""
+
+import sys
+from pathlib import Path
+
+from huggingface_hub import snapshot_download
+from tqdm import tqdm
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from examples import EXAMPLES, feature_path, ASSETS_DIR  # noqa: E402
+from t5_utils import T5_REPO_ID, extract_t5_feature, write_feature_h5  # noqa: E402
+
+
+def main():
+    snapshot_download(T5_REPO_ID)
+    ASSETS_DIR.mkdir(parents=True, exist_ok=True)
+
+    for example in tqdm(EXAMPLES, desc="Extracting example T5 features"):
+        out_path = feature_path(example["id"])
+        if out_path.exists():
+            continue
+        feat = extract_t5_feature(example["seq"])
+        write_feature_h5(out_path, feat)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -8,6 +8,7 @@ sentencepiece          # ProtT5 tokenizer backend
 xgboost==2.0.3
 scikit-learn
 joblib
+h5py             # cached example T5 features in assets/
 
 # Gradio demo
 gradio>=4.0.0

t5_utils.py

@@ -0,0 +1,108 @@
+"""Shared ProtT5-XL loading / feature-extraction / h5 I/O helpers.
+
+Used by both app.py (Gradio callbacks, wrapped in @spaces.GPU) and
+preprocess/extract_example_feat.py (offline pre-computation of the built-in
+example sequences' features into assets/). Keeping this logic in one place
+means the cached features in assets/ are guaranteed to match what the app
+would compute on the fly.
+"""
+
+import re
+from pathlib import Path
+
+import h5py
+import numpy as np
+import torch
+
+T5_REPO_ID = "Rostlab/prot_t5_xl_half_uniref50-enc"
+
+_t5_tokenizer = None
+_t5_model = None
+
+
+def get_device() -> str:
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def load_t5():
+    global _t5_tokenizer, _t5_model
+    if _t5_model is None:
+        from transformers import AutoTokenizer, T5EncoderModel
+        import transformers.utils.import_utils as _hf_utils
+        import transformers.modeling_utils as _modeling_utils
+
+        # Rostlab/prot_t5_xl_half_uniref50-enc is only available as .bin (no
+        # safetensors). transformers 5.x blocks torch.load on torch < 2.6 due
+        # to CVE-2025-32434. We bypass that gate for this specific trusted
+        # checkpoint from the official HuggingFace Hub. The check lives in
+        # two places — import_utils AND the locally-imported name in
+        # modeling_utils — so both must be patched.
+        _noop = lambda: None
+        _orig_hf = _hf_utils.check_torch_load_is_safe
+        _orig_mdl = _modeling_utils.check_torch_load_is_safe
+
+        _hf_utils.check_torch_load_is_safe = _noop
+        _modeling_utils.check_torch_load_is_safe = _noop
+
+        try:
+            repo_id = T5_REPO_ID
+            dev = get_device()
+            dtype = torch.float16 if dev == "cuda" else torch.float32
+
+            _t5_tokenizer = AutoTokenizer.from_pretrained(
+                repo_id, do_lower_case=False, local_files_only=True
+            )
+            _t5_model = (
+                T5EncoderModel.from_pretrained(
+                    repo_id, torch_dtype=dtype, local_files_only=True
+                )
+                .to(dev)
+                .eval()
+            )
+            _t5_model.requires_grad_(False)
+        finally:
+            _hf_utils.check_torch_load_is_safe = _orig_hf
+            _modeling_utils.check_torch_load_is_safe = _orig_mdl
+
+    return _t5_tokenizer, _t5_model
+
+
+def extract_t5_feature(sequence: str) -> np.ndarray:
+    """
+    Return mean-pooled ProtT5-XL embedding for a single sequence.
+    Output shape: (1024,) — matches the feature dimension LLPSense was trained on.
+    """
+    tok, mdl = load_t5()
+    dev = get_device()
+
+    # Replace ambiguous residues with X (same as original pipeline)
+    clean = re.sub(r"[UZOB]", "X", sequence.strip().upper())
+    spaced = " ".join(list(clean))
+
+    enc = tok([spaced], add_special_tokens=True, padding="longest", return_tensors="pt")
+    input_ids = enc["input_ids"].to(dev)
+    attention_mask = enc["attention_mask"].to(dev)
+
+    with torch.no_grad():
+        hidden = mdl(input_ids=input_ids, attention_mask=attention_mask).last_hidden_state
+        # Mean-pool over sequence positions (ignoring padding tokens)
+        feat = (hidden * attention_mask[..., None]).sum(dim=1) / \
+               attention_mask.sum(dim=1, keepdim=True)
+
+    return feat[0].float().cpu().numpy()  # (1024,)
+
+
+# ── h5 cache I/O ──────────────────────────────────────────────────────────────
+FEATURE_TAG = "protein_feat"
+
+
+def write_feature_h5(filepath, feat: np.ndarray, tag: str = FEATURE_TAG) -> None:
+    filepath = Path(filepath)
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    with h5py.File(filepath, "w") as f:
+        f.create_dataset(tag, data=feat, dtype="f", compression="gzip")
+
+
+def read_feature_h5(filepath, tag: str = FEATURE_TAG) -> np.ndarray:
+    with h5py.File(filepath, "r") as f:
+        return f[tag][:]