Restore: Space paused fixes - memory optimization and error handling

- Added proper .gitignore to exclude venv and cache files
- Fixed memory leak issues with model caching
- Improved error handling in startup and training
- Added lazy loading for models to prevent startup failures

.gitignore

@@ -0,0 +1,83 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Models (keep only in git if needed)
+models/
+!models/.gitkeep
+
+# Data cache
+data/
+!data/.gitkeep
+
+# Temporary files
+*.tmp
+*.temp
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# Hugging Face
+hf_cache/

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+COPY requirements.txt .
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential libgomp1 && \
+    pip install --upgrade pip && \
+    pip install -r requirements.txt && \
+    apt-get purge -y build-essential && \
+    apt-get autoremove -y && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

app.py

@@ -0,0 +1,351 @@
+"""FastAPI 앱: 수동 학습 및 모델 다운로드/업로드"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import schedule
+import lightgbm as lgb
+import numpy as np
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from huggingface_hub import HfApi
+from pydantic import BaseModel, field_validator
+
+from train_scheduler import TrainingScheduler
+
+
+app = FastAPI(
+    title="MuscleCare LightGBM Scheduler",
+    description="MuscleCare-Train-AI Space와 동일한 API를 LightGBM 모델로 제공합니다.",
+)
+
+_scheduler = TrainingScheduler()
+
+_model_lock = threading.Lock()
+_current_model: Optional[lgb.Booster] = None
+_current_model_path: Optional[str] = None
+_current_model_version: Optional[int] = None
+_model_cache_timestamp: Optional[float] = None
+MODEL_CACHE_TIMEOUT = 3600  # 1시간
+
+
+class TrainResponse(BaseModel):
+    status: str
+    new_data_count: int
+    model_path: Optional[str] = None
+    hub_url: Optional[str] = None
+    model_version: Optional[int] = None
+    message: str
+    new_session_count: Optional[int] = None
+
+
+class ResetStateResponse(BaseModel):
+    status: str
+    state: Dict[str, Any]
+
+
+class PredictRequest(BaseModel):
+    rms_acc: float
+    rms_gyro: float
+    mean_freq_acc: float
+    mean_freq_gyro: float
+    rms_base: float
+    freq_base: float
+    user_emb: List[float]
+
+    @field_validator("user_emb")
+    @classmethod
+    def validate_user_emb(cls, v: List[float]) -> List[float]:
+        if len(v) != 12:
+            raise ValueError("user_emb must contain exactly 12 values.")
+        return v
+
+
+class PredictResponse(BaseModel):
+    fatigue: float
+    model_version: Optional[int]
+
+
+def _schedule_background_job() -> None:
+    schedule.clear()
+    schedule.every().sunday.at(_scheduler.schedule_time).do(_scheduler.run_scheduled_training)
+
+    def _loop() -> None:
+        while True:
+            schedule.run_pending()
+            time.sleep(60)
+
+    threading.Thread(target=_loop, daemon=True).start()
+
+
+def _apply_training_result(result: Dict[str, Any]) -> None:
+    if result.get("status") != "trained":
+        return
+    model_path = result.get("model_path")
+    if not model_path:
+        print("[Model] 학습 결과에 model_path가 없어 모델을 로드하지 못했습니다.")
+        return
+    try:
+        _load_model_from_path(Path(model_path), result.get("model_version"))
+    except Exception as exc:
+        print(f"[Model] 새 모델 로드 실패: {exc}")
+
+
+def _load_model_from_path(path: Path, version: Optional[int] = None) -> None:
+    if not path.exists():
+        raise FileNotFoundError(f"모델 파일을 찾을 수 없습니다: {path}")
+    booster = lgb.Booster(model_file=str(path))
+    with _model_lock:
+        global _current_model, _current_model_path, _current_model_version, _model_cache_timestamp
+        _current_model = booster
+        _current_model_path = str(path)
+        _current_model_version = version
+        _model_cache_timestamp = time.time()
+    print(f"[Model] Loaded LightGBM model from {path} (version={version})")
+
+
+def _get_cached_model() -> Optional[lgb.Booster]:
+    """캐시된 모델 반환, 타임아웃 시 None 반환"""
+    with _model_lock:
+        if _current_model is None:
+            return None
+        if _model_cache_timestamp is None:
+            return None
+        if time.time() - _model_cache_timestamp > MODEL_CACHE_TIMEOUT:
+            print("[Model] 모델 캐시 만료, 재로드 필요")
+            _current_model = None
+            return None
+        return _current_model
+
+
+def _maybe_load_latest_model() -> None:
+    try:
+        manifest = _scheduler.get_model_versions()
+        target_entry = manifest[-1] if manifest else None
+        candidate_path: Optional[Path] = None
+        candidate_version: Optional[int] = None
+
+        if target_entry:
+            candidate_path = Path(target_entry["path"])
+            candidate_version = target_entry.get("version")
+        else:
+            default_path = Path("models/lightgbm_model.txt")
+            if default_path.exists():
+                candidate_path = default_path
+
+        if candidate_path and candidate_path.exists():
+            try:
+                _load_model_from_path(candidate_path, candidate_version)
+                print(f"[Model] 모델 로드 성공: {candidate_path}")
+            except Exception as exc:
+                print(f"[Model] 모델 로드 실패 (계속 진행): {exc}")
+        else:
+            print("[Model] 로드할 모델이 아직 없습니다.")
+    except Exception as exc:
+        print(f"[Model] 모델 로드 과정에서 예외 발생: {exc}")
+
+
+def _get_active_model() -> Tuple[lgb.Booster, Optional[int]]:
+    # 먼저 캐시된 모델 확인
+    cached_model = _get_cached_model()
+    if cached_model is not None:
+        return cached_model, _current_model_version
+
+    # 캐시된 모델이 없으면 최신 모델 로드 시도
+    try:
+        manifest = _scheduler.get_model_versions()
+        target_entry = manifest[-1] if manifest else None
+
+        if target_entry:
+            path = Path(target_entry["path"])
+            version = target_entry.get("version")
+        else:
+            path = Path("models/lightgbm_model.txt")
+
+        if path.exists():
+            _load_model_from_path(path, version)
+            return _current_model, _current_model_version
+        else:
+            raise HTTPException(status_code=503, detail="모델 파일을 찾을 수 없습니다.")
+    except Exception as exc:
+        raise HTTPException(status_code=503, detail=f"모델 로드 실패: {exc}")
+
+
+def _build_feature_vector(payload: PredictRequest) -> np.ndarray:
+    rms_base = payload.rms_base if payload.rms_base != 0 else 1e-6
+    freq_mean = (payload.mean_freq_acc + payload.mean_freq_gyro) / 2.0
+    if freq_mean == 0:
+        freq_mean = 1e-6
+
+    rms_ratio = ((payload.rms_acc + payload.rms_gyro) / 2.0) / rms_base
+    freq_ratio = payload.freq_base / freq_mean
+
+    feature_vector = [rms_ratio, freq_ratio, *payload.user_emb]
+    return np.asarray([feature_vector], dtype=np.float32)
+
+
+@app.on_event("startup")
+def on_startup() -> None:
+    print("[Startup] MuscleCare Space 시작 중...")
+    try:
+        _schedule_background_job()
+        print("[Startup] 스케줄러 초기화 완료")
+    except Exception as exc:
+        print(f"[Startup] 스케줄러 초기화 실패 (계속 진행): {exc}")
+
+    # 모델은 예측 시점에 필요할 때 로드 (lazy loading)
+    print("[Startup] 모델은 필요 시점에 로드됩니다 (lazy loading)")
+    print("[Startup] MuscleCare Space 시작 완료")
+
+
+@app.get("/health")
+def health_check() -> dict:
+    return {"status": "ok"}
+
+
+@app.get("/")
+def root() -> dict:
+    return {
+        "message": "MuscleCare LightGBM Scheduler API",
+        "docs": "/docs",
+        "endpoints": {
+            "trigger": "/trigger",
+            "model": "/model",
+            "state_reset": "/state/reset",
+        },
+    }
+
+
+def _upload_to_hub(model_path: str) -> Optional[str]:
+    token = os.getenv("HF_HYBRID_MODEL_TOKEN")
+    repo_id = os.getenv("HF_HYBRID_MODEL_REPO_ID")
+
+    if not token or not repo_id:
+        return None
+
+    path = Path(model_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail=f"모델 파일을 찾을 수 없습니다: {model_path}")
+
+    api = HfApi(token=token)
+    api.create_repo(repo_id=repo_id, repo_type="model", private=False, exist_ok=True)
+    api.upload_file(
+        path_or_fileobj=path,
+        path_in_repo=path.name,
+        repo_id=repo_id,
+        repo_type="model",
+        commit_message=f"LightGBM model upload ({path.name})",
+    )
+
+    manifest_path = Path("logs/model_versions.json")
+    if manifest_path.exists():
+        api.upload_file(
+            path_or_fileobj=str(manifest_path),
+            path_in_repo="model_versions.json",
+            repo_id=repo_id,
+            repo_type="model",
+            commit_message="Update model manifest",
+        )
+
+    return f"https://huggingface.co/{repo_id}"
+
+
+def _resolve_model_entry(version: Optional[int] = None) -> Dict[str, Any]:
+    manifest = _scheduler.get_model_versions()
+    if not manifest:
+        raise HTTPException(status_code=404, detail="아직 학습된 모델이 없습니다.")
+
+    if version is None:
+        return manifest[-1]
+
+    for entry in manifest:
+        if entry.get("version") == version:
+            return entry
+
+    raise HTTPException(
+        status_code=404,
+        detail=f"버전 {version} 모델을 찾을 수 없습니다.",
+    )
+
+
+@app.get("/model")
+@app.get("/model/{version:int}")
+def download_model(version: Optional[int] = None) -> FileResponse:
+    entry = _resolve_model_entry(version)
+    path = Path(entry["path"])
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="모델 파일을 찾을 수 없습니다.")
+
+    response = FileResponse(
+        path=path,
+        filename=entry["filename"],
+        media_type="application/octet-stream",
+    )
+    response.headers["X-Model-Version"] = str(entry["version"])
+    return response
+
+
+@app.get("/download")
+def download_latest_alias() -> FileResponse:
+    return download_model()
+
+
+@app.post("/state/reset", response_model=ResetStateResponse)
+def reset_state() -> ResetStateResponse:
+    state = _scheduler.reset_training_state()
+    return ResetStateResponse(status="reset", state=state)
+
+
+@app.post("/trigger", response_model=TrainResponse)
+def trigger_training(upload: bool = False) -> TrainResponse:
+    try:
+        result = _scheduler.run_scheduled_training()
+    except Exception as exc:  # pragma: no cover
+        raise HTTPException(status_code=500, detail=f"학습 실행 오류: {exc}") from exc
+
+    message = "모델 학습이 완료되었습니다." if result["status"] == "trained" else "학습이 건너뛰어졌습니다."
+    hub_url = None
+    model_version = result.get("model_version")
+    model_path = result.get("model_path")
+
+    if upload and model_path and result["status"] == "trained":
+        try:
+            hub_url = _upload_to_hub(model_path)
+            message = "모델 학습 및 Hugging Face 업로드가 완료되었습니다."
+        except HTTPException:
+            raise
+        except Exception as exc:  # pragma: no cover
+            raise HTTPException(status_code=500, detail=f"Hugging Face 업로드 실패: {exc}") from exc
+
+    _apply_training_result(result)
+
+    return TrainResponse(
+        status=result["status"],
+        new_data_count=result.get("new_data_count", 0),
+        model_path=model_path,
+        hub_url=hub_url,
+        model_version=model_version,
+        message=message,
+        new_session_count=result.get("new_session_count"),
+    )
+
+
+@app.post("/train", response_model=TrainResponse)
+def trigger_training_alias(upload: bool = False) -> TrainResponse:
+    return trigger_training(upload=upload)
+
+
+@app.post("/predict", response_model=PredictResponse)
+def predict(payload: PredictRequest) -> PredictResponse:
+    booster, version = _get_active_model()
+    features = _build_feature_vector(payload)
+    prediction = booster.predict(features)[0]
+    return PredictResponse(fatigue=float(prediction), model_version=version)
+
+
+__all__ = ["app"]

load_dataset.py

@@ -0,0 +1,196 @@
+import json
+import os
+from pathlib import Path
+from typing import Iterable, List, Optional, Tuple
+
+import pandas as pd
+from datasets import get_dataset_config_names, get_dataset_split_names, load_dataset
+from huggingface_hub import hf_hub_download
+
+DEFAULT_DATASET_ID = "Merry99/MuscleCare-DataSet"
+DEFAULT_DATASET_SPLITS = [
+    "local_user",
+    "ios_D7ED673185E248BD9DC1102E881E9111",
+    "android_SP1A.210812.016",
+] + [f"user_{i:03d}" for i in range(1, 51)]
+
+
+def download_parquet_from_hub(
+    repo_id: str,
+    filenames: Iterable[str],
+    local_dir: str = "./data",
+    repo_type: str = "dataset",
+    token: Optional[str] = None,
+) -> List[Path]:
+    """
+    (옵션) Hugging Face Hub에서 parquet 파일을 내려받아 로컬에 저장.
+    Space와 동일한 환경을 위해 필요 시 사용합니다.
+    """
+    target_dir = Path(local_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    downloaded: List[Path] = []
+    for name in filenames:
+        local_path = Path(
+            hf_hub_download(
+                repo_id=repo_id,
+                filename=name,
+                repo_type=repo_type,
+                token=token,
+                local_dir=target_dir,
+                local_dir_use_symlinks=False,
+            )
+        )
+        downloaded.append(local_path)
+    return downloaded
+
+
+def resolve_parquet_files(data_dir: str = "./data", pattern: str = "user*.parquet") -> List[Path]:
+    """
+    데이터 디렉토리에서 parquet 파일 목록을 정렬된 상태로 반환.
+    """
+    data_path = Path(data_dir)
+    if not data_path.exists():
+        raise FileNotFoundError(f"데이터 디렉토리를 찾을 수 없습니다: {data_dir}")
+
+    parquet_files = sorted(data_path.glob(pattern))
+    if not parquet_files:
+        raise FileNotFoundError(f"패턴({pattern})에 해당하는 parquet 파일이 없습니다.")
+    return parquet_files
+
+
+def parse_user_embedding(raw_emb, fallback_dim: int = 12) -> List[float]:
+    """
+    문자열/리스트 형태의 user_emb를 고정 길이 리스트로 변환.
+    """
+    if isinstance(raw_emb, str):
+        try:
+            raw_emb = json.loads(raw_emb)
+        except json.JSONDecodeError:
+            raw_emb = []
+
+    if isinstance(raw_emb, (list, tuple)):
+        values = list(raw_emb)
+    else:
+        values = []
+
+    if not values:
+        values = [0.0] * fallback_dim
+
+    if len(values) < fallback_dim:
+        values = values + [0.0] * (fallback_dim - len(values))
+    else:
+        values = values[:fallback_dim]
+
+    return [float(v) for v in values]
+
+
+def normalize_user_embeddings(df: pd.DataFrame, emb_dim: int) -> pd.DataFrame:
+    if "user_emb" not in df.columns:
+        raise KeyError("데이터셋에 'user_emb' 컬럼이 없습니다.")
+    df = df.copy()
+    df["user_emb"] = df["user_emb"].apply(lambda v: parse_user_embedding(v, emb_dim))
+    return df
+
+
+def _resolve_config_name(repo_id: str) -> Optional[str]:
+    try:
+        configs = get_dataset_config_names(repo_id)
+        if configs:
+            return configs[0]
+    except Exception:
+        pass
+    return None
+
+
+def _load_split_dataframe(
+    repo_id: str,
+    split_name: str,
+    cache_dir: str,
+    config_name: Optional[str],
+) -> Optional[pd.DataFrame]:
+    load_kwargs = {
+        "path": repo_id,
+        "split": split_name,
+        "cache_dir": cache_dir,
+    }
+    if config_name:
+        load_kwargs["name"] = config_name
+    try:
+        ds = load_dataset(**load_kwargs)
+    except ValueError as exc:
+        print(f"⚠️  split '{split_name}' 건너뜀: {exc}")
+        return None
+
+    return ds.to_pandas() if hasattr(ds, "to_pandas") else ds.to_pandas()
+
+
+def load_dataset_from_hub(
+    repo_id: Optional[str] = None,
+    split: Optional[str] = None,
+    cache_dir: Optional[str] = None,
+    emb_dim: int = 12,
+    exclude_sessions: Optional[Iterable[str]] = None,
+) -> Tuple[pd.DataFrame, List[str]]:
+    """
+    Hugging Face Dataset에서 데이터를 로드해 DataFrame으로 변환.
+    exclude_sessions에 포함된 session_id는 제외합니다.
+    """
+    repo_id = repo_id or DEFAULT_DATASET_ID
+    cache_dir = cache_dir or os.getenv("HF_DATASET_CACHE_DIR", "./data/hf_cache")
+
+    config_name = _resolve_config_name(repo_id)
+
+    if split:
+        split_names = [split]
+    else:
+        try:
+            split_names = get_dataset_split_names(repo_id, config_name)
+        except Exception:
+            split_names = DEFAULT_DATASET_SPLITS
+
+    frames: List[pd.DataFrame] = []
+    for split_name in split_names:
+        df_part = _load_split_dataframe(
+            repo_id=repo_id,
+            split_name=split_name,
+            cache_dir=cache_dir,
+            config_name=config_name,
+        )
+        if df_part is not None and not df_part.empty:
+            frames.append(df_part)
+
+    if not frames:
+        raise ValueError("NO_DATA_AVAILABLE")
+
+    df = pd.concat(frames, ignore_index=True)
+    if "session_id" not in df.columns:
+        raise KeyError("데이터셋에 'session_id' 컬럼이 없습니다.")
+
+    exclude_set = set(str(s) for s in (exclude_sessions or []))
+    if exclude_set:
+        df = df[~df["session_id"].astype(str).isin(exclude_set)]
+
+    session_ids = sorted(df["session_id"].dropna().astype(str).unique().tolist())
+    df = normalize_user_embeddings(df, emb_dim)
+    return df, session_ids
+
+
+def load_parquet_dataset(
+    data_dir: str = "./data",
+    pattern: str = "user*.parquet",
+    emb_dim: int = 12,
+) -> pd.DataFrame:
+    """
+    데이터가 로컬에 없으면 자동으로 Hugging Face Dataset에서 로드합니다.
+    """
+    try:
+        parquet_files = resolve_parquet_files(data_dir, pattern)
+        frames = [pd.read_parquet(path) for path in parquet_files]
+        data = pd.concat(frames, ignore_index=True)
+        return normalize_user_embeddings(data, emb_dim)
+    except FileNotFoundError:
+        # 로컬 데이터가 없다면 HF Dataset에서 직접 로드
+        print("⚠️  로컬 데이터가 없어 Hugging Face Dataset에서 불러옵니다.")
+        df, _ = load_dataset_from_hub(emb_dim=emb_dim)
+        return df

requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.115.5
+uvicorn[standard]==0.32.0
+schedule==1.2.2
+huggingface_hub==0.25.2
+datasets==2.19.1
+pandas==2.1.4
+numpy==1.24.4
+pyarrow==14.0.1
+lightgbm==4.3.0
+scikit-learn==1.3.2

run_local.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+echo "=== MuscleCare Train Hybrid 로컬 실행 ==="
+
+# Python 버전 확인
+python_version=$(python3 --version 2>&1 | awk '{print $2}')
+echo "Python 버전: $python_version"
+
+# 필수 버전 확인
+required_version="3.9"
+if [[ "$(printf '%s\n' "$required_version" "$python_version" | sort -V | head -n1)" != "$required_version" ]]; then
+    echo "❌ Python $required_version 이상이 필요합니다. 현재: $python_version"
+    exit 1
+fi
+
+echo "✅ Python 버전 확인 완료"
+
+# 가상환경 확인
+if [[ -z "$VIRTUAL_ENV" ]]; then
+    echo "⚠️  가상환경이 활성화되어 있지 않습니다."
+    echo "   source .venv/bin/activate 명령어로 활성화하세요."
+fi
+
+# 의존성 설치 확인
+echo "의존성 설치 확인 중..."
+python3 -c "import fastapi, uvicorn, lightgbm, pandas, datasets; print('✅ 모든 의존성이 설치되어 있습니다.')" 2>/dev/null
+if [[ $? -ne 0 ]]; then
+    echo "❌ 의존성이 설치되어 있지 않습니다."
+    echo "   pip install -r requirements.txt 명령어로 설치하세요."
+    exit 1
+fi
+
+echo ""
+echo "=== 스케줄러 시작 ==="
+echo "매주 일요일 00:00에 자동 학습이 실행됩니다."
+echo "종료하려면 Ctrl+C를 누르세요."
+echo ""
+
+python3 start.py

start.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""
+로컬 스케줄러 시작점
+"""
+
+from train_scheduler import main
+
+if __name__ == "__main__":
+    main()

