The-Ouroboros/README.md

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

KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자체 전략 코드를 TDD 기반으로 진화시키는 자율 주식 트레이딩 에이전트.

아키텍처

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  KIS Broker │◄───►│    Main     │◄───►│ Gemini Brain│
│  (매매 실행) │     │ (거래 루프)  │     │  (의사결정)  │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────┴──────┐ ┌──┴───┐ ┌──────┴──────┐
       │Risk Manager │ │  DB  │ │  Telegram   │
       │  (안전장치)  │ │      │ │ (알림+명령)  │
       └──────┬──────┘ └──────┘ └─────────────┘
              │
     ┌────────┼────────┐
     │        │        │
┌────┴────┐┌──┴──┐┌────┴─────┐
│Strategy ││Ctx  ││Evolution │
│(플레이북)││(메모리)││ (진화)   │
└─────────┘└─────┘└──────────┘

v2 핵심: "Plan Once, Execute Locally" — 장 시작 전 AI가 시나리오 플레이북을 1회 생성하고, 거래 시간에는 로컬 시나리오 매칭만 수행하여 API 비용과 지연 시간을 대폭 절감.

핵심 모듈

모듈	위치	설명
설정	src/config.py	Pydantic 기반 환경변수 로딩 및 타입 검증 (35+ 변수)
브로커	src/broker/	KIS API 비동기 래퍼 (국내 + 해외 9개 시장)
두뇌	src/brain/	Gemini 프롬프트 구성, JSON 파싱, 토큰 최적화
방패	src/core/risk_manager.py	서킷 브레이커 + 팻 핑거 체크 (READ-ONLY)
전략	src/strategy/	Pre-Market Planner, Scenario Engine, Playbook Store
컨텍스트	src/context/	L1-L7 계층형 메모리 시스템
분석	src/analysis/	RSI, ATR, Smart Volatility Scanner
알림	src/notifications/	텔레그램 양방향 (알림 + 9개 명령어)
대시보드	src/dashboard/	FastAPI 읽기 전용 모니터링 (8개 API)
진화	src/evolution/	전략 진화 + Daily Review + Scorecard
의사결정 로그	src/logging/	전체 거래 결정 감사 추적
데이터	src/data/	뉴스, 시장 데이터, 경제 캘린더 연동
백업	src/backup/	자동 백업, S3 클라우드, 무결성 검증
DB	src/db.py	SQLite 거래 로그 (5개 테이블)

안전장치

규칙	내용
서킷 브레이커	일일 손실률 -3.0% 초과 시 전체 매매 중단 (SystemExit)
팻 핑거 방지	주문 금액이 보유 현금의 30% 초과 시 주문 거부
신뢰도 임계값	Gemini 신뢰도 80 미만이면 강제 HOLD
레이트 리미터	Leaky Bucket 알고리즘으로 API 호출 제한
토큰 자동 갱신	만료 1분 전 자동으로 Access Token 재발급
손절 모니터링	플레이북 시나리오 기반 실시간 포지션 보호

빠른 시작

1. 환경 설정

cp .env.example .env
# .env 파일에 KIS API 키와 Gemini API 키 입력

2. 의존성 설치

pip install ".[dev]"

3. 테스트 실행

pytest -v --cov=src --cov-report=term-missing

4. 실행 (모의투자)

# 기본 실행
python -m src.main --mode=paper

# 대시보드 활성화
python -m src.main --mode=paper --dashboard

5. Docker 실행

docker compose up -d ouroboros

지원 시장

국가	거래소	코드
🇰🇷 한국	KRX	KR
🇺🇸 미국	NASDAQ, NYSE, AMEX	US_NASDAQ, US_NYSE, US_AMEX
🇯🇵 일본	TSE	JP
🇭🇰 홍콩	SEHK	HK
🇨🇳 중국	상하이, 선전	CN_SHA, CN_SZA
🇻🇳 베트남	하노이, 호치민	VN_HNX, VN_HSX

ENABLED_MARKETS 환경변수로 활성 시장 선택 (기본: KR,US).

텔레그램 (선택사항)

거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.

빠른 설정

1. 봇 생성: 텔레그램에서 @BotFather 메시지 → /newbot 명령
2. 채팅 ID 확인: @userinfobot 메시지 → /start 명령
3. 환경변수 설정: .env 파일에 추가

   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
   TELEGRAM_CHAT_ID=123456789
   TELEGRAM_ENABLED=true
   

4. 테스트: 봇과 대화 시작 (/start 전송) 후 에이전트 실행

상세 문서: src/notifications/README.md

알림 종류

