evaluation: channel ablation script + feature importance LOPO

README.md

@@ -1,25 +1,25 @@
 # FocusGuard
 
-Real-time webcam-based focus detection system combining geometric feature extraction with machine learning classification. The pipeline extracts 17 facial features (EAR, gaze, head pose, PERCLOS, blink rate, etc.) from MediaPipe landmarks and classifies attentiveness using MLP and XGBoost models. Served via a React + FastAPI web application with live 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.
 
-## 1. Project Structure
+## Project layout
 
 ```
-├── data/                     Raw collected sessions (collected_<name>/*.npz)
-├── data_preparation/         Data loading, cleaning, and exploration
-├── notebooks/                Training notebooks (MLP, XGBoost) with LOPO evaluation
-├── models/                   Feature extraction modules and training scripts
-├── checkpoints/              All saved weights (mlp_best.pt, xgboost_*_best.json, GRU, scalers)
-├── evaluation/               Training logs and metrics (JSON)
-├── ui/                       Live OpenCV demo and inference pipeline
-├── src/                      React/Vite frontend source
-├── static/                   Built frontend (served by FastAPI)
-├── app.py / main.py          FastAPI backend (API, WebSocket, DB)
-├── requirements.txt          Python dependencies
-└── package.json              Frontend dependencies
+├── data/                 collected_<name>/*.npz
+├── data_preparation/     loaders, split, scale
+├── notebooks/            MLP/XGB training + LOPO
+├── models/               face_mesh, head_pose, eye_scorer, train scripts
+├── checkpoints/          mlp_best.pt, xgboost_*_best.json, scalers
+├── evaluation/           logs, plots, justify_thresholds
+├── ui/                   pipeline.py, live_demo.py
+├── src/                  React frontend
+├── static/               built frontend (after npm run build)
+├── main.py, app.py       FastAPI backend
+├── requirements.txt
+└── package.json
 ```
 
-## 2. Setup
+## Setup
 
 ```bash
 python -m venv venv
@@ -27,65 +27,56 @@ source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-Frontend (only needed if modifying the React app):
+To rebuild the frontend after changes:
 
 ```bash
 npm install
 npm run build
