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

안전/운영 컴포넌트도 핵심입니다.

• RiskManager: circuit breaker, fat-finger 검증
• PriorityTaskQueue + CriticalityAssessor: 우선순위/지연 제어

Market Scope

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

현재 코드 기준 주의점(런타임 영향):

• 설정은 KR,US를 기본값으로 사용
• 스케줄 레이어(src/markets/schedule.py)는 US_NASDAQ, US_NYSE 구조를 아직 유지
• US 코드가 스케줄에 직접 정의되지 않아 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() 실행

Risk Policy

• RiskManager는 주문 전 검증을 강제합니다.
• circuit breaker: 손실 임계치 하회 시 거래 중단
• fat-finger: 주문 금액 과대 시 주문 차단
• 실패 시 알림은 보내되, 예외 처리로 루프 안정성 유지

Error Handling Strategy

• API 호출 실패: 재시도(지수 백오프) 후 종목/사이클 스킵
• 시나리오/플래너 실패: empty 또는 defensive playbook으로 안전 폴백
• Telegram 실패: warning 로깅 후 거래 루프 지속
• 대시보드 스레드 실패: warning 로깅 후 메인 트레이딩 루프와 분리 유지

Configuration Reference

상세 설정은 src/config.py를 기준으로 합니다.

• 거래 모드: TRADE_MODE, DAILY_SESSIONS, SESSION_INTERVAL_HOURS
• 전략: PRE_MARKET_MINUTES, MAX_SCENARIOS_PER_STOCK, RESCAN_INTERVAL_SECONDS
• 시장: ENABLED_MARKETS
• 대시보드: DASHBOARD_ENABLED, DASHBOARD_HOST, DASHBOARD_PORT
• 알림: TELEGRAM_*

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 정규화 계층 명시 미흡
• 영향: price_change_pct 기반 조건은 현재 사실상 매칭되지 않음
• HOLD 시 별도 손절 모니터링 플래그 처리 미완
• US 스캐닝 확장(fetch_overseas_rankings) 미구현