TremorQuant

Browser-based essential-tremor severity scoring from a 30-second webcam clip. Returns an FTM-TRS-aligned subscore. Research use only — clinical decision support, not a primary diagnostic device.

What this is

TremorQuant turns a 30-second webcam clip of a patient's hand into an Fahn-Tolosa-Marin Tremor Rating Scale (FTM-TRS) subscore — the clinical gold standard for essential-tremor severity — along with peak frequency (Hz), normalized amplitude, bilateral symmetry, and a confidence score.

v1 ships with a synthetic pose backend so the entire API surface is exercisable on a laptop. The real MediaPipe Hands path is a thin module that loads when you pip install .[model].

Quick start

pip install -e ".[dev]"
pytest tests/ -q
tremorquant-api --reload
# → http://localhost:8000/docs

Docker

# CPU image (small, ~150 MB; synthetic backend)
docker build -t tremorquant:cpu --target cpu .

# Real model image (mediapipe + opencv)
docker build -t tremorquant:model --target model .

Usage

# 1. Register a patient
curl -X POST http://localhost:8000/v1/patients \
  -H "Authorization: Bearer *** -H "Content-Type: application/json" \
  -d '{"patient_id": "pat_001", "display_name": "Jane Doe"}'

# 2. Upload a 30-second session (21 hand landmarks per frame, 30 Hz)
curl -X POST http://localhost:8000/v1/sessions \
  -H "Authorization: Bearer *** -H "Content-Type: application/json" \
  -d @examples/upload_session.json

# 3. Score
curl -X POST http://localhost:8000/v1/score/{session_id} -H "Authorization: Bearer *** 4. Fetch the time-series for the patient
curl http://localhost:8000/v1/patients/pat_001/history -H "Authorization: Bearer *** API

| Endpoint | Auth | Purpose |
|---|---|---|
| `GET /healthz` | public | Liveness |
| `GET /readyz` | public | Readiness + pose/scorer backends |
| `GET /metrics` | public | Prometheus exposition |
| `GET /docs` | public | Swagger UI |
| `GET /dashboard` | public | Clinician web console |
| `POST /v1/patients` | Bearer | Register a patient |
| `GET /v1/patients/{id}` | Bearer | Patient metadata + session count |
| `GET /v1/patients/{id}/history` | Bearer | Longitudinal score time series |
| `POST /v1/sessions` | Bearer | Upload a landmark session |
| `POST /v1/score/{session_id}` | Bearer | Score an uploaded session |
| `GET /v1/score/{session_id}` | Bearer | Idempotent re-fetch |
| `GET /v1/models` | Bearer | Pose + scoring backends |
| `GET /v1/usage` | Bearer | Per-tenant usage for the current billing period |

## Pricing tiers (v1)

| Tier | Price | Patients | Sessions/mo |
|---|---|---|---|
| Free | $0 | 5 | 20 |
| Practice | $199/mo | 100 | 500 |
| Network | $999/mo | 1000 | 10,000 |
| Pharma | custom | unlimited | unlimited |

## Privacy, safety, regulatory

- **No raw video by default.** v1 accepts pre-extracted hand landmarks; raw video is processed in-memory and discarded.
- **Clinical decision support, not a primary diagnostic device.** The output is a score; the clinician is the diagnostic authority.
- **HIPAA-eligible deployment** (Practice+ tier) — BAA available.
- **GDPR Art 9 / EDPB** — explicit consent required for health-data processing.

## License

MIT. See [LICENSE](LICENSE).