# SHAP Analysis Plugin

SHAP(SHapley Additive exPlanations)를 사용하여 모델 예측을 설명하고 해석하는 플러그인입니다.

## 📋 개요

이 플러그인은 설명 가능한 AI(XAI)를 위한 도구로, 다음을 제공합니다:

### 주요 기능
- ✅ **전역 설명**: Summary Plot, Bar Plot
- ✅ **지역 설명**: Waterfall Plot, Force Plot
- ✅ **특성 의존성**: Dependence Plot
- ✅ **개별 예측 설명**: 텍스트 + 시각화
- ✅ **다양한 Explainer**: Tree, Linear, Kernel
- ✅ **Markdown 리포트 자동 생성**

### SHAP이란?
SHAP(SHapley Additive exPlanations)는 게임 이론의 Shapley 값을 기반으로 한 모델 해석 방법입니다.
- 각 특성이 예측에 얼마나 기여했는지 정량화
- 모델 유형에 관계없이 일관된 설명 제공
- 이론적으로 검증된 유일한 공정한 기여도 분배 방법

## 🚀 빠른 시작

### 1. 의존성 설치

**uv 사용 (권장 - 10-100배 빠름)**:
```bash
# uv 설치 (한 번만)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 패키지 설치
cd plugins/shap-analysis/skills/shap-analysis
uv pip install -r requirements.txt
```

**pip 사용 (기존 방식)**:
```bash
cd plugins/shap-analysis/skills/shap-analysis
pip install -r requirements.txt
```

### 2. SHAP 분석 실행

```bash
# Claude Code에서 실행
/analyze-shap \
  --model-path "projects/creditcard-fraud-detection/models/xgboost_model.pkl" \
  --test-data "projects/creditcard-fraud-detection/data/processed/test.csv" \
  --target-column "Class"

# 또는 Python 스크립트 직접 실행
cd plugins/shap-analysis/skills/shap-analysis/scripts
python analyze_shap.py \
  --model-path "../../../../../projects/creditcard-fraud-detection/models/xgboost_model.pkl" \
  --test-data "../../../../../projects/creditcard-fraud-detection/data/processed/test.csv" \
  --target-column "Class" \
  --sample-size 1000
```

**출력**: `projects/creditcard-fraud-detection/outputs/shap/` 폴더에 모든 시각화 및 리포트 저장

## 📁 플러그인 구조

```
plugins/shap-analysis/
├── plugin.json                      # 플러그인 메타데이터
├── README.md                        # 플러그인 문서
├── agents/
│   └── shap-analyst.md             # SHAP 분석 에이전트
├── commands/
│   └── analyze-shap.md             # SHAP 분석 커맨드
└── skills/
    └── shap-analysis/
        ├── requirements.txt         # Python 패키지 의존성
        └── scripts/
            └── analyze_shap.py     # SHAP 분석 스크립트
```

## 🎯 주요 기능

### 1. SHAP Explainer 자동 선택
- **TreeExplainer**: XGBoost, LightGBM, RandomForest 등
- **LinearExplainer**: LogisticRegression, LinearRegression 등
- **KernelExplainer**: 범용 (모든 모델 지원, 느림)

### 2. 전역 설명 (Global Explanation)

#### Summary Plot
- 모든 샘플의 SHAP 값 분포
- 특성 중요도 + 특성 값의 영향
- 색상으로 특성 값 표현 (빨강=높음, 파랑=낮음)

#### Bar Plot
- 평균 절댓값 SHAP 값
- 특성 중요도 순위
- 단순하고 직관적

### 3. 지역 설명 (Local Explanation)

#### Waterfall Plot
- 개별 예측의 단계별 설명
- Base value → Final prediction
- 양수/음수 기여 시각화

#### Force Plot
- 개별 예측의 시각적 설명
- 양성/음성 기여 색상 구분

#### Dependence Plot
- 특성 값과 SHAP 값의 관계
- 비선형 관계 탐지
- 상호작용 효과

### 4. 개별 인스턴스 설명
- 실제 vs 예측 레이블
- 상위 5개 영향 특성
- 텍스트 설명 파일