-cp -r dist/* static/
+mkdir -p static && cp -r dist/* static/
 ```
 
-## 3. Running
+## Run
 
-**Web application (API + frontend):**
+**Web app:** Use the venv and run uvicorn via Python so it picks up your deps (otherwise you get `ModuleNotFoundError: aiosqlite`):
 
 ```bash
-uvicorn main:app --host 0.0.0.0 --port 7860
+source venv/bin/activate
+python -m uvicorn main:app --host 0.0.0.0 --port 7860
 ```
 
-Open http://localhost:7860 in a browser.
+Then open http://localhost:7860.
 
-**Live camera demo (OpenCV):**
+**OpenCV demo:**
 
 ```bash
 python ui/live_demo.py
-python ui/live_demo.py --xgb      # XGBoost mode
+python ui/live_demo.py --xgb
 ```
 
-**Training:**
+**Train:**
 
 ```bash
-python -m models.mlp.train        # MLP
-python -m models.xgboost.train    # XGBoost
+python -m models.mlp.train
+python -m models.xgboost.train
 ```
 
-## 4. Dataset
-
-- **9 participants**, each recorded via webcam with real-time labelling (focused / unfocused)
-- **144,793 total samples**, 10 selected features, binary classification
-- Collected using `python -m models.collect_features --name <name>`
-- Stored as `.npz` files in `data/collected_<name>/`
-
-## 5. Models
+## Data
 
-| Model | Test Accuracy | Test F1 | ROC-AUC |
-|-------|--------------|---------|---------|
-| XGBoost (600 trees, depth 8, lr 0.149) | 95.87% | 0.959 | 0.991 |
-| MLP (64→32, 30 epochs, lr 1e-3) | 92.92% | 0.929 | 0.971 |
+9 participants, 144,793 samples, 10 features, binary labels. Collect with `python -m models.collect_features --name <name>`. Data lives in `data/collected_<name>/`.
 
-Both evaluated on a held-out 15% stratified test split. LOPO (Leave-One-Person-Out) cross-validation available in `notebooks/`.
+## Model numbers (15% test split)
 
-## 6. Feature Pipeline
+| 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 |
 
-1. **Face mesh** — MediaPipe 478-landmark detection
-2. **Head pose** — solvePnP → yaw, pitch, roll, face score, gaze offset, head deviation
-3. **Eye scorer** — EAR (left/right/avg), horizontal/vertical gaze ratio, MAR
-4. **Temporal tracking** — PERCLOS, blink rate, closure duration, yawn duration
-5. **Classification** — 10-feature vector → MLP or XGBoost → focused / unfocused
+## Pipeline
 
-## 7. Tech Stack
+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
 
-- **Backend:** Python, FastAPI, WebSocket, aiosqlite
-- **Frontend:** React, Vite, TypeScript
-- **ML:** PyTorch (MLP), XGBoost, scikit-learn
-- **Vision:** MediaPipe, OpenCV
+**Stack:** FastAPI, aiosqlite, React/Vite, PyTorch, XGBoost, MediaPipe, OpenCV.

data_preparation/README.md

@@ -1,75 +1,9 @@
 # data_preparation/
 
-Shared data loading, cleaning, and exploratory analysis.
+Load and split the .npz data. Used by all training code and notebooks.
 
-## 1. Files
+**prepare_dataset.py:** `load_all_pooled()`, `load_per_person()` for LOPO, `get_numpy_splits()` (XGBoost), `get_dataloaders()` (MLP). Cleans yaw/pitch/roll and EAR to fixed ranges. Face_orientation uses 10 features: head_deviation, s_face, s_eye, h_gaze, pitch, ear_left, ear_avg, ear_right, gaze_offset, perclos.
 
-| File | Description |
-|------|-------------|
-| `prepare_dataset.py` | Central data loading module used by all training scripts and notebooks |
-| `data_exploration.ipynb` | EDA notebook: feature distributions, class balance, correlations |
+**data_exploration.ipynb:** EDA — stats, class balance, histograms, correlations.
 
-## 2. prepare_dataset.py
-
-Provides a consistent pipeline for loading raw `.npz` data from `data/`:
-
-| Function | Purpose |
-|----------|---------|
-| `load_all_pooled(model_name)` | Load all participants, clean, select features, concatenate |
-| `load_per_person(model_name)` | Load grouped by person (for LOPO cross-validation) |
-| `get_numpy_splits(model_name)` | Load + stratified 70/15/15 split + StandardScaler |
-| `get_dataloaders(model_name)` | Same as above, wrapped in PyTorch DataLoaders |
-| `_split_and_scale(features, labels, ...)` | Reusable split + optional scaling |
-
-### Cleaning rules
-
-- `yaw` clipped to [-45, 45], `pitch`/`roll` to [-30, 30]
-- `ear_left`, `ear_right`, `ear_avg` clipped to [0, 0.85]
-
-### Selected features (face_orientation)
-
-`head_deviation`, `s_face`, `s_eye`, `h_gaze`, `pitch`, `ear_left`, `ear_avg`, `ear_right`, `gaze_offset`, `perclos`
-
-## 3. data_exploration.ipynb
-
-Run from this folder or from the project root. Covers:
-
-1. Per-feature statistics (mean, std, min, max)
-2. Class distribution (focused vs unfocused)
-3. Feature histograms and box plots
-4. Correlation matrix
-
-## 4. How to run
-
-`prepare_dataset.py` is a **library module**, not a standalone script. You don’t run it directly; you import it from code that needs data.
-
-**From repo root:**
-
-```bash
-# Optional: quick test that loading works
-python -c "
-from data_preparation.prepare_dataset import load_all_pooled
-X, y, names = load_all_pooled('face_orientation')
-print(f'Loaded {X.shape[0]} samples, {X.shape[1]} features: {names}')
-"
-```
-
-**Used by:**
-
-- `python -m models.mlp.train`
-- `python -m models.xgboost.train`
-- `notebooks/mlp.ipynb`, `notebooks/xgboost.ipynb`
-- `data_preparation/data_exploration.ipynb`
-
-## 5. Usage (in code)
-
-```python
-from data_preparation.prepare_dataset import load_all_pooled, get_numpy_splits
-
-# pooled data
-X, y, names = load_all_pooled("face_orientation")
-
-# ready-to-train splits
-splits, n_features, n_classes, scaler = get_numpy_splits("face_orientation")
-X_train, y_train = splits["X_train"], splits["y_train"]
-```
+You don’t run prepare_dataset directly; import it from `models.mlp.train`, `models.xgboost.train`, or the notebooks.

data_preparation/prepare_dataset.py

@@ -209,6 +209,8 @@ def get_numpy_splits(model_name: str, split_ratios=(0.7, 0.15, 0.15), seed: int
     features, labels = _load_real_data(model_name)
     num_features = features.shape[1]
     num_classes = int(labels.max()) + 1
+    if num_classes < 2:
+        raise ValueError("Dataset has only one class; need at least 2 for classification.")
     splits, scaler = _split_and_scale(features, labels, split_ratios, seed, scale)
     return splits, num_features, num_classes, scaler
 
@@ -218,6 +220,8 @@ def get_dataloaders(model_name: str, batch_size: int = 32, split_ratios=(0.7, 0.
     features, labels = _load_real_data(model_name)
     num_features = features.shape[1]
     num_classes = int(labels.max()) + 1
+    if num_classes < 2:
+        raise ValueError("Dataset has only one class; need at least 2 for classification.")
     splits, scaler = _split_and_scale(features, labels, split_ratios, seed, scale)
 
     train_ds = FeatureVectorDataset(splits["X_train"], splits["y_train"])

evaluation/README.md

@@ -1,79 +1,19 @@
 # evaluation/
 
-Training logs, threshold analysis, and performance metrics.
+Training logs, threshold/weight analysis, and metrics.
 
-## 1. Contents
+**Contents:** `logs/` (JSON from training runs), `plots/` (ROC, weight search, EAR/MAR), `justify_thresholds.py`, `feature_importance.py`, and the generated markdown reports.
 
-```
-logs/              # training run logs (JSON)
-plots/             # threshold justification figures (ROC, weight search, EAR/MAR)
-justify_thresholds.py   # LOPO analysis script
-feature_importance.py   # XGBoost importance + leave-one-out ablation
-THRESHOLD_JUSTIFICATION.md   # report (auto-generated by justify_thresholds)
-feature_selection_justification.md   # report (auto-generated by feature_importance)
-```
-
-**Logs (when present):** Scripts write to `evaluation/logs/`. MLP script: `face_orientation_training_log.json`; XGBoost script/notebook: `xgboost_face_orientation_training_log.json`; MLP notebook may write `mlp_face_orientation_training_log.json`.
-```
-logs/
-├── face_orientation_training_log.json   # from models/mlp/train.py
-├── xgboost_face_orientation_training_log.json
-└── (optional) mlp_face_orientation_training_log.json  # from notebooks/mlp.ipynb
-```
-
-## 2. Log Format
-
-Each JSON file records the full training history:
-
-**MLP logs:**
-```json
-{
-  "config": { "epochs": 30, "lr": 0.001, "batch_size": 32, ... },
-  "history": {
-    "train_loss": [0.287, 0.260, ...],
-    "val_loss":   [0.256, 0.245, ...],
-    "train_acc":  [0.889, 0.901, ...],
-    "val_acc":    [0.905, 0.909, ...]
-  },
-  "test": { "accuracy": 0.929, "f1": 0.929, "roc_auc": 0.971 }
-}
-```
-
-**XGBoost logs:**
-```json
-{
-  "config": { "n_estimators": 600, "max_depth": 8, "learning_rate": 0.149, ... },
-  "train_losses": [0.577, ...],
-  "val_losses":   [0.576, ...],
-  "test": { "accuracy": 0.959, "f1": 0.959, "roc_auc": 0.991 }
-}
-```
-
-## 3. Threshold justification
+**Logs:** MLP writes `face_orientation_training_log.json`, XGBoost writes `xgboost_face_orientation_training_log.json`. Paths: `evaluation/logs/`.
 
-Thresholds and weights used in the app (geometric, MLP, XGBoost, hybrid) are justified in **THRESHOLD_JUSTIFICATION.md**. The report is generated by:
+**Threshold report:** Generate `THRESHOLD_JUSTIFICATION.md` and plots with:
 
 ```bash
 python -m evaluation.justify_thresholds
 ```
 
-From repo root, with venv active. The script runs LOPO over 9 participants (~145k samples), computes ROC + Youden's J for ML/XGB thresholds, grid-searches geometric and hybrid weights, and plots EAR/MAR distributions. It writes:
-
-- `plots/roc_mlp.png`, `plots/roc_xgb.png`
-- `plots/geo_weight_search.png`, `plots/hybrid_weight_search.png`
-- `plots/ear_distribution.png`, `plots/mar_distribution.png`
-- `THRESHOLD_JUSTIFICATION.md`
-
-Takes ~10–15 minutes. Re-run after changing data or pipeline weights (e.g. geometric face/eye); hybrid optimal w_mlp depends on the geometric sub-score weights.
-
-## 4. Feature selection justification
-
-Run `python -m evaluation.feature_importance` to compute XGBoost gain-based importance for the 10 face_orientation features and a leave-one-feature-out LOPO ablation. Writes **feature_selection_justification.md** with tables. Use this to justify the 10-of-17 feature set (ablation + importance; see PAPER_AUDIT §2.7).
+(LOPO over 9 participants, Youden’s J, weight grid search; ~10–15 min.) Outputs go to `plots/` and the markdown file.
 
-## 5. Generated by
+**Feature importance:** Run `python -m evaluation.feature_importance` for XGBoost gain and leave-one-feature-out LOPO; writes `feature_selection_justification.md`.
 
-- `python -m models.mlp.train` → MLP log in `logs/`
-- `python -m models.xgboost.train` → XGBoost log in `logs/`
-- `python -m evaluation.justify_thresholds` → plots + THRESHOLD_JUSTIFICATION.md
-- `python -m evaluation.feature_importance` → feature_selection_justification.md
-- Notebooks in `notebooks/` can also write logs here
+**Who writes here:** `models.mlp.train`, `models.xgboost.train`, `evaluation.justify_thresholds`, `evaluation.feature_importance`, and the notebooks.

evaluation/feature_importance.py

@@ -70,7 +70,7 @@ def run_ablation_lopo():
                 n_estimators=600, max_depth=8, learning_rate=0.05,
                 subsample=0.8, colsample_bytree=0.8,
                 reg_alpha=0.1, reg_lambda=1.0,
-                use_label_encoder=False, eval_metric="logloss",
+                eval_metric="logloss",
                 random_state=SEED, verbosity=0,
             )
             xgb.fit(X_tr_sc, train_y)
@@ -96,7 +96,7 @@ def run_baseline_lopo_f1():
             n_estimators=600, max_depth=8, learning_rate=0.05,
             subsample=0.8, colsample_bytree=0.8,
             reg_alpha=0.1, reg_lambda=1.0,
-            use_label_encoder=False, eval_metric="logloss",
+            eval_metric="logloss",
             random_state=SEED, verbosity=0,
         )
         xgb.fit(X_tr_sc, train_y)
@@ -105,6 +105,47 @@ def run_baseline_lopo_f1():
     return np.mean(f1s)
 
 
+# Channel subsets for ablation (subset name -> list of feature names)
+CHANNEL_SUBSETS = {
+    "head_pose": ["head_deviation", "s_face", "pitch"],
+    "eye_state": ["ear_left", "ear_avg", "ear_right", "perclos"],
+    "gaze": ["h_gaze", "gaze_offset", "s_eye"],
+}
+
+
+def run_channel_ablation():
+    """LOPO XGBoost with head-only, eye-only, gaze-only, and all 10. Returns dict subset_name -> mean F1."""
+    by_person, _, _ = load_per_person("face_orientation")
+    persons = sorted(by_person.keys())
+    results = {}
+    for subset_name, feat_list in CHANNEL_SUBSETS.items():
+        idx_keep = [FEATURES.index(f) for f in feat_list]
+        f1s = []
+        for held_out in persons:
+            train_X = np.concatenate([by_person[p][0] for p in persons if p != held_out])
+            train_y = np.concatenate([by_person[p][1] for p in persons if p != held_out])
+            X_test, y_test = by_person[held_out]
+            X_tr = train_X[:, idx_keep]
+            X_te = X_test[:, idx_keep]
+            scaler = StandardScaler().fit(X_tr)
+            X_tr_sc = scaler.transform(X_tr)
+            X_te_sc = scaler.transform(X_te)
+            xgb = XGBClassifier(
+                n_estimators=600, max_depth=8, learning_rate=0.05,
+                subsample=0.8, colsample_bytree=0.8,
+                reg_alpha=0.1, reg_lambda=1.0,
+                eval_metric="logloss",
+                random_state=SEED, verbosity=0,
+            )
+            xgb.fit(X_tr_sc, train_y)
+            pred = xgb.predict(X_te_sc)
+            f1s.append(f1_score(y_test, pred, average="weighted"))
+        results[subset_name] = np.mean(f1s)
+    baseline = run_baseline_lopo_f1()
+    results["all_10"] = baseline
+    return results
+
+
 def main():
     print("=== Feature importance (XGBoost gain) ===")
     imp = xgb_feature_importance()
@@ -124,6 +165,11 @@ def main():
     worst_drop = min(ablation.items(), key=lambda x: x[1])
     print(f"  Largest F1 drop when dropping: {worst_drop[0]} (F1={worst_drop[1]:.4f})")
 
+    print("\n=== Channel ablation (LOPO mean F1) ===")
+    channel_f1 = run_channel_ablation()
+    for name, f1 in channel_f1.items():
+        print(f"  {name}: {f1:.4f}")
+
     out_dir = os.path.join(_PROJECT_ROOT, "evaluation")
     out_path = os.path.join(out_dir, "feature_selection_justification.md")
     lines = [

evaluation/justify_thresholds.py

@@ -95,7 +95,7 @@ def run_lopo_models():
             n_estimators=600, max_depth=8, learning_rate=0.05,
             subsample=0.8, colsample_bytree=0.8,
             reg_alpha=0.1, reg_lambda=1.0,
-            use_label_encoder=False, eval_metric="logloss",
+            eval_metric="logloss",
             random_state=SEED, verbosity=0,
         )
         xgb.fit(X_tr_sc, train_y)
@@ -430,7 +430,7 @@ def run_hybrid_xgb_weight_search(lopo_results):
             n_estimators=600, max_depth=8, learning_rate=0.05,
             subsample=0.8, colsample_bytree=0.8,
             reg_alpha=0.1, reg_lambda=1.0,
-            use_label_encoder=False, eval_metric="logloss",
+            eval_metric="logloss",
             random_state=SEED, verbosity=0,
         )
         xgb_tr.fit(X_tr_sc, train_y)
@@ -504,7 +504,7 @@ def run_hybrid_lr_combiner(lopo_results, use_xgb=True):
                 n_estimators=600, max_depth=8, learning_rate=0.05,
                 subsample=0.8, colsample_bytree=0.8,
                 reg_alpha=0.1, reg_lambda=1.0,
-                use_label_encoder=False, eval_metric="logloss",
+                eval_metric="logloss",
                 random_state=SEED, verbosity=0,
             )
             xgb_tr.fit(X_tr_sc, train_y)

evaluation/run_channel_ablation_only.py

@@ -0,0 +1,63 @@
+"""Run only channel ablation LOPO (no leave-one-out). Quick run for paper data."""
+import os
+import sys
+import numpy as np
+from sklearn.preprocessing import StandardScaler
+from sklearn.metrics import f1_score
+from xgboost import XGBClassifier
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, _PROJECT_ROOT)
+from data_preparation.prepare_dataset import load_per_person, SELECTED_FEATURES
+
+SEED = 42
+FEATURES = SELECTED_FEATURES["face_orientation"]
+CHANNEL_SUBSETS = {
+    "head_pose": ["head_deviation", "s_face", "pitch"],
+    "eye_state": ["ear_left", "ear_avg", "ear_right", "perclos"],
+    "gaze": ["h_gaze", "gaze_offset", "s_eye"],
+}
+
+
+def main():
+    by_person, _, _ = load_per_person("face_orientation")
+    persons = sorted(by_person.keys())
+    results = {}
+    for subset_name, feat_list in CHANNEL_SUBSETS.items():
+        idx_keep = [FEATURES.index(f) for f in feat_list]
+        f1s = []
+        for held_out in persons:
+            train_X = np.concatenate([by_person[p][0] for p in persons if p != held_out])
+            train_y = np.concatenate([by_person[p][1] for p in persons if p != held_out])
+            X_test, y_test = by_person[held_out]
+            X_tr = train_X[:, idx_keep]
+            X_te = X_test[:, idx_keep]
+            scaler = StandardScaler().fit(X_tr)
+            xgb = XGBClassifier(n_estimators=600, max_depth=8, learning_rate=0.05,
+                subsample=0.8, colsample_bytree=0.8, reg_alpha=0.1, reg_lambda=1.0,
+                eval_metric="logloss", random_state=SEED, verbosity=0)
+            xgb.fit(scaler.transform(X_tr), train_y)
+            pred = xgb.predict(scaler.transform(X_te))
+            f1s.append(f1_score(y_test, pred, average="weighted"))
+        results[subset_name] = np.mean(f1s)
+        print(f"{subset_name}: {results[subset_name]:.4f}")
+    # baseline
+    f1s = []
+    for held_out in persons:
+        train_X = np.concatenate([by_person[p][0] for p in persons if p != held_out])
+        train_y = np.concatenate([by_person[p][1] for p in persons if p != held_out])
+        X_test, y_test = by_person[held_out]
+        scaler = StandardScaler().fit(train_X)
+        xgb = XGBClassifier(n_estimators=600, max_depth=8, learning_rate=0.05,
+            subsample=0.8, colsample_bytree=0.8, reg_alpha=0.1, reg_lambda=1.0,
+            eval_metric="logloss", random_state=SEED, verbosity=0)
+        xgb.fit(scaler.transform(train_X), train_y)
+        pred = xgb.predict(scaler.transform(X_test))
+        f1s.append(f1_score(y_test, pred, average="weighted"))
+    results["all_10"] = np.mean(f1s)
+    print(f"all_10: {results['all_10']:.4f}")
+    return results
+
+
+if __name__ == "__main__":
+    main()

main.py

@@ -14,6 +14,7 @@ import math
 import os
 from pathlib import Path
 from typing import Callable
+from contextlib import asynccontextmanager
 import asyncio
 import concurrent.futures
 import threading
@@ -148,8 +149,42 @@ _MESH_INDICES = sorted(set(
 # Build a lookup: original_index -> position in sparse array, so client can reconstruct.
 _MESH_INDEX_SET = set(_MESH_INDICES)
 
-# Initialize FastAPI app
-app = FastAPI(title="Focus Guard API")
+@asynccontextmanager
+async def lifespan(app):
+    global _cached_model_name
+    print(" Starting Focus Guard API...")
+    await init_database()
+    async with aiosqlite.connect(db_path) as db:
+        cursor = await db.execute("SELECT model_name FROM user_settings WHERE id = 1")
+        row = await cursor.fetchone()
+        if row:
+            _cached_model_name = row[0]
+    print("[OK] Database initialized")
+    try:
+        pipelines["geometric"] = FaceMeshPipeline()
+        print("[OK] FaceMeshPipeline (geometric) loaded")
+    except Exception as e:
+        print(f"[WARN] FaceMeshPipeline unavailable: {e}")
+    try:
+        pipelines["mlp"] = MLPPipeline()
+        print("[OK] MLPPipeline loaded")
+    except Exception as e:
+        print(f"[ERR] Failed to load MLPPipeline: {e}")
+    try:
+        pipelines["hybrid"] = HybridFocusPipeline()
+        print("[OK] HybridFocusPipeline loaded")
+    except Exception as e:
+        print(f"[WARN] HybridFocusPipeline unavailable: {e}")
+    try:
+        pipelines["xgboost"] = XGBoostPipeline()
+        print("[OK] XGBoostPipeline loaded")
+    except Exception as e:
+        print(f"[ERR] Failed to load XGBoostPipeline: {e}")
+    yield
+    _inference_executor.shutdown(wait=False)
+    print(" Shutting down Focus Guard API...")
+
+app = FastAPI(title="Focus Guard API", lifespan=lifespan)
 
 # Add CORS middleware
 app.add_middleware(
@@ -163,7 +198,18 @@ app.add_middleware(
 # Global variables
 db_path = "focus_guard.db"
 pcs = set()
-_cached_model_name = "mlp"  # in-memory cache, updated via /api/settings
+_cached_model_name = "mlp"
+pipelines = {
+    "geometric": None,
+    "mlp": None,
+    "hybrid": None,
+    "xgboost": None,
+}
+_inference_executor = concurrent.futures.ThreadPoolExecutor(
+    max_workers=4,
+    thread_name_prefix="inference",
+)
+_pipeline_locks = {name: threading.Lock() for name in ("geometric", "mlp", "hybrid", "xgboost")}
 
 async def _wait_for_ice_gathering(pc: RTCPeerConnection):
     if pc.iceGatheringState == "complete":
@@ -454,72 +500,10 @@ class _EventBuffer:
         except Exception as e:
             print(f"[DB] Flush error: {e}")
 
-# ================ STARTUP/SHUTDOWN ================
-
-pipelines = {
-    "geometric": None,
-    "mlp": None,
-    "hybrid": None,
-    "xgboost": None,
-}
-
-# Thread pool for CPU-bound inference so the event loop stays responsive.
-_inference_executor = concurrent.futures.ThreadPoolExecutor(
-    max_workers=4,
-    thread_name_prefix="inference",
-)
-# One lock per pipeline so shared state (TemporalTracker, etc.) is not corrupted when
-# multiple frames are processed in parallel by the thread pool.
-_pipeline_locks = {name: threading.Lock() for name in ("geometric", "mlp", "hybrid", "xgboost")}
-
-
 def _process_frame_safe(pipeline, frame, model_name: str):
-    """Run process_frame in executor with per-pipeline lock."""
     with _pipeline_locks[model_name]:
         return pipeline.process_frame(frame)
 
-@app.on_event("startup")
-async def startup_event():
-    global pipelines, _cached_model_name
-    print(" Starting Focus Guard API...")
-    await init_database()
-    # Load cached model name from DB
-    async with aiosqlite.connect(db_path) as db:
-        cursor = await db.execute("SELECT model_name FROM user_settings WHERE id = 1")
-        row = await cursor.fetchone()
-        if row:
-            _cached_model_name = row[0]
-    print("[OK] Database initialized")
-
-    try:
-        pipelines["geometric"] = FaceMeshPipeline()
-        print("[OK] FaceMeshPipeline (geometric) loaded")
-    except Exception as e:
-        print(f"[WARN] FaceMeshPipeline unavailable: {e}")
-
-    try:
-        pipelines["mlp"] = MLPPipeline()
-        print("[OK] MLPPipeline loaded")
-    except Exception as e:
-        print(f"[ERR] Failed to load MLPPipeline: {e}")
-
-    try:
-        pipelines["hybrid"] = HybridFocusPipeline()
-        print("[OK] HybridFocusPipeline loaded")
-    except Exception as e:
-        print(f"[WARN] HybridFocusPipeline unavailable: {e}")
-
-    try:
-        pipelines["xgboost"] = XGBoostPipeline()
-        print("[OK] XGBoostPipeline loaded")
-    except Exception as e:
-        print(f"[ERR] Failed to load XGBoostPipeline: {e}")
-
-@app.on_event("shutdown")
-async def shutdown_event():
-    _inference_executor.shutdown(wait=False)
-    print(" Shutting down Focus Guard API...")
-
 # ================ WEBRTC SIGNALING ================
 
 @app.post("/api/webrtc/offer")
@@ -898,6 +882,22 @@ async def update_settings(settings: SettingsUpdate):
             await db.commit()
         return {"status": "success", "updated": len(updates) > 0}
 
+@app.get("/api/stats/system")
+async def get_system_stats():
+    """Return server CPU and memory usage for UI display."""
+    try:
+        import psutil
+        cpu = psutil.cpu_percent(interval=0.1)
+        mem = psutil.virtual_memory()
+        return {
+            "cpu_percent": round(cpu, 1),
+            "memory_percent": round(mem.percent, 1),
+            "memory_used_mb": round(mem.used / (1024 * 1024), 0),
+            "memory_total_mb": round(mem.total / (1024 * 1024), 0),
+        }
+    except ImportError:
+        return {"cpu_percent": None, "memory_percent": None, "memory_used_mb": None, "memory_total_mb": None}
+
 @app.get("/api/stats/summary")
 async def get_stats_summary():
     async with aiosqlite.connect(db_path) as db:

models/README.md

@@ -1,51 +1,16 @@
 # models/
 
-Feature extraction modules and model training scripts.
+Feature extraction (face mesh, head pose, eye scorer, collect_features) and training scripts.
 
-## 1. Feature Extraction
+**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.
 
-Root-level modules form the real-time inference pipeline:
+**Training:**
 
-| 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 |
-| `collect_features.py` | BGR frame | 17-d feature vector + temporal features (PERCLOS, blink rate, etc.) |
+| 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 |
 
-## 2. Training Scripts
+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).
 
-| 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 |
+**Results:** XGBoost 95.87% acc, 0.959 F1, 0.991 AUC; MLP 92.92%, 0.929, 0.971.

models/xgboost/add_accuracy.py

@@ -32,7 +32,6 @@ for idx, row in df.iterrows():
         "reg_alpha": float(row["reg_alpha"]),
         "reg_lambda": float(row["reg_lambda"]),
         "random_state": 42,
-        "use_label_encoder": False,
         "verbosity": 0,
         "eval_metric": "logloss"
     }

models/xgboost/sweep_local.py

@@ -35,7 +35,6 @@ def objective(trial):
         "reg_lambda": trial.suggest_float("reg_lambda", 0.5, 5.0),
         "eval_metric": "logloss",
         "random_state": SEED,
-        "use_label_encoder": False,
         "verbosity": 0
     }
 

models/xgboost/train.py

@@ -81,7 +81,8 @@ def main():
         eval_set=[(X_train, y_train), (X_val, y_val)],
         verbose=10,
     )
-    print(f"[TRAIN] Best iteration: {model.best_iteration} / {CFG['n_estimators']}")
+    best_it = getattr(model, "best_iteration", None)
+    print(f"[TRAIN] Best iteration: {best_it} / {CFG['n_estimators']}")
 
     # ── Evaluation ────────────────────────────────────────────────
     evals = model.evals_result()

notebooks/README.md

@@ -1,42 +1,7 @@
 # notebooks/
 
-Training and evaluation notebooks for MLP and XGBoost models.
+MLP and XGBoost training + LOPO evaluation.
 
-## 1. Files
+**Files:** `mlp.ipynb`, `xgboost.ipynb`. Same flow: config → data from prepare_dataset → 70/15/15 train → loss curves → test metrics → save checkpoint + JSON log → LOPO over 9 participants.
 
-| Notebook | Model | Description |
-|----------|-------|-------------|
-| `mlp.ipynb` | PyTorch MLP | Training, evaluation, and LOPO cross-validation |
-| `xgboost.ipynb` | XGBoost | Training, evaluation, and LOPO cross-validation |
-
-## 2. Structure (both notebooks)
-
-Each notebook follows the same layout:
-
-1. **Imports and CFG** — single config dict, project root setup
-2. **ClearML (optional)** — opt-in experiment tracking
-3. **Data loading** — uses `data_preparation.prepare_dataset` for consistent loading
-4. **Random split training** — 70/15/15 stratified split with per-epoch/round logging
-5. **Loss curves** — train vs validation loss plots
-6. **Test evaluation** — accuracy, F1, ROC-AUC, classification report, confusion matrix
-7. **Checkpoint saving** — model weights + JSON training log
-8. **LOPO evaluation** — Leave-One-Person-Out cross-validation across all 9 participants
-9. **LOPO summary** — per-person accuracy table + bar chart
-
-## 3. Running
-
-Open in Jupyter or VS Code with the Python kernel set to the project venv:
-
-```bash
-source venv/bin/activate
-jupyter notebook notebooks/mlp.ipynb
-```
-
-Make sure the kernel's working directory is either the project root or `notebooks/` — the path resolution handles both.
-
-## 4. Results
-
-| Model | Random Split Accuracy | Random Split F1 | LOPO (mean) |
-|-------|-----------------------|-----------------|-------------|
-| XGBoost | 95.87% | 0.959 | see notebook |
-| MLP | 92.92% | 0.929 | see notebook |
+Run in Jupyter with the project venv; set kernel cwd to repo root or `notebooks/`.

notebooks/xgboost.ipynb

@@ -169,7 +169,6 @@
         "    reg_alpha=CFG[\"reg_alpha\"],\n",
         "    reg_lambda=CFG[\"reg_lambda\"],\n",
         "    eval_metric=CFG[\"eval_metric\"],\n",
-        "    use_label_encoder=False,\n",
         "    random_state=CFG[\"seed\"],\n",
         "    verbosity=1,\n",
         ")\n",
@@ -355,7 +354,6 @@
         "        reg_alpha=cfg[\"reg_alpha\"],\n",
         "        reg_lambda=cfg[\"reg_lambda\"],\n",
         "        eval_metric=cfg[\"eval_metric\"],\n",
-        "        use_label_encoder=False,\n",
         "        random_state=cfg[\"seed\"],\n",
         "        verbosity=0,\n",
         "    )\n",

requirements.txt

@@ -11,7 +11,10 @@ joblib>=1.2.0
 torch>=2.0.0
 fastapi>=0.104.0
 uvicorn[standard]>=0.24.0
+httpx>=0.24.0
 aiosqlite>=0.19.0
+psutil>=5.9.0
 pydantic>=2.0.0
 xgboost>=2.0.0
 clearml>=2.0.2
+pytest>=7.0.0

src/App.css

@@ -106,16 +106,15 @@ body {
 /* PAGE A SPECIFIC */
 #page-a {
     justify-content: center; /* Center vertically */
