127 lines
3.2 KiB
Markdown
127 lines
3.2 KiB
Markdown
# 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`: 알림 및 명령 핸들러
|
|
|
|
## Quick Start
|
|
|
|
### 1. 환경 설정
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
필수 값:
|
|
|
|
- `KIS_APP_KEY`
|
|
- `KIS_APP_SECRET`
|
|
- `KIS_ACCOUNT_NO`
|
|
- `GEMINI_API_KEY`
|
|
|
|
### 2. 의존성 설치
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### 3. 테스트
|
|
|
|
```bash
|
|
pytest -v --cov=src
|
|
ruff check src/ tests/
|
|
mypy src/ --strict
|
|
```
|
|
|
|
## 실행
|
|
|
|
### 기본 실행
|
|
|
|
```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` 정규화 어댑터 명시 구현 없음
|
|
- 영향: `price_change_pct_above/below` 조건을 사용하는 시나리오는 사실상 매칭 불가(dead path)
|
|
- HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡
|
|
- 시장 코드 정합성 이슈:
|
|
- 설정 기본값은 `ENABLED_MARKETS="KR,US"`
|
|
- 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심
|
|
- 영향: `get_open_markets(["KR", "US"])`에서 `US` 미정의로 US 시장이 누락될 수 있음(런타임 영향)
|
|
|
|
## 테스트
|
|
|
|
로컬 수집 기준:
|
|
|
|
```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`
|