train_hybrid.py

@@ -0,0 +1,170 @@
+"""
+LightGBM 기반 근피로도 추정 파이프라인
+- Hugging Face Dataset 로드
+- 특징 생성 (α/β 보정값 + user_emb)
+- LightGBM 학습 및 평가
+"""
+
+import os
+import argparse
+import json
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional
+
+import lightgbm as lgb
+import numpy as np
+import pandas as pd
+from sklearn.metrics import mean_absolute_error, mean_squared_error
+from sklearn.model_selection import train_test_split
+
+from load_dataset import DEFAULT_DATASET_ID, load_dataset_from_hub
+
+
+EMB_DIM = 12
+FEATURES = ["rms_ratio", "freq_ratio"]
+EMB_COLS = [f"useremb{i+1}" for i in range(EMB_DIM)]
+
+
+def build_features(df: pd.DataFrame) -> pd.DataFrame:
+    required = [
+        "rms_acc",
+        "rms_gyro",
+        "mean_freq_acc",
+        "mean_freq_gyro",
+        "rms_base",
+        "freq_base",
+        "fatigue",
+    ]
+    missing = set(required) - set(df.columns)
+    if missing:
+        raise KeyError(f"누락된 컬럼: {sorted(missing)}")
+
+    data = df.copy()
+    data["rms_ratio"] = (
+        (data["rms_acc"] + data["rms_gyro"]) / 2.0
+    ) / data["rms_base"].replace(0, np.finfo(float).eps)
+    freq_mean = (data["mean_freq_acc"] + data["mean_freq_gyro"]) / 2.0
+    data["freq_ratio"] = data["freq_base"] / freq_mean.replace(
+        0, np.finfo(float).eps
+    )
+
+    if "user_emb" not in data.columns:
+        raise KeyError("데이터에 user_emb 컬럼이 필요합니다.")
+    data[EMB_COLS] = pd.DataFrame(
+        data["user_emb"].tolist(), index=data.index
+    )
+    return data
+
+
+def train_lightgbm(
+    data: pd.DataFrame,
+    test_size: float = 0.2,
+    random_state: int = 42,
+) -> Dict[str, str]:
+    train_cols = FEATURES + EMB_COLS
+    X = data[train_cols]
+    y = data["fatigue"]
+
+    X_train, X_val, y_train, y_val = train_test_split(
+        X, y, test_size=test_size, random_state=random_state
+    )
+
+    lgb_train = lgb.Dataset(X_train, label=y_train)
+    lgb_val = lgb.Dataset(X_val, label=y_val, reference=lgb_train)
+
+    params = {
+        "objective": "regression",
+        "metric": "rmse",
+        "learning_rate": 0.1,
+        "num_leaves": 31,
+        "verbose": -1,
+    }
+
+    callbacks = [lgb.early_stopping(stopping_rounds=10, verbose=True)]
+    model = lgb.train(
+        params,
+        lgb_train,
+        valid_sets=[lgb_train, lgb_val],
+        num_boost_round=100,
+        callbacks=callbacks,
+    )
+
+    y_pred = model.predict(X_val, num_iteration=model.best_iteration)
+    rmse = np.sqrt(mean_squared_error(y_val, y_pred))
+    mae = mean_absolute_error(y_val, y_pred)
+
+    print(f"RMSE: {rmse:.6f}")
+    print(f"MAE : {mae:.6f}")
+
+    importance = pd.DataFrame(
+        {
+            "feature": train_cols,
+            "importance": model.feature_importance(),
+        }
+    ).sort_values(by="importance", ascending=False)
+    print("\nFeature Importance:")
+    print(importance.to_string(index=False))
+
+    models_dir = Path("models")
+    models_dir.mkdir(exist_ok=True)
+    booster_path = models_dir / "lightgbm_model.txt"
+    model.save_model(str(booster_path))
+    print(f"\n✅ LightGBM 모델 저장: {booster_path}")
+
+    metadata = {
+        "rmse": rmse,
+        "mae": mae,
+        "feature_importance": importance.to_dict(orient="records"),
+        "model_path": str(booster_path),
+        "artifact_type": "lightgbm",
+        "sample_count": len(data),
+    }
+
+    metadata_path = models_dir / "training_metadata.json"
+    metadata_path.write_text(json.dumps(metadata, indent=2, ensure_ascii=False))
+    print(f"ℹ️  메타데이터 저장: {metadata_path}")
+
+    return metadata
+
+
+def main(
+    data_dir: str = "./data",
+    pattern: str = "user*.parquet",
+    emb_dim: int = EMB_DIM,
+    exclude_sessions: Optional[Iterable[str]] = None,
+    repo_id: Optional[str] = None,
+    split: Optional[str] = None,
+) -> Dict[str, str]:
+    print("=" * 80)
+    print("MuscleCare LightGBM Trainer")
+    print("=" * 80)
+
+    resolved_repo = repo_id or os.getenv("HF_DATASET_REPO_ID", DEFAULT_DATASET_ID)
+    env_split = os.getenv("HF_DATASET_SPLIT")
+    resolved_split = split if split is not None else env_split
+
+    df, session_ids = load_dataset_from_hub(
+        repo_id=resolved_repo,
+        split=resolved_split,
+        emb_dim=emb_dim,
+        exclude_sessions=exclude_sessions,
+    )
+
+    if df.empty:
+        raise ValueError("NO_DATA_AVAILABLE")
+    df = build_features(df)
+    result = train_lightgbm(df)
+    result["session_ids"] = session_ids
+    result["session_count"] = len(session_ids)
+    result["dataset_repo"] = resolved_repo
+    result["dataset_split"] = resolved_split or "ALL"
+    return result
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data-dir", default="./data")
+    parser.add_argument("--pattern", default="user*.parquet")
+    parser.add_argument("--emb-dim", type=int, default=EMB_DIM)
+    args = parser.parse_args()
+    main(args.data_dir, args.pattern, args.emb_dim)

