82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
# Architecture
|
||
|
||
> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
|
||
|
||
## 프로젝트 개요
|
||
|
||
Belkin & Suchower (1998) + Vasicek 단일팩터 모델 기반으로, 한국 3사 전이행렬과 BOK ECOS 거시경제변수를 결합하여 **50년 Lifetime PD**를 호황/중립/불황 시나리오별로 산출하는 시스템.
|
||
|
||
## 디렉토리 구조
|
||
|
||
```
|
||
LifetimePD/
|
||
├── main.py # 7단계 파이프라인 오케스트레이터
|
||
├── config.yaml # API 키, 모형 파라미터, 시나리오 설정
|
||
├── data/
|
||
│ ├── transition_matrices.py # 한국 3사 전이행렬 (builtin + CSV 로더)
|
||
│ └── macro_data.py # BOK ECOS API 거시경제변수 6종 수집
|
||
├── models/
|
||
│ ├── credit_cycle.py # Belkin & Suchower Zt 추정 (WLS)
|
||
│ ├── vasicek.py # Vasicek 조건부 PD/전이행렬
|
||
│ └── macro_model.py # Zt~거시 OLS 회귀 (Stepwise AIC)
|
||
├── scenarios/
|
||
│ └── scenario_engine.py # 호황/중립/불황 시나리오 + Mean-reversion
|
||
├── projection/
|
||
│ └── lifetime_pd.py # 50년 누적/한계 PD + 확률가중평균
|
||
├── validation/
|
||
│ └── statistical_tests.py # ADF, Ljung-Box, R², ARCH, PD 성질 검증
|
||
├── output/
|
||
│ └── visualizer.py # 차트 7종 + 요약 테이블
|
||
├── results/ # 생성 결과물 (PNG, CSV)
|
||
├── doc/ # 원본 자료 (3사 PDF, ECOS API 명세)
|
||
│ ├── ECOS_API/ # 한은 API 개발명세서 + 통계표
|
||
│ └── *.pdf # 3사 전이행렬 원본 PDF
|
||
├── docs/
|
||
│ ├── methodology.md # 이론 방법론 상세 (9개 섹션)
|
||
│ └── devlog/ # 세션별 작업 기록
|
||
└── .agent/.agents/ # AI 에이전트 설정
|
||
```
|
||
|
||
## 핵심 모듈
|
||
|
||
| 모듈 | 역할 | 의존성 |
|
||
|------|------|--------|
|
||
| `data/transition_matrices.py` | 전이행렬 로딩 + TTC 산출 | numpy, scipy |
|
||
| `data/macro_data.py` | ECOS API 6종 거시변수 수집 | requests, pandas |
|
||
| `models/credit_cycle.py` | Belkin-Suchower Zt 추정 (WLS) | numpy, scipy.optimize |
|
||
| `models/vasicek.py` | 조건부 PD/전이행렬 | numpy, scipy.stats |
|
||
| `models/macro_model.py` | Zt~거시 OLS + Stepwise AIC | statsmodels |
|
||
| `scenarios/scenario_engine.py` | 3-시나리오 Zt 경로 + Mean-reversion | numpy |
|
||
| `projection/lifetime_pd.py` | 50년 행렬곱 PD + 가중평균 | numpy |
|
||
| `validation/statistical_tests.py` | 8개 통계 검정 | statsmodels, scipy |
|
||
| `output/visualizer.py` | 차트 7종 | matplotlib |
|
||
|
||
## 데이터 흐름
|
||
|
||
```
|
||
전이행렬(26yr) → TTC 평균 → Φ⁻¹ 임계값 → WLS Zt 추정
|
||
↓
|
||
ECOS API 거시 6변수 ──→ Stepwise OLS ──→ Zt~거시 회귀
|
||
↓
|
||
시나리오(3종) × PIT→MR→TTC 수렴 → 조건부 TM → 행렬곱 → PD term structure
|
||
```
|
||
|
||
## 실행 방법
|
||
|
||
```powershell
|
||
# ECOS API 사용 (기본)
|
||
C:\ProgramData\miniforge3\envs\quant\python.exe main.py
|
||
|
||
# Fallback 데이터 사용
|
||
C:\ProgramData\miniforge3\envs\quant\python.exe main.py --no-api
|
||
|
||
# ρ 동시 추정
|
||
C:\ProgramData\miniforge3\envs\quant\python.exe main.py --estimate-rho
|
||
```
|
||
|
||
## 미완료 사항 (다음 작업자 참고)
|
||
|
||
1. **#290 실제 3사 전이행렬 CSV 변환** — `doc/`의 PDF에서 전이행렬을 추출하여 `data/raw/` CSV로 변환 필요. 현재는 builtin synthetic 데이터 사용 중
|
||
2. **#293 거시 시나리오 고도화** — IMF WEO/KDI 전망치를 직접 입력하여 시나리오 정밀화
|
||
3. **GDP 성장률 코드** — 현재 `902Y015/KOR` (국제 비교 통계) 사용. 한은 국민계정 직접 통계표코드 발견 시 교체 권장
|