docs: expand model training guide

Add setup, training, evaluation, output paths, and optional ClearML usage details in models README for faster onboarding.

models/README.md

@@ -1,16 +1,84 @@
 # models/
 
-Feature extraction (face mesh, head pose, eye scorer, collect_features) and training scripts.
+Feature extraction + model training scripts for FocusGuard.
 
-**Extraction:** `face_mesh.py` → landmarks; `head_pose.py` → yaw/pitch/roll, scores; `eye_scorer.py` → EAR, gaze, MAR; `collect_features.py` → 17-d vector + PERCLOS, blink, etc.
+## What is here
 
-**Training:**
+- `face_mesh.py`: MediaPipe landmarks
+- `head_pose.py`: yaw/pitch/roll and face-orientation scores
+- `eye_scorer.py`: EAR, gaze offsets, MAR
+- `collect_features.py`: writes per-session `.npz` feature files
+- `mlp/`: MLP training and utilities
+- `xgboost/`: XGBoost training and utilities
 
-| Path | Command | Checkpoint |
-|------|---------|------------|
-| mlp/ | `python -m models.mlp.train` | checkpoints/mlp_best.pt |
-| xgboost/ | `python -m models.xgboost.train` | checkpoints/xgboost_face_orientation_best.json |
+## 1) Setup
 
-MLP: train.py, sweep.py, eval_accuracy.py. XGB: train.py, sweep_local.py, eval_accuracy.py. Both use `data_preparation.prepare_dataset` (get_numpy_splits / get_dataloaders).
+From repo root:
 
-**Results:** XGBoost 95.87% acc, 0.959 F1, 0.991 AUC; MLP 92.92%, 0.929, 0.971.
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## 2) Collect training data (if needed)
+
+```bash
+python -m models.collect_features --name <participant_name>
+```
+
+This writes files under `data/collected_<participant_name>/`.
+
+## 3) Train models
+
+Both scripts read config from `config/default.yaml` (split ratios, seeds, hyperparameters).
+
+### MLP
+
+```bash
+python -m models.mlp.train
+```
+
+Outputs:
+- checkpoint: `checkpoints/mlp_best.pt` (best by validation F1)
+- scaler/meta: `checkpoints/scaler_mlp.joblib`, `checkpoints/meta_mlp.npz`
+- log: `evaluation/logs/face_orientation_training_log.json`
+
+### XGBoost
+
+```bash
+python -m models.xgboost.train
+```
+
+Outputs:
+- checkpoint: `checkpoints/xgboost_face_orientation_best.json`
+- log: `evaluation/logs/xgboost_face_orientation_training_log.json`
+
+## 4) Run evaluation after training
+
+```bash
+python -m evaluation.justify_thresholds
+python -m evaluation.grouped_split_benchmark --quick
+python -m evaluation.feature_importance --quick --skip-lofo
+```
+
+Generated reports:
+- `evaluation/THRESHOLD_JUSTIFICATION.md`
+- `evaluation/GROUPED_SPLIT_BENCHMARK.md`
+- `evaluation/feature_selection_justification.md`
+
+## 5) Optional: ClearML tracking
+
+Run training with ClearML logging:
+
+```bash
+USE_CLEARML=1 python -m models.mlp.train
+USE_CLEARML=1 python -m models.xgboost.train
+```
+
+Remote execution via agent queue:
+
+```bash
+USE_CLEARML=1 CLEARML_QUEUE=gpu python -m models.mlp.train
+USE_CLEARML=1 CLEARML_QUEUE=gpu python -m models.xgboost.train
+```