Model serving as REST API using FastAPI

REST API serving an LSTM+Attention model that classifies audio recordings as depression / no_depression.

Prerequisites

• Python 3.11+
• A trained model checkpoint at model/best_model.pt

Quick Start (local)

# 1. Create and activate a virtual environment
python -m venv .venv && source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. (Optional) Copy and edit the environment file
cp .env.example .env

# 4. Start the server
uvicorn app.main:app --reload --port 8000

Interactive API docs: http://localhost:8000/docs

Docker

# Build and start
docker compose up --build

# The model checkpoint is mounted as a volume — not baked into the image.
# Make sure model/best_model.pt exists before starting.

API

POST /predict

Upload a .wav file, receive a prediction.

curl -X POST http://localhost:8000/predict \
     -F "file=@recording.wav"

Response:

{
  "label": "depression",
  "probability": 0.83,
  "confidence": "high",
  "num_frames": 14,
  "processing_time_ms": 212
}

Field	Description
label	depression or no_depression
probability	Probability of depression (0–1)
confidence	high (>0.75) · medium (0.50–0.75) · low (<0.50)
num_frames	Number of audio frames processed
processing_time_ms	End-to-end latency

GET /health

Liveness probe — returns {"status": "ok", "model_loaded": true/false}.

GET /info

Model metadata: checkpoint path, config snapshot, PyTorch version.

Configuration

Edit configs/serving.yaml or override any value with an environment variable:

Env var	Default	Description
MODEL_PATH	model/best_model.pt	Path to the checkpoint
DEVICE	cpu	cpu or cuda
MAX_UPLOAD_MB	25	Upload size limit

Tests

pytest tests/ -v

Tests use a randomly-initialised model — no checkpoint required.

Smoke test against a running server

python scripts/healthcheck.py