docs: HF Space README YAML (title, emoji, colors) + merge doc sections

README.md

@@ -1,21 +1,20 @@
-<<<<<<< HEAD
 ---
-title: FocusGuard
+title: Focus Guard Final v2
+emoji: 🎯
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 app_port: 7860
+pinned: false
+short_description: Webcam focus detection — MediaPipe, MLP/XGBoost/L2CS, React + FastAPI.
 ---
 
-=======
->>>>>>> feature/integration2.0
 # FocusGuard
 
-Webcam-based focus detection: MediaPipe face mesh -> 17 features (EAR, gaze, head pose, PERCLOS, etc.) -> MLP or XGBoost for focused/unfocused. React + FastAPI app with WebSocket video.
+Webcam-based focus detection: MediaPipe face mesh → 17 features (EAR, gaze, head pose, PERCLOS, etc.) → MLP or XGBoost for focused/unfocused. React + FastAPI app with WebSocket video.
 
-<<<<<<< HEAD
-=======
-**Repository:** Add your repo link here (e.g. `https://github.com/your-org/FocusGuard`).
+**Repository:** [KCL GAP project](https://github.kcl.ac.uk) (internal) — adjust link if you publish a public mirror.
 
->>>>>>> feature/integration2.0
 ## Project layout
 
 ```
@@ -41,13 +40,10 @@ Webcam-based focus detection: MediaPipe face mesh -> 17 features (EAR, gaze, hea
 └── package.json
 ```
 
-<<<<<<< HEAD
-=======
 ## Config
 
 Hyperparameters and app settings live in `config/default.yaml` (learning rates, batch size, thresholds, L2CS weights, etc.). Override with env `FOCUSGUARD_CONFIG` pointing to another YAML.
 
->>>>>>> feature/integration2.0
 ## Setup
 
 ```bash
@@ -95,8 +91,6 @@ python -m models.mlp.train
 python -m models.xgboost.train
 ```
 
-<<<<<<< HEAD
-=======
 ### ClearML experiment tracking
 
 All training and evaluation config (from `config/default.yaml`) is exposed as ClearML task parameters. Enable logging with `USE_CLEARML=1`; optionally run on a **remote GPU agent** instead of locally:
@@ -115,23 +109,19 @@ clearml-agent daemon --queue gpu
 
 Logged to ClearML: **parameters** (full flattened config), **scalars** (loss, accuracy, F1, ROC-AUC, per-class precision/recall/F1, dataset sizes and class counts), **artifacts** (best checkpoint, training log JSON), and **plots** (confusion matrix, ROC curves in evaluation).
 
->>>>>>> feature/integration2.0
 ## Data
 
 9 participants, 144,793 samples, 10 features, binary labels. Collect with `python -m models.collect_features --name <name>`. Data lives in `data/collected_<name>/`.
 
-<<<<<<< HEAD
-=======
 **Train/val/test split:** All pooled training and evaluation use the same split for reproducibility. The test set is held out before any preprocessing; `StandardScaler` is fit on the training set only, then applied to val and test. Split ratios and random seed come from `config/default.yaml` (`data.split_ratios`, `mlp.seed`) via `data_preparation.prepare_dataset.get_default_split_config()`. MLP train, XGBoost train, eval_accuracy scripts, and benchmarks all use this single source so reported test accuracy is on the same held-out set.
 
->>>>>>> feature/integration2.0
 ## Models
 
 | Model | What it uses | Best for |
 |-------|-------------|----------|
 | **Geometric** | Head pose angles + eye aspect ratio (EAR) | Fast, no ML needed |
 | **XGBoost** | Trained classifier on head/eye features (600 trees, depth 8) | Balanced accuracy/speed |
-| **MLP** | Neural network on same features (64->32) | Higher accuracy |
+| **MLP** | Neural network on same features (64→32) | Higher accuracy |
 | **Hybrid** | Weighted MLP + Geometric ensemble | Best head-pose accuracy |
 | **L2CS** | Deep gaze estimation (ResNet50, Gaze360 weights) | Detects eye-only gaze shifts |
 
@@ -140,10 +130,8 @@ Logged to ClearML: **parameters** (full flattened config), **scalars** (loss, ac
 | Model | Accuracy | F1 | ROC-AUC |
 |-------|----------|-----|---------|
 | XGBoost (600 trees, depth 8) | 95.87% | 0.959 | 0.991 |
-| MLP (64->32) | 92.92% | 0.929 | 0.971 |
+| MLP (64→32) | 92.92% | 0.929 | 0.971 |
 
-<<<<<<< HEAD
-=======
 ## Model numbers (LOPO, 9 participants)
 
 | Model | LOPO AUC | Best threshold (Youden's J) | F1 @ best threshold | F1 @ 0.50 |
@@ -152,6 +140,7 @@ Logged to ClearML: **parameters** (full flattened config), **scalars** (loss, ac
 | XGBoost | 0.8695 | 0.280 | 0.8549 | 0.8324 |
 
 From the latest `python -m evaluation.justify_thresholds` run:
+
 - Best geometric face weight (`alpha`) = `0.7` (mean LOPO F1 = `0.8195`)
 - Best hybrid MLP weight (`w_mlp`) = `0.3` (mean LOPO F1 = `0.8409`)
 
@@ -180,23 +169,24 @@ Latest quick feature-selection run (`python -m evaluation.feature_importance --q
 Top-5 XGBoost gain features: `s_face`, `ear_right`, `head_deviation`, `ear_avg`, `perclos`.
 For full leave-one-feature-out ablation, run `python -m evaluation.feature_importance` (slower).
 
->>>>>>> feature/integration2.0
 ## L2CS Gaze Tracking
 
 L2CS-Net predicts where your eyes are looking, not just where your head is pointed. This catches the scenario where your head faces the screen but your eyes wander.
 
 ### Standalone mode
-Select **L2CS** as the model - it handles everything.
+Select **L2CS** as the model — it handles everything.
 
 ### Boost mode
 Select any other model, then click the **GAZE** toggle. L2CS runs alongside the base model:
+
 - Base model handles head pose and eye openness (35% weight)
 - L2CS handles gaze direction (65% weight)
 - If L2CS detects gaze is clearly off-screen, it **vetoes** the base model regardless of score
 
 ### Calibration
 After enabling L2CS or Gaze Boost, click **Calibrate** while a session is running:
-1. A fullscreen overlay shows 9 target dots (3x3 grid)
+
+1. A fullscreen overlay shows 9 target dots (3×3 grid)
 2. Look at each dot as the progress ring fills
 3. The first dot (centre) sets your baseline gaze offset
 4. After all 9 points, a polynomial model maps your gaze angles to screen coordinates
@@ -205,9 +195,9 @@ After enabling L2CS or Gaze Boost, click **Calibrate** while a session is runnin
 ## Pipeline
 
 1. Face mesh (MediaPipe 478 pts)
-2. Head pose -> yaw, pitch, roll, scores, gaze offset
-3. Eye scorer -> EAR, gaze ratio, MAR
-4. Temporal -> PERCLOS, blink rate, yawn
-5. 10-d vector -> MLP or XGBoost -> focused / unfocused
+2. Head pose → yaw, pitch, roll, scores, gaze offset
+3. Eye scorer → EAR, gaze ratio, MAR
+4. Temporal → PERCLOS, blink rate, yawn
+5. 10-d vector → MLP or XGBoost → focused / unfocused
 
 **Stack:** FastAPI, aiosqlite, React/Vite, PyTorch, XGBoost, MediaPipe, OpenCV, L2CS-Net.