quantppi / app.py
trizzhal9000's picture
Deploy QuantPPI Studio real-data 3D platform & API
5585d19 verified
Raw History Blame Contribute Delete
14.5 kB
#!/usr/bin/env python3
"""
QuantPPI / RSLM — Free Hugging Face Gradio Space + FastAPI Backend Entrypoint.
How this works on a 100% FREE Hugging Face Gradio Space (CPU Basic: 16 GB RAM, 50 GB Disk):
1. Hugging Face Spaces (`sdk: gradio`) runs `python app.py` on port 7860.
2. We mount all `/api/*` REST endpoints (`/api/overview`, `/api/proteins`, `/api/quantize`,
`/api/search`, `/api/ablation`, `/api/structure`, `/api/benchmarks`) with CORS enabled
onto the underlying FastAPI app BEFORE mounting the Gradio interface.
3. This means:
- Your **Vercel frontend** (`explainer/vercel.json`) can proxy `/api/:path*` directly to
`https://<your-username>-<your-space>.hf.space/api/:path*` for 100% FREE!
- Anyone visiting the Hugging Face Space directly also sees the embedded React 3D Studio
(`/studio/`) plus interactive Gradio tabs powered by the exact same real HDF5 & PDB data!
"""
import os
import sys
from pathlib import Path
from typing import Any, Dict
os.environ.setdefault("MPLCONFIGDIR", "/tmp")
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 the real-data backend engine from explainer/server.py
import server as qserver
def create_gradio_and_api_app():
import gradio as gr
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse, JSONResponse
api = FastAPI(
title="QuantPPI Studio Real-Data API (Hugging Face Gradio Space + Vercel Backend)",
version="1.0.0",
)
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=False,
allow_methods=["*"],
allow_headers=["*"],
)
@api.get("/api/overview")
def api_overview(dataset: str = "scope", model_scale: str = "esm2_650m"):
geom = qserver.STATE.get_corpus_geometry(dataset, model_scale)
return JSONResponse({
"geometry": geom,
"codecs": qserver.CODEC_CATALOG,
"datasets": [
{
"id": "scope",
"name": "SCOPe 2.08 ASTRAL-40",
"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": [
{"id": "esm2_650m", "name": "ESM-2 650M (33-Layer, D=1280)", "dimension": 1280, "fp32_bytes": 5120},
{"id": "esm2_150m", "name": "ESM-2 150M (30-Layer, D=640)", "dimension": 640, "fp32_bytes": 2560},
{"id": "esm2_35m", "name": "ESM-2 35M (12-Layer, D=480)", "dimension": 480, "fp32_bytes": 1920},
],
})
@api.get("/api/proteins")
def api_proteins(
dataset: str = "scope",
q: str = "",
queries_only: str = "0",
limit: int = 40,
offset: int = 0,
):
q_clean = q.strip().lower()
q_only = queries_only == "1"
lim = min(int(limit), 200)
off = int(offset)
if dataset == "scope":
source = qserver.STATE.scope_p1_queries if q_only else qserver.STATE.scope_entries
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 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,
})
@api.get("/api/quantize")
def api_quantize_get(
dataset: str = "scope",
model_scale: str = "esm2_650m",
protein_id: str = "d1dlwa_",
codec_id: str = "track3_hybrid_k2_block224",
transform_name: str = "circulant",
custom_sequence: str = "",
):
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)
@api.post("/api/quantize")
async def api_quantize_post(request: Request):
body: Dict[str, Any] = await request.json()
res = qserver.run_single_protein_quantization_pipeline(
dataset=body.get("dataset", "scope"),
model_scale=body.get("model_scale", "esm2_650m"),
protein_id=body.get("protein_id", "d1dlwa_"),
codec_id=body.get("codec_id", "track3_hybrid_k2_block224"),
transform_name=body.get("transform_name", "circulant"),
custom_sequence=body.get("custom_sequence"),
)
return JSONResponse(res)
@api.get("/api/search")
def api_search(
dataset: str = "scope",
model_scale: str = "esm2_650m",
query_id: str = "d1dlwa_",
codec_id: str = "track3_hybrid_k2_block224",
top_k: int = 30,
):
res = qserver.run_live_search(
dataset=dataset,
model_scale=model_scale,
query_id=query_id,
codec_id=codec_id,
top_k=min(int(top_k), 100),
)
return JSONResponse(res)
@api.get("/api/ablation")
def api_ablation(
query_id: str = "d1dlwa_",
k: int = 4,
model_scale: str = "esm2_650m",
):
res = qserver.run_live_theorem_ablation(
query_id=query_id,
k=int(k),
model_scale=model_scale,
)
return JSONResponse(res)
@api.get("/api/structure")
def api_structure(id: str = "d6a1ia1", compare_id: str = ""):
dom_id = id.strip()
comp_id = compare_id.strip()
ent_path = qserver.PDB_DIR / f"{dom_id}.ent"
if not qserver.has_pdb_structure(dom_id):
return JSONResponse({"error": f"3D PDB structure not found for {dom_id}"}, status_code=404)
primary = qserver.parse_pdb_ca_atoms(ent_path)
raw_idx = qserver.STATE.scope_id_to_raw_idx.get(dom_id)
primary["metadata"] = qserver.STATE.scope_entries[raw_idx] if raw_idx is not None else {"id": dom_id}
comparison = None
if comp_id and qserver.has_pdb_structure(comp_id):
comp_path = qserver.PDB_DIR / f"{comp_id}.ent"
comparison = qserver.parse_pdb_ca_atoms(comp_path)
c_raw_idx = qserver.STATE.scope_id_to_raw_idx.get(comp_id)
comparison["metadata"] = (
qserver.STATE.scope_entries[c_raw_idx] if c_raw_idx is not None else {"id": comp_id}
)
if 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})
@api.get("/api/benchmarks")
def api_benchmarks():
return JSONResponse(qserver.STATE.benchmarks_payload)
# Serve the compiled React/Vite visual studio under /studio/ as well
dist_dir = EXPLAINER_DIR / "dist"
@api.get("/studio")
@api.get("/studio/{rest_of_path:path}")
def serve_studio(rest_of_path: str = "index.html"):
rel = rest_of_path.lstrip("/") or "index.html"
target = dist_dir / rel
if not target.exists() or target.is_dir():
target = dist_dir / "index.html"
return FileResponse(target)
# Also serve /assets/* from explainer/dist/assets/* so /studio works seamlessly
@api.get("/assets/{asset_path:path}")
def serve_studio_assets(asset_path: str):
target = dist_dir / "assets" / asset_path
if target.exists() and target.is_file():
return FileResponse(target)
return JSONResponse({"error": "Asset not found"}, status_code=404)
# Build the Gradio Blocks UI (which both embeds the full 3D Studio AND provides native Gradio controls)
codec_choices = [(f"{c['name']} ({c['compression_1280']}x)", c["id"]) for c in qserver.CODEC_CATALOG]
def gr_search(dataset: str, model_scale: str, query_id: str, codec_id: str):
res = qserver.run_live_search(dataset, model_scale, query_id.strip(), codec_id, top_k=20)
m = res["metrics"]
summary_md = (
f"### Query `{res['query']['id']}` — {res['query']['description']} ({res['query']['seq_len']} aa)\n"
f"- **Codec**: `{res['codec']['name']}` (`{res['codec']['actual_bytes']} B/protein`, `{res['codec']['db_size_mb']} MB` DB vs `{res['codec']['fp32_db_size_mb']} MB` FP32)\n"
f"- **Recall@20@30**: **{m['recall_20_at_30']*100:.1f}%** (vs `{m['base_1bit_recall_20_at_30']*100:.1f}%` Unprotected 1-bit)\n"
f"- **Inner-Product MSE**: `{m['inner_product_mse']:.2e}` (**{m['mse_reduction_vs_1bit']}x lower error** vs 1-bit) · **Latency**: `{m['search_latency_ms']} ms`"
)
rows = []
for h in res["hits"]:
rows.append({
"Quant Rank": h["quant_rank"],
"FP32 Rank": h["fp32_rank"],
"1-Bit Rank": h["base_1bit_rank"],
"Protein ID": h["id"],
"Fold / Gene": h.get("sccs") or h.get("gene") or "",
"Homology / GO": h.get("homology_tier") or f"GO Jaccard {h.get('go_jaccard', 0):.3f}",
"Quant Score": h["quant_score"],
"FP32 Score": h["fp32_score"],
"Description": h["description"],
})
return summary_md, pd.DataFrame(rows)
with gr.Blocks(title="QuantPPI Studio — Real-Data Protein Quantization & 3D Homology Search") as demo:
gr.Markdown(
"## QuantPPI Studio — Real-Data Protein Embedding Compression & 3D Structural Search\n"
"This Space serves both the **REST `/api/*` backend** (for your Vercel frontend) and the "
"**full interactive 3D React Studio** (embedded below or at [`/studio`](/studio))."
)
with gr.Tabs():
with gr.TabItem("Interactive 3D Visual Studio (Full Web App)"):
gr.HTML(
'<iframe src="/studio" style="width:100%; height:920px; border:1px solid #1e293b; border-radius:12px;" allow="fullscreen"></iframe>'
)
with gr.TabItem("Native Gradio Live Homology Search"):
with gr.Row():
ds_in = gr.Dropdown(
choices=[("SCOPe 2.08 (15,166 Domains)", "scope"), ("Swiss-Prot Human (18,099 Proteins)", "swissprot")],
value="scope",
label="Biological Corpus",
)
scale_in = gr.Dropdown(
choices=[("ESM-2 650M (D=1280)", "esm2_650m"), ("ESM-2 150M (D=640)", "esm2_150m"), ("ESM-2 35M (D=480)", "esm2_35m")],
value="esm2_650m",
label="ESM-2 Scale",
)
qid_in = gr.Textbox(value="d1dlwa_", label="Query Protein ID (e.g. d1dlwa_, d6a1ia1, P04637)")
codec_in = gr.Dropdown(choices=codec_choices, value="track3_hybrid_k2_block224", label="QuantPPI Codec")
run_btn = gr.Button("Run Live Asymmetric 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, codec_in], outputs=[out_md, out_df])
demo.load(gr_search, inputs=[ds_in, scale_in, qid_in, codec_in], outputs=[out_md, out_df])
app = gr.mount_gradio_app(api, demo, path="/")
return app
if __name__ == "__main__":
import uvicorn
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"))
app = create_gradio_and_api_app()
uvicorn.run(app, host=host, port=port)