• 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
• 🚨 서킷 브레이커 발동 (자동 거래 중단)
• ⚠️ 팻 핑거 차단 (과도한 주문 차단)
• ℹ️ 장 시작/종료 알림
• 📝 시스템 시작/종료 상태

양방향 명령어

TELEGRAM_COMMANDS_ENABLED=true (기본값) 설정 시 9개 대화형 명령어 지원:

명령어	설명
/help	사용 가능한 명령어 목록
/status	거래 상태 (모드, 시장, P&L)
/positions	계좌 요약 (잔고, 현금, P&L)
/report	일일 요약 (거래 수, P&L, 승률)
/scenarios	오늘의 플레이북 시나리오
/review	최근 스코어카드 (L6_DAILY)
/dashboard	대시보드 URL 표시
/stop	거래 일시 정지
/resume	거래 재개

안전장치: 알림 실패해도 거래는 계속 진행됩니다.

테스트

551개 테스트가 25개 파일에 걸쳐 구현되어 있습니다. 최소 커버리지 80%.

tests/test_scenario_engine.py    — 시나리오 매칭 (44개)
tests/test_data_integration.py   — 외부 데이터 연동 (38개)
tests/test_pre_market_planner.py — 플레이북 생성 (37개)
tests/test_main.py               — 거래 루프 통합 (37개)
tests/test_token_efficiency.py   — 토큰 최적화 (34개)
tests/test_strategy_models.py    — 전략 모델 검증 (33개)
tests/test_telegram_commands.py  — 텔레그램 명령어 (31개)
tests/test_latency_control.py    — 지연시간 제어 (30개)
tests/test_telegram.py           — 텔레그램 알림 (25개)
... 외 16개 파일

상세: docs/testing.md

기술 스택

• 언어: Python 3.11+ (asyncio 기반)
• 브로커: KIS Open API (REST, 국내+해외)
• AI: Google Gemini Pro
• DB: SQLite (5개 테이블: trades, contexts, decision_logs, playbooks, context_metadata)
• 대시보드: FastAPI + uvicorn
• 검증: pytest + coverage (551 tests)
• CI/CD: GitHub Actions
• 배포: Docker + Docker Compose

프로젝트 구조

The-Ouroboros/
├── docs/
│   ├── architecture.md          # 시스템 아키텍처
│   ├── testing.md               # 테스트 가이드
│   ├── commands.md              # 명령어 레퍼런스
│   ├── context-tree.md          # L1-L7 메모리 시스템
│   ├── workflow.md              # Git 워크플로우
│   ├── agents.md                # 에이전트 정책
│   ├── skills.md                # 도구 목록
│   ├── disaster_recovery.md     # 백업/복구
│   └── requirements-log.md      # 요구사항 기록
├── src/
│   ├── analysis/                # 기술적 분석 (RSI, ATR, Smart Scanner)
│   ├── backup/                  # 백업 (스케줄러, S3, 무결성 검증)
│   ├── brain/                   # Gemini 의사결정 (프롬프트 최적화, 컨텍스트 선택)
│   ├── broker/                  # KIS API (국내 + 해외)
│   ├── context/                 # L1-L7 계층 메모리
│   ├── core/                    # 리스크 관리 (READ-ONLY)
│   ├── dashboard/               # FastAPI 모니터링 대시보드
│   ├── data/                    # 외부 데이터 연동
│   ├── evolution/               # 전략 진화 + Daily Review
│   ├── logging/                 # 의사결정 감사 추적
│   ├── markets/                 # 시장 스케줄 + 타임존
│   ├── notifications/           # 텔레그램 알림 + 명령어
│   ├── strategy/                # 플레이북 (Planner, Scenario Engine)
│   ├── config.py                # Pydantic 설정
│   ├── db.py                    # SQLite 데이터베이스
│   └── main.py                  # 비동기 거래 루프
├── tests/                       # 551개 테스트 (25개 파일)
├── Dockerfile                   # 멀티스테이지 빌드
├── docker-compose.yml           # 서비스 오케스트레이션
└── pyproject.toml               # 의존성 및 도구 설정

문서

• 아키텍처 — 시스템 설계, 컴포넌트, 데이터 흐름
• 테스트 — 테스트 구조, 커버리지, 작성 가이드
• 명령어 — CLI, Dashboard, Telegram 명령어
• 컨텍스트 트리 — L1-L7 계층 메모리
• 워크플로우 — Git 워크플로우 정책
• 에이전트 정책 — 안전 제약, 금지 행위
• 백업/복구 — 재해 복구 절차
• 요구사항 — 사용자 요구사항 추적

라이선스

이 프로젝트의 라이선스는 LICENSE 파일을 참조하세요.