Sync from GitHub Actions

.claude/skills/verify/SKILL.md

@@ -1,47 +0,0 @@
----
-name: verify
-description: 이 저장소의 변경을 실제 구동으로 검증하는 레시피 — 로컬 서버 기동, UI 구동, API 호출 방법
----
-
-# nbeats 검증 레시피
-
-## 로컬 서버 기동
-
-반드시 `venv`를 사용한다 (`.venv`는 의존성 불완전 — slowapi 없음, 시스템 anaconda python도 마찬가지):
-
-```bash
-./venv/bin/python -m uvicorn main:app --port 8077   # 부팅 20~40초 (torch/darts 임포트)
-curl http://127.0.0.1:8077/health                    # {"status":"ok"} 대기
-```
-
-macOS Apple Silicon에서 PyTorch+LightGBM OpenMP 충돌 방어 코드가 main.py에 이미 있으므로 별도 env 불필요.
-
-## 표면 구동
-
-- 페이지: `/`, `/prophet`, `/arima`, `/xgboost`, `/ets`, `/lightgbm`, `/theta`, `/hybrid`, `/timesfm`
-- 앙상블 API (파일 업로드 + horizon만 받음):
-  ```bash
-  curl -X POST http://127.0.0.1:8077/api/hybrid/predict \
-    -F "file=@test_data/stable_trend.csv" -F "forecast_horizon=12"
-  ```
-- 테스트 데이터: `test_data/stable_trend.csv` (월별 120행, 빠름), `daily_high_freq.csv` (일별 400행, 스트레스), `small_dataset.csv` (31행 — 50행 미만 검증 에러 확인용)
-- 앙상블 소요: 월별 120행 기준 로컬 수십 초, HF Space 26초 / 일별 400행은 HF Space 103초
-
-## 브라우저 파일 업로드 (claude-in-chrome)
-
-file_upload 도구가 호스트 경로를 거부하므로 javascript_tool로 주입:
-
-```js
-const f = new File([csvText], 'x.csv', {type:'text/csv'});
-const dt = new DataTransfer(); dt.items.add(f);
-const input = document.getElementById('fileInput');
-input.files = dt.files;
-input.dispatchEvent(new Event('change', {bubbles:true}));
-```
-
-## 라이브 Space 확인
-
-```bash
-curl https://psnc-time-series-prediction.hf.space/health          # {"status":"ok"}
-curl https://psnc-time-series-prediction.hf.space/api/timesfm/status  # {"status":"loaded"}
-```

AGENTS.md