### 5. SHAP 리포트
- Markdown 형식
- 전역 특성 중요도 테이블
- 시각화 파일 목록

## 📊 사용 예시

### Example 1: 기본 SHAP 분석
```bash
/analyze-shap \
  --model-path "projects/my-project/models/model.pkl" \
  --test-data "projects/my-project/data/test.csv" \
  --target-column "target"
```

### Example 2: 특정 인스턴스 분석
```bash
/analyze-shap \
  --model-path "projects/my-project/models/model.pkl" \
  --test-data "projects/my-project/data/test.csv" \
  --target-column "target" \
  --instance-idx 42
```

### Example 3: 대용량 데이터 (샘플링)
```bash
/analyze-shap \
  --model-path "projects/large-project/models/model.pkl" \
  --test-data "projects/large-project/data/test.csv" \
  --target-column "target" \
  --sample-size 500
```

## 🔧 파라미터

### 필수 파라미터
- `--model-path`: 학습된 모델 파일 경로 (.pkl)
- `--test-data`: 테스트 데이터 파일 경로
- `--target-column`: 타겟 컬럼명

### 선택 파라미터
- `--sample-size`: SHAP 계산 샘플 크기 (기본값: 1000)
- `--instance-idx`: 설명할 인스턴스 인덱스 (기본값: 0)
- `--output-dir`: 출력 디렉토리 (기본값: projects/{project-name}/outputs/shap)

## 📤 출력

### 시각화 파일 (PNG)
**전역 설명**:
- `shap_summary_plot.png`: Summary Plot
- `shap_bar_plot.png`: Bar Plot

**지역 설명**:
- `shap_waterfall_plot_instance_X.png`: Waterfall Plot
- `shap_force_plot_instance_X.png`: Force Plot

**특성 의존성**:
- `shap_dependence_plot_{feature}.png`: Dependence Plot

### 텍스트 설명
- `instance_X_explanation.txt`: 개별 인스턴스 설명

### Markdown 리포트
- `{model_name}_shap_report.md`: 종합 SHAP 리포트

### 콘솔 출력
```
═══════════════════════════════════════════════════════════
SHAP 분석 시작
═══════════════════════════════════════════════════════════

✓ 출력 디렉토리: projects/creditcard-fraud-detection/outputs/shap
✓ 데이터 로드 중: projects/creditcard-fraud-detection/data/processed/test.csv
  샘플링: 56,962건 → 1,000건
✓ 데이터 로드 완료: 1,000건, 30개 특성

✓ 모델 로드 중: projects/creditcard-fraud-detection/models/xgboost_model.pkl
✓ 모델 로드 완료: XGBClassifier

────────────────────────────────────────────────────────
SHAP Explainer 생성
────────────────────────────────────────────────────────

모델 타입: XGBClassifier
⏳ Explainer 생성 중...
✓ TreeExplainer 생성 완료

────────────────────────────────────────────────────────
SHAP 값 계산
────────────────────────────────────────────────────────

⏳ 1,000개 샘플에 대한 SHAP 값 계산 중...
✓ SHAP 값 계산 완료
  Shape: (1000, 30)

────────────────────────────────────────────────────────
Summary Plot 생성
────────────────────────────────────────────────────────

✓ Summary Plot 저장: projects/.../shap_summary_plot.png
  상위 특성들의 SHAP 값 분포를 보여줍니다.

────────────────────────────────────────────────────────
Bar Plot 생성
────────────────────────────────────────────────────────

✓ Bar Plot 저장: projects/.../shap_bar_plot.png
  특성 중요도(평균 절댓값)를 보여줍니다.

────────────────────────────────────────────────────────
Waterfall Plot 생성 (인스턴스 0)
────────────────────────────────────────────────────────

✓ Waterfall Plot 저장: projects/.../shap_waterfall_plot_instance_0.png
  개별 예측에 대한 특성별 기여도를 보여줍니다.

────────────────────────────────────────────────────────
Force Plot 생성 (인스턴스 0)
────────────────────────────────────────────────────────

✓ Force Plot 저장: projects/.../shap_force_plot_instance_0.png
  개별 예측의 시각적 설명을 보여줍니다.

────────────────────────────────────────────────────────
Dependence Plot 생성 (V17)
────────────────────────────────────────────────────────

✓ Dependence Plot 저장: projects/.../shap_dependence_plot_V17.png
  V17 특성의 값에 따른 SHAP 값 변화를 보여줍니다.

────────────────────────────────────────────────────────
인스턴스 0 예측 설명
────────────────────────────────────────────────────────

실제 레이블: 0
예측 레이블: 0

상위 5개 영향 특성:
  1. V17                  :    -1.2345 (SHAP: -0.4567, 음성 기여)
  2. V14                  :     0.8765 (SHAP: -0.3456, 음성 기여)
  3. V12                  :     1.4567 (SHAP: -0.2345, 음성 기여)
  4. V10                  :    -0.9876 (SHAP: -0.1987, 음성 기여)
  5. V4                   :     2.3456 (SHAP: +0.1234, 양성 기여)

✓ 설명 저장: projects/.../instance_0_explanation.txt

✓ SHAP 리포트 저장: projects/.../xgboost_model_shap_report.md

═══════════════════════════════════════════════════════════
SHAP 분석 완료
═══════════════════════════════════════════════════════════

📁 모든 결과가 저장되었습니다: projects/creditcard-fraud-detection/outputs/shap/
   - 시각화: *.png
   - 리포트: xgboost_model_shap_report.md
   - 개별 설명: instance_*_explanation.txt
```

