refactor: single checkpoints/ dir, fix uvicorn cmd and hybrid config path

README.md

@@ -40,7 +40,7 @@ cp -r dist/* static/
 **Web application (API + frontend):**
 
 ```bash
-uvicorn app:app --host 0.0.0.0 --port 7860
+uvicorn main:app --host 0.0.0.0 --port 7860
 ```
 
 Open http://localhost:7860 in a browser.

evaluation/README.md

@@ -13,12 +13,12 @@ THRESHOLD_JUSTIFICATION.md   # report (auto-generated by justify_thresholds)
 feature_selection_justification.md   # report (auto-generated by feature_importance)
 ```
 
-**Logs (when present):**
+**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
-├── mlp_face_orientation_training_log.json
-└── xgboost_face_orientation_training_log.json
+├── 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

evaluation/feature_importance.py

@@ -27,9 +27,6 @@ FEATURES = SELECTED_FEATURES["face_orientation"]
 
 
 def _resolve_xgb_path():
-    p = os.path.join(_PROJECT_ROOT, "models", "xgboost", "checkpoints", "face_orientation_best.json")
-    if os.path.isfile(p):
-        return p
     return os.path.join(_PROJECT_ROOT, "checkpoints", "xgboost_face_orientation_best.json")
 
 

evaluation/justify_thresholds.py

@@ -927,7 +927,7 @@ def write_hybrid_config(use_xgb, best_w_mlp, best_w_xgb, config_path,
     }
     if combiner_path:
         cfg["combiner"] = "logistic"
-        cfg["combiner_path"] = os.path.normpath(combiner_path)
+        cfg["combiner_path"] = os.path.basename(combiner_path)
     with open(config_path, "w", encoding="utf-8") as f:
         json.dump(cfg, f, indent=2)
     print(f"  Written {config_path} (use_xgb={cfg['use_xgb']}, combiner={cfg.get('combiner', 'heuristic')})")

notebooks/xgboost.ipynb

@@ -64,7 +64,7 @@
         "    \"reg_alpha\": 1.1407,\n",
         "    \"reg_lambda\": 2.4181,\n",
         "    \"eval_metric\": \"logloss\",\n",
-        "    \"checkpoints_dir\": os.path.join(PROJECT_ROOT, \"models\", \"xgboost\", \"checkpoints\"),\n",
+        "    \"checkpoints_dir\": os.path.join(PROJECT_ROOT, \"checkpoints\"),\n",
         "    \"logs_dir\": os.path.join(PROJECT_ROOT, \"evaluation\", \"logs\"),\n",
         "}\n",
         "\n",
@@ -306,7 +306,7 @@
       "outputs": [],
       "source": [
         "os.makedirs(CFG[\"checkpoints_dir\"], exist_ok=True)\n",
-        "model_path = os.path.join(CFG[\"checkpoints_dir\"], f\"{CFG['model_name']}_best.json\")\n",
+        "model_path = os.path.join(CFG[\"checkpoints_dir\"], f\"xgboost_{CFG['model_name']}_best.json\")\n",
         "model.save_model(model_path)\n",
         "\n",
         "history = {\n",

ui/README.md

@@ -15,7 +15,7 @@ Live camera demo and real-time inference pipeline.
 |----------|----------|-------|--------|
 | `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 | `models/xgboost/checkpoints/face_orientation_best.json` |
+| `XGBoostPipeline` | 10 selected features | XGBoost | `checkpoints/xgboost_face_orientation_best.json` |
 
 ## 3. Running
 

ui/pipeline.py

@@ -329,9 +329,7 @@ def _load_hybrid_config(model_dir: str, config_path: str | None = None):
 class MLPPipeline:
     def __init__(self, model_dir=None, detector=None, threshold=0.23):
         if model_dir is None:
-            model_dir = os.path.join(_PROJECT_ROOT, "MLP", "models")
-            if not os.path.exists(model_dir):
-                model_dir = os.path.join(_PROJECT_ROOT, "checkpoints")
+            model_dir = os.path.join(_PROJECT_ROOT, "checkpoints")
 
         self._mlp, self._scaler, self._feature_names = _load_mlp_artifacts(model_dir)
         self._indices = [FEATURE_NAMES.index(n) for n in self._feature_names]
@@ -404,9 +402,6 @@ class MLPPipeline:
 
 
 def _resolve_xgb_path():
-    p = os.path.join(_PROJECT_ROOT, "models", "xgboost", "checkpoints", "face_orientation_best.json")
-    if os.path.isfile(p):
-        return p
     return os.path.join(_PROJECT_ROOT, "checkpoints", "xgboost_face_orientation_best.json")
 
 
@@ -582,10 +577,7 @@ class XGBoostPipeline:
         from xgboost import XGBClassifier
 
         if model_path is None:
-            model_path = os.path.join(_PROJECT_ROOT, "models", "xgboost", "checkpoints", "face_orientation_best.json")
-            if not os.path.isfile(model_path):
-                # Fallback to legacy path
-                model_path = os.path.join(_PROJECT_ROOT, "checkpoints", "xgboost_face_orientation_best.json")
+            model_path = os.path.join(_PROJECT_ROOT, "checkpoints", "xgboost_face_orientation_best.json")
         if not os.path.isfile(model_path):
             raise FileNotFoundError(f"No XGBoost checkpoint at {model_path}")