FinRL-IRT는 면역학적 Replicator-Transport 연산자를 금융 강화학습 파이프라인에 통합하여 시장 위기 상황에서도 안정적인 포트폴리오 운용을 달성하고자 하는 연구 프로젝트입니다. Stable Baselines3의 SAC 구조 위에 IRT Actor를 결합하고, 위기 감지(T-Cell) 및 최적수송(Sinkhorn)을 통해 위기 레짐 전환에 능동적으로 대응합니다.
- 면역계의 B/T-Cell 원리를 차용하여 위기 감지 → 학습률 가열 → 전문가 혼합의 파이프라인을 구성합니다.
- Optimal Transport와 Replicator Dynamics를 결합한
IRT연산자가 프로토타입 전략을 동적으로 혼합합니다. - Stable Baselines3의 Critic을 재사용하면서 Actor만 커스텀 IRT Actor로 교체하여 기존 FinRL 코드베이스와 호환됩니다.
- 위기 민감 보상(
dsr_cvar)과 시각화(XAI, 프로토타입 추적)를 통해 모델 해석성을 확보합니다. - 학습·평가·문서화·테스트가 모두 포함된 재현 가능한 연구 버전을 제공합니다.
[ wt = (1-\alpha_c), \tilde{w}_t + \alpha_c, P_t\mathbf{1}, \quad \tilde{w}_t \propto w{t-1},\exp{\eta(c_t)(f_t - \bar{f}_t) - r_t} ]
- (P_t): Sinkhorn 알고리즘으로 계산한 최적수송 계획
- (\alpha_c): 위기 레벨 및 Sharpe 변화에 의해 조정되는 혼합 계수
- (\eta(c_t)): 위기 레벨에 따라 가열되는 Replicator 학습률
- (r_t): 자기-내성 서명과의 유사도에 기반한 억제 항
finrl/agents/irt/irt_operator.py: Sinkhorn 기반 비용 행렬 및 IRT 연산자 구현finrl/agents/irt/bcell_actor.py: 상태 인코딩, IRT 결합, Dirichlet 디코딩을 수행하는 B-Cell Actorfinrl/agents/irt/t_cell.py: 시장 피처로부터 위기 타입 점수와 공자극 임베딩을 추정하는 경량 T-Cellfinrl/agents/irt/irt_policy.py: SACPolicy를 상속받아 IRT Actor를 결합한 정책 클래스scripts/train_irt.py: 데이터 다운로드→환경 구성→학습→평가까지 일괄 수행하는 학습 스크립트scripts/evaluate.py: direct(deterministic) 및 drlagent 모드 평가, XAI·위험지표 추출 지원
FinFlow-rl/
├── docs/ # 알고리즘 및 실험 문서
├── finrl/agents/irt/ # IRT 핵심 모듈 (B-Cell, T-Cell, IRT Operator, Policy)
├── scripts/ # 학습·평가 CLI 스크립트
├── tests/ # 단위 테스트 및 최소 재현 실험
├── requirements.txt # 의존성 정의
├── pyproject.toml # 패키징/빌드 설정
└── README.md # 프로젝트 개요 (본 문서)
- 환경 설치
git clone <repo-url> cd FinFlow-rl pip install -r requirements.txt pip install -e .
- 최소 실행 검증
python tests/test_finrl_minimal.py python tests/test_irt_policy.py
- 브라우저 없이 로그만으로 결과 확인: 모든 스크립트는
logs/하위에 모델, 메타데이터, TensorBoard 로그를 남깁니다.
-
SAC/기본 알고리즘 학습
python scripts/train.py --model sac --mode both --episodes 200
-
IRT 전용 학습 + 즉시 평가
python scripts/train_irt.py --mode both --episodes 200 --alpha 0.45
-
평가 (direct / drlagent)
# direct 모드 (SB3 모델 직접 사용) python scripts/evaluate.py --model logs/irt/<time>/irt_final.zip --method direct --save-plot # drlagent 모드 (FinRL DRLAgent API) python scripts/evaluate.py --model logs/finrl_sac/<time>/sac_50k.zip --method drlagent
-
XAI 활성화 (direct 전용)
python scripts/evaluate.py --model logs/irt/<time>/irt_final.zip \ --method direct --xai-level full --xai-target critic_q --xai-k 64
- 기본 종목: Dow Jones 30 (
finrl/config_tickers.py) - 학습 구간: 2008-04-01 ~ 2020-12-31 / 평가 구간: 2021-01-01 ~ 2024-12-31 (
finrl/config.py) - 기술지표: MACD, Bollinger Band, RSI 등 8종 (
INDICATORS) - 보상 설정:
reward_type='dsr_cvar'사용 시 DSR·CVaR 특성이 상태에 포함되고 IRT Actor가 Sharpe/CVaR 신호를 함께 사용합니다.
scripts/train_irt.py는--seed인자를 받아 난수 시드를 고정합니다.- 학습 시 메타데이터(
env_meta.json)가 자동 저장되며 평가 시 동일 구성을 복원합니다. tests/디렉터리의 단위 테스트로 forward pass, simplex 제약, Critic 연동을 매번 검증합니다.- TensorBoard 로그는
logs/<model>/tensorboard/에 기록되어 실험 비교가 용이합니다.
docs/IRT.md: IRT 연산자, 위기 감지, 비용 함수에 대한 상세 수식 및 알고리즘 설명docs/SCRIPTS.md: 학습/평가 스크립트별 인자 설명과 사용 예시
- 라이선스: MIT (자세한 내용은 LICENSE 참조)
- 이슈/기여: GitHub Issues 및 Pull Request를 통해 제보 혹은 토론 바랍니다.
- 학술 협업 및 문의: 프로젝트 저장소의 Discussions 탭을 활용해 주세요.