docs/drift_detection.md

Drift Detection — 사용자 분류 패턴 변화 감지

SPEC §2.4 (4) 구현. 모듈 drift_detection.py · 라우트 /api/drift/* · 탭 "Drift 탐지".

---

1. 문제 — 분류 패턴은 시간이 지나면 변한다

실제 시나리오

시점	상황	결과
1개월차	AI: "이메일=S 민감" → 사용자 동의	정확도 90%
3개월차	회사 정책 변경: "이메일=O 일반"	사용자 매번 정정, 갭 누적
그 동안	AI 는 변화 모름	학습 자동 적용 전까지 정확도 ↓
더 심각	사람이 정확도 표를 매일 봐야 알아챔 — 안 봄	품질이 조용히 무너짐

핵심 통찰: 변화를 자동 감지·알림하지 않으면 분류기 품질이 조용히 무너진다.

ML 용어 — drift 의 3 종류

• Concept drift — "정답의 의미" 가 변함. (위 시나리오: 이메일 등급 기준 변경)
• Data drift — 입력 데이터 분포가 변함. (예: 새로운 문서 유형 등장)
• User drift — 사용자 판단 기준이 변함. (조직 정책 / 새 담당자 / 학습 등)

본 모듈은 결정 이력에서 위 세 가지를 통합적으로 감지합니다 (정확도·갭·entity 분포).

---

2. 알고리즘 — 3 지표로 drift 측정

윈도우 분할

결정 이력을 시간순 정렬 → 최근 N건 (window A) vs 이전 N건 (window B) 으로 분할.

시간 ←──────────────────────────────────→
   ┌──── window B ────┐┌──── window A ────┐
   [b1, b2, ..., bN]    [a1, a2, ..., aN]
       (이전)                 (최근)

지표 1 — 정확도 drift

acc_A = (AI = User in A) / |A|
acc_B = (AI = User in B) / |B|

drift = acc_A − acc_B

의미	AI 가 사용자와 얼마나 맞고 있나의 변화
임계값	acc_drift ≤ −0.15 → alert (빠른 하락)
	acc_drift ≥ +0.15 → info (학습 효과 / 패턴 안정화)

지표 2 — 평균 갭 drift

gap_A = mean(|AI − User|) in A          # O=0, S=1, C=2 절대 차이
gap_B = mean(|AI − User|) in B

drift = gap_A − gap_B

의미	사용자가 더 큰 폭으로 정정하는가
임계값	gap_drift ≥ +0.3 → warn (O→C 같은 두 단계 정정 증가)

지표 3 — Entity 분포 drift (PSI)

ratio_A = count_A(ent) / total_A
ratio_B = count_B(ent) / total_B

psi = (ratio_A − ratio_B) · log( (ratio_A + ε) / (ratio_B + ε) )

의미	어떤 PII 가 자주 나오는지의 변화
임계값	`
특수	appeared: 이전에 없던 entity 가 ≥3건 등장 → info
	disappeared: 이전 ≥5건 → 최근 0건 → info

PSI = Population Stability Index — 두 분포의 안정성 측정 (production ML 표준 지표).

시계열

sliding window (기본 10건씩, 5건 단위로 이동) 로 accuracy · mean_gap 의 시간 추이를 계산. SVG 차트로 시각화 (파란선=정확도, 주황선=평균 갭).

---

3. 데이터 흐름

[결정 이력]    [윈도우 분할]    [3 지표 계산]    [시계열]      [알림 생성]
decisions.db → 최근 N (A)    → acc / gap / PSI → sliding bin → alert/warn/info
시간순 정렬   이전 N (B)                          (기본 10건)   임계값 기반

API 라우트

GET /api/drift/snapshot?window=30
   &accuracy_drop=0.15
   &gap_rise=0.3
   &entity_psi=0.1

→ 응답: recent, previous, drift, entities[], alerts[]

GET /api/drift/timeline?bin=10

→ 응답: bins[] (각 bin 의 idx, n, accuracy, mean_gap, start_at, end_at)

---

4. 알림 예시 — 실제 응답

검증 시 받은 실제 데이터 (window=8):

{
  "ok": true,
  "window_size": 8,
  "recent":   { "n": 8, "accuracy": 0.375, "mean_gap": 1.00 },
  "previous": { "n": 8, "accuracy": 0.750, "mean_gap": 0.25 },
  "drift": {
    "accuracy_drift": -0.375,   //  ← 37.5%p 하락
    "gap_drift":      +0.75     //  ← 갭이 0.75 증가
  },
  "alerts": [
    {
      "severity": "alert",
      "type": "accuracy_drop",
      "message": "정확도 37.5%p 하락 — 분류기가 사용자 의도와 점점 어긋남."
    },
    {
      "severity": "warn",
      "type": "gap_rise",
      "message": "평균 갭이 0.75 증가 — 사용자가 더 큰 폭으로 정정 중."
    }
  ]
}

이 응답이 의미하는 것

• 최근 8건의 정확도가 37.5% 로, 이전 8건의 75% 보다 절반.
• 평균 갭도 0.25 → 1.00 으로 4배.
• → 사용자가 AI 와 점점 다른 방향으로 매기는 패턴. 학습 또는 룰 검토 필요 신호.

---

5. UI 구조 — "Drift 탐지" 탭

영역	내용
1. 초보 가이드	details/open — drift 란? + 3 종류 + 3 지표 + 임계값
2. 윈도우/임계값 설정	window 크기 + acc/gap/PSI 임계값 input + "Drift 분석 실행" 버튼
3. 알림 영역	🚨 alert (빨강) · ⚠️ warn (주황) · ℹ️ info (회색) 카드 list. 좌측 4px 보더
4. 윈도우 비교 카드 (3 컬럼)	📊 최근 · 📊 이전 · ↕ Drift (A−B). 각 카드: n / 정확도 / 평균갭 / entity 합계
5. 시계열 SVG	파란선=정확도 (좌축 01) · 주황선=평균갭 (우축 0maxGap) · 점 표시 + bin size 조정
6. Entity 분포 변화 표	Entity Type · 최근 · 이전 · 비율 변화 · PSI · 상태 (신규/소멸/변화 큼)

---

6. 파일 변경 요약

파일	유형	분량	내용
drift_detection.py	신규	~180줄	snapshot() / timeline() / _window_stats / _entity_drift / _build_alerts
app.py / app_lite.py	수정	+30줄 × 2	import + 2 라우트
templates/index.html	수정	+280줄	사이드바 nav 1 + 새 탭 panel + JS (SVG 시계열)
templates/index.html	수정	+30줄	전체 구성도 9번째 파이프라인 + 가이드 갱신
docs/drift_detection.pptx	신규	8 슬라이드	이론 + 구현 + 검증 PPT
docs/drift_detection_theory_and_impl.py	신규	~350줄	PPT 생성 스크립트
docs/drift_detection.md	신규	이 문서	마크다운 정리본

---

7. 검증 절차

# 1) 결정 이력 누적 — 파일 분석 탭에서 [C][S][O] 클릭으로 최소 20+ 건
#    (window=10 기준)

# 2) 사이드바 → 운영 → "Drift 탐지" 클릭

# 3) window 크기 + 임계값 설정 후 "Drift 분석 실행"
#    → 알림 카드, 윈도우 비교 3컬럼, Entity 표, 시계열 SVG 모두 표시

# 4) bin size 변경 후 "시계열 새로고침" — 정확도·갭 추이 확인

# 5) curl 직접 검증
curl "http://127.0.0.1:5050/api/drift/snapshot?window=8"
curl "http://127.0.0.1:5050/api/drift/timeline?bin=5"

검증 결과 (현재 노트북)

• accuracy_drift = −37.5%p → alert
• gap_drift = +0.75 → warn
• 총 알림 2건 (실제 결정 이력 기반)

---

8. 향후 보완 (선택)

항목	분량	효과
주기적 자동 실행 (cron + Slack/email 알림)	1일	사람이 탭을 안 봐도 알람
KS 검정 / CUSUM	2일	통계적으로 더 엄밀한 변화점 탐지
사용자별 분리 (user_id 별 drift)	1일	다중 사용자 환경
Drift 원인 자동 분류 (concept vs data vs user)	2~3일	진단 자동화
알림 영속 (alerts.db + 대시보드)	1일	이력 추적

---

9. SPEC §2.4 완료 상태

항목	모듈	상태
(1) sample weight (학습 시 가중치)	train.py	✅
(2) Platt calibration (신뢰도 보정)	platt_calibration.py	✅
(3) Rule mining (자동 룰 후보)	rule_mining.py	✅
(4) Drift detection (패턴 변화 감지)	drift_detection.py	✅ 이번 구현

SPEC §2.4 갭 활용 4가지 전부 구현 완료.

---

참고

• SPEC: SPEC_파일분류_PoC.md §2.4 (4) — "User profile drift detection: 특정 사용자의 갭이 커지면 → 정책 변경/조직 변경 신호로 알림"
• PSI 이론: Karakoulas (2004) "Empirical Validation of Retail Credit-Scoring Models"
• 보조 자료: docs/drift_detection.pptx — 슬라이드로 같은 내용