Development

Daily workflow

• keep behavioral changes and docs changes together
• run pytest -q before committing
• run mkdocs build --strict before pushing doc changes
• prefer updating the canonical starter configs instead of documenting stale paths

Key code areas

• src/training/datasets.py: dataset ingestion, feature selection, sanitation, variance threshold, and SVD defaults
• src/training/pipeline_steps.py: scaler, PCA, polynomial features, sampler creation, and pipeline ordering
• src/training/model_runner.py: nested CV, search execution, hold-out scoring, and metrics YAML output
• src/training/reporting.py: dataset summary YAML and CSV output
• src/cli/: public CLI surfaces that docs must match exactly

Adding a new model

1. Add a builder in src/training/model_registry.py.
2. Register it in MODEL_BUILDERS.
3. Add metadata and a param_grid in the chosen hyperparameter YAML.
4. Verify requires_scaler and use_smote are set deliberately.
5. Add or extend tests that cover discoverability and training behavior.

Updating docs safely

When behavior changes:

• validate CLI examples against --help
• validate file names and path patterns against the actual code, not older docs
• check whether config defaults, output names, or pipeline order changed
• keep the GitHub Pages home page, root README, and canonical config aligned

Config hygiene

• treat configs/train.yaml as the canonical starter path because the training CLI help points there
• use configs/train_example_dpk.yaml only when the DPK CSV has actually been generated
• remember that metadata columns preserved by process_features must be dropped at training time
• remember that the shared run ledger always lives at models/tracking/training_runs.csv

Docs and CI

The repository now uses:

• mkdocs.yml as the site entrypoint
• .github/workflows/ci.yml to run tests and mkdocs build --strict
• .github/workflows/pages.yml to publish the GitHub Pages site from main

If a docs change breaks navigation or links, the strict MkDocs build should fail in CI.