The-Ouroboros/docs/architecture.md

System Architecture

Overview

The Ouroboros V2는 Proactive 구조를 중심으로 동작합니다.

• 장전: Gemini 1회 호출로 시장별 DayPlaybook 생성
• 장중: ScenarioEngine이 로컬 조건 매칭으로 의사결정
• 장후: ContextAggregator + DailyReviewer로 성과 집계/교훈 생성

main.py가 아래 컴포넌트를 오케스트레이션합니다.

• KISBroker / OverseasBroker
• PreMarketPlanner / ScenarioEngine / PlaybookStore
• ContextStore / ContextAggregator / ContextScheduler
• DailyReviewer / EvolutionOptimizer
• TelegramClient / TelegramCommandHandler

Market Scope

V2 기본 설정은 ENABLED_MARKETS="KR,US" 입니다.

현재 코드 기준 주의점:

• 설정은 KR,US를 기본값으로 사용
• 스케줄 레이어(src/markets/schedule.py)는 US_NASDAQ, US_NYSE 구조를 아직 유지
• 완전한 US 단일 코드 통합은 추가 정리 필요

Decision Flow

1) Pre-market

1. SmartVolatilityScanner.scan()으로 후보 종목 수집
2. PreMarketPlanner.generate_playbook(market, candidates) 호출
3. 결과를 PlaybookStore.save()로 DB 저장
4. 실패 시 empty/defensive playbook 사용

2) In-market

1. 시장 데이터 + 스캐너 메트릭(rsi, volume_ratio) 구성
2. ScenarioEngine.evaluate(playbook, stock_code, market_data, portfolio_data)
3. TradeDecision 변환 후 주문/로그/알림 처리
4. decision_logs와 trades를 decision_id로 연결

3) End-of-day

1. ContextAggregator.aggregate_daily_from_trades(date, market)
2. DailyReviewer.generate_scorecard(date, market)
3. store_scorecard_in_context()로 scorecard_{market} 저장
4. generate_lessons()로 장후 교훈 생성
5. (US 종료 시) EvolutionOptimizer.evolve() 실행

Context Tree

레이어 전략:

• L7~L5: 시장별 키
• L4~L1: 글로벌 통합 롤업

구현 포인트:

• L7 쓰기: volatility_{market}_{stock} 등
• L6 집계: total_pnl_KR, trade_count_US 등
• ContextScheduler.run_if_due():
• 주간/월간/분기/연간/legacy 집계
• 일 1회 cleanup_expired_contexts() 호출

Data Model (핵심)

trades

• market, exchange_code, selection_context, decision_id 포함
• SELL 시 get_latest_buy_trade()를 통해 원본 BUY decision_id를 찾아 결과 업데이트

decision_logs

• 의사결정 입력/컨텍스트 스냅샷 저장
• outcome_pnl, outcome_accuracy 업데이트 가능

playbooks

• UNIQUE(date, market)
• status, token_count, scenario_count, match_count 관리

Dashboard

src/dashboard/app.py의 FastAPI 앱이 SQLite를 직접 조회합니다.

엔드포인트:

• GET /api/status
• GET /api/playbook/{date}?market=KR
• GET /api/scorecard/{date}?market=KR
• GET /api/performance?market=all
• GET /api/context/{layer}
• GET /api/decisions?market=KR
• GET /api/scenarios/active?market=US

실행 통합:

• CLI --dashboard
• 또는 DASHBOARD_ENABLED=true
• main.py에서 daemon thread로 uvicorn 실행

Known Gaps (2026-02-16)

• Issue 4-1 Telegram 확장 명령 미구현 (/report, /scenarios, /review, /dashboard)
• Issue 1-7 일부 미완:
• price_change_pct 정규화 계층 명시 미흡
• HOLD 시 별도 손절 모니터링 플래그 처리 미완
• US 스캐닝 확장(fetch_overseas_rankings) 미구현