@@ -1,227 +0,0 @@
-# AGENTS.md — N-BEATS Time Series Forecasting Service
-
-## 프로젝트 개요
-
-FastAPI 기반 시계열 예측 서비스. 7가지 예측 모델을 웹 UI와 REST API로 제공하며, Hugging Face Spaces에 Docker 컨테이너로 배포된다.
-
-- **서비스 URL:** https://huggingface.co/spaces/psnc/time-series-prediction
-- **라이선스:** MIT License
-
----
-
-## 기술 스택
-
-| 레이어 | 기술 |
-|--------|------|
-| Web Framework | FastAPI + Uvicorn (ASGI) |
-| Deep Learning | Darts (N-BEATS), PyTorch, PyTorch Lightning |
-| Statistical | statsmodels (ARIMA, ETS, Theta), Prophet |
-| ML | XGBoost, LightGBM |
-| Data | pandas, numpy |
-| Frontend | Vanilla JS, Chart.js, XLSX.js (다크 테마) |
-| Deploy | Docker → Hugging Face Spaces via GitHub Actions |
-
----
-
-## 디렉터리 구조
-
-```
-nbeats/
-├── main.py                          # FastAPI 앱, 모든 라우트 정의 (782줄)
-├── requirements.txt
-├── Dockerfile                       # HF Spaces 배포용 (port 7860)
-├── run.sh                           # 개발 서버 (--reload)
-├── start.sh                         # 프로덕션 서버
-├── run_test.py                      # 서비스 직접 테스트
-├── .github/workflows/deploy.yml    # main push → HF 자동 배포
-├── src/domains/time_series_prediction/
-│   ├── data_service.py             # 파일 파싱 및 유효성 검사
-│   ├── data_profile.py             # 공통 데이터 분석 (DataProfile 데이터클래스)
-│   ├── model_parameters.py         # N-BEATS 파라미터 스키마
-│   ├── nbeats_service.py           # N-BEATS 구현 (575줄)
-│   ├── prophet_service.py          # Prophet 구현 (412줄)
-│   ├── arima_service.py            # ARIMA/SARIMA 구현 (516줄)
-│   ├── xgboost_service.py          # XGBoost 구현 (557줄)
-│   ├── ets_service.py              # ETS/Holt-Winters 구현 (315줄)
-│   ├── lightgbm_service.py         # LightGBM 구현 (506줄)
-│   └── theta_service.py            # Theta Method 구현 (302줄)
-├── static/
-│   ├── index.html                  # N-BEATS UI
-│   ├── prophet.html
-│   ├── arima.html
-│   ├── xgboost.html
-│   ├── ets.html
-│   ├── lightgbm.html
-│   └── theta.html
-├── test_data/                      # 테스트용 CSV 데이터셋
-├── tests/
-│   ├── test_nbeats.py
-│   ├── test_auto_scaling.py
-│   └── generate_test_datasets.py
-└── backend/                        # 레거시 코드 (보관용)
-```
-
----
-
-## 구현된 모델
-
-| 모델 | 유형 | 라이브러리 | 특징 |
-|------|------|-----------|------|
-| **N-BEATS** | 딥러닝 | Darts + PyTorch | 스택 기반 신경망, 앙상블 |
-| **Prophet** | 베이지안 | Meta/Facebook | 추세 변화점 자동 감지, 신뢰구간 |
-| **ARIMA/SARIMA** | 통계 | statsmodels | AIC 기반 자동 차수 선택 |
-| **XGBoost** | 그래디언트 부스팅 | xgboost | 래그 피처, 롤링 통계 |
-| **LightGBM** | 그래디언트 부스팅 | lightgbm | Leaf-wise 분할, XGBoost 대비 2-5배 빠름 |
-| **ETS** | 지수평활 | statsmodels | Holt-Winters, 감쇠 추세 |
-| **Theta** | 고전 통계 | statsmodels | M3 대회 우승 알고리즘 |
-
----
-
-## API 구조
-
-### 공통 패턴
-
-- **Page Routes:** `GET /`, `/prophet`, `/arima`, `/xgboost`, `/ets`, `/lightgbm`, `/theta`
-- **Health:** `GET /health`, `GET /api/status`
-- **Template:** `GET /download_template?file_format=csv|xlsx|json`
-
-### 모델별 엔드포인트
-
-```
-POST /nbeats                          → N-BEATS 예측 (백테스트 옵션)
-GET  /nbeats/parameters               → 파라미터 스키마
-POST /nbeats/evaluate                 → 훈련/테스트 분리 평가
-
-POST /api/{prophet,arima,xgboost,ets,lightgbm,theta}/predict
-```
-
-### 공통 응답 형식
-
-```json
-{
-  "success": true,
-  "data": [{"ds": "2024-01-01", "y": 100.0, "yhat": 102.5}],
-  "metrics": {"mae": 2.1, "rmse": 3.4, "mape": 0.021, "r2": 0.95},
-  "test_size": 30
-}
-```
-
----
-
-## 데이터 처리 파이프라인
-
-### 입력 포맷
-- **지원:** CSV, Excel (.xlsx), JSON
-- **필수 컬럼:** `date`(또는 `ds`) + `value`/`target`(또는 `y`)
-- **최소 데이터 포인트:** 50개
-
-### DataProfile (data_profile.py)
-자동 분석 결과를 담는 데이터클래스. 모든 모델의 파라미터 자동 조정에 사용된다.
-
-```python
-@dataclass
-class DataProfile:
-    n_samples: int
-    freq: str               # 'D', 'W', 'MS', 'QS', 'YS' 등
-    seasonal_period: int
-    break_index: int        # 구조적 변화점 인덱스 (-1이면 없음)
-    volatility: float       # 변동성 지수
-    trend_type: str         # 'stable', 'gradual', 'sudden'
-    seasonality_mode: str   # 'additive', 'multiplicative'
-```
-
-### 자동 파라미터 조정 (Auto-Tuning)
-모든 모델은 `DataProfile`에 기반하여 파라미터를 자동 조정한다:
-- **주파수 감지** → 계절 주기 자동 설정
-- **구조적 변화점 감지** (CUSUM) → 최근 데이터만 학습 옵션
-- **이상값 감지** (IQR 2.5배) → 전처리 적용
-- **계절성 모드** (변동계수 비교) → additive/multiplicative 선택
-
----
-
-## 서비스 레이어 규칙
-
-새 모델 추가 시 `{model}_service.py`에 다음 4개 함수를 구현한다:
-
-```python
-def apply_defaults(params: dict) -> dict:
-    """파라미터 기본값 병합"""
-
-def get_parameters() -> dict:
-    """파라미터 스키마 반환 (UI 렌더링용)"""
-
-def predict_with_{model}(df: pd.DataFrame, params: dict) -> dict:
-    """예측 실행 → {"success", "data", "metrics"} 반환"""
-
-def evaluate_with_{model}(df: pd.DataFrame, params: dict) -> dict:
-    """백테스트 평가"""
-```
-
----
-
-## 배포
-
-### 로컬 실행
-
-```bash
-# 개발 (자동 리로드)
-bash run.sh
-# 또는
-uvicorn main:app --reload --port 8000
-
-# 프로덕션 테스트
-bash start.sh
-```
-
-### GitHub Actions → Hugging Face 자동 배포
-
-`main` 브랜치에 push하면 `.github/workflows/deploy.yml`이 실행되어 HF Spaces로 force push한다.
-
-- **필요 Secret:** `HF_TOKEN` (GitHub Settings에 등록)
-- **HF Port:** 7860 (Dockerfile에 명시됨)
-- **HF User:** psnc
-
-### Docker
-
-```dockerfile
-FROM python:3.10-slim
-# 빌드 도구 필요: gcc, g++, build-essential (Prophet, statsmodels 컴파일)
-# 비root 실행: appuser (UID 1000)
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
-```
-
----
-
-## 테스트
-
-```bash
-# 단위 테스트
-python -m pytest tests/
-
-# 서비스 직접 테스트 (API 없이)
-python run_test.py
-```
-
-**주요 테스트 파일:**
-- `tests/test_nbeats.py` — N-BEATS 예측 정확도
-- `tests/test_auto_scaling.py` — 자동 파라미터 조정 검증 (MASE < 2.0 기대값)
-
----
-
-## 코딩 컨벤션
-
-- **언어:** Python 3.10+
-- **네이밍:** 클래스 CamelCase, 함수/변수 snake_case
-- **주석/독스트링:** 한국어
-- **에러 처리:** `HTTPException` + `logging` (INFO 레벨)
-- **타입 힌트:** 일부 함수는 누락 (기존 코드 수정 시 강제 추가 불필요)
-- **배치 크기:** N-BEATS는 메모리 안전을 위해 최대 32로 제한
-
----
-
-## 주의사항
-
-- N-BEATS는 포인트 예측만 제공 (신뢰구간 없음). 구간 예측이 필요하면 Prophet 또는 ARIMA 사용 권장.
-- XGBoost/LightGBM은 Direct Multi-Step 방식 사용 (각 예측 스텝별 별도 모델로 오차 누적 방지).
-- HF Spaces 재배포는 Docker 빌드를 포함하므로 시간이 걸릴 수 있다.
-- `backend/` 디렉터리는 레거시 코드로 실제 서비스에 사용되지 않는다.

