Metadata-Version: 2.4
Name: meddeid-training
Version: 0.2.0
Summary: One-stage and publication-protocol training for MedDeID
Author: Stig Hellemans
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://stighellemans.github.io/meddeid.github.io/
Project-URL: Documentation, https://stighellemans.github.io/meddeid.github.io/workflows/train-and-evaluate/
Project-URL: Source, https://github.com/stighellemans/meddeid-training
Project-URL: Issues, https://github.com/stighellemans/meddeid-training/issues
Project-URL: MedDeID on Hugging Face, https://huggingface.co/collections/stighellemans/meddeid
Keywords: de-identification,clinical-nlp,transformers,training
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: meddeid-core<0.3,>=0.2
Requires-Dist: meddeid-eval<0.4,>=0.3
Requires-Dist: PyYAML>=6
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7; extra == "plots"
Provides-Extra: train
Requires-Dist: meddeid<0.3,>=0.2; extra == "train"
Requires-Dist: torch>=2.2; extra == "train"
Requires-Dist: transformers<6,>=5.5; extra == "train"
Requires-Dist: safetensors>=0.4; extra == "train"
Requires-Dist: scikit-learn>=1.4; extra == "train"
Requires-Dist: numpy>=1.24; extra == "train"
Requires-Dist: tqdm>=4.66; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: meddeid<0.3,>=0.2; extra == "dev"
Requires-Dist: torch>=2.2; extra == "dev"
Requires-Dist: transformers<6,>=5.5; extra == "dev"
Requires-Dist: safetensors>=0.4; extra == "dev"
Requires-Dist: scikit-learn>=1.4; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: tqdm>=4.66; extra == "dev"
Dynamic: license-file

# meddeid-training

Training and export tools for MedDeID sequence-labeling models. Researchers can
run one ordinary fit, while release workflows can separate epoch selection from
the final full-data fit so a benchmark remains sealed during model selection.

The [training and evaluation workflow](https://stighellemans.github.io/meddeid.github.io/workflows/train-and-evaluate/)
shows the cross-suite handoffs. This repository and its training protocol remain
authoritative for configuration, fitting, refitting, and export.

## Installation

```bash
python -m pip install 'meddeid-training[train]'
```

## One-time training

For an ordinary research run, fit once using separate train, validation, and
test files. Validation chooses the best checkpoint and the test set is evaluated
after training:

```bash
meddeid-train fit \
  --config configs/release.yaml \
  --data prepared/fit \
  --run runs/fit
```

Use `--epochs N` to override the maximum configured epoch count. The resulting
checkpoint is `runs/fit/checkpoints/best.pt`.

Install `meddeid-training[plots]` together with the training dependencies to
guarantee Matplotlib availability. Every run then writes readable loss and
task-specific F1 small multiples under `RUN/plots/` as both PNG and searchable
vector PDF. Plotting remains optional and never makes training fail.

## Publication protocol

1. Create a held-out validation subset from the 6,493-document synthetic
   development corpus.
2. Select an epoch count using only that validation subset.
3. Restart from the configured initial model and refit on the complete corpus
   for the selected number of epochs.
4. Evaluate once on the independent 300-document synthetic benchmark.
5. Export a self-contained Safetensors model bundle.

```bash
meddeid-train select-epochs \
  --config configs/release.yaml \
  --data prepared/selection \
  --run runs/selection

meddeid-train refit \
  --config configs/release.yaml \
  --selection runs/selection/run.json \
  --data prepared/refit \
  --run runs/refit

meddeid-train export \
  --checkpoint runs/refit/checkpoints/best.pt \
  --run-metadata runs/refit/train_metrics.json \
  --output release/meddeid-dutch-synth
```

`configs/release.yaml` initializes both stages from the complete
`stighellemans/meddeid-dutch-synth` bundle, including its encoder and trained
classifier heads. To train new heads from a base encoder, set that encoder as
`model_name` and pin its immutable `model_revision`.

The `select-epochs` and `refit` commands deliberately name the two stages of
this stricter protocol; they are not required for an ordinary one-time fit.
Selection and refit always restart independently from the configured initial
model; refit never continues from the selection checkpoint. Dataset manifests,
model revisions, ordered labels, run configuration, and output checksums are
recorded for reproducibility.

See [Release training protocol](docs/training-protocol.md) for input layout,
stage invariants, configuration, and export requirements.

## Development

```bash
pip install -e '.[dev]'
pytest
```

## Licence

AGPL-3.0-only. Datasets and model artifacts are distributed separately under
the terms stated with each artifact.