-    /* 注意：因为 React 结构变化，如果感觉偏下，可以微调这个 margin-top */
     margin-top: -40px; 
-    flex: 1; /* 确保它占满剩余空间以便垂直居中 */
+    flex: 1;
 }
 
 #page-a h1 {
     font-size: 80px;
     margin: 0 0 10px 0;
     color: #000;
-    text-align: center; /* 确保文字居中 */
+    text-align: center;
 }
 
 #page-a p {
@@ -145,13 +144,13 @@ body {
 #page-b {
     justify-content: space-evenly; /* Distribute vertical space */
     padding-bottom: 20px;
-    min-height: calc(100vh - 60px); /* 再次确保高度足够 */
+    min-height: calc(100vh - 60px);
 }
 
 /* 1. Display Area */
 #display-area {
     width: 60%;
-    height: 50vh; /* 改用 vh 单位，确保在不同屏幕下的高度比例 */
+    height: 50vh;
     min-height: 300px;
     border: 2px solid #ddd;
     border-radius: 12px;
@@ -162,14 +161,13 @@ body {
     color: #555;
     font-size: 24px;
     position: relative;
-    /* 确保视频元素也能居中且不溢出 */
     overflow: hidden; 
 }
 
 #display-area video {
     width: 100%;
     height: 100%;