CLAUDE.md

@@ -1,297 +0,0 @@
-# CLAUDE.md — N-BEATS Time Series Forecasting Service
-
-## 프로젝트 개요
-
-FastAPI 기반 시계열 예측 서비스. 7개 단일 모델 + TimesFM 파운데이션 모델 + 하이브리드 앙상블을 웹 UI와 REST API로 제공하며, Hugging Face Spaces에 Docker 컨테이너로 배포된다. TimesFM 전용 Next.js 프론트엔드는 Vercel에 별도 배포된다.
-
-- **서비스 URL:** https://huggingface.co/spaces/psnc/time-series-prediction
-- **직접 접근:** https://psnc-time-series-prediction.hf.space
-- **라이선스:** MIT License
-
----
-
-## 기술 스택
-
-| 레이어 | 기술 |
-|--------|------|
-| Web Framework | FastAPI + Uvicorn (ASGI) |
-| Deep Learning | Darts (N-BEATS), PyTorch (CPU 전용 휠), PyTorch Lightning |
-| Foundation Model | TimesFM 2.5 200M (Google, GitHub 소스 핀 설치) |
-| Statistical | statsmodels (ARIMA, ETS, Theta), Prophet |
-| ML | XGBoost, LightGBM |
-| Data | pandas, numpy |
-| Frontend | Vanilla JS, Chart.js, XLSX.js (다크 테마) / TimesFM 전용: Next.js |
-| Deploy | Docker → HF Spaces + Next.js → Vercel (GitHub Actions) |
-
----
-
-## 디렉터리 구조
-
-```
-nbeats/
-├── main.py                          # FastAPI 앱, 모든 라우트 정의 (638줄)
-├── requirements.txt                 # 전 의존성 버전 고정 (+cpu torch)
-├── Dockerfile                       # HF Spaces 배포용 (port 7860)
-├── run.sh                           # 개발 서버 (--reload, port 8000)
-├── start.sh                         # 프로덕션 서버
-├── run_test.py                      # 서비스 직접 테스트
-├── .github/workflows/deploy.yml    # main push → HF + Vercel 자동 배포
-├── .claude/skills/verify/          # 검증 레시피 (로컬 기동·UI 구동 방법)
-├── src/domains/time_series_prediction/
-│   ├── data_service.py             # 파일 파싱 및 유효성 검사
-│   ├── data_profile.py             # 공통 데이터 분석 (DataProfile 데이터클래스)
-│   ├── model_parameters.py         # N-BEATS 파라미터 스키마
-│   ├── nbeats_service.py           # N-BEATS 구현
-│   ├── prophet_service.py          # Prophet 구현
-│   ├── arima_service.py            # ARIMA/SARIMA 구현
-│   ├── xgboost_service.py          # XGBoost 구현
-│   ├── ets_service.py              # ETS/Holt-Winters 구현
-│   ├── lightgbm_service.py         # LightGBM 구현
-│   ├── theta_service.py            # Theta Method 구현
-│   ├── ensemble_service.py         # 7모델 비동기 앙상블 오케스트레이터
-│   └── timesfm_service.py          # TimesFM 2.5 (싱글톤 로드)
-├── static/                          # 모델별 UI (index=N-BEATS, prophet, arima,
-│   │                                #  xgboost, ets, lightgbm, theta,
-│   ├── hybrid.html                  #  하이브리드 앙상블, timesfm)
-│   ├── nav.js                       # 공유 모델 드롭다운 내비 (모델 추가 시 MODELS 배열만 수정)
-│   └── ...
-├── timesfm-frontend/                # TimesFM 전용 Next.js 앱 (Vercel 배포)
-├── test_data/                       # 테스트용 CSV 데이터셋
-├── tests/                           # 전체 pytest 호환 (92개, CI 배포 게이트로 실행)
-│   ├── test_nbeats.py
-│   ├── test_auto_scaling.py
-│   ├── test_hybrid.py              # 앙상블 가중치·집계 단위 테스트
-│   ├── test_api_contract.py        # API 응답 형식·에러 코드 계약
-│   ├── test_nonblocking_endpoints.py
-│   ├── test_timesfm_horizon.py
-│   ├── test_ensemble_concurrency.py
-│   ├── test_data_service.py
-│   ├── test_supply_chain_hardening.py
-│   └── generate_test_datasets.py
-└── backend/                         # 레거시 코드 (보관용)
-```
-
----
-
-## 구현된 모델
-
-| 모델 | 유형 | 라이브러리 | 특징 |
-|------|------|-----------|------|
-| **N-BEATS** | 딥러닝 | Darts + PyTorch | 스택 기반 신경망, 앙상블 |
-| **Prophet** | 베이지안 | Meta/Facebook | 추세 변화점 자동 감지, 신뢰구간 |
-| **ARIMA/SARIMA** | 통계 | statsmodels | AIC 기반 자동 차수 선택 |
-| **XGBoost** | 그래디언트 부스팅 | xgboost | 래그 피처, 롤링 통계 |
-| **LightGBM** | 그래디언트 부스팅 | lightgbm | Leaf-wise 분할, XGBoost 대비 2-5배 빠름 |
-| **ETS** | 지수평활 | statsmodels | Holt-Winters, 감쇠 추세 |
-| **Theta** | 고전 통계 | statsmodels | M3 대회 우승 알고리즘 |
-| **TimesFM 2.5** | 파운데이션 모델 | Google (200M) | 제로샷 예측, 분위수 신뢰구간, 요청별 학습 불필요 |
-| **하이브리드 앙상블** | 메타 | ensemble_service | 위 7개 단일 모델의 DataProfile 기반 가중 평균 |
-
----
-
-## API 구조
-
-### 공통 패턴
-
-- **Page Routes:** `GET /`, `/prophet`, `/arima`, `/xgboost`, `/ets`, `/lightgbm`, `/theta`, `/hybrid`, `/timesfm`
-- **Health:** `GET /health`, `GET /api/status`
-- **Template:** `GET /download_template?file_format=csv|xlsx|json`
-
-### 모델별 엔드포인트
-
-```
-POST /nbeats                          → N-BEATS 예측 (백테스트 옵션)
-GET  /nbeats/parameters               → 파라미터 스키마
-POST /nbeats/evaluate                 → 훈련/테스트 분리 평가
-
-POST /api/{prophet,arima,xgboost,ets,lightgbm,theta}/predict
-GET  /api/{prophet,arima,xgboost,ets,lightgbm,theta}/parameters
-
-POST /api/hybrid/predict              → 7모델 앙상블 (file + forecast_horizon(1~500) + model_weights(JSON, 선택))
-GET  /api/timesfm/status              → TimesFM 로딩 상태 (not_loaded|loading|loaded|error)
-POST /api/timesfm/predict             → TimesFM 제로샷 예측
-```
-
-### 공통 응답 형식 (단일 모델)
-
-```json
-{
-  "success": true,
-  "data": [{"ds": "2024-01-01", "y": 100.0, "yhat": 102.5}],
-  "metrics": {"mae": 2.1, "rmse": 3.4, "mape": 0.021, "r2": 0.95},
-  "test_size": 30
-}
-```
-
-### 하이브리드 앙상블 응답
-
-```json
-{
-  "success": true,
-  "baseline": {
-    "data": [{"ds": "...", "y": null, "yhat": 0.0, "yhat_upper": 0.0, "yhat_lower": 0.0}],
-    "model_weights": {"nbeats": 0.2},
-    "uncertainty": 0.07
-  },
-  "models_used": ["nbeats", "..."],
-  "models_failed": []
-}
-```
-
-- 역사 구간 행은 `yhat=null`, 예측 구간 행은 `y=null` — 하위 처리 시 None 체크 필수.
-- `yhat_upper/lower`는 모델 간 예측 표준편차 ±1.96σ. 백테스트가 없어 `metrics`는 빈 dict.
-- LLM 보정 레이어는 2026-07-10 제거됨 (침묵 폴백 문제 + 검증 불가). 순수 앙상블만 제공.
-
----
-
-## 데이터 처리 파이프라인
-
-### 입력 포맷
-- **지원:** CSV, Excel (.xlsx), JSON
-- **필수 컬럼:** `date`(또는 `ds`) + `value`/`target`(또는 `y`)
-- **최소 데이터 포인트:** 50개
-- **최대 파일 크기:** 10MB (초과 시 413)
-
-### DataProfile (data_profile.py)
-자동 분석 결과를 담는 데이터클래스. 모든 모델의 파라미터 자동 조정에 사용된다.
-
-```python
-@dataclass
-class DataProfile:
-    n_samples: int
-    freq: str               # 'D', 'W', 'MS', 'QS', 'YS' 등
-    seasonal_period: int
-    break_index: int        # 구조적 변화점 인덱스 (-1이면 없음)
-    volatility: float       # 변동성 지수
-    trend_type: str         # 'stable', 'gradual', 'sudden'
-    seasonality_mode: str   # 'additive', 'multiplicative'
-```
-
-### 자동 파라미터 조정 (Auto-Tuning)
-모든 모델은 `DataProfile`에 기반하여 파라미터를 자동 조정한다:
-- **주파수 감지** → 계절 주기 자동 설정
-- **구조적 변화점 감지** (CUSUM) → 최근 데이터만 학습 옵션
-- **이상값 감지** (IQR 2.5배) → 전처리 적용
-- **계절성 모드** (변동계수 비교) → additive/multiplicative 선택
-
-앙상블 가중치도 DataProfile로 조정된다 (ensemble_service.py):
-volatility > 0.3 → nbeats·prophet +0.05, trend stable → ets·theta +0.05,
-구조 변화점 존재 → xgboost·lightgbm +0.05, 합계 1.0 정규화.
-`model_weights`(JSON, 선택)로 수동 가중치를 넘기면 자동 조정 대신 사용되며,
-가중치 0인 모델은 실행 자체를 건너뛴다 (양수 모델 2개 미만이면 422).
-
----
-
-## 서비스 레이어 규칙
-
-새 모델 추가 시 `{model}_service.py`에 다음 4개 함수를 구현한다:
-
-```python
-def apply_defaults(params: dict) -> dict:
-    """파라미터 기본값 병합"""
-
-def get_parameters() -> dict:
-    """파라미터 스키마 반환 (UI 렌더링용)"""
-
-def predict_with_{model}(df: pd.DataFrame, params: dict) -> dict:
-    """예측 실행 → {"success", "data", "metrics"} 반환"""
-
-def evaluate_with_{model}(df: pd.DataFrame, params: dict) -> dict:
-    """백테스트 평가"""
-```
-
-앙상블에 편입하려면 `ensemble_service.py`의 `model_configs`와 `_DEFAULT_WEIGHTS`에 등록한다.
-
----
-
-## 배포
-
-### 로컬 실행
-
-```bash
-# 개발 (자동 리로드) — 반드시 venv 사용 (.venv는 의존성 불완전)
-bash run.sh
-# 또는
-./venv/bin/python -m uvicorn main:app --reload --port 8000
-```
-
-부팅에 20~40초 걸린다 (torch/darts 임포트 + TimesFM 데몬 스레드 로드).
-
-### GitHub Actions → HF + Vercel 자동 배포
-
-`main` 브랜치에 push하면 `.github/workflows/deploy.yml`이 변경 경로에 따라 job을 선별 실행한다:
-
-- **changes:** git diff로 변경 파일을 backend/frontend/tests로 분류 (force-push·workflow_dispatch는 전체 배포로 폴백)
-- **test:** backend 또는 tests 변경 시 Python 3.10(프로덕션 Docker와 동일)에서 전체 pytest 실행 — deploy-hf의 필수 게이트. timesfm git 소스 설치를 위해 GIT_CONFIG_* 환경변수로 러너의 git-lfs 필터를 무력화한다
-- **deploy-hf:** backend 변경 + 테스트 통과 시에만 `HfApi.upload_folder`로 기존 Space에 직접 커밋 (free-tier Docker Space의 create_repo 402 페이월을 우회하기 위해 hf CLI 대신 사용). `tests/`는 업로드 제외
-- **deploy-vercel:** `timesfm-frontend/**` 변경 시에만 Vercel prebuilt 방식으로 프로덕션 배포
-
-**필요 Secret:** `HF_TOKEN`, `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`
-
-### Docker
-
-```dockerfile
-FROM python:3.10-slim
-# 빌드 도구 필요: gcc, g++, build-essential (Prophet, statsmodels 컴파일)
-# 비root 실행: appuser (UID 1000)
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
-```
-
-FastAPI 앱은 별도 환경변수 없이 동작한다. Claude API를 쓰는 곳은 timesfm-frontend의
-`/api/interpret` 라우트뿐이며, 키는 Vercel 환경변수 `ANTHROPIC_API_KEY`로 관리된다.
-
----
-
-## 테스트
-
-```bash
-# 단위 테스트
-python -m pytest tests/
-
-# 서비스 직접 테스트 (API 없이)
-python run_test.py
-```
-
-**주요 테스트 파일:**
-- `tests/test_nbeats.py` — N-BEATS 학습·예측 (소형 파라미터로 실제 학습)
-- `tests/test_auto_scaling.py` — 자동 파라미터 조정 검증 (MASE < 2.0 기대값)
-- `tests/test_hybrid.py` — 앙상블 가중치 산정·집계·수동 가중치 검증 로직
-- `tests/test_api_contract.py` — API 응답 형식·에러 코드 계약 (모델 학습 없이 빠름)
-- `tests/test_nonblocking_endpoints.py` — 예측 실행 중 이벤트 루프 논블로킹 검증
-- `tests/test_timesfm_horizon.py` — TimesFM horizon 한도(256) 처리
-- `tests/test_ensemble_concurrency.py` — 서버 전역 Semaphore(3) 동시 실행 제한
-- `tests/test_data_service.py` — 파일 파싱 (인코딩 폴백·오류 메시지 구분)
-- `tests/test_supply_chain_hardening.py` — 배포 공급망 방어 + 배포 경로 게이트 검증
-
-**테스트 작성 주의:** `ensemble_service._MODEL_SEMAPHORE`는 모듈 전역이라 최초
-경합 시 해당 이벤트 루프에 바인딩된다. `asyncio.run`(새 루프)으로
-`run_ensemble_async`를 직접 호출하는 테스트는 monkeypatch로 새 Semaphore를
-주입해야 다른 테스트와 순서 의존 충돌이 없다 (test_hybrid.py `_isolate_semaphore` 참고).
-
-변경 검증(로컬 기동·UI 구동 레시피)은 `.claude/skills/verify/SKILL.md` 참고.
-
----
-
-## 코딩 컨벤션
-
-- **언어:** Python 3.10+
-- **네이밍:** 클래스 CamelCase, 함수/변수 snake_case
-- **주석/독스트링:** 한국어
-- **에러 처리:** `HTTPException` + `logging` (INFO 레벨)
-- **타입 힌트:** 일부 함수는 누락 (기존 코드 수정 시 강제 추가 불필요)
-- **배치 크기:** N-BEATS는 메모리 안전을 위해 최대 32로 제한
-
----
-
-## 주의사항
-
-- **requirements.txt는 전 의존성 버전 고정.** torch는 반드시 CPU 전용 휠(`+cpu`, extra-index-url) — 기본 PyPI 휠은 CUDA 스택 ~3GB를 끌어와 HF CPU Space 부팅을 망가뜨린다.
-- **TimesFM은 GitHub 커밋 핀 설치** (`timesfm[torch] @ git+...@d720daa`). PyPI 버전과 API가 다르므로 임의 업그레이드 금지. 앱 시작 시 데몬 스레드로 로드해야 SIGTERM 종료가 매달리지 않는다 (main.py lifespan 참고).
-- **macOS Apple Silicon 로컬 실행 시** PyTorch+LightGBM OpenMP 충돌 방어가 main.py 상단에 있다 (`KMP_DUPLICATE_LIB_OK`, ML 임포트 전 설정 필수). 앙상블은 서버 전역 Semaphore(3)로 동시 실행 모델 수를 제한한다.
-- **Claude API 응답을 JSON 파싱할 때는 마크다운 코드블록 제거 필수** (timesfm-frontend의 interpret 라우트 참고). FastAPI 앱은 2026-07-10부터 Claude API를 사용하지 않는다 (hybrid LLM 보정·TimesFM 해설 모두 제거).
-- N-BEATS는 포인트 예측만 제공 (신뢰구간 없음). 구간 예측이 필요하면 Prophet, ARIMA, Theta, TimesFM 또는 하이브리드 앙상블 사용 권장. (ETS, XGBoost, LightGBM도 포인트 예측만.)
-- TimesFM은 test 구간 포함 최대 256 스텝(max_horizon)까지만 예측 — 초과 요청은 한도 내로 잘리고 경고 로그를 남긴다.
-- XGBoost/LightGBM은 Direct Multi-Step 방식 사용 (각 예측 스텝별 별도 모델로 오차 누적 방지).
-- 앙상블은 요청마다 7개 모델을 학습하므로 느리다 (HF Space 실측: 월별 120행 26초, 일별 400행 103초). 모델별 타임아웃 180초, 성공 모델 2개 미만이면 422.
-- HF Spaces 재배포는 Docker 빌드를 포함하므로 시간이 걸릴 수 있다.
-- `backend/` 디렉터리는 레거시 코드로 실제 서비스에 사용되지 않는다.

