#!/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://-.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( '' ) 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)