-    object-fit: cover; /* 类似于 background-size: cover */
+    object-fit: cover;
 }
 
 /* 2. Timeline Area */
@@ -367,7 +365,6 @@ body {
 #focus-chart {
     display: block;
     margin: 0 auto;
-    /* 确保图表在容器内自适应 */
     max-width: 100%;
 }
 
@@ -504,13 +501,12 @@ input[type="number"] {
     font-family: 'Nunito', sans-serif;
 }
 
-/* --- 新的代码：让按钮居中且变宽 --- */
 .setting-group .action-btn {
-    display: inline-block;   /* 允许并排显示 */
-    width: 48%;              /* 两个按钮各占约一半宽度 (留2%缝隙) */
-    margin: 15px 1%;         /* 上下 15px，左右 1% 间距来实现居中和分隔 */
-    text-align: center;      /* 文字居中 */
-    box-sizing: border-box;  /* 确保边框不会撑大按钮导致换行 */
+    display: inline-block;
+    width: 48%;
+    margin: 15px 1%;
+    text-align: center;
+    box-sizing: border-box;
 }
 
 #save-settings {
@@ -625,7 +621,6 @@ details p {
 }
 
 /* ================ SESSION SUMMARY MODAL ================ */
-/* 如果将来要做弹窗，这些样式可以直接复用 */
 .modal-overlay {
     position: fixed;
     top: 0;
@@ -743,17 +738,14 @@ details p {
         flex-direction: column;
     }
 }