README_N-BEATS.md

@@ -1,122 +0,0 @@
-# N-BEATS 시계열 예측 모델 사용 가이드
-
-## 입력 데이터 형식
-
-N-BEATS 및 다른 모든 시계열 예측 모델(Prophet, XGBoost, ARIMA, SARIMA 등)은 공통된 표준 데이터 형식을 사용합니다:
-
-### 필수 컬럼
-- `ds`: 날짜/시간 컬럼 (필수)
-- `y`: 예측하려는 대상 값 컬럼 (필수)
-
-### 데이터 요구사항
-- 최소 50개 이상의 데이터 포인트 필요 (더 많을수록 좋음)
-- 날짜는 일관된 간격을 가져야 함 (일별, 주별, 월별 등)
-- 결측치나 이상치는 모델 성능에 영향을 줄 수 있음
-
-### 지원되는 날짜 형식
-다음과 같은 다양한 날짜 형식을 지원합니다:
-- ISO 형식: `2023-01-01`
-- 슬래시 형식: `01/01/2023` 또는 `2023/01/01`
-- 컴팩트 형식: `20230101`
-- 텍스트 형식: `01-Jan-2023`, `Jan-01-2023`
-
-### 지원되는 파일 형식
-다음과 같은 파일 형식을 지원합니다:
-- CSV (`.csv`)
-- Excel (`.xlsx`, `.xls`)
-- JSON (`.json`)
-
-### 예시 CSV 형식
-```
-ds,y
-2023-01-01,100
-2023-01-02,105
-2023-01-03,98
-...
-```
-
-### 예시 JSON 형식
-```json
-[
-  {"ds": "2023-01-01", "y": 100},
-  {"ds": "2023-01-02", "y": 105},
-  {"ds": "2023-01-03", "y": 98},
-  ...
-]
-```
-또는
-```json
-{
-  "data": [
-    {"ds": "2023-01-01", "y": 100},
-    {"ds": "2023-01-02", "y": 105},
-    {"ds": "2023-01-03", "y": 98},
-    ...
-  ]
-}
-```
-
-## API 요청 예시
-
-```json
-{
-  "model_type": "nbeats", 
-  "forecast_periods": 30,
-  "params": {
-    "input_chunk_length": 24,
-    "output_chunk_length": 12,
-    "generic_architecture": true,
-    "num_stacks": 10,
-    "num_blocks": 1,
-    "num_layers": 4,
-    "layer_widths": 256,
-    "expansion_coefficient_dim": 5,
-    "dropout": 0.1,
-    "n_epochs": 100,
-    "batch_size": 32,
-    "learning_rate": 0.001
-  }
-}
-```
-
-## 주요 파라미터 설명
-
-### 기본 파라미터
-- `model_type`: 'nbeats' (고정값)
-- `forecast_periods`: 예측할 기간 수
-- `input_chunk_length`: 입력 시퀀스 길이 (과거 데이터 포인트 수)
-- `output_chunk_length`: 출력 시퀀스 길이 (한 번에 예측할 미래 데이터 포인트 수)
-
-### 고급 파라미터
-- `generic_architecture`: 일반 아키텍처 사용 여부 (true/false)
-- `num_stacks`: 스택 수
-- `num_blocks`: 블록 수
-- `num_layers`: 레이어 수
-- `layer_widths`: 레이어 너비
-- `expansion_coefficient_dim`: 확장 계수 차원
-- `dropout`: 드롭아웃 비율
-- `n_epochs`: 학습 에포크
-
-## 중요 참고사항
-
-1. N-BEATS 모델은 다른 시계열 예측 모델에 비해 많은 데이터 포인트를 필요로 합니다. 최소 50개 이상의 데이터 포인트를 제공하는 것이 좋습니다.
-
-2. 날짜 데이터는 일관된 간격을 가져야 합니다. 불규칙한 간격의 데이터는 모델 성능을 저하시킬 수 있습니다.
-
-3. 모든 예측 모델(N-BEATS, Prophet, XGBoost, ARIMA, SARIMA)은 동일한 'ds'와 'y' 컬럼 형식을 사용하므로, 데이터를 표준화하면 여러 모델을 쉽게 비교할 수 있습니다.
-
-4. 대규모 데이터셋의 경우 학습 시간이 길어질 수 있으므로 `n_epochs`와 `batch_size` 파라미터를 적절히 조정하는 것이 좋습니다.
-
-5. **신뢰 구간 없음**: N-BEATS는 기본적으로 신뢰 구간(상한/하한 경계)을 제공하지 않고 단일 예측값만 생성합니다. 이는 Prophet이나 ARIMA와 같은 통계적 모델과의 주요 차이점입니다. 신뢰 구간이 필요한 경우 Prophet 또는 ARIMA 모델 사용을 고려하세요.
-
-6. **배치 크기 제한**: 메모리 문제를 방지하기 위해 다음과 같은 배치 크기 가이드라인을 권장합니다:
-   - 기본 설정: 8 (안전한 기본값)
-   - 일반적인 사용: 16-32 (대부분의 시스템에서 안정적)
-   - 최대 권장: 32 (32를 초과하는 값은 메모리 오류 위험이 높아집니다)
-   - 시스템 메모리가 충분하면 최대 64까지 사용 가능
-   
-   시스템에서 자동으로 배치 크기를 32로 제한하여 메모리 오류를 방지합니다.
-
-7. **모델 복잡성과 학습 시간**: 복잡한 모델(스택, 블록, 레이어 수가 많은 모델)은 더 많은 메모리를 사용하므로 배치 크기를 줄여야 할 수 있습니다. 또한 학습 시간이 길어지므로 시간과 성능 사이의 균형을 고려하세요.
-
-8. **성능 평가 (백테스트)**: N-BEATS는 신뢰 구간을 제공하지 않지만, 백테스트로 모델 성능을 평가할 수 있습니다. 데이터의 마지막 20%를 검증용으로 분할하여 학습 후 예측값과 실제값을 비교하고, **MAE**, **RMSE**, **MAPE**, **R²** 지표를 계산합니다. 예측 API에 `include_evaluation=true`를 추가하거나 `/nbeats/evaluate` 엔드포인트를 사용하세요. (최소 60개 데이터 필요) 

requirements.txt

@@ -20,7 +20,7 @@ openpyxl==3.1.5
 
 # N-BEATS (Darts)
 darts==0.45.0
-torch==2.12.1+cpu
+torch==2.13.0+cpu
 pytorch-lightning==2.6.5
 
 # Prophet