Serving predictions

After packaging the IBD ensemble (previous page), the artefacts sit in app/backend/production_models/ibd_franzosa/. This page covers starting the backend and querying the inference API.

Starting the backend

python app/run_backend.py

The backend starts on port 8000. On startup it scans app/backend/production_models/ for *_config.json files and registers each one as an available model.

Open http://localhost:8000/docs to access the interactive Swagger UI.

Listing available models

curl http://localhost:8000/api/inference/models

The response includes every model discovered in production_models/, with its display name, target, number of ensemble members, and aggregation method.

Single-sample prediction

Send a feature dictionary for one sample:

curl -X POST http://localhost:8000/api/inference/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "ibd_franzosa",
    "features": {
      "d__Bacteria___p__Firmicutes___c__Clostridia___o__Eubacteriales___f__Lachnospiraceae___g__Roseburia": 1205.3,
      "d__Bacteria___p__Bacteroidota___c__Bacteroidia___o__Bacteroidales___f__Bacteroidaceae___g__Bacteroides": 8432.1
    }
  }'

The response contains the predicted class label, probability, confidence, and the number of ensemble members used.

Batch prediction

Upload a TSV file with multiple samples:

curl -X POST http://localhost:8000/api/inference/predict/batch \
  -F "model_id=ibd_franzosa" \
  -F "data=@example/IBD/data/FRANZOSA_IBD_2019_profiles_hierarchical.tsv" \
  -F "sample_id_column=Sample"

The response contains one prediction per sample. Each prediction includes the ensemble label, per-class probabilities, and a confidence score.

LIME explanations

Request feature-importance explanations for the first 5 samples:

curl -X POST http://localhost:8000/api/inference/explain \
  -F "model_id=ibd_franzosa" \
  -F "data=@example/IBD/data/FRANZOSA_IBD_2019_profiles_hierarchical.tsv" \
  -F "sample_id_column=Sample" \
  -F "num_features=10" \
  -F "num_samples=5"

Each sample explanation lists the top features ranked by absolute LIME importance, with a sign indicating the direction of the effect. The importance values are averaged across all ensemble members.

Using the web interface

To access predictions through the browser-based UI, start the frontend alongside the backend:

cd app/frontend
npm install   # first time only
npm run dev

Open http://localhost:3000, select the Inference mode, choose the IBD model, and upload a TSV file. The interface shows predictions and optional LIME bar charts for individual samples.