DDLS structure-api — a tiny ESMFold folding service

The course-hosted GPU structure-prediction service used in DDLS 2026, Computer Lab 4. It wraps the open-source ESMFold model (facebook/esmfold_v1) behind a small, key-gated FastAPI endpoint so a student's coding agent can fold a protein sequence that isn't in the AlphaFold Database — a designed construct, a mutant/truncation, or a two-chain complex — and read the confidence signals the lab teaches (per-residue pLDDT and the PAE matrix).

It exists to make one point concrete: wrap a model behind an API your agent can call. That's the whole service.

API

POST /fold      Authorization: Bearer <key>
  {"sequence": "MKT..."}                    # one chain
  {"sequences": ["CHAIN_A...", "CHAIN_B..."]}  # a complex (max 2 chains)
  -> {pdb, plddt[], mean_plddt, pae[][], ptm, chain_lengths, interface_pae_mean?}

GET  /healthz        # model_loaded, gpus, free_slots, busy_slots
GET  /skill.md?token=<key>   # agent-readable operating doc, token embedded

Caps (abuse + VRAM guards): ≤ 400 residues total, ≤ 2 chains, one fold in flight per client, a per-client rate limit, and a hard per-fold timeout. A fold of ≤ 400 aa takes ~1–5 s on a modern GPU. Folds are free (no upstream cost). When busy or still loading, requests get 429/503 with a Retry-After so the caller can wait and retry; unreachable is a genuine connection error.

Auth

One shared clear-text key (STRUCT_API_SHARED_KEY) — the course shows it to students. Requests are bucketed per client IP. If the key is unset, the service falls back to a legacy per-student mode that verifies keys against a portal SQLite DB (only useful when co-located with that portal).

Run it yourself

Needs a CUDA GPU with ~16 GB VRAM (ESMFold won't run on a laptop CPU in reasonable time).

pip install -r requirements.txt
STRUCT_API_SHARED_KEY="pick-a-key" STRUCT_API_DEVICES="cuda:0" \
  uvicorn app:app --host 0.0.0.0 --port 8110
# multi-GPU: STRUCT_API_DEVICES="cuda:0,cuda:1" runs one model replica per card

The ESMFold weights (~2.8 GB) download from the HuggingFace hub on first start.

Files

• app.py — FastAPI app: auth, caps, queue, /fold, /healthz, /skill.md.
• fold_model.py — the ESMFold wrapper: a per-GPU model pool, single- and two-chain folding.
• requirements.txt — torch, transformers, fastapi, uvicorn, …
• deploy/ — a Dockerfile and Kubernetes manifests (single-replica GPU Deployment + ingress).

Env knobs: STRUCT_API_SHARED_KEY, STRUCT_API_DEVICES (or STRUCT_API_DEVICE), STRUCT_API_MAX_LEN (400), STRUCT_API_MAX_CHAINS (2), STRUCT_API_TIMEOUT (240s), STRUCT_API_QUEUE_WAIT (120s), STRUCT_API_RATE_MAX (40), STRUCT_API_PUBLIC_URL.

Model: ESMFold, Lin et al., Science 2023 — facebook/esmfold_v1 (MIT).