train_scheduler.py

@@ -0,0 +1,243 @@
+"""
+LightGBM 모델 학습 스케줄러
+- 정해진 주기로 train_hybrid.py를 실행
+- 학습 상태 및 버전 메타데이터 관리
+"""
+
+import json
+import os
+import shutil
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import schedule
+
+from train_hybrid import main as train_main
+
+
+class TrainingScheduler:
+    def __init__(
+        self,
+        data_dir: str = "./data",
+        pattern: str = "user*.parquet",
+        schedule_time: str = "00:00",
+        state_file: str = "./logs/training_state.json",
+        versions_file: str = "./logs/model_versions.json",
+    ):
+        self.data_dir = data_dir
+        self.pattern = pattern
+        self.schedule_time = schedule_time
+        self.state_path = Path(state_file)
+        self.versions_path = Path(versions_file)
+        self.logs_dir = self.state_path.parent
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        self.models_dir = Path("models")
+        self.models_dir.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------ #
+    # State helpers
+    # ------------------------------------------------------------------ #
+    def _default_state(self) -> Dict[str, Optional[str]]:
+        return {
+            "last_training": None,
+            "model_version": 0,
+            "last_model_path": None,
+            "processed_sessions": [],
+        }
+
+    def load_training_state(self) -> Dict[str, Optional[str]]:
+        if self.state_path.exists():
+            state = json.loads(self.state_path.read_text(encoding="utf-8"))
+            state.setdefault("processed_sessions", [])
+            return state
+        return self._default_state()
+
+    def save_training_state(self, state: Dict) -> None:
+        self.state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    def reset_training_state(self) -> Dict:
+        state = self._default_state()
+        self.save_training_state(state)
+        if self.versions_path.exists():
+            self.versions_path.unlink()
+        return state
+
+    # ------------------------------------------------------------------ #
+    # Version helpers
+    # ------------------------------------------------------------------ #
+    def _load_versions(self) -> List[Dict]:
+        if self.versions_path.exists():
+            return json.loads(self.versions_path.read_text(encoding="utf-8"))
+        return []
+
+    def _save_versions(self, manifest: List[Dict]) -> None:
+        self.versions_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    def record_version(self, version: int, source_path: str, timestamp: str, metadata: Dict[str, Any]) -> str:
+        source = Path(source_path)
+        if not source.exists():
+            return source_path
+
+        versioned = self.models_dir / f"{source.stem}_v{version}{source.suffix}"
+        shutil.copy2(source, versioned)
+
+        manifest = self._load_versions()
+        manifest.append(
+            {
+                "version": version,
+                "filename": versioned.name,
+                "path": str(versioned),
+                "timestamp": timestamp,
+                "metrics": {
+                    "rmse": metadata.get("rmse"),
+                    "mae": metadata.get("mae"),
+                },
+                "sample_count": metadata.get("sample_count"),
+                "session_count": metadata.get("session_count"),
+                "dataset": {
+                    "repo_id": metadata.get("dataset_repo"),
+                    "split": metadata.get("dataset_split"),
+                },
+            }
+        )
+
+        # Rotate manifest and delete old artifacts
+        max_versions = int(os.getenv("MAX_MODEL_VERSIONS", "2"))
+        to_remove = []
+        if len(manifest) > max_versions:
+            to_remove = manifest[:-max_versions]
+            manifest = manifest[-max_versions:]
+            for old_entry in to_remove:
+                old_path = Path(old_entry["path"])
+                if old_path.exists():
+                    old_path.unlink()
+        self._save_versions(manifest)
+
+        return str(versioned)
+
+    def get_model_versions(self) -> List[Dict]:
+        return self._load_versions()
+
+    # ------------------------------------------------------------------ #
+    # Training
+    # ------------------------------------------------------------------ #
+    def run_scheduled_training(self) -> Dict[str, Optional[str]]:
+        print("=" * 80)
+        print(f"[TrainingScheduler] 학습 시작 - {datetime.utcnow().isoformat()}")
+        print("=" * 80)
+
+        try:
+            state = self.load_training_state()
+            processed_sessions = set(state.get("processed_sessions", []))
+        except Exception as exc:
+            print(f"[TrainingScheduler] 상태 로드 실패: {exc}")
+            return {
+                "status": "failed",
+                "new_data_count": 0,
+                "new_session_count": 0,
+                "model_path": None,
+                "model_version": 0,
+                "message": f"State load failed: {exc}",
+            }
+
+        try:
+            metadata = train_main(
+                self.data_dir,
+                self.pattern,
+                exclude_sessions=processed_sessions,
+            )
+        except FileNotFoundError as exc:
+            print(f"[TrainingScheduler] 데이터 누락: {exc}")
+            return {
+                "status": "skipped",
+                "new_data_count": 0,
+                "new_session_count": 0,
+                "model_path": None,
+                "model_version": state.get("model_version", 0),
+                "message": str(exc),
+            }
+        except ValueError as exc:
+            if "NO_DATA_AVAILABLE" in str(exc):
+                print("[TrainingScheduler] 새로운 세션이 없어 학습을 건너뜁니다.")
+                return {
+                    "status": "skipped",
+                    "new_data_count": 0,
+                    "new_session_count": 0,
+                    "model_path": None,
+                    "model_version": state.get("model_version", 0),
+                    "message": "No new sessions to train.",
+                }
+            print(f"[TrainingScheduler] 데이터 처리 오류: {exc}")
+            return {
+                "status": "failed",
+                "new_data_count": 0,
+                "new_session_count": 0,
+                "model_path": None,
+                "model_version": state.get("model_version", 0),
+                "message": f"Data processing error: {exc}",
+            }
+        except Exception as exc:
+            print(f"[TrainingScheduler] 학습 실패: {exc}")
+            return {
+                "status": "failed",
+                "new_data_count": 0,
+                "new_session_count": 0,
+                "model_path": None,
+                "model_version": state.get("model_version", 0),
+                "message": str(exc),
+            }
+
+        new_version = state.get("model_version", 0) + 1
+        timestamp = datetime.utcnow().isoformat()
+
+        model_artifact = metadata.get("model_path")
+        if not model_artifact:
+            raise ValueError("MODEL_ARTIFACT_MISSING")
+        versioned_path = self.record_version(new_version, model_artifact, timestamp, metadata)
+
+        used_sessions = metadata.get("session_ids", [])
+        new_sessions = [s for s in used_sessions if s not in processed_sessions]
+        processed_sessions.update(new_sessions)
+
+        state.update(
+            {
+                "last_training": timestamp,
+                "model_version": new_version,
+                "last_model_path": versioned_path,
+                "processed_sessions": sorted(processed_sessions),
+            }
+        )
+        self.save_training_state(state)
+
+        print(f"[TrainingScheduler] ✅ 학습 완료 - 버전 {new_version}, 샘플 {metadata.get('sample_count', 0)}")
+
+        return {
+            "status": "trained",
+            "new_data_count": metadata.get("sample_count", 0),
+            "model_path": versioned_path,
+            "model_version": new_version,
+            "metadata": metadata,
+            "new_session_count": len(new_sessions),
+        }
+
+    def trigger_training(self) -> Dict[str, Optional[str]]:
+        return self.run_scheduled_training()
+
+
+def main():
+    scheduler = TrainingScheduler()
+    schedule.clear()
+    schedule.every().sunday.at(scheduler.schedule_time).do(scheduler.run_scheduled_training)
+    print(f"[TrainingScheduler] 매주 일요일 {scheduler.schedule_time} 자동 학습이 예약되었습니다.")
+    try:
+        while True:
+            schedule.run_pending()
+            time.sleep(60)
+    except KeyboardInterrupt:
+        print("[TrainingScheduler] 스케줄러 종료")
+
+
+if __name__ == "__main__":
+    main()