## 🔍 SHAP 해석 가이드

### SHAP 값의 의미
- **양수**: 예측을 증가시킴 (분류: 양성 클래스 확률 증가)
- **음수**: 예측을 감소시킴 (분류: 음성 클래스 확률 감소)
- **절댓값**: 영향력의 크기

### Summary Plot 읽기
1. **세로축**: 특성 (중요도 순)
2. **가로축**: SHAP 값 (음수 ← 0 → 양수)
3. **점 색상**: 특성 값 (빨강=높음, 파랑=낮음)
4. **점 분포**: SHAP 값의 다양성

### Waterfall Plot 읽기
1. **Base value**: 평균 예측값
2. **화살표**: 각 특성의 기여도
3. **최종 값**: Base + 모든 기여도

## 🐛 트러블슈팅

### 문제: SHAP 계산이 너무 느림
**원인**: KernelExplainer 사용 또는 샘플이 너무 큼
**해결**:
```bash
# 샘플 크기 줄이기
--sample-size 500

# Tree-based 모델은 TreeExplainer 자동 사용 (빠름)
```

### 문제: 메모리 부족
**해결**:
```bash
--sample-size 200
```

### 문제: Force Plot 생성 실패
**원인**: JavaScript 초기화 실패
**해결**: Waterfall Plot 사용 (동일한 정보 제공)

## 📚 관련 문서

- [SHAP 공식 문서](https://shap.readthedocs.io/)
- [SHAP GitHub](https://github.com/slundberg/shap)
- [Shapley Values 논문](https://arxiv.org/abs/1705.07874)

## 🔗 관련 플러그인

- `model-evaluation`: 모델 성능 평가
- `model-monitoring`: 프로덕션 모델 모니터링
- `feature-engineering`: 특성 엔지니어링
- `model-selection`: 모델 선택 및 학습

## 💡 활용 사례

### 1. 모델 디버깅
- 예상치 못한 예측 원인 파악
- 잘못된 특성 의존성 탐지

### 2. 규제 준수
- 설명 가능한 AI (XAI)
- 금융, 의료 등 규제 산업

### 3. 비즈니스 인사이트
- 주요 영향 요인 발견
- 도메인 전문가와 소통

### 4. Feature Engineering
- 중요 특성 파악
- 상호작용 효과 발견

## 📝 라이선스

MIT License

## 👤 작성자

- **Dante Labs**
- Email: datapod.k@gmail.com
- 버전: 1.0.0