quantppi / app.py
trizzhal9000's picture
Deploy QuantPPI Studio real-data 3D platform & API
fec35c4 verified
Raw History Blame Contribute Delete
53.7 kB
#!/usr/bin/env python3 """ QuantPPI — Hugging Face ZeroGPU Gradio Space + Cloud FastAPI Backend Entrypoint. Supports all 10 Protein Language Models from QuantPPI.ipynb: - ESM-2: 8M (D=320), 35M (D=480), 150M (D=640), 650M (D=1280), 3B (D=2560), 15B (D=5120) - ESM-C: 300M (D=960), 600M (D=1152), 6B (D=2560) - ESM-3: 1.4B (D=1536) Architecture: 1. `spaces` is imported prior to any `torch` import as required by Hugging Face ZeroGPU. 2. Precomputed corpus embeddings (.h5) for all 10 PLMs stream on-demand from `HF_DATASET_REPO` (`trizzhal9000/quantppi-embeddings`). 3. Custom raw FASTA queries execute via EvolutionaryScale Forge API (`ESM_FORGE_TOKEN`) for ESM-C / ESM-3 and `@spaces.GPU` (Nvidia H200 / A10G ZeroGPU) for ESM-2 8M–15B. 4. Launches via `demo.launch(...)` so ZeroGPU's worker daemon initializes natively while exposing `/api/*`, `/figures/*`, and `/studio` with CORS enabled for Vercel production. """ import collections.abc import gc import json import os import re import struct import sys import threading from pathlib import Path from typing import Any, Dict, List, Optional # ZeroGPU requirement: import `spaces` before anything that could import `torch` try: import spaces except ImportError: spaces = None os.environ.setdefault("MPLCONFIGDIR", "/tmp") os.environ.setdefault("HF_DATASET_REPO", "trizzhal9000/quantppi-embeddings") REPO_ROOT = Path(__file__).resolve().parent EXPLAINER_DIR = REPO_ROOT / "explainer" if str(REPO_ROOT) not in sys.path: sys.path.insert(0, str(REPO_ROOT)) if str(EXPLAINER_DIR) not in sys.path: sys.path.insert(0, str(EXPLAINER_DIR)) import numpy as np import pandas as pd import server as qserver from src.evaluators.umap_projection import ( compute_umap_projection, quantize_coords_int16, _safe_l2_normalize, ) def _gpu_decorator(fn): if spaces is not None and hasattr(spaces, "GPU"): return spaces.GPU(duration=180)(fn) return fn ESM2_HF_REPOS: Dict[str, str] = { "esm2_8m": "facebook/esm2_t6_8M_UR50D", "esm2_35m": "facebook/esm2_t12_35M_UR50D", "esm2_150m": "facebook/esm2_t30_150M_UR50D", "esm2_650m": "facebook/esm2_t33_650M_UR50D", "esm2_3b": "facebook/esm2_t36_3B_UR50D", "esm2_15b": "facebook/esm2_t48_15B_UR50D", } FORGE_MODEL_CANDIDATES: Dict[str, List[str]] = { "esmc_300m": ["esmc-300m-2024-12", "esmc_300m"], "esmc_600m": ["esmc-600m-2024-12", "esmc_600m"], "esmc_6b": ["esmc-6b-2024-12", "esmc_6b"], "esm3_1.4b": ["esm3-open-2024-03", "esm3-sm-open-v1", "esm3-medium-2024-08"], } _CPU_SMALL_MODEL_CACHE: Dict[str, Any] = {} def _extract_via_forge_api(clean_seq: str, model_scale: str) -> Optional[List[float]]: """Extracts ESM-C (300M, 600M, 6B) and ESM-3 (1.4B) embeddings via EvolutionaryScale Forge API.""" forge_token = (os.environ.get("ESM_FORGE_TOKEN") or "").strip() if not forge_token or model_scale not in FORGE_MODEL_CANDIDATES: return None try: from esm.sdk import client as esm_forge_client from esm.sdk.api import ESMProtein, LogitsConfig s_trunc = clean_seq[:1022] for model_name in FORGE_MODEL_CANDIDATES[model_scale]: try: forge_client = esm_forge_client( model=model_name, url="https://forge.evolutionaryscale.ai", token=forge_token, ) protein_tensor = forge_client.encode(ESMProtein(sequence=s_trunc)) res = forge_client.logits( protein_tensor, LogitsConfig(sequence=True, return_embeddings=True), ) emb_t = res.embeddings if hasattr(emb_t, "detach"): arr = emb_t.detach().float().cpu().numpy() else: arr = np.asarray(emb_t, dtype=np.float32) tok_slice = arr[0, 1 : 1 + len(s_trunc), :] if arr.ndim == 3 else arr[1 : 1 + len(s_trunc), :] vec = tok_slice.astype(np.float32).mean(axis=0) nrm = float(np.linalg.norm(vec)) if nrm > 1e-12: vec /= nrm return vec.tolist() except Exception as inner_exc: print(f"[QuantPPI Forge] Model {model_name} attempt notice: {inner_exc}") continue except Exception as exc: print(f"[QuantPPI Forge] SDK notice: {exc}") return None @_gpu_decorator def zerogpu_extract_sequence_embedding(clean_seq: str, model_scale: str) -> List[float]: """Runs PLM forward pass on Hugging Face ZeroGPU (Nvidia H200 / A10G) and returns unit-L2 vector.""" import torch s_trunc = clean_seq[:1022] device = "cuda" if torch.cuda.is_available() else "cpu" hf_token = (os.environ.get("HF_TOKEN") or "").strip() or None if model_scale in ESM2_HF_REPOS: from transformers import AutoTokenizer, EsmModel hf_id = ESM2_HF_REPOS[model_scale] use_bf16 = device == "cuda" and model_scale in ("esm2_3b", "esm2_15b") dtype = torch.bfloat16 if use_bf16 else torch.float32 tokenizer = AutoTokenizer.from_pretrained(hf_id, token=hf_token) model = EsmModel.from_pretrained( hf_id, add_pooling_layer=False, torch_dtype=dtype, token=hf_token, ).to(device).eval() try: with torch.inference_mode(): toks = tokenizer([s_trunc], return_tensors="pt", truncation=True, max_length=1024).to(device) if use_bf16: with torch.autocast(device_type="cuda", dtype=torch.bfloat16): hidden = model(**toks).last_hidden_state else: hidden = model(**toks).last_hidden_state vec = hidden[0, 1 : 1 + len(s_trunc), :].to(torch.float32).mean(dim=0) vec = torch.nn.functional.normalize(vec, p=2, dim=0) return vec.cpu().numpy().tolist() finally: del model gc.collect() if torch.cuda.is_available(): torch.cuda.empty_cache() if model_scale in ("esmc_300m", "esmc_600m", "esmc_6b"): try: from esm.models.esmc import ESMC from esm.sdk.api import ESMProtein, LogitsConfig client = ESMC.from_pretrained(model_scale).to(device) client = (client.to(torch.bfloat16) if (device == "cuda" and model_scale == "esmc_6b") else client.float()).eval() try: with torch.inference_mode(): pt = client.encode(ESMProtein(sequence=s_trunc)) out = client.logits(pt, LogitsConfig(sequence=True, return_embeddings=True)) emb_t = out.embeddings tok_slice = emb_t[0, 1 : 1 + len(s_trunc), :].float() if emb_t.ndim == 3 else emb_t[1 : 1 + len(s_trunc), :].float() vec = torch.nn.functional.normalize(tok_slice.mean(dim=0), p=2, dim=0) return vec.cpu().numpy().tolist() finally: del client gc.collect() if torch.cuda.is_available(): torch.cuda.empty_cache() except Exception: if model_scale in ("esmc_300m", "esmc_600m"): from transformers import AutoModel, AutoTokenizer hf_repo = "Synthyra/ESMplusplus_small" if model_scale == "esmc_300m" else "Synthyra/ESMplusplus_large" tok = AutoTokenizer.from_pretrained(hf_repo, trust_remote_code=True, token=hf_token) mod = AutoModel.from_pretrained(hf_repo, trust_remote_code=True, torch_dtype=torch.float32, token=hf_token).to(device).eval() try: with torch.inference_mode(): enc = tok(s_trunc, return_tensors="pt", truncation=True, max_length=1024).to(device) outs = mod(**enc, output_hidden_states=True) hid = outs.last_hidden_state if getattr(outs, "last_hidden_state", None) is not None else outs.hidden_states[-1] vec = torch.nn.functional.normalize(hid[0, 1 : 1 + len(s_trunc), :].float().mean(dim=0), p=2, dim=0) return vec.cpu().numpy().tolist() finally: del mod gc.collect() if torch.cuda.is_available(): torch.cuda.empty_cache() raise if model_scale == "esm3_1.4b": if hf_token: os.environ.setdefault("HF_TOKEN", hf_token) from esm.models.esm3 import ESM3 from esm.sdk.api import ESMProtein, LogitsConfig client = None for cand in ("esm3_sm_open_v1", "esm3-sm-open-v1"): try: client = ESM3.from_pretrained(cand).to(device) break except Exception: continue if client is None: raise RuntimeError("Could not load ESM-3 1.4B weights.") client = (client.to(torch.bfloat16) if device == "cuda" else client.float()).eval() try: with torch.inference_mode(): pt = client.encode(ESMProtein(sequence=s_trunc)) out = client.logits(pt, LogitsConfig(sequence=True, return_embeddings=True)) emb_t = out.embeddings tok_slice = emb_t[0, 1 : 1 + len(s_trunc), :].float() if emb_t.ndim == 3 else emb_t[1 : 1 + len(s_trunc), :].float() vec = torch.nn.functional.normalize(tok_slice.mean(dim=0), p=2, dim=0) return vec.cpu().numpy().tolist() finally: del client gc.collect() if torch.cuda.is_available(): torch.cuda.empty_cache() raise ValueError(f"Unsupported model_scale for ZeroGPU FASTA inference: {model_scale}") def _cpu_stateless_fallback(clean_seq: str, model_scale: str) -> Optional[List[float]]: """Stateless CPU fallback on HF Space host RAM for small/medium checkpoints when called via external REST.""" import torch s_trunc = clean_seq[:1022] hf_token = (os.environ.get("HF_TOKEN") or "").strip() or None if model_scale in ("esm2_8m", "esm2_35m", "esm2_150m", "esm2_650m"): from transformers import AutoTokenizer, EsmModel hf_id = ESM2_HF_REPOS[model_scale] if hf_id not in _CPU_SMALL_MODEL_CACHE: if len(_CPU_SMALL_MODEL_CACHE) >= 2: _CPU_SMALL_MODEL_CACHE.pop(next(iter(_CPU_SMALL_MODEL_CACHE.keys())), None) tok = AutoTokenizer.from_pretrained(hf_id, token=hf_token) mod = EsmModel.from_pretrained(hf_id, add_pooling_layer=False, torch_dtype=torch.float32, token=hf_token).eval() _CPU_SMALL_MODEL_CACHE[hf_id] = (tok, mod) tok, mod = _CPU_SMALL_MODEL_CACHE[hf_id] with torch.inference_mode(): toks = tok([s_trunc], return_tensors="pt", truncation=True, max_length=1024) hid = mod(**toks).last_hidden_state vec = torch.nn.functional.normalize(hid[0, 1 : 1 + len(s_trunc), :].float().mean(dim=0), p=2, dim=0) return vec.numpy().tolist() if model_scale in ("esmc_300m", "esmc_600m"): from transformers import AutoModel, AutoTokenizer hf_repo = "Synthyra/ESMplusplus_small" if model_scale == "esmc_300m" else "Synthyra/ESMplusplus_large" if hf_repo not in _CPU_SMALL_MODEL_CACHE: if len(_CPU_SMALL_MODEL_CACHE) >= 2: _CPU_SMALL_MODEL_CACHE.pop(next(iter(_CPU_SMALL_MODEL_CACHE.keys())), None) tok = AutoTokenizer.from_pretrained(hf_repo, trust_remote_code=True, token=hf_token) mod = AutoModel.from_pretrained(hf_repo, trust_remote_code=True, torch_dtype=torch.float32, token=hf_token).eval() _CPU_SMALL_MODEL_CACHE[hf_repo] = (tok, mod) tok, mod = _CPU_SMALL_MODEL_CACHE[hf_repo] with torch.inference_mode(): enc = tok(s_trunc, return_tensors="pt", truncation=True, max_length=1024) outs = mod(**enc, output_hidden_states=True) hid = outs.last_hidden_state if getattr(outs, "last_hidden_state", None) is not None else outs.hidden_states[-1] vec = torch.nn.functional.normalize(hid[0, 1 : 1 + len(s_trunc), :].float().mean(dim=0), p=2, dim=0) return vec.numpy().tolist() return None def cloud_extract_fasta_dispatcher(clean_seq: str, model_scale: str) -> Optional[List[float]]: """Dispatches custom FASTA embedding extraction across Forge API -> ZeroGPU -> Space CPU.""" if model_scale in FORGE_MODEL_CANDIDATES: forge_vec = _extract_via_forge_api(clean_seq, model_scale) if forge_vec is not None: return forge_vec try: return zerogpu_extract_sequence_embedding(clean_seq, model_scale) except Exception as gpu_exc: print(f"[QuantPPI Space] ZeroGPU call notice for {model_scale}: {gpu_exc}") return _cpu_stateless_fallback(clean_seq, model_scale) # Register cloud FASTA extractor onto server module qserver.EXTERNAL_CLOUD_FASTA_EXTRACTOR = cloud_extract_fasta_dispatcher _UMAP_DISK_LOCK = threading.Lock() def _compute_umap_core( dataset: str, model_scale: str, codec_id: str, scope_mode: str = "full_corpus", use_gpu: Any = "auto", ) -> Dict[str, Any]: qserver.validate_umap_params(dataset, model_scale=model_scale, codec_id=codec_id, scope=scope_mode) dim = int(qserver.STATE.MODEL_DIM_MAP[model_scale]) codec_id = qserver.resolve_umap_codec_id(codec_id, max_k=max(1, dim // 2)) fp16_pool_path = qserver.THIS_DIR / "public" / "realdata" / "embeddings" / f"{dataset}_{model_scale}.fp16.bin" labels: Optional[List[Any]] = None full_meta: Optional[Dict[str, Any]] = None if scope_mode == "active_pool": if not fp16_pool_path.exists(): raise FileNotFoundError( f"Active-pool embeddings not found for ({dataset}, {model_scale}): {fp16_pool_path}" ) x_fp32 = _safe_l2_normalize(np.fromfile(fp16_pool_path, dtype=np.float16).reshape(-1, dim).astype(np.float32)) try: meta_pool = qserver.get_umap_metadata(dataset, scope="active_pool") if len(meta_pool["categories"]) == len(x_fp32): labels = meta_pool["categories"] except Exception: labels = None else: try: x_fp32 = _safe_l2_normalize(qserver.STATE.get_embeddings(dataset, model_scale)) except qserver.BadRequestError: raise except ValueError as exc: raise FileNotFoundError(str(exc)) from exc full_meta = qserver.get_umap_metadata(dataset, scope="full_corpus") if len(full_meta["categories"]) == len(x_fp32): labels = full_meta["categories"] n_samples = int(x_fp32.shape[0]) if codec_id == "exact_fp32": vecs = x_fp32 bpv = dim * 4 else: try: codec = qserver.STATE.create_codec( codec_id=codec_id, dimension=dim, transform_name="circulant", dataset=dataset, model_scale=model_scale, ) except qserver.BadRequestError: raise except ValueError as exc: raise FileNotFoundError(str(exc)) from exc packed = codec.encode(x_fp32) vecs = _safe_l2_normalize(codec.decode(packed, n_samples)) bpv = int(getattr(codec, "total_bytes_per_vector", qserver._compute_bytes_per_vector(codec_id, dim))) ref_coords = None if codec_id != "exact_fp32": ref_coords = qserver._find_reference_fp32_coords(dataset, model_scale, n_samples, scope_mode) eff_use_gpu = False if sys.platform == "darwin" else use_gpu try: res = compute_umap_projection( vecs, reference_coords=ref_coords, n_neighbors=15, min_dist=0.1, spread=1.0, n_epochs=200, seed=42, labels=labels, use_gpu=eff_use_gpu, chunk_size=512, compute_metrics=True, ) q_coords, bounds_tuple = quantize_coords_int16(res["coords"]) return { "q_coords_bytes": np.ascontiguousarray(q_coords, dtype="<i2").tobytes(), "bounds": tuple(float(v) for v in bounds_tuple), "metrics": qserver._sanitize_umap_json_value(dict(res.get("metrics") or {})), "bytes_per_vector": int(bpv), "count": int(n_samples), "scope_mode": scope_mode, "scope": "zerogpu_computed", "full_meta": {k: v for k, v in full_meta.items() if k != "available_bit_widths"} if full_meta is not None else None, } finally: gc.collect() if "torch" in sys.modules: import torch if torch.cuda.is_available(): torch.cuda.empty_cache() @_gpu_decorator def zerogpu_compute_umap( dataset: str, model_scale: str, codec_id: str, scope_mode: str = "full_corpus", ) -> Dict[str, Any]: """ZeroGPU-accelerated UMAP projection entrypoint (falls back cleanly to CPU on macOS).""" use_gpu: Any = False if sys.platform == "darwin" else "auto" return _compute_umap_core( dataset=dataset, model_scale=model_scale, codec_id=codec_id, scope_mode=scope_mode, use_gpu=use_gpu, ) def _persist_umap_result_on_host( dataset: str, model_scale: str, codec_id: str, res: Dict[str, Any], ) -> None: scope_mode = res.get("scope_mode", "full_corpus") persist_dir = (qserver.UMAP_CACHE_DIR / "pool") if scope_mode == "active_pool" else qserver.UMAP_CACHE_DIR fname = f"{dataset}__{model_scale}__{codec_id}.umap.bin" bounds_tuple = tuple(float(v) for v in res["bounds"]) dim = int(qserver.STATE.MODEL_DIM_MAP[model_scale]) bpv = int(res["bytes_per_vector"]) bpd = round((bpv * 8.0) / dim, 2) bounds_dict = { "xmin": round(bounds_tuple[0], 6), "xmax": round(bounds_tuple[1], 6), "ymin": round(bounds_tuple[2], 6), "ymax": round(bounds_tuple[3], 6), } with _UMAP_DISK_LOCK: bin_bytes = struct.pack("<4f", *bounds_tuple) + bytes(res["q_coords_bytes"]) qserver._atomic_write_bytes(persist_dir / fname, bin_bytes) qserver._atomic_write_json( (persist_dir / fname).with_suffix(".meta.json"), { "dataset": dataset, "model_scale": model_scale, "codec_id": codec_id, "scope": "zerogpu_computed", "count": int(res["count"]), "bytes_per_vector": bpv, "bits_per_dim": bpd, "bounds": bounds_dict, "metrics": res.get("metrics") or {}, }, ) if scope_mode != "active_pool": full_meta = res.get("full_meta") if full_meta is not None and qserver._load_and_validate_umap_meta_file( persist_dir / f"{dataset}__metadata.json", dataset, "full_corpus", expected_count=int(res["count"]), expected_ids=qserver._get_full_corpus_ids(dataset), ) is None: qserver._atomic_write_json(persist_dir / f"{dataset}__metadata.json", full_meta) manifest_path = persist_dir / "manifest.json" try: manifest = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.exists() else { "schema_version": 1, "mode": "full_corpus", "projections": [], } projs = manifest.get("projections", []) if isinstance(projs, list): codec_info = qserver.get_codec_spec(codec_id, max_k=max(1, dim // 2)) new_entry = { "dataset": dataset, "model_scale": model_scale, "dimension": dim, "codec_id": codec_id, "codec_name": codec_info["name"], "short_name": codec_info["short_name"], "bit_width_label": codec_info["bit_width_label"], "bytes_per_vector": bpv, "bits_per_dim": bpd, "count": int(res["count"]), "file": fname, "bounds": bounds_dict, "metrics": res.get("metrics") or {}, } projs = [ p for p in projs if not ( isinstance(p, dict) and p.get("dataset") == dataset and p.get("model_scale") == model_scale and p.get("codec_id") == codec_id ) ] projs.append(new_entry) manifest["projections"] = projs qserver._atomic_write_json(manifest_path, manifest) except Exception as exc: print(f"[QuantPPI Space] UMAP manifest update notice: {exc}") def cloud_compute_umap_dispatcher( dataset: str, model_scale: str, codec_id: str, scope_mode: str = "full_corpus", ) -> Dict[str, Any]: """Dispatches on-demand UMAP computation across ZeroGPU -> Space CPU and persists atomically.""" try: codec_id = qserver.resolve_umap_codec_id(codec_id) if isinstance(codec_id, str) else codec_id res = zerogpu_compute_umap(dataset, model_scale, codec_id, scope_mode) except (FileNotFoundError, qserver.BadRequestError): raise except Exception as gpu_exc: print(f"[QuantPPI Space] ZeroGPU UMAP notice for ({dataset}, {model_scale}, {codec_id}): {gpu_exc}") res = _compute_umap_core(dataset, model_scale, codec_id, scope_mode, use_gpu=False) try: _persist_umap_result_on_host(dataset, model_scale, codec_id, res) except Exception as disk_exc: print(f"[QuantPPI Space] UMAP cache persist notice: {disk_exc}") res.pop("full_meta", None) return res # Register ZeroGPU UMAP computer onto server module qserver.EXTERNAL_UMAP_COMPUTER = cloud_compute_umap_dispatcher ALL_MODEL_SCALES_META = [ {"id": "esm2_8m", "name": "ESM-2 8M (6-layer, D=320)", "dimension": 320, "fp32_bytes": 1280}, {"id": "esm2_35m", "name": "ESM-2 35M (12-layer, D=480)", "dimension": 480, "fp32_bytes": 1920}, {"id": "esm2_150m", "name": "ESM-2 150M (30-layer, D=640)", "dimension": 640, "fp32_bytes": 2560}, {"id": "esmc_300m", "name": "ESM-C 300M (30-layer, D=960)", "dimension": 960, "fp32_bytes": 3840}, {"id": "esmc_600m", "name": "ESM-C 600M (36-layer, D=1152)", "dimension": 1152, "fp32_bytes": 4608}, {"id": "esm2_650m", "name": "ESM-2 650M (33-layer, D=1280)", "dimension": 1280, "fp32_bytes": 5120}, {"id": "esm3_1.4b", "name": "ESM-3 1.4B (48-layer, D=1536)", "dimension": 1536, "fp32_bytes": 6144}, {"id": "esm2_3b", "name": "ESM-2 3B (36-layer, D=2560)", "dimension": 2560, "fp32_bytes": 10240}, {"id": "esmc_6b", "name": "ESM-C 6B (80-layer, D=2560)", "dimension": 2560, "fp32_bytes": 10240}, {"id": "esm2_15b", "name": "ESM-2 15B (48-layer, D=5120)", "dimension": 5120, "fp32_bytes": 20480}, ] def _load_structure_entry_shared(target_raw: str) -> Optional[Dict[str, Any]]: tid = target_raw.strip() if not tid: return None if tid == "custom_fasta": if qserver.STATE._last_fasta_query: closest_scaff = qserver.STATE.match_closest_scope_by_sequence(qserver.STATE._last_fasta_query)["id"] return _load_structure_entry_shared(closest_scaff) return _load_structure_entry_shared("d1dlwa_") if qserver.has_pdb_structure(tid): ent_p = qserver.PDB_DIR / f"{tid}.ent" obj = qserver.parse_pdb_ca_atoms(ent_p) obj["ca_atoms"] = [dict(a) for a in obj["ca_atoms"]] if ent_p.exists(): try: obj["raw_pdb_text"] = ent_p.read_text(encoding="utf-8", errors="replace") except Exception: pass r_idx = qserver.STATE.scope_id_to_raw_idx.get(tid) obj["metadata"] = dict(qserver.STATE.scope_entries[r_idx]) if r_idx is not None else {"id": tid} return obj if re.match(r"^[0-9][A-Za-z0-9]{3}$", tid): live = qserver.fetch_live_rcsb_pdb(tid) if live: mapped = ( qserver.STATE.resolve_scope_entry(tid) if qserver.STATE.has_exact_or_alias_scope_match(tid) else qserver.STATE.match_closest_scope_by_sequence(live["metadata"].get("sequence", "")) ) meta = dict(live["metadata"]) if mapped: meta.setdefault("sccs", mapped.get("sccs", "")) meta.setdefault("class_name", mapped.get("class_name", "")) return { **live, "ca_atoms": [dict(a) for a in live["ca_atoms"]], "metadata": meta, } if tid.upper() in qserver.STATE.sp_by_acc: sp_entry = qserver.STATE.sp_by_acc[tid.upper()] scaff = qserver.STATE.match_closest_scope_by_sequence(sp_entry.get("sequence", "")) scaff_id = scaff["id"] if qserver.has_pdb_structure(scaff_id): ent_p = qserver.PDB_DIR / f"{scaff_id}.ent" obj = qserver.parse_pdb_ca_atoms(ent_p) obj["ca_atoms"] = [dict(a) for a in obj["ca_atoms"]] obj["metadata"] = { **dict(sp_entry), "sccs": scaff.get("sccs", ""), "pdb_id": scaff.get("pdb_id", ""), "description": f"{sp_entry.get('description', tid)} [Homologous crystal domain {scaff_id}]", } return obj res_entry = qserver.STATE.resolve_scope_entry(tid) resolved = qserver.STATE.scope_entries[res_entry["raw_idx"]]["id"] if "raw_idx" in res_entry else res_entry["id"] if qserver.has_pdb_structure(resolved): ent_p = qserver.PDB_DIR / f"{resolved}.ent" obj = qserver.parse_pdb_ca_atoms(ent_p) obj["ca_atoms"] = [dict(a) for a in obj["ca_atoms"]] if ent_p.exists(): try: obj["raw_pdb_text"] = ent_p.read_text(encoding="utf-8", errors="replace") except Exception: pass r_idx = qserver.STATE.scope_id_to_raw_idx.get(resolved) meta = dict(qserver.STATE.scope_entries[r_idx]) if r_idx is not None else {"id": resolved} if re.match(r"^[0-9][A-Za-z0-9]{3}$", tid): meta["id"] = tid.upper() meta["pdb_id"] = tid.upper() obj["metadata"] = meta return obj return None def build_quantppi_rest_app() -> Any: """Builds a dedicated FastAPI app with CORS for `/api/*`, `/figures/*`, `/studio`, and `/assets/*`.""" from fastapi import FastAPI, Request from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import FileResponse, JSONResponse rest_app = FastAPI(title="QuantPPI Cloud ZeroGPU API", version="2.0.0") rest_app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=False, allow_methods=["*"], allow_headers=["*"], ) def _extract_header_values(headers: Any, name: str) -> List[str]: if headers is None: return [] target = name.lower() vals: List[str] = [] if hasattr(headers, "getlist"): try: vals = [str(v) for v in headers.getlist(name)] except Exception: vals = [] elif hasattr(headers, "get_all"): try: vals = [str(v) for v in (headers.get_all(name) or [])] except Exception: vals = [] elif isinstance(headers, collections.abc.Mapping): for k, v in headers.items(): if isinstance(k, str) and k.lower() == target and v is not None: if isinstance(v, (list, tuple)): vals.extend(str(item) for item in v if item is not None) else: vals.append(str(v)) elif hasattr(headers, "get"): try: v = headers.get(name) if v is not None: if isinstance(v, (list, tuple)): vals.extend(str(item) for item in v if item is not None) else: vals.append(str(v)) except Exception: pass return vals async def _read_json_object_body(request: Any): headers = getattr(request, "headers", None) if headers is not None: te_vals = _extract_header_values(headers, "transfer-encoding") if any("chunked" in v.lower() for v in te_vals): return None, JSONResponse({"error": "Chunked Transfer-Encoding is not supported"}, status_code=400) raw_lens = _extract_header_values(headers, "content-length") if len(raw_lens) > 1: return None, JSONResponse({"error": "Invalid Content-Length header"}, status_code=400) if len(raw_lens) == 1: raw_len_s = raw_lens[0].strip() if not raw_len_s or not raw_len_s.isascii() or not raw_len_s.isdigit(): return None, JSONResponse({"error": "Invalid Content-Length header"}, status_code=400) if len(raw_len_s) > 18: return None, JSONResponse( {"error": f"Request body too large (Content-Length exceeds {qserver.MAX_POST_BODY_BYTES} byte limit)"}, status_code=413, ) try: cl_int = int(raw_len_s) except ValueError: return None, JSONResponse( {"error": f"Request body too large (Content-Length exceeds {qserver.MAX_POST_BODY_BYTES} byte limit)"}, status_code=413, ) if cl_int > qserver.MAX_POST_BODY_BYTES: return None, JSONResponse( {"error": f"Request body too large ({cl_int} bytes exceeds {qserver.MAX_POST_BODY_BYTES} byte limit)"}, status_code=413, ) try: raw_body = await request.body() except (OverflowError, MemoryError): return None, JSONResponse({"error": "Invalid Content-Length header"}, status_code=400) if len(raw_body) > qserver.MAX_POST_BODY_BYTES: return None, JSONResponse( {"error": f"Request body too large ({len(raw_body)} bytes exceeds {qserver.MAX_POST_BODY_BYTES} byte limit)"}, status_code=413, ) try: body = json.loads(raw_body.decode("utf-8")) if raw_body else {} except (json.JSONDecodeError, UnicodeDecodeError, ValueError) as exc: return None, JSONResponse({"error": f"Malformed JSON request body: {exc}"}, status_code=400) if not isinstance(body, dict): return None, JSONResponse({"error": "Request body must be a JSON object"}, status_code=400) return body, None @rest_app.get("/api/health") def api_health(): return JSONResponse({ "status": "ok", "zerogpu": spaces is not None, "hf_dataset_repo": os.environ.get("HF_DATASET_REPO", "trizzhal9000/quantppi-embeddings"), "forge_configured": bool(os.environ.get("ESM_FORGE_TOKEN")), "models": [m["id"] for m in ALL_MODEL_SCALES_META], "umap_endpoints": ["/api/umap/metadata", "/api/umap", "/api/umap/project-query"], }) @rest_app.get("/api/overview") def api_overview(dataset: str = "scope", model_scale: str = "esm2_650m"): try: geom = qserver.STATE.get_corpus_geometry(dataset, model_scale) return JSONResponse({ "geometry": geom, "codecs": qserver.CODEC_CATALOG, "benchmarks": qserver.STATE.benchmarks_payload, "datasets": [ { "id": "scope", "name": "SCOPe 2.08 ASTRAL-40 Structural Domains", "total_sequences": len(qserver.STATE.scope_entries), "candidates": len(qserver.STATE.p1_cand_raw_ids), "canonical_queries": len(qserver.STATE.p1_query_raw_ids), "pdb_structures": 15118, "source_fasta": "data/astral-scopedom-seqres-gd-sel-gs-bib-40-2.08.fa", }, { "id": "swissprot", "name": "UniProtKB/Swiss-Prot Human Proteome", "total_sequences": len(qserver.STATE.sp_entries), "candidates": len(qserver.STATE.p5_cand_raw_ids), "canonical_queries": len(qserver.STATE.p5_query_raw_ids), "go_annotated": len(qserver.STATE.go_map), "source_fasta": "data/swissprot_human_full.fasta", }, ], "model_scales": ALL_MODEL_SCALES_META, }) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.get("/api/proteins") def api_proteins( dataset: str = "scope", q: str = "", queries_only: str = "0", limit: str = "40", offset: str = "0", ): try: if not isinstance(dataset, str) or dataset not in qserver.VALID_DATASETS: raise qserver.BadRequestError( f"Invalid dataset '{dataset}'. Expected one of {list(qserver.VALID_DATASETS)}." ) if not isinstance(q, str): raise qserver.BadRequestError("Parameter 'q' must be a string.") q_clean = q.strip().lower() q_only = str(queries_only).lower() in ("1", "true") lim = qserver._parse_bounded_int(limit, "limit", min_val=1, max_val=200, clamp_max=True) off = qserver._parse_bounded_int(offset, "offset", min_val=0) if dataset == "scope": source = qserver.STATE.scope_p1_queries if q_only else qserver.STATE.scope_p1_candidates if q_clean: filtered = [ e for e in source if q_clean in e["id"].lower() or q_clean in e["pdb_id"].lower() or q_clean in e["sccs"].lower() or q_clean in e["description"].lower() or q_clean in e["organism"].lower() or (len(q_clean) >= 4 and q_clean.upper() in e["sequence"]) ] else: filtered = source else: source = qserver.STATE.sp_p5_queries if q_only else (list(qserver.STATE.sp_extra_entries.values()) + qserver.STATE.sp_entries) if q_clean: filtered = [ e for e in source if q_clean in e["id"].lower() or q_clean in e["gene"].lower() or q_clean in e["entry_name"].lower() or q_clean in e["description"].lower() or any(q_clean in go.lower() for go in e.get("go_terms", [])) or (len(q_clean) >= 4 and q_clean.upper() in e["sequence"]) ] else: filtered = source slice_items = [ {k: v for k, v in item.items() if k != "sequence"} for item in filtered[off : off + lim] ] return JSONResponse({ "dataset": dataset, "total_matches": len(filtered), "items": slice_items, }) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) @rest_app.get("/api/quantize") def api_quantize_get( dataset: str = "scope", model_scale: str = "esm2_650m", protein_id: str = "d1dlwa_", codec_id: str = "quantppi_block_k2", transform_name: str = "circulant", custom_sequence: str = "", ): try: res = qserver.run_single_protein_quantization_pipeline( dataset=dataset, model_scale=model_scale, protein_id=protein_id, codec_id=codec_id, transform_name=transform_name, custom_sequence=custom_sequence or None, ) return JSONResponse(res) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.post("/api/quantize") async def api_quantize_post(request: Request): body, err_resp = await _read_json_object_body(request) if err_resp is not None: return err_resp assert body is not None try: for req_key in ("dataset", "model_scale", "protein_id", "codec_id", "transform_name"): if req_key in body and body[req_key] is None: raise qserver.BadRequestError(f"Parameter '{req_key}' must be a string.") dataset = body.get("dataset", "scope") default_pid = "d1dlwa_" if dataset == "scope" else "P04637" res = qserver.run_single_protein_quantization_pipeline( dataset=dataset, model_scale=body.get("model_scale", "esm2_650m"), protein_id=body.get("protein_id", default_pid), codec_id=body.get("codec_id", "quantppi_block_k2"), transform_name=body.get("transform_name", "circulant"), custom_sequence=body.get("custom_sequence"), ) return JSONResponse(res) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.get("/api/search") def api_search( dataset: str = "scope", model_scale: str = "esm2_650m", query_id: str = "d1dlwa_", codec_id: str = "quantppi_block_k2", top_k: str = "30", fasta_sequence: str = "", ): try: parsed_top_k = qserver._parse_bounded_int(top_k, "top_k", min_val=1, max_val=100, clamp_max=True) res = qserver.run_live_search( dataset=dataset, model_scale=model_scale, query_id=query_id, codec_id=codec_id, top_k=parsed_top_k, fasta_sequence=fasta_sequence or None, ) return JSONResponse(res) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.post("/api/search") async def api_search_post(request: Request): body, err_resp = await _read_json_object_body(request) if err_resp is not None: return err_resp assert body is not None try: for req_key in ("dataset", "model_scale", "query_id", "codec_id"): if req_key in body and body[req_key] is None: raise qserver.BadRequestError(f"Parameter '{req_key}' must be a string.") dataset = body.get("dataset", "scope") default_qid = "d1dlwa_" if dataset == "scope" else "P68871" parsed_top_k = qserver._parse_bounded_int( body.get("top_k", 30), "top_k", min_val=1, max_val=100, clamp_max=True ) res = qserver.run_live_search( dataset=dataset, model_scale=body.get("model_scale", "esm2_650m"), query_id=body.get("query_id", default_qid), codec_id=body.get("codec_id", "quantppi_block_k2"), top_k=parsed_top_k, fasta_sequence=body.get("fasta_sequence"), ) return JSONResponse(res) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.get("/api/ablation") def api_ablation( query_id: str = "d1dlwa_", k: str = "4", model_scale: str = "esm2_650m", ): try: parsed_k = qserver._parse_bounded_int(k, "k", min_val=1, max_val=64) res = qserver.run_live_theorem_ablation( query_id=query_id, k=parsed_k, model_scale=model_scale, ) return JSONResponse(res) except qserver.BadRequestError as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.get("/api/structure") def api_structure(id: str = "d6a1ia1", compare_id: str = ""): primary = _load_structure_entry_shared(id) if not primary: return JSONResponse({"error": f"3D PDB structure not found for {id}"}, status_code=404) comparison = _load_structure_entry_shared(compare_id) if compare_id else None if comparison and primary["ca_atoms"] and comparison["ca_atoms"]: ref_xyz = np.array([[a["cx"], a["cy"], a["cz"]] for a in primary["ca_atoms"]], dtype=np.float64) mov_xyz = np.array([[a["cx"], a["cy"], a["cz"]] for a in comparison["ca_atoms"]], dtype=np.float64) aligned_xyz, rmsd = qserver.kabsch_superpose(ref_xyz, mov_xyz) for i, a in enumerate(comparison["ca_atoms"]): a["ax"] = round(float(aligned_xyz[i, 0]), 3) a["ay"] = round(float(aligned_xyz[i, 1]), 3) a["az"] = round(float(aligned_xyz[i, 2]), 3) comparison["kabsch_rmsd_angstrom"] = round(rmsd, 3) return JSONResponse({"primary": primary, "comparison": comparison}) @rest_app.get("/api/benchmarks") def api_benchmarks(): return JSONResponse(qserver.STATE.benchmarks_payload) @rest_app.get("/api/umap/metadata") def api_umap_metadata( dataset: str = "scope", scope: str = "auto", model_scale: Optional[str] = None, codec_id: Optional[str] = None, ): try: return JSONResponse( qserver.get_umap_metadata( dataset=dataset, scope=scope, model_scale=model_scale or None, codec_id=codec_id or None, ) ) except (qserver.BadRequestError, ValueError) as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.get("/api/umap") def api_umap( dataset: str = "scope", model_scale: str = "esm2_650m", codec_id: str = "exact_fp32", scope: str = "auto", ): try: return JSONResponse( qserver.get_umap_projection( dataset=dataset, model_scale=model_scale, codec_id=codec_id, scope=scope, ) ) except (qserver.BadRequestError, ValueError) as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) @rest_app.post("/api/umap/project-query") async def api_umap_project_query(request: Request): body, err_resp = await _read_json_object_body(request) if err_resp is not None: return err_resp assert body is not None try: return JSONResponse(qserver.project_umap_query(body)) except (qserver.BadRequestError, ValueError) as exc: return JSONResponse({"error": str(exc)}, status_code=400) except FileNotFoundError as exc: return JSONResponse({"error": str(exc)}, status_code=404) dist_dir = EXPLAINER_DIR / "dist" fig_dir = EXPLAINER_DIR / "public" / "figures" @rest_app.get("/figures/{fig_name:path}") def serve_figure(fig_name: str): for base in (dist_dir / "figures", fig_dir): try: base_resolved = base.resolve() cand = (base_resolved / fig_name).resolve() except (ValueError, OSError): continue if not cand.is_relative_to(base_resolved) or cand == base_resolved: continue if cand.exists() and cand.is_file(): return FileResponse(cand) return JSONResponse({"error": "Figure not found"}, status_code=404) @rest_app.get("/studio") @rest_app.get("/studio/{rest_of_path:path}") def serve_studio(rest_of_path: str = "index.html"): rel = rest_of_path.lstrip("/") or "index.html" try: base_resolved = dist_dir.resolve() target = (base_resolved / rel).resolve() except (ValueError, OSError): return JSONResponse({"error": "Not found"}, status_code=404) if not target.is_relative_to(base_resolved): return JSONResponse({"error": "Not found"}, status_code=404) if not target.exists() or target.is_dir(): target = base_resolved / "index.html" if not target.exists() or not target.is_file(): return JSONResponse({"error": "Studio build not found"}, status_code=404) return FileResponse(target) @rest_app.get("/assets/{asset_path:path}") def serve_studio_assets(asset_path: str): try: base_resolved = (dist_dir / "assets").resolve() target = (base_resolved / asset_path).resolve() except (ValueError, OSError): return JSONResponse({"error": "Asset not found"}, status_code=404) if not target.is_relative_to(base_resolved) or target == base_resolved: return JSONResponse({"error": "Asset not found"}, status_code=404) if target.exists() and target.is_file(): return FileResponse(target) return JSONResponse({"error": "Asset not found"}, status_code=404) return rest_app class QuantPPIRestDispatchMiddleware: """Intercepts `/api/*`, `/figures/*`, `/studio*`, and `/assets/*` at the ASGI layer before Gradio's SPA router.""" def __init__(self, app: Any, rest_app: Any) -> None: self.app = app self.rest_app = rest_app async def __call__(self, scope: Dict[str, Any], receive: Any, send: Any) -> None: if scope.get("type") == "http": path = scope.get("path", "") if ( path.startswith("/api/") or path == "/api" or path.startswith("/figures/") or path == "/studio" or path.startswith("/studio/") or path.startswith("/assets/") ): await self.rest_app(scope, receive, send) return await self.app(scope, receive, send) def install_gradio_asgi_dispatch_hook() -> None: """Hooks into `gradio.routes.App.create_app` BEFORE `demo.launch()` starts Uvicorn on ZeroGPU.""" from gradio.routes import App as GradioServerApp if getattr(GradioServerApp, "_quantppi_hooked", False): return rest_app = build_quantppi_rest_app() orig_create_app = GradioServerApp.create_app def _patched_create_app(*args: Any, **kwargs: Any) -> Any: gradio_fastapi_app = orig_create_app(*args, **kwargs) gradio_fastapi_app.add_middleware(QuantPPIRestDispatchMiddleware, rest_app=rest_app) return gradio_fastapi_app GradioServerApp.create_app = staticmethod(_patched_create_app) GradioServerApp._quantppi_hooked = True def build_gradio_blocks(): import gradio as gr codec_choices = [(f"{c['name']} ({c['compression_1280']}x)", c["id"]) for c in qserver.CODEC_CATALOG] scale_choices = [(m["name"], m["id"]) for m in ALL_MODEL_SCALES_META] def gr_search(dataset: str, model_scale: str, query_id: str, fasta_seq: str, codec_id: str): f_clean = fasta_seq.strip() res = qserver.run_live_search( dataset=dataset, model_scale=model_scale, query_id=query_id.strip(), codec_id=codec_id, top_k=30, fasta_sequence=f_clean if f_clean else None, ) m = res["metrics"] summary_md = ( f"### Query `{res['query']['id']}` — {res['query']['description']} ({res['query']['seq_len']} aa)\n" f"- **Model Scale**: `{model_scale}` (`D={res['dimension']}`) · **Codec**: `{res['codec']['name']}` (`{res['codec']['actual_bytes']} B/protein`)\n" f"- **Recall@20@30**: **{m['recall_20_at_30']*100:.1f}%** · **Latency**: `{m['search_latency_ms']} ms`" ) rows = [ { "Quant Rank": h["quant_rank"], "FP32 Rank": h["fp32_rank"], "Protein ID": h["id"], "Fold / Gene": h.get("sccs") or h.get("gene") or "", "Homology / GO": h.get("homology_tier") or "", "Quant Score": h["quant_score"], "FP32 Score": h["fp32_score"], "Description": h["description"], } for h in res["hits"] ] return summary_md, pd.DataFrame(rows) with gr.Blocks(title="QuantPPI — ZeroGPU 10-PLM Protein Embedding Compression & Homology Search") as demo: gr.Markdown( "## QuantPPI — Bleed-Free Multi-Radix Quantization Across 10 PLMs (ESM-2, ESM-C & ESM-3)\n" "Live ZeroGPU + EvolutionaryScale Forge cloud backend powering all 10 PLMs (`ESM-2 8M–15B`, `ESM-C 300M–6B`, `ESM-3 1.4B`), " "the 108-codec QuantPPI registry, arbitrary raw FASTA sequence embedding extraction, and 3D PyMOL Kabsch superposition." ) with gr.Tabs(): with gr.TabItem("Interactive Web Showcase (/studio)"): gr.HTML( '<iframe src="/studio" style="width:100%; height:1020px; border:1px solid #cbd5e1; border-radius:12px; background:#ffffff;" allow="fullscreen"></iframe>' ) with gr.TabItem("ZeroGPU Direct Homology & FASTA Search"): with gr.Row(): ds_in = gr.Dropdown( choices=[("SCOPe ASTRAL-40 (15,166)", "scope"), ("Swiss-Prot Human (18,102)", "swissprot")], value="scope", label="Corpus Database", ) scale_in = gr.Dropdown( choices=scale_choices, value="esm2_650m", label="Model Scale (10 PLMs)", ) codec_in = gr.Dropdown( choices=codec_choices, value="quantppi_block_k2", label="QuantPPI Codec", ) with gr.Row(): qid_in = gr.Textbox(value="d1dlwa_", label="Catalog Query ID (ignored if FASTA provided)") fasta_in = gr.Textbox( value="", lines=2, placeholder="Optional: paste raw FASTA sequence here to run live ZeroGPU / Forge inference...", label="Raw FASTA Sequence (Optional)", ) run_btn = gr.Button("Execute Live QuantPPI Search", variant="primary") out_md = gr.Markdown() out_df = gr.Dataframe(interactive=False) run_btn.click(gr_search, inputs=[ds_in, scale_in, qid_in, fasta_in, codec_in], outputs=[out_md, out_df]) return demo if __name__ == "__main__": install_gradio_asgi_dispatch_hook() port = int(os.environ.get("GRADIO_SERVER_PORT", os.environ.get("PORT", "7860"))) host = os.environ.get("GRADIO_SERVER_NAME", os.environ.get("HOST", "0.0.0.0")) demo = build_gradio_blocks() demo.queue() print(f"[QuantPPI Space] Launching ZeroGPU Gradio + REST /api/* on http://{host}:{port}") demo.launch( server_name=host, server_port=port, ) elif os.environ.get("SPACE_ID"): install_gradio_asgi_dispatch_hook() demo = build_gradio_blocks()
#!/usr/bin/env python3
"""
QuantPPI — Hugging Face ZeroGPU Gradio Space + Cloud FastAPI Backend Entrypoint.
Supports all 10 Protein Language Models from QuantPPI.ipynb:
- ESM-2: 8M (D=320), 35M (D=480), 150M (D=640), 650M (D=1280), 3B (D=2560), 15B (D=5120)
- ESM-C: 300M (D=960), 600M (D=1152), 6B (D=2560)
- ESM-3: 1.4B (D=1536)
Architecture:
1. `spaces` is imported prior to any `torch` import as required by Hugging Face ZeroGPU.
2. Precomputed corpus embeddings (.h5) for all 10 PLMs stream on-demand from `HF_DATASET_REPO`
(`trizzhal9000/quantppi-embeddings`).
3. Custom raw FASTA queries execute via EvolutionaryScale Forge API (`ESM_FORGE_TOKEN`) for
ESM-C / ESM-3 and `@spaces.GPU` (Nvidia H200 / A10G ZeroGPU) for ESM-2 8M–15B.
4. Launches via `demo.launch(...)` so ZeroGPU's worker daemon initializes natively while
exposing `/api/*`, `/figures/*`, and `/studio` with CORS enabled for Vercel production.
"""
import collections.abc
import gc
import json
import os
import re
import struct
import sys
import threading
from pathlib import Path
from typing import Any, Dict, List, Optional
# ZeroGPU requirement: import `spaces` before anything that could import `torch`
try:
import spaces
except ImportError:
spaces = None
os.environ.setdefault("MPLCONFIGDIR", "/tmp")
os.environ.setdefault("HF_DATASET_REPO", "trizzhal9000/quantppi-embeddings")
REPO_ROOT = Path(__file__).resolve().parent
EXPLAINER_DIR = REPO_ROOT / "explainer"
if str(REPO_ROOT) not in sys.path:
sys.path.insert(0, str(REPO_ROOT))
if str(EXPLAINER_DIR) not in sys.path:
sys.path.insert(0, str(EXPLAINER_DIR))
import numpy as np
import pandas as pd
import server as qserver
from src.evaluators.umap_projection import (
compute_umap_projection,
quantize_coords_int16,
_safe_l2_normalize,
)
def _gpu_decorator(fn):
if spaces is not None and hasattr(spaces, "GPU"):
return spaces.GPU(duration=180)(fn)
return fn
ESM2_HF_REPOS: Dict[str, str] = {
"esm2_8m": "facebook/esm2_t6_8M_UR50D",
"esm2_35m": "facebook/esm2_t12_35M_UR50D",
"esm2_150m": "facebook/esm2_t30_150M_UR50D",
"esm2_650m": "facebook/esm2_t33_650M_UR50D",
"esm2_3b": "facebook/esm2_t36_3B_UR50D",
"esm2_15b": "facebook/esm2_t48_15B_UR50D",
}
FORGE_MODEL_CANDIDATES: Dict[str, List[str]] = {
"esmc_300m": ["esmc-300m-2024-12", "esmc_300m"],
"esmc_600m": ["esmc-600m-2024-12", "esmc_600m"],
"esmc_6b": ["esmc-6b-2024-12", "esmc_6b"],
"esm3_1.4b": ["esm3-open-2024-03", "esm3-sm-open-v1", "esm3-medium-2024-08"],
}
_CPU_SMALL_MODEL_CACHE: Dict[str, Any] = {}
def _extract_via_forge_api(clean_seq: str, model_scale: str) -> Optional[List[float]]:
"""Extracts ESM-C (300M, 600M, 6B) and ESM-3 (1.4B) embeddings via EvolutionaryScale Forge API."""
forge_token = (os.environ.get("ESM_FORGE_TOKEN") or "").strip()
if not forge_token or model_scale not in FORGE_MODEL_CANDIDATES:
return None
try:
from esm.sdk import client as esm_forge_client
from esm.sdk.api import ESMProtein, LogitsConfig
s_trunc = clean_seq[:1022]
for model_name in FORGE_MODEL_CANDIDATES[model_scale]:
try:
forge_client = esm_forge_client(
model=model_name,
url="https://forge.evolutionaryscale.ai",
token=forge_token,
)