# The Ouroboros — 자가 진화형 AI 투자 시스템

KIS API 기반 자동매매 + Gemini 기반 장전 전략 생성 + 장중 로컬 시나리오 실행 + 장후 리뷰/진화 루프를 결합한 시스템입니다.

## 현재 상태 (2026-02-16)

- V2 계획 기준 완료: **18/20**
- 부분 완료: **1/20** (`1-7` 일부 항목)
- 미완료: **1/20** (`4-1` Telegram 확장 명령어)

핵심 전환은 이미 반영되었습니다.

- 기존: 장중 `brain.decide()` 실시간 의존
- 현재: 장전 `DayPlaybook` 생성 + 장중 `ScenarioEngine` 로컬 매칭

## 핵심 구성

- `src/main.py`: 시장 루프, 플레이북 생성/적용, EOD 집계, 리뷰/진화 연결
- `src/strategy/`: `models`, `pre_market_planner`, `scenario_engine`, `playbook_store`
- `src/context/`: `store`, `aggregator`, `scheduler` (L1~L7)
- `src/evolution/daily_review.py`: 시장별 scorecard/lessons 생성
- `src/dashboard/app.py`: FastAPI 관측 API
- `src/notifications/telegram_client.py`: 알림 및 명령 핸들러

## 실행

### 기본 실행

```bash
python -m src.main --mode=paper
```

### 대시보드 포함 실행

```bash
python -m src.main --mode=paper --dashboard
```

또는 환경변수:

```bash
DASHBOARD_ENABLED=true
DASHBOARD_HOST=127.0.0.1
DASHBOARD_PORT=8080
```

## 주요 API/기능

- 플레이북 저장: `playbooks` 테이블 (`date + market` UNIQUE)
- 의사결정/결과 연결: `trades.decision_id` + `DecisionLogger.update_outcome()`
- 시장별 scorecard 컨텍스트: `scorecard_KR`, `scorecard_US`
- 컨텍스트 스케줄러: weekly/monthly/quarterly/annual/legacy + cleanup
- 대시보드 API:
- `/api/status`
- `/api/playbook/{date}?market=KR`
- `/api/scorecard/{date}?market=KR`
- `/api/performance?market=all`
- `/api/context/{layer}`
- `/api/decisions?market=KR`
- `/api/scenarios/active?market=US`

## 현재 갭 (코드 기준)

- `Issue 4-1` 미구현: `/report`, `/scenarios`, `/review`, `/dashboard` Telegram 명령 미등록
- `Issue 1-7` 일부 미완:
- `price_change_pct` 정규화 어댑터 명시 구현 없음
- HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡
- 시장 코드 정합성 이슈:
- 설정 기본값은 `ENABLED_MARKETS="KR,US"`
- 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심
- 완전 통합 전 추가 정리 필요

## 테스트

로컬 수집 기준:

```bash
pytest --collect-only -q
# 538 tests collected
```

권장 검증:

```bash
pytest -v --cov=src
ruff check src/ tests/
mypy src/ --strict
```

## 문서

- 아키텍처: `docs/architecture.md`
- 컨텍스트 트리: `docs/context-tree.md`
- 워크플로우: `docs/workflow.md`
- 요구사항 로그: `docs/requirements-log.md`
- 명령 레퍼런스: `docs/commands.md`