-/* =========================================
-   SESSION RESULT OVERLAY (新增)
-   ========================================= */
-
+/* SESSION RESULT OVERLAY */
 .session-result-overlay {
     position: absolute;
     top: 0;
     left: 0;
     width: 100%;
     height: 100%;
-    background-color: rgba(0, 0, 0, 0.85); /* 深色半透明背景 */
+    background-color: rgba(0, 0, 0, 0.85);
     display: flex;
     flex-direction: column;
     justify-content: center;
@@ -761,13 +753,13 @@ details p {
     color: white;
     z-index: 10;
     animation: fadeIn 0.5s ease;
-    backdrop-filter: blur(5px); /* 背景模糊效果 (可选) */
+    backdrop-filter: blur(5px);
 }
 
 .session-result-overlay h3 {
     font-size: 32px;
     margin-bottom: 30px;
-    color: #4cd137; /* 绿色标题 */
+    color: #4cd137;
     text-transform: uppercase;
     letter-spacing: 2px;
 }
@@ -775,7 +767,7 @@ details p {
 .session-result-overlay .result-item {
     display: flex;
     justify-content: space-between;
-    width: 200px; /* 控制宽度 */
+    width: 200px;
     margin-bottom: 15px;
     font-size: 20px;
     border-bottom: 1px solid rgba(255,255,255,0.2);
@@ -790,7 +782,7 @@ details p {
 .session-result-overlay .value {
     color: #fff;
     font-weight: bold;
-    font-family: 'Courier New', monospace; /* 看起来像数据 */
+    font-family: 'Courier New', monospace;
 }
 
 @keyframes fadeIn {
@@ -798,7 +790,7 @@ details p {
     to { opacity: 1; transform: scale(1); }
 }
 
-/* ================= 迎宾弹窗样式 ================= */
+/* welcome modal */
 .welcome-modal-overlay {
 position: fixed;
 top: 0; left: 0; right: 0; bottom: 0;
@@ -822,7 +814,7 @@ border: 1px solid #333;
 .welcome-modal p { margin-bottom: 30px; color: #ccc; }
 .welcome-buttons { display: flex; gap: 20px; justify-content: center; }
 
-/* ================= 左上角头像样式 (修改版) ================= */
+/* top avatar */
 #top-menu {
 position: relative;
 display: flex;
@@ -852,30 +844,29 @@ border: 2px solid transparent;
 
 .avatar-circle.user { background-color: #555; }
 .avatar-circle.admin { background-color: #ffaa00; border-color: #fff; box-shadow: 0 0 10px rgba(255, 170, 0, 0.5); }
-/* ================= 首页按钮 2x2 响应式网格 (终极修正版) ================= */
+/* home 2x2 button grid */
 .home-button-grid {
   display: grid;
-  grid-template-columns: 1fr 1fr; /* 强行平分两列，绝不妥协 */
-  gap: 20px; /* 按钮之间的间距 */
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
   width: 100%;
-  max-width: 500px; /* 限制最大宽度，宽屏下也不会显得傻大黑粗 */
-  margin: 40px auto 0 auto; /* 上边距40px，左右auto保证绝对居中！ */
+  max-width: 500px;
+  margin: 40px auto 0 auto;
 }
 
 .home-button-grid .btn-main {
   width: 100%;
-  height: 60px; /* 统一高度，像一块块整齐的砖头 */
-  margin: 0; /* 清除默认外边距 */
+  height: 60px;
+  margin: 0;
   padding: 10px;
   font-size: 1rem;
   display: flex;
   justify-content: center;
   align-items: center;
   text-align: center;
-  box-sizing: border-box; /* 保证边框和内边距不会撑破格子 */
+  box-sizing: border-box;
 }
 
-/* 📱 手机端专属适配 (屏幕宽度小于 600px 时自动缩放) */
 @media (max-width: 600px) {
   .home-button-grid {
     gap: 15px; 

src/App.jsx

@@ -16,7 +16,7 @@ function App() {
   const [sessionResult, setSessionResult] = useState(null);
   const [role, setRole] = useState('user'); 
 
-  // 刚进网页时，静默清空数据库，不弹窗！
+  //
   useEffect(() => {
     fetch('/api/history', { method: 'DELETE' }).catch(err => console.error(err));
 
@@ -37,7 +37,7 @@ function App() {
     };
   }, []);
 
-  // 点击头像，直接跳转到首页(Home)
+  //
   const handleAvatarClick = () => {
     setActiveTab('home');
   };
@@ -76,7 +76,7 @@ function App() {
         </button>
       </nav>
 
-      {/* 把核心状态传给 Home 组件 */}
+      {/* pass state to Home */}
       {activeTab === 'home' && <Home setActiveTab={setActiveTab} role={role} setRole={setRole} />}
       
       <FocusPageLocal

src/components/Achievement.jsx

@@ -7,10 +7,10 @@ function Achievement() {
     avg_focus_score: 0,
     streak_days: 0
   });
+  const [systemStats, setSystemStats] = useState(null);
   const [badges, setBadges] = useState([]);
   const [loading, setLoading] = useState(true);
 
-  // 格式化时间显示
   const formatTime = (seconds) => {
     const hours = Math.floor(seconds / 3600);
     const minutes = Math.floor((seconds % 3600) / 60);
@@ -18,7 +18,6 @@ function Achievement() {
     return `${minutes}m`;
   };
 
-  // 加载统计数据
   useEffect(() => {
     fetch('/api/stats/summary')
       .then(res => res.json())
@@ -33,11 +32,21 @@ function Achievement() {
       });
   }, []);
 
-  // 根据统计数据计算徽章
+  useEffect(() => {
+    const fetchSystem = () => {
+      fetch('/api/stats/system')
+        .then(res => res.json())
+        .then(data => setSystemStats(data))
+        .catch(() => setSystemStats(null));
+    };
+    fetchSystem();
+    const interval = setInterval(fetchSystem, 3000);
+    return () => clearInterval(interval);
+  }, []);
+
   const calculateBadges = (data) => {
     const earnedBadges = [];
 
-    // 首次会话徽章
     if (data.total_sessions >= 1) {
       earnedBadges.push({
         id: 'first-session',
@@ -48,7 +57,6 @@ function Achievement() {
       });
     }
 
-    // 10次会话徽章
     if (data.total_sessions >= 10) {
       earnedBadges.push({
         id: 'ten-sessions',
@@ -59,7 +67,6 @@ function Achievement() {
       });
     }
 
-    // 50次会话徽章
     if (data.total_sessions >= 50) {
       earnedBadges.push({
         id: 'fifty-sessions',
@@ -70,7 +77,6 @@ function Achievement() {
       });
     }
 
-    // 专注大师徽章 (平均专注度 > 80%)
     if (data.avg_focus_score >= 0.8 && data.total_sessions >= 5) {
       earnedBadges.push({
         id: 'focus-master',
@@ -81,7 +87,6 @@ function Achievement() {
       });
     }
 
-    // 连续天数徽章
     if (data.streak_days >= 7) {
       earnedBadges.push({
         id: 'week-streak',
@@ -102,7 +107,6 @@ function Achievement() {
       });
     }
 
-    // 时长徽章 (10小时+)
     if (data.total_focus_time >= 36000) {
       earnedBadges.push({
         id: 'ten-hours',
@@ -113,7 +117,6 @@ function Achievement() {
       });
     }
 
-    // 未解锁徽章（示例）
     const allBadges = [
       {
         id: 'first-session',
@@ -186,6 +189,22 @@ function Achievement() {
         </div>
       ) : (
         <>
+          {systemStats && systemStats.cpu_percent != null && (
+            <div style={{
+              textAlign: 'center',
+              marginBottom: '12px',
+              padding: '8px 12px',
+              background: 'rgba(0,0,0,0.2)',
+              borderRadius: '8px',
+              fontSize: '13px',
+              color: '#aaa'
+            }}>
+              Server: CPU <strong style={{ color: '#8f8' }}>{systemStats.cpu_percent}%</strong>
+              {' · '}
+              RAM <strong style={{ color: '#8af' }}>{systemStats.memory_percent}%</strong>
+              {systemStats.memory_used_mb != null && ` (${systemStats.memory_used_mb}/${systemStats.memory_total_mb} MB)`}
+            </div>
+          )}
           <div className="stats-grid">
             <div className="stat-card">
               <div className="stat-number" id="total-sessions">{stats.total_sessions}</div>

src/components/Customise.jsx

@@ -6,10 +6,10 @@ function Customise() {
   const [notificationsEnabled, setNotificationsEnabled] = useState(true);
   const [threshold, setThreshold] = useState(30);
   
-  // 引用隐藏的文件输入框
+  //
   const fileInputRef = useRef(null);
 
-  // 1. 加载设置
+  //
   useEffect(() => {
     fetch('/api/settings')
       .then(res => res.json())
@@ -24,7 +24,7 @@ function Customise() {
       .catch(err => console.error("Failed to load settings", err));
   }, []);
 
-  // 2. 保存设置
+  //
   const handleSave = async () => {
     const settings = {
       sensitivity: parseInt(sensitivity),
@@ -46,34 +46,34 @@ function Customise() {
     }
   };
 
-  // 3. 导出数据 (Export)
+  //
   const handleExport = async () => {
     try {
-      // 请求获取所有历史记录
+      //
       const response = await fetch('/api/sessions?filter=all');
       if (!response.ok) throw new Error("Failed to fetch data");
       
       const data = await response.json();
       
-      // 创建 JSON Blob
+      //
       const jsonString = JSON.stringify(data, null, 2);
-      // 在浏览器缓存里存一份
+      //
       localStorage.setItem('focus_magic_backup', jsonString);
 
       const blob = new Blob([jsonString], { type: 'application/json' });
       
-      // 创建临时下载链接
+      //
       const url = URL.createObjectURL(blob);
       const link = document.createElement('a');
       link.href = url;
-      // 文件名包含当前日期
+      //
       link.download = `focus-guard-backup-${new Date().toISOString().slice(0, 10)}.json`;
       
-      // 触发下载
+      //
       document.body.appendChild(link);
       link.click();
       
-      // 清理
+      //
       document.body.removeChild(link);
       URL.revokeObjectURL(url);
     } catch (error) {
@@ -82,12 +82,12 @@ function Customise() {
     }
   };
 
-  // 4. 触发导入文件选择
+  //
   const triggerImport = () => {
     fileInputRef.current.click();
   };
 
-  // 5. 处理文件导入 (Import)
+  //
   const handleFileChange = async (event) => {
     const file = event.target.files[0];
     if (!file) return;
@@ -98,12 +98,12 @@ function Customise() {
         const content = e.target.result;
         const sessions = JSON.parse(content);
 
-        // 简单的验证：确保它是一个数组
+        //
         if (!Array.isArray(sessions)) {
           throw new Error("Invalid file format: Expected a list of sessions.");
         }
 
-        // 发送给后端进行存储
+        //
         const response = await fetch('/api/import', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -119,13 +119,13 @@ function Customise() {
       } catch (err) {
         alert("Error parsing file: " + err.message);
       }
-      // 清空 input，允许重复上传同一个文件
+      //
       event.target.value = '';
     };
     reader.readAsText(file);
   };
 
-  // 6. 清除历史 (Clear History)
+  //
   const handleClearHistory = async () => {
     if (!window.confirm("Are you sure? This will delete ALL your session history permanently.")) {
         return;
@@ -187,7 +187,7 @@ function Customise() {
         <div className="setting-group">
           <h2>Data Management</h2>
           
-          {/* 隐藏的文件输入框，只接受 json */}
+          {/* hidden file input, json only */}
           <input 
             type="file" 
             ref={fileInputRef} 
@@ -197,17 +197,17 @@ function Customise() {
           />
 
           <div style={{ display: 'flex', gap: '10px', justifyContent: 'center', flexWrap: 'wrap' }}>
-            {/* Export 按钮 */}
+            {/* Export */}
             <button id="export-data" className="action-btn blue" onClick={handleExport} style={{ width: '30%', minWidth: '120px' }}>
                 Export Data
             </button>
             
-            {/* Import 按钮 */}
+            {/* Import */}
             <button id="import-data" className="action-btn yellow" onClick={triggerImport} style={{ width: '30%', minWidth: '120px' }}>
                 Import Data
             </button>
             
-            {/* Clear 按钮 */}
+            {/* Clear */}
             <button id="clear-history" className="action-btn red" onClick={handleClearHistory} style={{ width: '30%', minWidth: '120px' }}>
                 Clear History
             </button>

src/components/FocusPage.jsx

@@ -6,9 +6,9 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
 
   const videoRef = displayVideoRef;
 
-  // 辅助函数：格式化时间
+  //
   const formatDuration = (seconds) => {
-    // 如果是 0，直接显示 0s (或者你可以保留原来的 0m 0s)
+    //
     if (seconds === 0) return "0s";
 
     const mins = Math.floor(seconds / 60);
@@ -19,7 +19,7 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
   useEffect(() => {
     if (!videoManager) return;
 
-    // 设置回调函数来更新时间轴
+    //
     const originalOnStatusUpdate = videoManager.callbacks.onStatusUpdate;
     videoManager.callbacks.onStatusUpdate = (isFocused) => {
       setTimelineEvents(prev => {
@@ -27,11 +27,11 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
         if (newEvents.length > 60) newEvents.shift();
         return newEvents;
       });
-      // 调用原始回调（如果有）
+      //
       if (originalOnStatusUpdate) originalOnStatusUpdate(isFocused);
     };
 
-    // 清理函数：不再自动停止session，只清理回调
+    //
     return () => {
       if (videoManager) {
         videoManager.callbacks.onStatusUpdate = originalOnStatusUpdate;
@@ -42,7 +42,7 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
   const handleStart = async () => {
     try {
       if (videoManager) {
-        setSessionResult(null); // 开始时清除结果层
+        setSessionResult(null);
         setTimelineEvents([]);
 
         console.log('🎬 Initializing camera...');
@@ -114,16 +114,16 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
     }
   };
 
-  // 浮窗功能
+  //
   const handleFloatingWindow = () => {
     handlePiP();
   };
 
   // ==========================================
-  // 新增功能：预览按钮的处理函数
+  //
   // ==========================================
   const handlePreview = () => {
-    // 强制设置一个 0 分 0 秒的假数据，触发 overlay 显示
+    //
     setSessionResult({
         duration_seconds: 0,
         focus_score: 0
@@ -165,7 +165,7 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
           style={{ width: '100%', height: '100%', objectFit: 'contain' }}
         />
 
-        {/* 结果覆盖层 */}
+        {/* result overlay */}
         {sessionResult && (
           <div className="session-result-overlay">
             <h3>Session Complete!</h3>
@@ -178,7 +178,7 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
               <span className="value">{(sessionResult.focus_score * 100).toFixed(1)}%</span>
             </div>
             
-            {/* 新增：加一个小按钮方便关闭预览 */}
+            {/* close preview */}
             <button 
                 onClick={handleCloseOverlay}
                 style={{
@@ -226,11 +226,11 @@ function FocusPage({ videoManager, sessionResult, setSessionResult, isActive, di
         <button id="btn-cam-start" className="action-btn green" onClick={handleStart}>Start</button>
         <button id="btn-floating" className="action-btn yellow" onClick={handleFloatingWindow}>Floating Window</button>
         
-        {/* 修改：把 Models 按钮暂时改成 Preview 按钮，或者加在它后面 */}
+        {/* preview button */}
         <button 
             id="btn-preview" 
             className="action-btn" 
-            style={{ backgroundColor: '#6c5ce7' }} // 紫色按钮以示区别
+            style={{ backgroundColor: '#6c5ce7' }}
             onClick={handlePreview}
         >
             Preview Result

src/components/FocusPageLocal.jsx

@@ -4,15 +4,15 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
   const [currentFrame, setCurrentFrame] = useState(15);
   const [timelineEvents, setTimelineEvents] = useState([]);
   const [stats, setStats] = useState(null);
+  const [systemStats, setSystemStats] = useState(null);
   const [availableModels, setAvailableModels] = useState([]);
   const [currentModel, setCurrentModel] = useState('mlp');
 
   const localVideoRef = useRef(null);
   const displayCanvasRef = useRef(null);
-  const pipVideoRef = useRef(null); // 用于 PiP 的隐藏 video 元素
+  const pipVideoRef = useRef(null);
   const pipStreamRef = useRef(null);
 
-  // 辅助函数：格式化时间
   const formatDuration = (seconds) => {
     if (seconds === 0) return "0s";
     const mins = Math.floor(seconds / 60);
@@ -23,7 +23,6 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
   useEffect(() => {
     if (!videoManager) return;
 
-    // 设置回调函数来更新时间轴
     const originalOnStatusUpdate = videoManager.callbacks.onStatusUpdate;
     videoManager.callbacks.onStatusUpdate = (isFocused) => {
       setTimelineEvents(prev => {
@@ -34,7 +33,6 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
       if (originalOnStatusUpdate) originalOnStatusUpdate(isFocused);
     };
 
-    // 定期更新统计信息
     const statsInterval = setInterval(() => {
       if (videoManager && videoManager.getStats) {
         setStats(videoManager.getStats());
@@ -60,6 +58,19 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
       .catch(err => console.error('Failed to fetch models:', err));
   }, []);
 
+  // Poll server CPU/memory for UI
+  useEffect(() => {
+    const fetchSystem = () => {
+      fetch('/api/stats/system')
+        .then(res => res.json())
+        .then(data => setSystemStats(data))
+        .catch(() => setSystemStats(null));
+    };
+    fetchSystem();
+    const interval = setInterval(fetchSystem, 3000);
+    return () => clearInterval(interval);
+  }, []);
+
   const handleModelChange = async (modelName) => {
     try {
       const res = await fetch('/api/settings', {
@@ -129,7 +140,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
 
   const handlePiP = async () => {
     try {
-      // 检查是否有视频管理器和是否在运行
+      //
       if (!videoManager || !videoManager.isStreaming) {
         alert('Please start the video first.');
         return;
@@ -140,20 +151,20 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
         return;
       }
 
-      // 如果已经在 PiP 模式，且是本视频，退出
+      //
       if (document.pictureInPictureElement === pipVideoRef.current) {
         await document.exitPictureInPicture();
         console.log('PiP exited');
         return;
       }
 
-      // 检查浏览器支持
+      //
       if (!document.pictureInPictureEnabled) {
         alert('Picture-in-Picture is not supported in this browser.');
         return;
       }
 
-      // 创建或获取 PiP video 元素
+      //
       const pipVideo = pipVideoRef.current;
       if (!pipVideo) {
         alert('PiP video element not ready.');
@@ -162,7 +173,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
 
       const isSafariPiP = typeof pipVideo.webkitSetPresentationMode === 'function';
 
-      // 优先用画布流（带检测框），失败再回退到摄像头流
+      //
       let stream = pipStreamRef.current;
       if (!stream) {
         const capture = displayCanvasRef.current.captureStream;
@@ -180,7 +191,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
         pipStreamRef.current = stream;
       }
 
-      // 确保流有轨道
+      //
       if (!stream || stream.getTracks().length === 0) {
         alert('Failed to capture video stream from canvas.');
         return;
@@ -188,7 +199,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
 
       pipVideo.srcObject = stream;
 
-      // 播放视频（Safari 可能不会触发 onloadedmetadata）
+      //
       if (pipVideo.readyState < 2) {
         await new Promise((resolve) => {
           const onReady = () => {
@@ -198,7 +209,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
           };
           pipVideo.addEventListener('loadeddata', onReady);
           pipVideo.addEventListener('canplay', onReady);
-          // 兜底：短延迟后继续尝试
+          //
           setTimeout(resolve, 600);
         });
       }
@@ -206,17 +217,17 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
       try {
         await pipVideo.play();
       } catch (_) {
-        // Safari 可能拒绝自动播放，但仍可进入 PiP
+        //
       }
 
-      // Safari 支持（优先）
+      //
       if (isSafariPiP) {
         try {
           pipVideo.webkitSetPresentationMode('picture-in-picture');
           console.log('PiP activated (Safari)');
           return;
         } catch (e) {
-          // 如果画布流失败，回退到摄像头流再试一次
+          //
           const cameraStream = localVideoRef.current?.srcObject;
           if (cameraStream && cameraStream !== pipVideo.srcObject) {
             pipVideo.srcObject = cameraStream;
@@ -231,7 +242,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
         }
       }
 
-      // 标准 API
+      //
       if (typeof pipVideo.requestPictureInPicture === 'function') {
         await pipVideo.requestPictureInPicture();
         console.log('PiP activated');
@@ -263,7 +274,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
       return;
     }
 
-    // 获取当前统计数据
+    //
     const currentStats = videoManager.getStats();
 
     if (!currentStats.sessionId) {
@@ -271,15 +282,15 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
       return;
     }
 
-    // 计算当前持续时间（从 session 开始到现在）
+    //
     const sessionDuration = Math.floor((Date.now() - (videoManager.sessionStartTime || Date.now())) / 1000);
 
-    // 计算当前专注分数
+    //
     const focusScore = currentStats.framesProcessed > 0
       ? (currentStats.framesProcessed * (currentStats.currentStatus ? 1 : 0)) / currentStats.framesProcessed
       : 0;
 
-    // 显示当前实时数据
+    //
     setSessionResult({
       duration_seconds: sessionDuration,
       focus_score: focusScore,
@@ -320,7 +331,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
     <main id="page-b" className="page" style={pageStyle}>
       {/* 1. Camera / Display Area */}
       <section id="display-area" style={{ position: 'relative', overflow: 'hidden' }}>
-        {/* 用于 PiP 的隐藏 video 元素（保持在 DOM 以提高兼容性） */}
+        {/* hidden PiP video element */}
         <video
           ref={pipVideoRef}
           muted
@@ -334,7 +345,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
             pointerEvents: 'none'
           }}
         />
-        {/* 本地视频流（隐藏，仅用于截图） */}
+        {/* local video (hidden, for capture) */}
         <video
           ref={localVideoRef}
           muted
@@ -343,7 +354,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
           style={{ display: 'none' }}
         />
 
-        {/* 显示处理后的视频（使用 Canvas） */}
+        {/* processed video (canvas) */}
         <canvas
           ref={displayCanvasRef}
           width={640}
@@ -356,7 +367,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
           }}
         />
 
-        {/* 结果覆盖层 */}
+        {/* result overlay */}
         {sessionResult && (
           <div className="session-result-overlay">
             <h3>Session Complete!</h3>
@@ -386,7 +397,7 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
           </div>
         )}
 
-        {/* 性能统计显示（开发模式） */}
+        {/* stats overlay */}
         {stats && stats.isStreaming && (
           <div style={{
             position: 'absolute',
@@ -405,10 +416,36 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
             <div>Latency: {stats.avgLatency.toFixed(0)}ms</div>
             <div>Status: {stats.currentStatus ? 'Focused' : 'Not Focused'}</div>
             <div>Confidence: {(stats.lastConfidence * 100).toFixed(1)}%</div>
+            {systemStats && systemStats.cpu_percent != null && (
+              <div style={{ marginTop: '6px', borderTop: '1px solid #444', paddingTop: '4px' }}>
+                <div>CPU: {systemStats.cpu_percent}%</div>
+                <div>RAM: {systemStats.memory_percent}% ({systemStats.memory_used_mb}/{systemStats.memory_total_mb} MB)</div>
+              </div>
+            )}
           </div>
         )}
       </section>
 
+      {/* Server CPU / Memory (always visible) */}
+      {systemStats && (systemStats.cpu_percent != null || systemStats.memory_percent != null) && (
+        <section style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: '16px',
+          padding: '6px 12px',
+          background: 'rgba(0,0,0,0.3)',
+          borderRadius: '8px',
+          margin: '6px auto',
+          maxWidth: '400px',
+          fontSize: '13px',
+          color: '#aaa'
+        }}>
+          <span title="Server CPU">CPU: <strong style={{ color: '#8f8' }}>{systemStats.cpu_percent}%</strong></span>
+          <span title="Server memory">RAM: <strong style={{ color: '#8af' }}>{systemStats.memory_percent}%</strong> ({systemStats.memory_used_mb}/{systemStats.memory_total_mb} MB)</span>
+        </section>
+      )}
+
       {/* 2. Model Selector */}
       {availableModels.length > 0 && (
         <section style={{

src/components/Home.jsx

@@ -3,13 +3,13 @@ import React, { useRef } from 'react';
 function Home({ setActiveTab, role, setRole }) {
   const fileInputRef = useRef(null);
 
-  // 1. 开始新生活
+  //
   const handleNewStart = async () => {
     await fetch('/api/history', { method: 'DELETE' });
     setActiveTab('focus');
   };
 
-  // 2. 自动导入 (使用缓存魔术)
+  //
   const handleAutoImport = async () => {
     const backup = localStorage.getItem('focus_magic_backup');
     if (backup) {
@@ -33,7 +33,7 @@ function Home({ setActiveTab, role, setRole }) {
     }
   };
 
-  // 3. 手动导入
+  //
   const handleFileChange = async (event) => {
     const file = event.target.files[0];
     if (!file) return;
@@ -57,7 +57,7 @@ function Home({ setActiveTab, role, setRole }) {
     reader.readAsText(file);
   };
 
-  // 4. 切换 Admin/User 模式
+  //
   const handleAdminToggle = async () => {
     if (role === 'admin') {
       if (window.confirm("Switch back to User mode? Current data will be cleared.")) {
@@ -96,10 +96,10 @@ function Home({ setActiveTab, role, setRole }) {
       <h1>FocusGuard</h1>
       <p>Your productivity monitor assistant.</p>
 
-      {/* 🔪 把隐藏的上传框放在网格外面，绝对不让它占格子！ */}
+      {/* hidden file input outside grid */}
       <input type="file" ref={fileInputRef} style={{ display: 'none' }} accept=".json" onChange={handleFileChange} />
 
-      {/* 使用全新的 2x2 网格容器，里面只放 4 个纯净的按钮 */}
+      {/* 2x2 button grid */}
       <div className="home-button-grid">
         
         <button className="btn-main" onClick={handleNewStart}>

src/components/Records.jsx

@@ -6,14 +6,14 @@ function Records() {
   const [loading, setLoading] = useState(false);
   const chartRef = useRef(null);
 
-  // 格式化时间
+  //
   const formatDuration = (seconds) => {
     const mins = Math.floor(seconds / 60);
     const secs = seconds % 60;
     return `${mins}m ${secs}s`;
   };
 
-  // 格式化日期
+  //
   const formatDate = (dateString) => {
     const date = new Date(dateString);
     return date.toLocaleDateString('en-US', {
@@ -24,7 +24,7 @@ function Records() {
     });
   };
 
-  // 加载会话数据
+  //
   const loadSessions = async (filterType) => {
     setLoading(true);
     try {
@@ -39,7 +39,7 @@ function Records() {
     }
   };
 
-  // 绘制图表
+  //
   const drawChart = (data) => {
     const canvas = chartRef.current;
     if (!canvas) return;
@@ -48,7 +48,7 @@ function Records() {
     const width = canvas.width = canvas.offsetWidth;
     const height = canvas.height = 300;
 
-    // 清空画布
+    //
     ctx.clearRect(0, 0, width, height);
 
     if (data.length === 0) {
@@ -59,17 +59,17 @@ function Records() {
       return;
     }
 
-    // 准备数据 (最多显示最近20个会话)
+    //
     const displayData = data.slice(0, 20).reverse();
     const padding = 50;
     const chartWidth = width - padding * 2;
     const chartHeight = height - padding * 2;
     const barWidth = chartWidth / displayData.length;
 
-    // 找到最大值用于缩放
+    //
     const maxScore = 1.0;
 
-    // 绘制坐标轴
+    //
     ctx.strokeStyle = '#E0E0E0';
     ctx.lineWidth = 2;
     ctx.beginPath();
@@ -78,7 +78,7 @@ function Records() {
     ctx.lineTo(width - padding, height - padding);
     ctx.stroke();
 
-    // 绘制Y轴刻度
+    //
     ctx.fillStyle = '#666';
     ctx.font = '12px Nunito';
     ctx.textAlign = 'right';
@@ -87,7 +87,7 @@ function Records() {
       const value = (maxScore * i / 4 * 100).toFixed(0);
       ctx.fillText(value + '%', padding - 10, y + 4);
 
-      // 绘制网格线
+      //
       ctx.strokeStyle = '#F0F0F0';
       ctx.lineWidth = 1;
       ctx.beginPath();
@@ -96,14 +96,14 @@ function Records() {
       ctx.stroke();
     }
 
-    // 绘制柱状图
+    //
     displayData.forEach((session, index) => {
       const barHeight = (session.focus_score / maxScore) * chartHeight;
       const x = padding + index * barWidth + barWidth * 0.1;
       const y = height - padding - barHeight;
       const barActualWidth = barWidth * 0.8;
 
-      // 根据分数设置颜色 - 使用蓝色主题
+      //
       const score = session.focus_score;
       let color;
       if (score >= 0.8) color = '#4A90E2';
@@ -114,32 +114,32 @@ function Records() {
       ctx.fillStyle = color;
       ctx.fillRect(x, y, barActualWidth, barHeight);
 
-      // 绘制边框
+      //
       ctx.strokeStyle = color;
       ctx.lineWidth = 1;
       ctx.strokeRect(x, y, barActualWidth, barHeight);
     });
 
-    // 绘制图例
+    //
     ctx.textAlign = 'left';
     ctx.font = 'bold 14px Nunito';
     ctx.fillStyle = '#4A90E2';
     ctx.fillText('Focus Score by Session', padding, 30);
   };
 
-  // 初始加载
+  //
   useEffect(() => {
     loadSessions(filter);
   }, [filter]);
 
-  // 处理筛选按钮点击
+  //
   const handleFilterClick = (filterType) => {
     setFilter(filterType);
   };
 
-  // 查看详情
+  //
   const handleViewDetails = (sessionId) => {
-    // 这里可以实现查看详情的功能，比如弹窗显示该会话的详细信息
+    //
     alert(`View details for session ${sessionId}\n(Feature can be extended later)`);
   };
 

src/utils/VideoManager.js

@@ -2,12 +2,10 @@
 
 export class VideoManager {
     constructor(callbacks) {
-        // callbacks 用于通知 React 组件更新界面
-        // 例如: onStatusUpdate, onSessionStart, onSessionEnd
         this.callbacks = callbacks || {};
 
-        this.videoElement = null; // 显示后端处理后的视频
-        this.stream = null; // 本地摄像头流
+        this.videoElement = null;
+        this.stream = null;
         this.pc = null;
         this.dataChannel = null;
 
@@ -15,25 +13,21 @@ export class VideoManager {
         this.sessionId = null;
         this.frameRate = 30;
 
-        // 状态平滑处理
         this.currentStatus = false;
         this.statusBuffer = [];
         this.bufferSize = 5;
 
-        // 检测数据
         this.latestDetectionData = null;
         this.lastConfidence = 0;
         this.detectionHoldMs = 30;
 
-        // 通知系统
         this.notificationEnabled = true;
-        this.notificationThreshold = 30; // 默认30秒
+        this.notificationThreshold = 30;
         this.unfocusedStartTime = null;
         this.lastNotificationTime = null;
-        this.notificationCooldown = 60000; // 通知冷却时间60秒
+        this.notificationCooldown = 60000;
     }
 
-    // 初始化：获取摄像头流，并记录展示视频的元素
     async initCamera(videoRef) {
         try {
             this.stream = await navigator.mediaDevices.getUserMedia({
@@ -62,9 +56,9 @@ export class VideoManager {
 
         console.log('📹 Starting streaming...');
 
-        // 请求通知权限
+        //
         await this.requestNotificationPermission();
-        // 加载通知设置
+        //
         await this.loadNotificationSettings();
 
         this.pc = new RTCPeerConnection({
@@ -78,7 +72,7 @@ export class VideoManager {
             iceCandidatePoolSize: 10
         });
 
-        // 添加连接状态监控
+        //
         this.pc.onconnectionstatechange = () => {
             console.log('🔗 Connection state:', this.pc.connectionState);
         };
@@ -199,7 +193,7 @@ export class VideoManager {
                     requireInteraction: false
                 });
 
-                // 3秒后自动关闭
+                //
                 setTimeout(() => notification.close(), 3000);
             } catch (error) {
                 console.error('Failed to send notification:', error);
@@ -247,28 +241,28 @@ export class VideoManager {
             this.currentStatus = false;
         }
 
-        // 通知逻辑
+        //
         this.handleNotificationLogic(previousStatus, this.currentStatus);
     }
 
     handleNotificationLogic(previousStatus, currentStatus) {
         const now = Date.now();
 
-        // 如果从专注变为不专注，记录开始时间
+        //
         if (previousStatus && !currentStatus) {
             this.unfocusedStartTime = now;
         }
 
-        // 如果从不专注变为专注，清除计时
+        //
         if (!previousStatus && currentStatus) {
             this.unfocusedStartTime = null;
         }
 
-        // 如果持续不专注
+        //
         if (!currentStatus && this.unfocusedStartTime) {
-            const unfocusedDuration = (now - this.unfocusedStartTime) / 1000; // 秒
+            const unfocusedDuration = (now - this.unfocusedStartTime) / 1000;
 
-            // 检查是否超过阈值且不在冷却期
+            //
             if (unfocusedDuration >= this.notificationThreshold) {
                 const canSendNotification = !this.lastNotificationTime ||
                                            (now - this.lastNotificationTime) >= this.notificationCooldown;
@@ -335,7 +329,7 @@ export class VideoManager {
             }
         }
 
-        // 清理通知状态
+        //
         this.unfocusedStartTime = null;
         this.lastNotificationTime = null;
         this.sessionId = null;

src/utils/VideoManagerLocal.js

@@ -1,12 +1,12 @@
 // src/utils/VideoManagerLocal.js
-// 本地视频处理版本 - 使用 WebSocket + Canvas，不依赖 WebRTC
+// WebSocket + Canvas (no WebRTC)
 
 export class VideoManagerLocal {
     constructor(callbacks) {
         this.callbacks = callbacks || {};
 
-        this.localVideoElement = null;  // 显示本地摄像头
-        this.displayVideoElement = null; // 显示处理后的视频
+        this.localVideoElement = null;
+        this.displayVideoElement = null;
         this.canvas = null;
         this.stream = null;
         this.ws = null;
@@ -14,15 +14,13 @@ export class VideoManagerLocal {
         this.isStreaming = false;
         this.sessionId = null;
         this.sessionStartTime = null;
-        this.frameRate = 15; // 降低帧率以减少网络负载
+        this.frameRate = 15;
         this.captureInterval = null;
 
-        // 状态平滑处理
         this.currentStatus = false;
         this.statusBuffer = [];
         this.bufferSize = 3;
 
-        // 检测数据
         this.latestDetectionData = null;
         this.lastConfidence = 0;
 
@@ -32,14 +30,12 @@ export class VideoManagerLocal {
         // Continuous render loop
         this._animFrameId = null;
 
-        // 通知系统
         this.notificationEnabled = true;
         this.notificationThreshold = 30;
         this.unfocusedStartTime = null;
         this.lastNotificationTime = null;
         this.notificationCooldown = 60000;
 
-        // 性能统计
         this.stats = {
             framesSent: 0,
             framesProcessed: 0,
@@ -48,7 +44,6 @@ export class VideoManagerLocal {
         };
     }
 
-    // 初始化摄像头
     async initCamera(localVideoRef, displayCanvasRef) {
         try {
             console.log('Initializing local camera...');
@@ -65,13 +60,11 @@ export class VideoManagerLocal {
             this.localVideoElement = localVideoRef;
             this.displayCanvas = displayCanvasRef;
 
-            // 显示本地视频流
             if (this.localVideoElement) {
                 this.localVideoElement.srcObject = this.stream;
                 this.localVideoElement.play();
             }
 
-            // 创建用于截图的 canvas (smaller for faster encode + transfer)
             this.canvas = document.createElement('canvas');
             this.canvas.width = 320;
             this.canvas.height = 240;
@@ -84,7 +77,6 @@ export class VideoManagerLocal {
         }
     }
 
-    // 开始流式处理
     async startStreaming() {
         if (!this.stream) {
             throw new Error('Camera not initialized');
@@ -109,14 +101,14 @@ export class VideoManagerLocal {
             }
         }
 
-        // 请求通知权限
+        //
         await this.requestNotificationPermission();
         await this.loadNotificationSettings();
 
-        // 建立 WebSocket 连接
+        //
         await this.connectWebSocket();
 
-        // 开始定期截图并发送
+        //
         this.startCapture();
 
         // Start continuous render loop for smooth video
@@ -126,7 +118,7 @@ export class VideoManagerLocal {
         console.log('Streaming started');
     }
 
-    // 建立 WebSocket 连接
+    //
     async connectWebSocket() {
         return new Promise((resolve, reject) => {
             const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -139,7 +131,7 @@ export class VideoManagerLocal {
             this.ws.onopen = () => {
                 console.log('WebSocket connected');
 
-                // 发送开始会话请求
+                //
                 this.ws.send(JSON.stringify({ type: 'start_session' }));
                 resolve();
             };
@@ -168,7 +160,7 @@ export class VideoManagerLocal {
         });
     }
 
-    // 开始截图并发送 (binary blobs for speed)
+    //
     startCapture() {
         const interval = 1000 / this.frameRate;
         this._sendingBlob = false; // prevent overlapping toBlob calls
@@ -272,7 +264,7 @@ export class VideoManagerLocal {
         }
     }
 
-    // 处理服务器消息
+    //
     handleServerMessage(data) {
         switch (data.type) {
             case 'session_started':
@@ -590,17 +582,17 @@ export class VideoManagerLocal {
         this._stopRenderLoop();
         this._lastDetection = null;
 
-        // 停止截图
+        //
         if (this.captureInterval) {
             clearInterval(this.captureInterval);
             this.captureInterval = null;
         }
 
-        // 发送结束会话请求并等待响应
+        //
         if (this.ws && this.ws.readyState === WebSocket.OPEN && this.sessionId) {
             const sessionId = this.sessionId;
 
-            // 等待 session_ended 消息
+            //
             const waitForSessionEnd = new Promise((resolve) => {
                 const originalHandler = this.ws.onmessage;
                 const timeout = setTimeout(() => {
@@ -618,7 +610,7 @@ export class VideoManagerLocal {
                             this.ws.onmessage = originalHandler;
                             resolve();
                         } else {
-                            // 仍然处理其他消息
+                            //
                             this.handleServerMessage(data);
                         }
                     } catch (e) {
@@ -633,37 +625,37 @@ export class VideoManagerLocal {
                 session_id: sessionId
             }));
 
-            // 等待响应或超时
+            //
             await waitForSessionEnd;
         }
 
-        // 延迟关闭 WebSocket 确保消息发送完成
+        //
         await new Promise(resolve => setTimeout(resolve, 200));
 
-        // 关闭 WebSocket
+        //
         if (this.ws) {
             this.ws.close();
             this.ws = null;
         }
 
-        // 停止摄像头
+        //
         if (this.stream) {
             this.stream.getTracks().forEach(track => track.stop());
             this.stream = null;
         }
 
-        // 清空视频
+        //
         if (this.localVideoElement) {
             this.localVideoElement.srcObject = null;
         }
 
-        // 清空 canvas
+        //
         if (this.displayCanvas) {
             const ctx = this.displayCanvas.getContext('2d');
             ctx.clearRect(0, 0, this.displayCanvas.width, this.displayCanvas.height);
         }
 
-        // 清理状态
+        //
         this.unfocusedStartTime = null;
         this.lastNotificationTime = null;
 
@@ -675,7 +667,7 @@ export class VideoManagerLocal {
         this.frameRate = Math.max(10, Math.min(30, rate));
         console.log(`Frame rate set to ${this.frameRate} FPS`);
 
-        // 重启截图（如果正在运行）
+        //
         if (this.isStreaming && this.captureInterval) {
             clearInterval(this.captureInterval);
             this.startCapture();

tests/test_data_preparation.py

@@ -24,7 +24,7 @@ def test_generate_synthetic_data_shape():
 def test_get_numpy_splits_consistency():
     splits, num_features, num_classes, scaler = get_numpy_splits("face_orientation")
 
-    # number of sample > 0，and split each in train/val/test
+    # train/val/test each have samples
     n_train = len(splits["y_train"])
     n_val = len(splits["y_val"])
     n_test = len(splits["y_test"])

ui/README.md

@@ -1,40 +1,16 @@
 # ui/
 
-Live camera demo and real-time inference pipeline.
+Live OpenCV demo and inference pipelines used by the app.
 
-## 1. Files
+**Files:** `pipeline.py` (FaceMesh, MLP, XGBoost, Hybrid pipelines), `live_demo.py` (webcam window with mesh + focus label).
 
-| File | Description |
-|------|-------------|
-| `pipeline.py` | Inference pipelines: `FaceMeshPipeline`, `MLPPipeline`, `XGBoostPipeline` |
-| `live_demo.py` | OpenCV webcam window with mesh overlay and focus classification |
+**Pipelines:** FaceMesh = rule-based head/eye; MLP = 10 features → PyTorch MLP (checkpoints/mlp_best.pt + scaler); XGBoost = same 10 features → xgboost_face_orientation_best.json. Hybrid combines ML/XGB with geometric scores.
 
-## 2. Pipelines
-
-| Pipeline | Features | Model | Source |
-|----------|----------|-------|--------|
-| `FaceMeshPipeline` | Head pose + eye geometry | Rule-based fusion | `models/head_pose.py`, `models/eye_scorer.py` |
-| `MLPPipeline` | 10 selected features | PyTorch MLP (10→64→32→2) | `checkpoints/mlp_best.pt` + `scaler_mlp.joblib` |
-| `XGBoostPipeline` | 10 selected features | XGBoost | `checkpoints/xgboost_face_orientation_best.json` |
-
-## 3. Running
+**Run demo:**
 
 ```bash
-# default mode (cycles through available pipelines)
 python ui/live_demo.py
-
-# start directly in XGBoost mode
 python ui/live_demo.py --xgb
 ```
 
-### Controls
-
-| Key | Action |
-|-----|--------|
-| `m` | Cycle mesh overlay (full → contours → off) |
-| `p` | Switch pipeline (FaceMesh → MLP → XGBoost) |
-| `q` | Quit |
-
-## 4. Integration
-
-The same pipelines are used by the FastAPI backend (`main.py`) for WebSocket-based video inference in the React app.
+`m` = cycle mesh, `p` = switch pipeline, `q` = quit. Same pipelines back the FastAPI WebSocket video in `main.py`.

ui/pipeline.py

@@ -375,7 +375,7 @@ class MLPPipeline:
         out["mar"] = float(vec[_FEAT_IDX["mar"]])
 
         X = vec[self._indices].reshape(1, -1).astype(np.float32)
-        X_sc = self._scaler.transform(X)
+        X_sc = self._scaler.transform(X) if self._scaler is not None else X
         with torch.no_grad():
             x_t = torch.from_numpy(X_sc).float()
             logits = self._mlp(x_t)
@@ -534,7 +534,7 @@ class HybridFocusPipeline:
                 focus_score = self._cfg["w_xgb"] * model_prob + self._cfg["w_geo"] * out["geo_score"]
         else:
             X = vec[self._indices].reshape(1, -1).astype(np.float32)
-            X_sc = self._scaler.transform(X)
+            X_sc = self._scaler.transform(X) if self._scaler is not None else X
             with torch.no_grad():
                 x_t = torch.from_numpy(X_sc).float()
                 logits = self._mlp(x_t)