chore: untrack .env.example and add timesfm phase1 plan doc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/superpowers/plans/2026-04-03-timesfm-phase1.md

@@ -0,0 +1,1074 @@
+# TimesFM Phase 1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 기존 FastAPI 백엔드에 TimesFM 2.5 예측 모델을 추가하고 전용 UI 페이지를 제공한다.
+
+**Architecture:** `timesfm_service.py`에서 싱글톤 패턴으로 모델을 한 번만 로드하고, `main.py`의 lifespan 이벤트로 앱 시작 시 백그라운드 로딩을 실행한다. 기존 7개 모델 코드는 일절 수정하지 않는다.
+
+**Tech Stack:** timesfm[torch], anthropic SDK, FastAPI lifespan, Chart.js, Vanilla JS
+
+---
+
+## 파일 맵
+
+| 작업 | 경로 | 비고 |
+|------|------|------|
+| 수정 | `requirements.txt` | timesfm[torch], huggingface_hub 추가 |
+| 신규 | `src/domains/time_series_prediction/timesfm_service.py` | 싱글톤 모델 + 예측 + Claude 해석 |
+| 수정 | `main.py` | lifespan 추가, 4개 라우트 추가, 3개 import 추가 |
+| 신규 | `static/timesfm.html` | TimesFM 전용 다크 테마 UI |
+| 수정 | `Dockerfile` | HF 캐시 디렉터리 설정 |
+
+---
+
+## Task 1: requirements.txt에 패키지 추가
+
+**Files:**
+- Modify: `requirements.txt`
+
+- [ ] **Step 1: requirements.txt 하단에 추가**
+
+기존 내용 유지, 파일 맨 끝에 다음 블록 추가:
+
+```
+# TimesFM 관련 추가 패키지
+timesfm[torch]
+huggingface_hub>=0.23.0
+```
+
+> `anthropic>=0.25.0`은 이미 있으므로 추가하지 않는다.
+
+- [ ] **Step 2: 커밋**
+
+```bash
+git add requirements.txt
+git commit -m "chore: add timesfm and huggingface_hub to requirements"
+```
+
+---
+
+## Task 2: timesfm_service.py 신규 생성
+
+**Files:**
+- Create: `src/domains/time_series_prediction/timesfm_service.py`
+
+- [ ] **Step 1: 파일 생성**
+
+```python
+"""
+TimesFM 2.5 예측 서비스
+싱글톤 패턴으로 모델을 한 번만 로드하고 재사용한다.
+"""
+import os
+import logging
+import threading
+import math
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+# ─── 싱글톤 모델 상태 ────────────────────────────────────────
+_model = None
+_model_status = "not_loaded"  # "not_loaded" | "loading" | "loaded" | "error:<msg>"
+_lock = threading.Lock()
+
+
+def load_model():
+    """앱 시작 시 1회 호출. CPU 백엔드로 TimesFM 2.5 로드."""
+    global _model, _model_status
+    with _lock:
+        if _model_status in ("loading", "loaded"):
+            return
+        _model_status = "loading"
+    try:
+        import timesfm
+        model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+            "google/timesfm-2.5-200m-pytorch"
+        )
+        model.compile(
+            timesfm.ForecastConfig(
+                max_context=1024,
+                max_horizon=256,
+                normalize_inputs=True,
+                use_continuous_quantile_head=True,
+                infer_is_positive=True,
+                fix_quantile_crossing=True,
+            )
+        )
+        with _lock:
+            _model = model
+            _model_status = "loaded"
+        logger.info("TimesFM 2.5 모델 로딩 완료")
+    except Exception as e:
+        with _lock:
+            _model_status = f"error: {str(e)}"
+        logger.error("TimesFM 모델 로딩 실패: %s", e)
+
+
+def get_status() -> str:
+    """현재 모델 로딩 상태 반환."""
+    return _model_status
+
+
+# ─── 주파수 인디케이터 변환 ──────────────────────────────────
+_FREQ_HIGH = {"D", "H", "T", "MIN", "S"}
+_FREQ_LOW = {"YS", "Y", "A", "AS"}
+
+
+def get_freq_indicator(freq_str: str) -> int:
+    """pandas freq string → TimesFM freq indicator (0/1/2)."""
+    upper = freq_str.upper() if freq_str else "MS"
+    if upper in _FREQ_HIGH:
+        return 0
+    if upper in _FREQ_LOW:
+        return 2
+    return 1  # W, M, MS, QS, Q 등 중빈도
+
+
+# ─── 메트릭 계산 ─────────────────────────────────────────────
+def _calc_metrics(y_true: np.ndarray, y_pred: np.ndarray) -> dict:
+    """MAE, RMSE, MAPE, R² 계산."""
+    mae = float(np.mean(np.abs(y_true - y_pred)))
+    rmse = float(np.sqrt(np.mean((y_true - y_pred) ** 2)))
+
+    # MAPE: y_true=0인 행 제외
+    mask = y_true != 0
+    mape = float(np.mean(np.abs((y_true[mask] - y_pred[mask]) / y_true[mask]))) if mask.any() else 0.0
+
+    ss_res = np.sum((y_true - y_pred) ** 2)
+    ss_tot = np.sum((y_true - np.mean(y_true)) ** 2)
+    r2 = float(1 - ss_res / ss_tot) if ss_tot != 0 else 0.0
+
+    return {"mae": round(mae, 4), "rmse": round(rmse, 4), "mape": round(mape, 4), "r2": round(r2, 4)}
+
+
+# ─── 예측 메인 함수 ─────────────────────────────��────────────
+def predict_with_timesfm(df: pd.DataFrame, params: dict) -> dict:
+    """
+    TimesFM 2.5로 시계열 예측 수행.
+
+    params:
+        horizon (int): 예측 스텝 수 (기본 12)
+        freq (str): pandas freq string (기본 "MS")
+        context_len (int): 사용할 최대 과거 포인트 수 (기본 512)
+        test_size (float): 백테스트 비율 (기본 0.2)
+        quantile_low (int): 하한 분위수 % (기본 10)
+        quantile_high (int): 상한 분위수 % (기본 90)
+    """
+    if _model_status != "loaded" or _model is None:
+        return {"success": False, "error": f"모델 미준비: {_model_status}"}
+
+    horizon = int(params.get("horizon", 12))
+    freq = str(params.get("freq", "MS"))
+    context_len = int(params.get("context_len", 512))
+    test_size = float(params.get("test_size", 0.2))
+    q_low_pct = int(params.get("quantile_low", 10))
+    q_high_pct = int(params.get("quantile_high", 90))
+
+    try:
+        # 1. 날짜/값 정규화
+        ds_col = "ds" if "ds" in df.columns else "date"
+        y_col = "y" if "y" in df.columns else "value"
+        df = df[[ds_col, y_col]].copy()
+        df.columns = ["ds", "y"]
+        df["ds"] = pd.to_datetime(df["ds"])
+        df = df.sort_values("ds").reset_index(drop=True)
+        df["y"] = pd.to_numeric(df["y"], errors="coerce")
+        df = df.dropna(subset=["y"])
+
+        # 2. context_len 슬라이싱
+        if len(df) > context_len:
+            df = df.iloc[-context_len:].reset_index(drop=True)
+
+        n = len(df)
+        test_n = max(1, int(n * test_size))
+        train_n = n - test_n
+
+        if train_n < 10:
+            return {"success": False, "error": f"학습 데이터 부족: {train_n}개 (최소 10개 필요)"}
+
+        train_values = df["y"].values[:train_n].tolist()
+        test_values = df["y"].values[train_n:].tolist()
+        freq_indicator = get_freq_indicator(freq)
+
+        # 3. test_n + horizon 스텝 예측 (test 구간 + 미래 포함)
+        predict_steps = test_n + horizon
+        point_forecast, quantile_forecast = _model.forecast(
+            horizon=predict_steps,
+            inputs=[train_values],
+            freq=[freq_indicator],
+        )
+        # point_forecast: (1, predict_steps)
+        # quantile_forecast: (1, predict_steps, 10)  → 0=10%, 4=50%, 8=90%
+        pf = point_forecast[0]         # (predict_steps,)
+        qf = quantile_forecast[0]      # (predict_steps, 10)
+
+        # 4. 분위수 인덱스 계산 (10개 분위: 10,20,...,90,100)
+        q_low_idx = max(0, min(9, (q_low_pct // 10) - 1))
+        q_high_idx = max(0, min(9, (q_high_pct // 10) - 1))
+
+        # 5. test 구간 metrics 계산
+        y_true = np.array(test_values)
+        y_pred = pf[:test_n]
+        metrics = _calc_metrics(y_true, y_pred)
+
+        # 6. 결과 데이터 조립
+        #    - 학습 구간: 실제값, yhat=None (차트에서 과거 실제값으로 표시)
+        #    - test 구간: 실제값 + 예측값
+        #    - 미래 구간: 실제값=None + 예측값
+        data = []
+
+        # 학습 구간
+        for i in range(train_n):
+            row = df.iloc[i]
+            ds_str = row["ds"].strftime("%Y-%m-%d") if hasattr(row["ds"], "strftime") else str(row["ds"])
+            data.append({
+                "ds": ds_str,
+                "y": float(row["y"]),
+                "yhat": None,
+                "yhat_lower": None,
+                "yhat_upper": None,
+                "is_future": False,
+            })
+
+        # test 구간
+        for i in range(test_n):
+            row = df.iloc[train_n + i]
+            ds_str = row["ds"].strftime("%Y-%m-%d") if hasattr(row["ds"], "strftime") else str(row["ds"])
+            data.append({
+                "ds": ds_str,
+                "y": float(row["y"]),
+                "yhat": round(float(pf[i]), 4),
+                "yhat_lower": round(float(qf[i][q_low_idx]), 4),
+                "yhat_upper": round(float(qf[i][q_high_idx]), 4),
+                "is_future": False,
+            })
+
+        # 미래 구간 — 마지막 날짜 기준으로 freq offset 생성
+        last_date = df["ds"].iloc[-1]
+        try:
+            future_dates = pd.date_range(start=last_date, periods=horizon + 1, freq=freq)[1:]
+        except Exception:
+            future_dates = pd.date_range(start=last_date, periods=horizon + 1, freq="MS")[1:]
+
+        for i in range(horizon):
+            ds_str = future_dates[i].strftime("%Y-%m-%d")
+            fi = test_n + i
+            data.append({
+                "ds": ds_str,
+                "y": None,
+                "yhat": round(float(pf[fi]), 4),
+                "yhat_lower": round(float(qf[fi][q_low_idx]), 4),
+                "yhat_upper": round(float(qf[fi][q_high_idx]), 4),
+                "is_future": True,
+            })
+
+        return {
+            "success": True,
+            "data": data,
+            "metrics": metrics,
+            "model_version": "timesfm-2.5-200m",
+            "test_size": test_n,
+        }
+
+    except Exception as e:
+        logger.exception("TimesFM 예측 오류")
+        return {"success": False, "error": str(e)}
+
+
+# ─── Claude 해석 ─────────────────────────────────────────────
+def interpret_forecast(forecast_summary: dict, domain_hint: str = "기타") -> dict:
+    """
+    Claude claude-sonnet-4-6 API로 예측 결과 한국어 해석 생성.
+    ANTHROPIC_API_KEY 환경변수 필요.
+    """
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return {"error": "ANTHROPIC_API_KEY 환경변수가 설정되지 않았습니다."}
+
+    try:
+        import anthropic
+        client = anthropic.Anthropic(api_key=api_key)
+        message = client.messages.create(
+            model="claude-sonnet-4-6",
+            max_tokens=512,
+            system=(
+                "당신은 공공데이터 시계열 분석 전문가입니다.\n"
+                "시계열 예측 결과를 받아 다음 내용을 한국어로 작성하세요.\n"
+                "1. 예측 신뢰도 평가 (MAPE 기준: <5% 매우 높음, 5-15% 높음, 15-30% 보통, >30% 낮음)\n"
+                "2. 핵심 트렌드 요약 (2-3문장)\n"
+                "3. 활용 제안 또는 주의사항 (1-2문장)\n\n"
+                'JSON만 반환하세요 (마크다운 없이):\n'
+                '{"reliability": "매우 높음", "reliability_reason": "...", "summary": "...", "notes": "..."}'
+            ),
+            messages=[
+                {
+                    "role": "user",
+                    "content": f"도메인: {domain_hint}\n예측 요약: {forecast_summary}",
+                }
+            ],
+        )
+        import json
+        text = message.content[0].text
+        return json.loads(text)
+    except Exception as e:
+        logger.error("Claude 해석 오류: %s", e)
+        return {"error": str(e)}
+```
+
+- [ ] **Step 2: 커밋**
+
+```bash
+git add src/domains/time_series_prediction/timesfm_service.py
+git commit -m "feat: add timesfm_service.py with singleton model loading"
+```
+
+---
+
+## Task 3: main.py — lifespan 및 라우트 추가
+
+**Files:**
+- Modify: `main.py` (line 29, 96-100, 끝부분)
+
+**세 곳을 수정한다:**
+
+### 3-A. import 추가 (line 29 수정)
+
+- [ ] **Step 1: fastapi import 라인에 Request 추가 (line 29)**
+
+기존:
+```python
+from fastapi import FastAPI, File, Form, HTTPException, Query, UploadFile
+```
+변경 후:
+```python
+from contextlib import asynccontextmanager
+import asyncio
+
+from fastapi import FastAPI, File, Form, HTTPException, Query, Request, UploadFile
+```
+
+### 3-B. app 선언 전에 lifespan 함수 추가, app 선언 수정
+
+- [ ] **Step 2: app = FastAPI(...) 블록 교체 (line 96-100)**
+
+기존:
+```python
+app = FastAPI(
+    title="시계열 예측 API",
+    description="N-BEATS, Prophet, ARIMA/SARIMA, XGBoost, ETS, LightGBM, Theta 기반 시계열 예측 서비스",
+    version="3.0.0",
+)
+```
+
+변경 후:
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """앱 시작 시 TimesFM 모델을 백그라운드 스레드에서 로드"""
+    from src.domains.time_series_prediction import timesfm_service
+    loop = asyncio.get_event_loop()
+    loop.run_in_executor(None, timesfm_service.load_model)
+    yield
+
+
+app = FastAPI(
+    title="시계열 예측 API",
+    description="N-BEATS, Prophet, ARIMA/SARIMA, XGBoost, ETS, LightGBM, Theta 기반 시계열 예측 서비스",
+    version="3.0.0",
+    lifespan=lifespan,
+)
+```
+
+### 3-C. 파일 끝에 TimesFM 라우트 추가
+
+- [ ] **Step 3: main.py 맨 끝(line 886~)에 아래 코드 추가**
+
+```python
+
+# ─── TimesFM 라우트 ──────────────────────────────────────────
+
+@app.get("/timesfm")
+async def timesfm_page():
+    """TimesFM 2.5 예측 페이지"""
+    return _serve_html("timesfm.html")
+
+
+@app.get("/api/timesfm/status")
+async def timesfm_status():
+    """TimesFM 모델 로딩 상태 확인"""
+    from src.domains.time_series_prediction import timesfm_service
+    return {"status": timesfm_service.get_status()}
+
+
+@app.post("/api/timesfm/predict")
+async def timesfm_predict(
+    file: UploadFile = File(...),
+    params: str = Form("{}"),
+):
+    """TimesFM 2.5로 시계열 예측"""
+    from src.domains.time_series_prediction import timesfm_service
+    try:
+        content = await file.read()
+        df, error = process_uploaded_file(content, file.filename or "data.csv")
+        if error:
+            raise HTTPException(status_code=400, detail=error)
+        is_valid, validation_error = validate_data(df)
+        if not is_valid:
+            raise HTTPException(status_code=400, detail=validation_error)
+        params_dict = json.loads(params) if params.strip() else {}
+        result = timesfm_service.predict_with_timesfm(df, params_dict)
+        if not result.get("success"):
+            raise HTTPException(status_code=422, detail=result.get("error", "예측 실패"))
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("TimesFM 예측 오류")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/timesfm/interpret")
+async def timesfm_interpret(request: Request):
+    """Claude API로 TimesFM 예측 결과 한국어 해석"""
+    from src.domains.time_series_prediction import timesfm_service
+    try:
+        body = await request.json()
+        result = timesfm_service.interpret_forecast(
+            body.get("forecast_summary"),
+            body.get("domain_hint", "기타"),
+        )
+        return result
+    except Exception as e:
+        logger.exception("TimesFM 해석 오류")
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+- [ ] **Step 4: 서버 기동 확인**
+
+```bash
+cd /Users/pjkk/Developer/Projects/nbeats
+uvicorn main:app --port 8000 --reload
+```
+
+예상 출력 (timesfm 패키지 미설치 환경에서는 load_model이 error 상태로 전환):
+```
+INFO:     Application startup complete.
+```
+`http://localhost:8000/api/timesfm/status` 응답: `{"status": "loading"}` 또는 `{"status": "error: ..."}`
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add main.py
+git commit -m "feat: add TimesFM lifespan loader and API routes to main.py"
+```
+
+---
+
+## Task 4: static/timesfm.html 신규 생성
+
+**Files:**
+- Create: `static/timesfm.html`
+
+- [ ] **Step 1: 파일 생성**
+
+아래 전체 내용을 `static/timesfm.html`로 저장한다. 기존 index.html의 CSS 변수·네비·카드 구조를 그대로 사용한다.
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>TimesFM 2.5 - 시계열 예측</title>
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🔮</text></svg>">
+  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/xlsx@0.18.5/dist/xlsx.full.min.js"></script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Outfit:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --bg: #0f0f12;
+      --surface: #1a1a1f;
+      --surface-hover: #222228;
+      --border: #2a2a32;
+      --text: #e8e8ed;
+      --text-muted: #8b8b96;
+      --accent: #6366f1;
+      --accent-hover: #818cf8;
+      --success: #22c55e;
+      --error: #ef4444;
+      --warning: #f59e0b;
+      --sky: #38bdf8;
+      --radius: 12px;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: 'Outfit', sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; line-height: 1.6; }
+
+    /* 네비게이션 */
+    .top-nav { background: var(--surface); border-bottom: 1px solid var(--border); position: sticky; top: 0; z-index: 100; }
+    .nav-inner { max-width: 1060px; margin: 0 auto; padding: 0 2rem; display: flex; align-items: center; gap: 2rem; height: 56px; overflow-x: auto; }
+    .nav-brand { font-weight: 700; font-size: 1rem; color: var(--text); text-decoration: none; letter-spacing: -0.01em; white-space: nowrap; }
+    .nav-links { display: flex; gap: 0.25rem; list-style: none; }
+    .nav-links a { display: flex; align-items: center; gap: 0.4rem; padding: 0.5rem 0.75rem; border-radius: 8px; text-decoration: none; font-size: 0.82rem; font-weight: 500; white-space: nowrap; color: var(--text-muted); transition: all 0.15s; }
+    .nav-links a:hover { color: var(--text); background: var(--surface-hover); }
+    .nav-links a.active { color: var(--sky); background: rgba(56, 189, 248, 0.1); }
+    .model-tag { font-size: 0.6rem; padding: 0.1rem 0.35rem; border-radius: 4px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.03em; }
+    .tag-dl { background: rgba(99,102,241,0.15); color: #a5b4fc; }
+    .tag-stat { background: rgba(34,197,94,0.15); color: #86efac; }
+    .tag-ml { background: rgba(245,158,11,0.15); color: #fcd34d; }
+    .tag-ets { background: rgba(16,185,129,0.15); color: #6ee7b7; }
+    .tag-theta { background: rgba(168,85,247,0.15); color: #c4b5fd; }
+    .tag-fm { background: rgba(56,189,248,0.15); color: #7dd3fc; }
+
+    /* 레이아웃 */
+    .container { max-width: 1060px; margin: 0 auto; padding: 2rem; }
+    header { margin-bottom: 2rem; padding-bottom: 1.25rem; border-bottom: 1px solid var(--border); display: flex; align-items: flex-start; justify-content: space-between; flex-wrap: wrap; gap: 0.75rem; }
+    h1 { font-size: 1.75rem; font-weight: 700; letter-spacing: -0.02em; background: linear-gradient(135deg, #fff 0%, #7dd3fc 100%); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; }
+    .subtitle { margin-top: 0.25rem; font-size: 0.875rem; color: var(--text-muted); }
+
+    /* 상태 뱃지 */
+    .status-badge { display: inline-flex; align-items: center; gap: 0.4rem; padding: 0.35rem 0.75rem; border-radius: 999px; font-size: 0.8rem; font-weight: 600; border: 1px solid; white-space: nowrap; }
+    .badge-loading { background: rgba(99,102,241,0.1); color: var(--accent); border-color: rgba(99,102,241,0.3); }
+    .badge-loaded  { background: rgba(34,197,94,0.1); color: var(--success); border-color: rgba(34,197,94,0.3); }
+    .badge-error   { background: rgba(239,68,68,0.1); color: var(--error); border-color: rgba(239,68,68,0.3); }
+    .badge-not_loaded { background: rgba(139,139,150,0.1); color: var(--text-muted); border-color: var(--border); }
+
+    /* 카드 */
+    .card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 1.5rem; margin-bottom: 1.25rem; }
+    .card-title { font-size: 0.8rem; font-weight: 600; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.04em; margin-bottom: 1rem; }
+
+    /* 업로드 */
+    .upload-zone { border: 2px dashed var(--border); border-radius: var(--radius); padding: 1.75rem; text-align: center; cursor: pointer; transition: all 0.2s; background: rgba(56,189,248,0.03); }
+    .upload-zone:hover, .upload-zone.dragover { border-color: var(--sky); background: rgba(56,189,248,0.08); }
+    .upload-zone input { display: none; }
+    .upload-zone .icon { font-size: 2.25rem; margin-bottom: 0.35rem; opacity: 0.7; }
+    .upload-zone p { color: var(--text-muted); font-size: 0.875rem; }
+    .upload-zone .file-name { margin-top: 0.4rem; font-family: 'JetBrains Mono', monospace; font-size: 0.85rem; color: var(--sky); }
+
+    /* 옵션 행 */
+    .options-row { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-top: 1rem; align-items: flex-end; }
+    .opt-group { display: flex; flex-direction: column; gap: 0.3rem; }
+    .opt-group label { font-size: 0.75rem; color: var(--text-muted); font-weight: 500; }
+    .opt-group input[type="number"],
+    .opt-group select { padding: 0.5rem 0.7rem; border: 1px solid var(--border); border-radius: 8px; background: var(--bg); color: var(--text); font-size: 0.9rem; font-family: inherit; min-width: 110px; }
+    .opt-group input[type="number"]:focus,
+    .opt-group select:focus { outline: none; border-color: var(--sky); }
+
+    /* 버튼 */
+    .actions { display: flex; gap: 0.75rem; margin-top: 1rem; flex-wrap: wrap; }
+    .btn { padding: 0.6rem 1.2rem; border: none; border-radius: 8px; font-size: 0.9rem; font-weight: 600; cursor: pointer; transition: all 0.2s; font-family: inherit; text-decoration: none; display: inline-flex; align-items: center; gap: 0.3rem; }
+    .btn-primary { background: var(--sky); color: #0f172a; }
+    .btn-primary:hover:not(:disabled) { background: #7dd3fc; transform: translateY(-1px); }
+    .btn-primary:disabled { opacity: 0.4; cursor: not-allowed; }
+    .btn-secondary { background: var(--surface-hover); color: var(--text); border: 1px solid var(--border); }
+    .btn-secondary:hover { background: var(--border); }
+    .btn-secondary:disabled { opacity: 0.4; cursor: not-allowed; }
+
+    /* 상태 메시지 */
+    .status-msg { margin-top: 1rem; padding: 0.7rem 1rem; border-radius: 8px; font-size: 0.875rem; display: none; }
+    .status-msg.error   { display: block; background: rgba(239,68,68,0.12); color: var(--error); border: 1px solid rgba(239,68,68,0.25); }
+    .status-msg.loading { display: block; background: rgba(56,189,248,0.08); color: var(--sky); border: 1px solid rgba(56,189,248,0.2); }
+    .status-msg.success { display: block; background: rgba(34,197,94,0.08); color: var(--success); border: 1px solid rgba(34,197,94,0.2); }
+
+    /* 결과 섹션 */
+    .results-section { margin-top: 1.5rem; display: none; }
+    .results-section.visible { display: block; }
+
+    /* 메트릭 */
+    .metrics-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 0.6rem; }
+    @media (max-width: 600px) { .metrics-grid { grid-template-columns: repeat(2, 1fr); } }
+    .metric-card { background: var(--bg); border: 1px solid var(--border); border-radius: 10px; padding: 0.9rem 1rem; }
+    .metric-label { font-size: 0.7rem; color: var(--text-muted); font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; }
+    .metric-value { font-family: 'JetBrains Mono', monospace; font-size: 1.3rem; font-weight: 700; margin-top: 0.2rem; color: var(--sky); }
+
+    /* 차트 */
+    .chart-container { height: 340px; }
+
+    /* AI 해석 */
+    .ai-section { margin-top: 1.25rem; }
+    .ai-header { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 0.75rem; }
+    .reliability-badge { padding: 0.25rem 0.7rem; border-radius: 999px; font-size: 0.78rem; font-weight: 700; }
+    .rel-very-high { background: rgba(34,197,94,0.15); color: #4ade80; }
+    .rel-high      { background: rgba(56,189,248,0.15); color: #7dd3fc; }
+    .rel-medium    { background: rgba(245,158,11,0.15); color: #fcd34d; }
+    .rel-low       { background: rgba(239,68,68,0.15); color: #f87171; }
+    .ai-text { font-size: 0.9rem; color: var(--text); line-height: 1.7; margin-bottom: 0.5rem; }
+    .ai-notes { font-size: 0.85rem; color: var(--text-muted); font-style: italic; }
+    .ai-loading { color: var(--text-muted); font-size: 0.875rem; display: flex; align-items: center; gap: 0.5rem; }
+
+    /* 스피너 */
+    .spinner { display: inline-block; width: 1em; height: 1em; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: spin 0.6s linear infinite; vertical-align: -0.15em; margin-right: 0.4em; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+  </style>
+</head>
+<body>
+  <nav class="top-nav">
+    <div class="nav-inner">
+      <a href="/" class="nav-brand">시계열 예측</a>
+      <ul class="nav-links">
+        <li><a href="/">N-BEATS <span class="model-tag tag-dl">DL</span></a></li>
+        <li><a href="/prophet">Prophet <span class="model-tag tag-stat">Stat</span></a></li>
+        <li><a href="/xgboost">XGBoost <span class="model-tag tag-ml">ML</span></a></li>
+        <li><a href="/lightgbm">LightGBM <span class="model-tag tag-ml">ML</span></a></li>
+        <li><a href="/arima">ARIMA <span class="model-tag tag-stat">Classical</span></a></li>
+        <li><a href="/theta">Theta <span class="model-tag tag-theta">Classical</span></a></li>
+        <li><a href="/ets">ETS <span class="model-tag tag-ets">Smoothing</span></a></li>
+        <li><a href="/hybrid">Hybrid <span class="model-tag" style="background:rgba(236,72,153,0.15);color:#f472b6;">LLM</span></a></li>
+        <li><a href="/timesfm" class="active">TimesFM <span class="model-tag tag-fm">FM</span></a></li>
+      </ul>
+    </div>
+  </nav>
+
+  <div class="container">
+    <header>
+      <div>
+        <h1>TimesFM 2.5 시계열 예측</h1>
+        <p class="subtitle">Google Research Foundation Model · Zero-Shot · 200M params · 신뢰구간 지원</p>
+      </div>
+      <div id="modelStatusBadge" class="status-badge badge-not_loaded">● 모델 미로딩</div>
+    </header>
+
+    <!-- 업로드 + 옵션 -->
+    <section class="card">
+      <div class="card-title">데이터 업로드 및 옵션</div>
+      <div class="upload-zone" id="uploadZone">
+        <input type="file" id="fileInput" accept=".csv,.xlsx,.xls,.json">
+        <div class="icon">📁</div>
+        <p>CSV, Excel, JSON 파일을 드래그하거나 클릭하여 선택</p>
+        <p class="file-name" id="fileName"></p>
+      </div>
+
+      <div class="options-row">
+        <div class="opt-group">
+          <label for="domainSelect">도메인</label>
+          <select id="domainSelect">
+            <option value="교통">교통</option>
+            <option value="재정">재정</option>
+            <option value="인구">인구</option>
+            <option value="기타" selected>기타</option>
+          </select>
+        </div>
+        <div class="opt-group">
+          <label for="horizonInput">예측 기간 (스텝)</label>
+          <input type="number" id="horizonInput" value="12" min="1" max="256">
+        </div>
+        <div class="opt-group">
+          <label for="freqSelect">데이터 주기</label>
+          <select id="freqSelect">
+            <option value="D">일별 (D)</option>
+            <option value="W">주별 (W)</option>
+            <option value="MS" selected>월별 (MS)</option>
+            <option value="QS">분기별 (QS)</option>
+            <option value="YS">연별 (YS)</option>
+          </select>
+        </div>
+        <div class="opt-group">
+          <label for="ciSelect">신뢰구간</label>
+          <select id="ciSelect">
+            <option value="80">80%</option>
+            <option value="90" selected>90%</option>
+            <option value="95">95%</option>
+          </select>
+        </div>
+      </div>
+
+      <div class="actions">
+        <button class="btn btn-primary" id="predictBtn" disabled>🔮 예측 실행</button>
+        <button class="btn btn-secondary" id="resetBtn">초기화</button>
+        <button class="btn btn-secondary" id="exportCsvBtn" disabled>CSV 다운로드</button>
+        <button class="btn btn-secondary" id="exportXlsxBtn" disabled>Excel 다운로드</button>
+      </div>
+
+      <div class="status-msg" id="statusMsg"></div>
+    </section>
+
+    <!-- 결과 -->
+    <section class="results-section" id="resultsSection">
+      <!-- 메트릭 -->
+      <div class="card">
+        <div class="card-title">예측 성능 지표 (백테스트)</div>
+        <div class="metrics-grid">
+          <div class="metric-card"><div class="metric-label">MAE</div><div class="metric-value" id="metMAE">—</div></div>
+          <div class="metric-card"><div class="metric-label">RMSE</div><div class="metric-value" id="metRMSE">—</div></div>
+          <div class="metric-card"><div class="metric-label">MAPE</div><div class="metric-value" id="metMAPE">—</div></div>
+          <div class="metric-card"><div class="metric-label">R²</div><div class="metric-value" id="metR2">—</div></div>
+        </div>
+      </div>
+
+      <!-- 차트 -->
+      <div class="card">
+        <div class="card-title">예측 결과 차트</div>
+        <div class="chart-container">
+          <canvas id="forecastChart"></canvas>
+        </div>
+      </div>
+
+      <!-- AI 해석 -->
+      <div class="card ai-section">
+        <div class="card-title">AI 해석 (Claude claude-sonnet-4-6)</div>
+        <div id="aiContent">
+          <div class="ai-loading"><span class="spinner"></span> 해석 생성 중...</div>
+        </div>
+      </div>
+    </section>
+  </div>
+
+  <script>
+  (() => {
+    // ── 상태 폴링 ─────────────────────────────────────────
+    let modelReady = false;
+    let forecastData = null;
+    let chartInstance = null;
+
+    function updateStatusBadge(status) {
+      const badge = document.getElementById('modelStatusBadge');
+      badge.className = 'status-badge';
+      if (status === 'loaded') {
+        badge.classList.add('badge-loaded');
+        badge.textContent = '● 모델 준비됨';
+        modelReady = true;
+        const f = document.getElementById('fileInput').files[0];
+        document.getElementById('predictBtn').disabled = !f;
+      } else if (status === 'loading') {
+        badge.classList.add('badge-loading');
+        badge.innerHTML = '<span class="spinner"></span> 모델 로딩 중...';
+        modelReady = false;
+        document.getElementById('predictBtn').disabled = true;
+      } else if (status && status.startsWith('error')) {
+        badge.classList.add('badge-error');
+        badge.textContent = '● 로딩 오류';
+        modelReady = false;
+      } else {
+        badge.classList.add('badge-not_loaded');
+        badge.textContent = '● 모델 미로딩';
+      }
+    }
+
+    async function pollStatus() {
+      try {
+        const res = await fetch('/api/timesfm/status');
+        const { status } = await res.json();
+        updateStatusBadge(status);
+        if (status !== 'loaded') setTimeout(pollStatus, 2000);
+      } catch { setTimeout(pollStatus, 3000); }
+    }
+    pollStatus();
+
+    // ── 파일 업로드 ───────────────────────────────────────
+    const uploadZone = document.getElementById('uploadZone');
+    const fileInput  = document.getElementById('fileInput');
+    const fileName   = document.getElementById('fileName');
+
+    uploadZone.addEventListener('click', () => fileInput.click());
+    uploadZone.addEventListener('dragover', e => { e.preventDefault(); uploadZone.classList.add('dragover'); });
+    uploadZone.addEventListener('dragleave', () => uploadZone.classList.remove('dragover'));
+    uploadZone.addEventListener('drop', e => {
+      e.preventDefault(); uploadZone.classList.remove('dragover');
+      if (e.dataTransfer.files[0]) { fileInput.files = e.dataTransfer.files; onFileChange(); }
+    });
+    fileInput.addEventListener('change', onFileChange);
+
+    function onFileChange() {
+      const f = fileInput.files[0];
+      if (f) {
+        fileName.textContent = f.name;
+        document.getElementById('predictBtn').disabled = !modelReady;
+      }
+    }
+
+    // ── 예측 실행 ─────────────────────────────────────────
+    document.getElementById('predictBtn').addEventListener('click', async () => {
+      const f = fileInput.files[0];
+      if (!f) return;
+
+      const horizon = parseInt(document.getElementById('horizonInput').value) || 12;
+      const freq    = document.getElementById('freqSelect').value;
+      const ci      = parseInt(document.getElementById('ciSelect').value);
+      const domain  = document.getElementById('domainSelect').value;
+
+      const ciLow  = 100 - ci;
+      const ciHigh = ci;
+
+      setStatus('loading', '예측 중...');
+      document.getElementById('predictBtn').disabled = true;
+
+      const fd = new FormData();
+      fd.append('file', f);
+      fd.append('params', JSON.stringify({ horizon, freq, quantile_low: ciLow, quantile_high: ciHigh }));
+
+      try {
+        const res = await fetch('/api/timesfm/predict', { method: 'POST', body: fd });
+        const result = await res.json();
+        if (!res.ok || !result.success) {
+          setStatus('error', result.detail || result.error || '예측 실패');
+          return;
+        }
+        forecastData = result;
+        renderResults(result, domain);
+        setStatus('success', `예측 완료 · 모델: ${result.model_version} · 백테스트: ${result.test_size}개`);
+      } catch (e) {
+        setStatus('error', `네트워크 오류: ${e.message}`);
+      } finally {
+        document.getElementById('predictBtn').disabled = false;
+      }
+    });
+
+    // ── 결과 렌더링 ───────────────────────────────────────
+    function renderResults(result, domain) {
+      // 메트릭
+      const m = result.metrics;
+      document.getElementById('metMAE').textContent  = m.mae  != null ? m.mae.toFixed(3)  : '—';
+      document.getElementById('metRMSE').textContent = m.rmse != null ? m.rmse.toFixed(3) : '—';
+      document.getElementById('metMAPE').textContent = m.mape != null ? (m.mape * 100).toFixed(1) + '%' : '—';
+      document.getElementById('metR2').textContent   = m.r2   != null ? m.r2.toFixed(3)   : '—';
+
+      // 차트
+      renderChart(result.data);
+
+      // 결과 섹션 표시
+      const sec = document.getElementById('resultsSection');
+      sec.classList.add('visible');
+
+      // 다운로드 버튼 활성화
+      document.getElementById('exportCsvBtn').disabled = false;
+      document.getElementById('exportXlsxBtn').disabled = false;
+
+      // AI 해석
+      document.getElementById('aiContent').innerHTML =
+        '<div class="ai-loading"><span class="spinner"></span> 해석 생성 중...</div>';
+      fetchInterpretation(m, domain);
+    }
+
+    function renderChart(data) {
+      const labels     = data.map(d => d.ds);
+      const actuals    = data.map(d => d.y);
+      const predicted  = data.map(d => d.yhat);
+      const lowers     = data.map(d => d.yhat_lower);
+      const uppers     = data.map(d => d.yhat_upper);
+
+      // 신뢰구간 fill: lower → upper
+      const ciUpper = data.map((d, i) => d.yhat_upper);
+      const ciLower = data.map((d, i) => d.yhat_lower);
+
+      if (chartInstance) chartInstance.destroy();
+      const ctx = document.getElementById('forecastChart').getContext('2d');
+      chartInstance = new Chart(ctx, {
+        type: 'line',
+        data: {
+          labels,
+          datasets: [
+            {
+              label: '신뢰구간 상한',
+              data: ciUpper,
+              borderColor: 'transparent',
+              backgroundColor: 'rgba(56,189,248,0.12)',
+              pointRadius: 0,
+              fill: '+1',
+              tension: 0.3,
+            },
+            {
+              label: '신뢰구간 하한',
+              data: ciLower,
+              borderColor: 'transparent',
+              backgroundColor: 'rgba(56,189,248,0.12)',
+              pointRadius: 0,
+              fill: false,
+              tension: 0.3,
+            },
+            {
+              label: '실제값',
+              data: actuals,
+              borderColor: '#e8e8ed',
+              backgroundColor: 'transparent',
+              pointRadius: 2,
+              borderWidth: 2,
+              tension: 0.3,
+              spanGaps: false,
+            },
+            {
+              label: '예측값',
+              data: predicted,
+              borderColor: '#38bdf8',
+              backgroundColor: 'transparent',
+              pointRadius: 2,
+              borderWidth: 2,
+              borderDash: [],
+              tension: 0.3,
+              spanGaps: false,
+            },
+          ],
+        },
+        options: {
+          responsive: true,
+          maintainAspectRatio: false,
+          interaction: { mode: 'index', intersect: false },
+          plugins: {
+            legend: { labels: { color: '#8b8b96', font: { size: 12 } } },
+            tooltip: { backgroundColor: '#1a1a1f', borderColor: '#2a2a32', borderWidth: 1, titleColor: '#e8e8ed', bodyColor: '#e8e8ed' },
+          },
+          scales: {
+            x: { ticks: { color: '#8b8b96', maxTicksLimit: 12 }, grid: { color: 'rgba(255,255,255,0.04)' } },
+            y: { ticks: { color: '#8b8b96' }, grid: { color: 'rgba(255,255,255,0.04)' } },
+          },
+        },
+      });
+    }
+
+    // ── Claude 해석 ───────────────────────────────────────
+    async function fetchInterpretation(metrics, domain) {
+      try {
+        const res = await fetch('/api/timesfm/interpret', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ forecast_summary: metrics, domain_hint: domain }),
+        });
+        const data = await res.json();
+        if (data.error) { renderAiError(data.error); return; }
+        renderAiResult(data);
+      } catch (e) { renderAiError(e.message); }
+    }
+
+    function reliabilityClass(r) {
+      if (r === '매우 높음') return 'rel-very-high';
+      if (r === '높음')     return 'rel-high';
+      if (r === '보통')     return 'rel-medium';
+      return 'rel-low';
+    }
+
+    function renderAiResult(d) {
+      document.getElementById('aiContent').innerHTML = `
+        <div class="ai-header">
+          <span class="reliability-badge ${reliabilityClass(d.reliability)}">${d.reliability}</span>
+          <span style="color:var(--text-muted);font-size:0.85rem;">${d.reliability_reason || ''}</span>
+        </div>
+        <p class="ai-text">${d.summary || ''}</p>
+        <p class="ai-notes">${d.notes || ''}</p>
+      `;
+    }
+
+    function renderAiError(msg) {
+      document.getElementById('aiContent').innerHTML =
+        `<p style="color:var(--text-muted);font-size:0.875rem;">해석 불가: ${msg}</p>`;
+    }
+
+    // ── 초기화 ────────────────────────────────────────────
+    document.getElementById('resetBtn').addEventListener('click', () => {
+      fileInput.value = '';
+      fileName.textContent = '';
+      forecastData = null;
+      document.getElementById('predictBtn').disabled = true;
+      document.getElementById('exportCsvBtn').disabled = true;
+      document.getElementById('exportXlsxBtn').disabled = true;
+      document.getElementById('resultsSection').classList.remove('visible');
+      setStatus('', '');
+      if (chartInstance) { chartInstance.destroy(); chartInstance = null; }
+    });
+
+    // ── 다운로드 ─────────────────────────────────────────
+    document.getElementById('exportCsvBtn').addEventListener('click', () => {
+      if (!forecastData) return;
+      const rows = ['ds,y,yhat,yhat_lower,yhat_upper,is_future'];
+      forecastData.data.forEach(d => {
+        rows.push([d.ds, d.y ?? '', d.yhat ?? '', d.yhat_lower ?? '', d.yhat_upper ?? '', d.is_future].join(','));
+      });
+      download('timesfm_forecast.csv', rows.join('\n'), 'text/csv');
+    });
+
+    document.getElementById('exportXlsxBtn').addEventListener('click', () => {
+      if (!forecastData) return;
+      const ws_data = [['날짜', '실제값', '예측값', '신뢰구간 하한', '신뢰구간 상한', '미래여부']];
+      forecastData.data.forEach(d => ws_data.push([d.ds, d.y, d.yhat, d.yhat_lower, d.yhat_upper, d.is_future]));
+      const ws = XLSX.utils.aoa_to_sheet(ws_data);
+      const wb = XLSX.utils.book_new();
+      XLSX.utils.book_append_sheet(wb, ws, 'TimesFM');
+      XLSX.writeFile(wb, 'timesfm_forecast.xlsx');
+    });
+
+    function download(name, content, type) {
+      const a = Object.assign(document.createElement('a'), {
+        href: URL.createObjectURL(new Blob([content], { type })),
+        download: name,
+      });
+      a.click();
+    }
+
+    // ── 유틸 ─────────────────────────────────────────────
+    function setStatus(type, msg) {
+      const el = document.getElementById('statusMsg');
+      el.className = 'status-msg';
+      if (type) { el.classList.add(type); el.innerHTML = type === 'loading' ? `<span class="spinner"></span>${msg}` : msg; }
+    }
+  })();
+  </script>
+</body>
+</html>
+```
+
+- [ ] **Step 2: 브라우저 확인**
+
+`http://localhost:8000/timesfm` 접속 → 헤더, 네비, 업로드 영역, 상태 뱃지 표시 확인.
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add static/timesfm.html
+git commit -m "feat: add timesfm.html UI with confidence intervals and AI interpretation"
+```
+
+---
+
+## Task 5: Dockerfile 수정
+
+**Files:**
+- Modify: `Dockerfile`
+
+- [ ] **Step 1: `useradd` 라인 전에 ENV + mkdir 삽입**
+
+기존 (line 33-35):
+```dockerfile
+# 비루트 사용자 (Hugging Face 보안 정책)
+RUN useradd -m -u 1000 appuser && chown -R appuser /app
+USER appuser
+```
+
+변경 후:
+```dockerfile
+# HuggingFace 모델 캐시 디렉터리 (appuser 접근 가능)
+ENV HF_HOME=/app/.cache/huggingface
+ENV TRANSFORMERS_CACHE=/app/.cache/huggingface
+RUN mkdir -p /app/.cache/huggingface
+
+# 비루트 사용자 (Hugging Face 보안 정책)
+RUN useradd -m -u 1000 appuser && chown -R appuser /app
+USER appuser
+```
+
+- [ ] **Step 2: 커밋**
+
+```bash
+git add Dockerfile
+git commit -m "chore: add HF cache dir env vars to Dockerfile"
+```
+
+---
+
+## Task 6: 기존 HTML 파일 nav에 TimesFM 링크 추가
+
+> **주의:** 스펙에서 "기존 `static/*.html` 파일 수정 금지"라고 명시되어 있으므로, 이 Task는 **건너뛴다**.  
+> 기존 파일들은 수정하지 않는다. `/timesfm` 경로는 네비바에 새로 추가한 `timesfm.html`에서만 표시된다.
+
+---
+
+## Self-Review 체크리스트
+
+- [x] **1-1** requirements.txt: timesfm[torch], huggingface_hub 추가 ✓
+- [x] **1-2** timesfm_service.py: load_model, get_status, predict_with_timesfm, get_freq_indicator, interpret_forecast ✓
+- [x] **1-3** main.py: lifespan 추가 + 4개 라우트 (/timesfm, /api/timesfm/status, /api/timesfm/predict, /api/timesfm/interpret) ✓
+- [x] **1-4** static/timesfm.html: 상태 뱃지, 파일 업로드, 옵션 패널, 차트(신뢰구간), 메트릭, AI 해석, 다운로드 ✓
+- [x] **1-5** Dockerfile: HF_HOME, TRANSFORMERS_CACHE, mkdir ✓
+- [x] **금지 사항**: 기존 *_service.py 미수정, 기존 static/*.html 미수정 ✓

timesfm-frontend/.env.example

@@ -1,3 +0,0 @@
-# HF Space URL — 서버사이드 프록시 라우트(/api/hf/*)에서 사용 (CORS 회피)
-HF_API_BASE=https://jkpaul-time-series-prediction.hf.space
-ANTHROPIC_API_KEY=

timesfm-frontend/.gitignore

@@ -32,7 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
-!.env.example
+.env.example
 
 # vercel
 .vercel