relevant-priors

Simple API to score prior studies as relevant for each case.

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Reproduce Training and Validation

Train the deployment artifact:

python -B app/train.py \
  --training-data relevant_priors_public.json \
  --output-model models/model.joblib \
  --threshold 0.62

Evaluate any labeled challenge-format payload:

python -B evaluate_public.py \
  --payload relevant_priors_public.json \
  --model models/model.joblib

Run case-level out-of-fold validation:

python -B analyze_oof_errors.py --folds 5 --threshold 0.62 --group-by patient

Run feature tests:

python -B -m unittest discover -s tests

The term inventories used by feature extraction live in app/taxonomy.py. Keep additions there and prefer token/phrase-boundary terms over broad substrings.

Run API

uvicorn app.main:app --reload

The API exposes POST /predict.

For a production-style local run:

PORT=8000 uvicorn app.main:app --host 0.0.0.0 --port "$PORT"

Health check:

curl "http://127.0.0.1:8000/health"

Deploy

The app is deployable as either a Python web service or a Docker container. The saved model artifact at models/model.joblib must be included with the deployed code.

Python web service command:

uvicorn app.main:app --host 0.0.0.0 --port "$PORT"

Docker:

docker build -t relevant-priors .
docker run --rm -p 8000:8000 -e PORT=8000 relevant-priors

Request shape

The endpoint accepts:

• challenge_id (string)
• schema_version (number)
• generated_at (ISO datetime)
• cases (list of case records with current/prior studies)

Example call

curl -X POST "http://127.0.0.1:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "relevant-priors-v1",
    "schema_version": 1,
    "generated_at": "2026-04-16T12:00:00.000Z",
    "cases": [
      {
        "case_id": "1001016",
        "patient_id": "606707",
        "patient_name": "Andrews, Micheal",
        "current_study": {
          "study_id": "3100042",
          "study_description": "MRI BRAIN STROKE LIMITED WITHOUT CONTRAST",
          "study_date": "2026-03-08"
        },
        "prior_studies": [
          {
            "study_id": "2453245",
            "study_description": "MRI BRAIN STROKE LIMITED WITHOUT CONTRAST",
            "study_date": "2020-03-08"
          },
          {
            "study_id": "992654",
            "study_description": "CT HEAD WITHOUT CNTRST",
            "study_date": "2021-03-08"
          }
        ]
      }
    ]
  }'