Data & training

Train it yourself

Training is fully offline and reproducible — runtime scoring only ever loads exported artifacts, it never trains on request. The visible workflow lives in notebooks/oss-maintenance-training.ipynb, which the npm run ml:train command drives headlessly.

Prerequisites

Node.js (for the npm run ml:* orchestration scripts).
Python with the scoring workspace requirements installed (mltraining/scoring).
A repository seed and locally downloaded GH Archive coverage — see Building the dataset.

Train and promote

1
Build (or refresh) the dataset
Training needs labeled snapshots. If you have not built them yet, do that first.
```
npm run ml:dataset:foundation
```
2
Train the artifacts
This runs the notebook-primary workflow end to end: dataset engineering, model fitting, calibration, evaluation, and artifact export. It trains Logistic Regression and XGBoost in both the full-history and cold-start regimes.
```
npm run ml:train        # add :force to retrain, or ml:notebook to open the notebook
```
3
Compare candidates and promote
Staging compares every candidate model against what is currently deployed and only promotes when no AUROC drop and no Brier increase exceeds 0.02 — so a worse model can never silently replace a better one.
```
npm run ml:stage-training -- --source-dir tmp/training-foundation/candidate \
  --minimum-repositories 5000 --minimum-inactive-repositories 1000
```

What gets produced & deployed

A run writes model artifacts to the runs directory (e.g. tmp/training/runs) plus a latest-run.json pointer. Promotion copies the accepted bundle into deployment/training. The API image bakes that folder in at build time and re-seeds it on start, so a deploy of a new image is what makes fresh artifacts live.

Promotion guardrails require: labeled rows with both classes; non-empty train/validation/test slices; held-out metrics for Logistic Regression and XGBoost in both regimes; the feature-set-v3 artifacts; and acceptable AUROC, Brier, and calibration behavior. What those metrics mean in practice is covered in Training results explained.