REST API

This hosted app runs the scoring pipeline entirely in your browser, so there is no live REST endpoint to call here. The endpoints below document the equivalent self-hosted API: run the open-source FastAPI backend (github.com/OfficialBishal/PertEMA) and the interactive schema is served at /docs (Swagger), /redoc, and /openapi.json. All scoring is post hoc and leakage-safe: the shipped estimator is never retrained on your ground truth.

Endpoints

method	path	what it does
GET	/health, /version	liveness and the provenance stamp (model version, build commit)
POST	/score	reliability, band, and conformal interval for an (n, 64) feature matrix (batches in one call)
POST	/explain	per-perturbation grouped feature attribution toward predicted error
POST	/ingest_score	parse, featurize, score, and explain a long-format predictions CSV
POST	/evaluate	realized reliability quality against YOUR out-of-sample ground truth (no retraining)
POST	/report	a self-contained, provenance-stamped HTML report for a predictions CSV
GET	/template, /example, /benchmark, /transfer_heatmap	the CSV template, the bundled example, the open benchmark table, the transfer-difficulty matrix

Authentication

Open by default so the demo runs without setup. Set PERTEMA_API_TOKEN on the server to require a bearer token on the scoring endpoints. Requests then need Authorization: Bearer <token> and return 401 without it. CORS is locked to PERTEMA_CORS_ORIGINS.

curl

# score a predictions CSV end to end
curl -s http://localhost:8000/ingest_score \
  -H 'Content-Type: application/json' \
  -d '{"csv":"perturbed_gene,gene,predicted_lfc\nIL2,IL2RA,0.83\nIL2,IFNG,-0.21\nSTAT5A,MYC,0.30\n"}'

# score a raw (n, 64) feature matrix, with a token if the server is protected
curl -s http://localhost:8000/score \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer ' \
  -d '{"features": [[0.4, 0.0, ... 64 values ...]]}'

# download a self-contained HTML report
curl -s http://localhost:8000/report \
  -H 'Content-Type: application/json' \
  -d @my_predictions.json > report.html

Python client (standard library, no install)

Copy app/client/pertema_client.py and use it directly.

from pertema_client import PertEMA

api = PertEMA("http://localhost:8000")          # reads PERTEMA_API_TOKEN from the env if set
out = api.ingest_csv(open("my_predictions.csv").read())
for gene, r in zip(out["genes"], out["results"]):
    print(gene, round(r["reliability"], 3), r["band"])

# measure realized quality on your OWN out-of-sample ground truth (never retrains the model)
q = api.evaluate(features, true_error)
print(q["spearman_reliability_vs_accuracy"], q["risk_coverage_auc"])

Batch

/score and /explain take an (n, 64) matrix and score every row in one call, up to PERTEMA_MAX_ROWS (default 200000). Larger jobs should be split into batches. Malformed input returns 422 and oversized input 413, never a crash.

Performance

Scoring is CPU-only and fast: the frozen gradient-boosted tree plus isotonic calibration and the conformal interval score about 48,000 perturbations per second at a batch of 100 and over 450,000 per second at a batch of 10,000 (10,000 perturbations in roughly 22 ms, measured on the reference host). Single-request latency is a couple of milliseconds. The frozen model and the bundled reference are loaded once at startup, so there is no per-request model-load cost. Batch your requests for the best throughput.