models/README.md

# models/

Feature extraction modules and model training scripts.

## 1. Feature Extraction

Root-level modules form the real-time inference pipeline:

| Module | Input | Output |
|--------|-------|--------|
| `face_mesh.py` | BGR frame | 478 MediaPipe landmarks |
| `head_pose.py` | Landmarks, frame size | yaw, pitch, roll, face/eye score, gaze offset, head deviation |
| `eye_scorer.py` | Landmarks | EAR (left/right/avg), gaze ratio (h/v), MAR |
| `eye_crop.py` | Landmarks, frame | Cropped eye region images |
| `eye_classifier.py` | Eye crops or landmarks | Eye open/closed prediction (geometric fallback) |
| `collect_features.py` | BGR frame | 17-d feature vector + temporal features (PERCLOS, blink rate, etc.) |

## 2. Training Scripts

| Folder | Model | Command |
|--------|-------|---------|
| `mlp/` | PyTorch MLP (64→32, 2-class) | `python -m models.mlp.train` |
| `xgboost/` | XGBoost (600 trees, depth 8) | `python -m models.xgboost.train` |

### mlp/

- `train.py` — training loop with early stopping, ClearML opt-in
- `sweep.py` — hyperparameter search (Optuna: lr, batch_size)
- `eval_accuracy.py` — load checkpoint and print test metrics
- Saves to **`checkpoints/mlp_best.pt`**

### xgboost/

- `train.py` — training with eval-set logging
- `sweep.py` / `sweep_local.py` — hyperparameter search (Optuna + ClearML)
- `eval_accuracy.py` — load checkpoint and print test metrics
- Saves to **`checkpoints/xgboost_face_orientation_best.json`**

## 3. Data Loading

All training scripts import from `data_preparation.prepare_dataset`:

```python
from data_preparation.prepare_dataset import get_numpy_splits   # XGBoost
from data_preparation.prepare_dataset import get_dataloaders     # MLP (PyTorch)
```

## 4. Results

| Model | Test Accuracy | F1 | ROC-AUC |
|-------|--------------|-----|---------|
| XGBoost | 95.87% | 0.959 | 0.991 |
| MLP | 92.92% | 0.929 | 0.971 |