LifetimePD/.agents/references/architecture.md

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

실행 방법

# 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 (국제 비교 통계) 사용. 한은 국민계정 직접 통계표코드 발견 시 교체 권장