The CAPA prediction backend

Overview

CAPA's backend is a FastAPI application that loads a trained PyTorch model on startup and exposes a REST API for inference. It runs inside Docker on HuggingFace Spaces — always-on, CPU-only, free tier.

The model pipeline: donor and recipient HLA alleles are resolved to protein sequences, embedded with frozen ESM-2 vectors (or looked up from a pre-built cache), passed through a cross-attention interaction network, and decoded by a DeepHit competing-risks survival head that jointly predicts the time-to-event distribution for GvHD, relapse, and TRM.

What the model returns

For every prediction you get three cumulative incidence functions (CIF) — one per competing event — evaluated at 100 evenly-spaced time points from 0 to 730 days post-transplant. Each CIF is a monotone non-decreasing curve in [0, 1]. The scalar risk_score is simply cif[−1]: the estimated probability of the event occurring within two years.

Quick start

The fastest way to try the API is a single curl call. You need at least one HLA locus for both donor and recipient.

curl https://coconutmocha-capa.hf.space/health

curl -s -X POST https://coconutmocha-capa.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{
    "donor_hla":     { "A": "A*02:01", "B": "B*07:02", "DRB1": "DRB1*15:01" },
    "recipient_hla": { "A": "A*01:01", "B": "B*08:01", "DRB1": "DRB1*03:01" }
  }'

import requests

payload = {
    "donor_hla": {
        "A": "A*02:01", "B": "B*07:02", "C": "C*07:02",
        "DRB1": "DRB1*15:01", "DQB1": "DQB1*06:02"
    },
    "recipient_hla": {
        "A": "A*01:01", "B": "B*08:01", "C": "C*07:01",
        "DRB1": "DRB1*03:01", "DQB1": "DQB1*02:01"
    },
    "clinical": {
        "age_recipient": 12,
        "age_donor": 34,
        "disease": "ALL",
        "conditioning": "MAC",
        "donor_type": "MUD",
        "stem_cell_source": "BM",
        "sex_mismatch": 0
    }
}

r = requests.post(
    "https://coconutmocha-capa.hf.space/predict",
    json=payload,
    timeout=30,
)
r.raise_for_status()
data = r.json()

print(f"GvHD 2-yr risk:    {data['gvhd']['risk_score']:.3f}")
print(f"Relapse 2-yr risk: {data['relapse']['risk_score']:.3f}")
print(f"TRM 2-yr risk:     {data['trm']['risk_score']:.3f}")
print(f"Mismatches:        {data['mismatch_count']}")

const res = await fetch("https://coconutmocha-capa.hf.space/predict", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    donor_hla:     { A: "A*02:01", DRB1: "DRB1*15:01" },
    recipient_hla: { A: "A*01:01", DRB1: "DRB1*03:01" },
  }),
});
const data = await res.json();
console.log(data.gvhd.risk_score);  // e.g. 0.331

Endpoints

{
  "status":         "ok",
  "model_version":  "model",
  "ready":          true,      // false if checkpoint missing or corrupt
  "startup_error":  null,      // human-readable error string if ready=false
  "uptime_seconds": 1382.4,
  "device":         "cpu"
}

Request format

All endpoints accept and return JSON (Content-Type: application/json).

HLA typing object

All fields are optional strings. Supply whichever loci you have — the model runs on any subset. Use standard IMGT allele notation (A*02:01, not A2).

Clinical covariates object optional

All fields are optional. Missing values are imputed with zeros or the "unknown" category — the model will still run, just with less information.

Full /predict request body

{
  "donor_hla": {          // required — at least one locus
    "A":    "A*02:01",
    "B":    "B*07:02",
    "C":    "C*07:02",
    "DRB1": "DRB1*15:01",
    "DQB1": "DQB1*06:02"
  },
  "recipient_hla": {      // required — at least one locus
    "A":    "A*01:01",
    "B":    "B*08:01",
    "C":    "C*07:01",
    "DRB1": "DRB1*03:01",
    "DQB1": "DQB1*02:01"
  },
  "clinical": {            // optional — all sub-fields optional
    "age_recipient":    12,
    "age_donor":        34,
    "disease":          "ALL",
    "conditioning":     "MAC",
    "donor_type":       "MUD",
    "stem_cell_source": "BM",
    "sex_mismatch":     0
  }
}

Response format

/predict response

{
  "gvhd": {
    "cumulative_incidence": [0.0, 0.003, …, 0.331],  // 100 values, 0–730 days
    "risk_score":          0.331,                       // = CIF at day 730
    "time_points":         [0.0, 7.37, …, 730.0]        // 100 day values
  },
  "relapse": { /* same shape */ },
  "trm":     { /* same shape */ },
  "attention_weights": [                               // n_loci × n_loci matrix
    [0.42, 0.12, 0.11, 0.21, 0.14],
    …
  ],
  "mismatch_count": 3,                                // allele-level loci mismatches
  "model_version":  "model"
}

/compare response

Returns all donors ranked by ascending composite score (GvHD risk + TRM risk). The best donor is first and identified by best_donor_label.

{
  "donors": [
    {
      "label":          "Donor A",
      "rank":           1,
      "gvhd_risk":      0.28,
      "relapse_risk":   0.31,
      "trm_risk":       0.19,
      "mismatch_count": 1,
      "full_prediction": { /* full /predict response */ }
    },
    …
  ],
  "best_donor_label": "Donor A",
  "model_version":    "model"
}

Run locally

Two options: Docker (self-contained, matches the HF Space exactly) or uv (faster iteration during development).

Option A — Docker

1. Clone the backend repo

   The Docker image lives in the HuggingFace Space repository, not the main GitHub repo.

   git clone https://huggingface.co/spaces/coconutmocha/capa capa-backend
   cd capa-backend

2. Build the image

   docker build -t capa-backend .

3. Run the container

   docker run -p 7860:7860 capa-backend

   The server starts on http://localhost:7860. Visit /health to confirm it's up.

Option B — uv (development)

1. Clone the backend repo and install

   git clone https://huggingface.co/spaces/coconutmocha/capa capa-backend
   cd capa-backend
   uv sync

   Requires Python 3.11+ and uv. Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh.

2. Checkpoint is already included

   The repo ships with a bundled checkpoint at runs/best/model.pt. The server finds it automatically — no extra config needed. To override, set CAPA_CHECKPOINT to any valid .pt path.

3. Start the server

   uv run uvicorn capa.api.predict:app \
     --reload --host 0.0.0.0 --port 8000

   The API is now at http://localhost:8000. The --reload flag restarts on code changes.

4. Point the frontend at your local server

   Edit web/config.js and change the apiUrl:

   window.CAPA_CONFIG = {
     apiUrl: 'http://localhost:8000'
   };

   Then open web/predict.html in a browser — the prediction UI now calls your local server.

Configuration

All runtime settings are controlled via environment variables. No config files to edit — set variables before starting the server or pass them to docker run -e.

Switching between the live and local backend

The frontend reads web/config.js at runtime. Change apiUrl there — no rebuild needed, just refresh the page.

window.CAPA_CONFIG = {
  // Live HF Space (production)
  apiUrl: 'https://coconutmocha-capa.hf.space'

  // Local dev server
  // apiUrl: 'http://localhost:8000'
};