881bbb4240
Some checks failed
CI / test (pull_request) Has been cancelled
Update project documentation to include Telegram notification feature that was added in issues #31-34. Changes: - CLAUDE.md: Add Telegram quick setup section with examples - README.md (Korean): Add 텔레그램 알림 section with setup guide - docs/architecture.md: Add Notifications component documentation - New section explaining TelegramClient architecture - Add notification step to data flow diagram - Add Telegram config to environment variables - Document error handling for notification failures Documentation covers: - Quick setup instructions (bot creation, chat ID, env config) - Notification types (trades, circuit breaker, fat-finger, etc.) - Fail-safe behavior (notifications never crash trading) - Links to detailed guide in src/notifications/README.md Project structure updated to reflect notifications/ directory and updated test count (273 tests). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# The Ouroboros — 자가 진화형 AI 투자 시스템
|
||
|
||
KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자체 전략 코드를 TDD 기반으로 진화시키는 자율 주식 트레이딩 에이전트.
|
||
|
||
## 아키텍처
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ KIS Broker │◄───►│ Main │◄───►│ Gemini Brain│
|
||
│ (매매 실행) │ │ (거래 루프) │ │ (의사결정) │
|
||
└─────────────┘ └──────┬──────┘ └─────────────┘
|
||
│
|
||
┌──────┴──────┐
|
||
│Risk Manager │
|
||
│ (안전장치) │
|
||
└──────┬──────┘
|
||
│
|
||
┌──────┴──────┐
|
||
│ Evolution │
|
||
│ (전략 진화) │
|
||
└─────────────┘
|
||
```
|
||
|
||
## 핵심 모듈
|
||
|
||
| 모듈 | 파일 | 설명 |
|
||
|------|------|------|
|
||
| 설정 | `src/config.py` | Pydantic 기반 환경변수 로딩 및 타입 검증 |
|
||
| 브로커 | `src/broker/kis_api.py` | KIS API 비동기 래퍼 (토큰 갱신, 레이트 리미터, 해시키) |
|
||
| 두뇌 | `src/brain/gemini_client.py` | Gemini 프롬프트 구성 및 JSON 응답 파싱 |
|
||
| 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 |
|
||
| 알림 | `src/notifications/telegram_client.py` | 텔레그램 실시간 거래 알림 (선택사항) |
|
||
| 진화 | `src/evolution/optimizer.py` | 실패 패턴 분석 → 새 전략 생성 → 테스트 → PR |
|
||
| DB | `src/db.py` | SQLite 거래 로그 기록 |
|
||
|
||
## 안전장치
|
||
|
||
| 규칙 | 내용 |
|
||
|------|------|
|
||
| 서킷 브레이커 | 일일 손실률 -3.0% 초과 시 전체 매매 중단 (`SystemExit`) |
|
||
| 팻 핑거 방지 | 주문 금액이 보유 현금의 30% 초과 시 주문 거부 |
|
||
| 신뢰도 임계값 | Gemini 신뢰도 80 미만이면 강제 HOLD |
|
||
| 레이트 리미터 | Leaky Bucket 알고리즘으로 API 호출 제한 |
|
||
| 토큰 자동 갱신 | 만료 1분 전 자동으로 Access Token 재발급 |
|
||
|
||
## 빠른 시작
|
||
|
||
### 1. 환경 설정
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# .env 파일에 KIS API 키와 Gemini API 키 입력
|
||
```
|
||
|
||
### 2. 의존성 설치
|
||
|
||
```bash
|
||
pip install ".[dev]"
|
||
```
|
||
|
||
### 3. 테스트 실행
|
||
|
||
```bash
|
||
pytest -v --cov=src --cov-report=term-missing
|
||
```
|
||
|
||
### 4. 실행 (모의투자)
|
||
|
||
```bash
|
||
python -m src.main --mode=paper
|
||
```
|
||
|
||
### 5. Docker 실행
|
||
|
||
```bash
|
||
docker compose up -d ouroboros
|
||
```
|
||
|
||
## 텔레그램 알림 (선택사항)
|
||
|
||
거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
|
||
|
||
### 빠른 설정
|
||
|
||
1. **봇 생성**: 텔레그램에서 [@BotFather](https://t.me/BotFather) 메시지 → `/newbot` 명령
|
||
2. **채팅 ID 확인**: [@userinfobot](https://t.me/userinfobot) 메시지 → `/start` 명령
|
||
3. **환경변수 설정**: `.env` 파일에 추가
|
||
```bash
|
||
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
|
||
TELEGRAM_CHAT_ID=123456789
|
||
TELEGRAM_ENABLED=true
|
||
```
|
||
4. **테스트**: 봇과 대화 시작 (`/start` 전송) 후 에이전트 실행
|
||
|
||
**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
|
||
|
||
### 알림 종류
|
||
|
||
- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
|
||
- 🚨 서킷 브레이커 발동 (자동 거래 중단)
|
||
- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
|
||
- ℹ️ 장 시작/종료 알림
|
||
- 📝 시스템 시작/종료 상태
|
||
|
||
**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
|
||
|
||
## 테스트
|
||
|
||
35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
|
||
|
||
```
|
||
tests/test_risk.py — 서킷 브레이커, 팻 핑거, 통합 검증 (11개)
|
||
tests/test_broker.py — 토큰 관리, 타임아웃, HTTP 에러, 해시키 (6개)
|
||
tests/test_brain.py — JSON 파싱, 신뢰도 임계값, 비정상 응답 처리 (15개)
|
||
```
|
||
|
||
## 기술 스택
|
||
|
||
- **언어**: Python 3.11+ (asyncio 기반)
|
||
- **브로커**: KIS Open API (REST)
|
||
- **AI**: Google Gemini Pro
|
||
- **DB**: SQLite
|
||
- **검증**: pytest + coverage
|
||
- **CI/CD**: GitHub Actions
|
||
- **배포**: Docker + Docker Compose
|
||
|
||
## 프로젝트 구조
|
||
|
||
```
|
||
The-Ouroboros/
|
||
├── .github/workflows/ci.yml # CI 파이프라인
|
||
├── docs/
|
||
│ ├── agents.md # AI 에이전트 페르소나 정의
|
||
│ └── skills.md # 사용 가능한 도구 목록
|
||
├── src/
|
||
│ ├── config.py # Pydantic 설정
|
||
│ ├── logging_config.py # JSON 구조화 로깅
|
||
│ ├── db.py # SQLite 거래 기록
|
||
│ ├── main.py # 비동기 거래 루프
|
||
│ ├── broker/kis_api.py # KIS API 클라이언트
|
||
│ ├── brain/gemini_client.py # Gemini 의사결정 엔진
|
||
│ ├── core/risk_manager.py # 리스크 관리
|
||
│ ├── notifications/telegram_client.py # 텔레그램 알림
|
||
│ ├── evolution/optimizer.py # 전략 진화 엔진
|
||
│ └── strategies/base.py # 전략 베이스 클래스
|
||
├── tests/ # TDD 테스트 스위트
|
||
├── Dockerfile # 멀티스테이지 빌드
|
||
├── docker-compose.yml # 서비스 오케스트레이션
|
||
└── pyproject.toml # 의존성 및 도구 설정
|
||
```
|
||
|
||
## 라이선스
|
||
|
||
이 프로젝트의 라이선스는 [LICENSE](LICENSE) 파일을 참조하세요.
|