From cc1489fd7c76b23a1603f8409d7a621d8a359c9c Mon Sep 17 00:00:00 2001 From: agentson Date: Mon, 16 Feb 2026 11:58:49 +0900 Subject: [PATCH] docs: sync V2 status and process docs for issue #131 --- README.md | 182 ++++++------------ docs/architecture.md | 402 +++++++++------------------------------ docs/commands.md | 216 +++++++-------------- docs/context-tree.md | 341 +++++---------------------------- docs/requirements-log.md | 33 ++++ docs/testing.md | 249 +++++------------------- docs/workflow.md | 5 +- 7 files changed, 347 insertions(+), 1081 deletions(-) diff --git a/README.md b/README.md index 16a818e..a92d960 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,96 @@ # The Ouroboros — 자가 진화형 AI 투자 시스템 -KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자체 전략 코드를 TDD 기반으로 진화시키는 자율 주식 트레이딩 에이전트. +KIS API 기반 자동매매 + Gemini 기반 장전 전략 생성 + 장중 로컬 시나리오 실행 + 장후 리뷰/진화 루프를 결합한 시스템입니다. -## 아키텍처 +## 현재 상태 (2026-02-16) -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ KIS Broker │◄───►│ Main │◄───►│ Gemini Brain│ -│ (매매 실행) │ │ (거래 루프) │ │ (의사결정) │ -└─────────────┘ └──────┬──────┘ └─────────────┘ - │ - ┌──────┴──────┐ - │Risk Manager │ - │ (안전장치) │ - └──────┬──────┘ - │ - ┌──────┴──────┐ - │ Evolution │ - │ (전략 진화) │ - └─────────────┘ -``` +- V2 계획 기준 완료: **18/20** +- 부분 완료: **1/20** (`1-7` 일부 항목) +- 미완료: **1/20** (`4-1` Telegram 확장 명령어) -## 핵심 모듈 +핵심 전환은 이미 반영되었습니다. -| 모듈 | 파일 | 설명 | -|------|------|------| -| 설정 | `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 거래 로그 기록 | +- 기존: 장중 `brain.decide()` 실시간 의존 +- 현재: 장전 `DayPlaybook` 생성 + 장중 `ScenarioEngine` 로컬 매칭 -## 안전장치 +## 핵심 구성 -| 규칙 | 내용 | -|------|------| -| 서킷 브레이커 | 일일 손실률 -3.0% 초과 시 전체 매매 중단 (`SystemExit`) | -| 팻 핑거 방지 | 주문 금액이 보유 현금의 30% 초과 시 주문 거부 | -| 신뢰도 임계값 | Gemini 신뢰도 80 미만이면 강제 HOLD | -| 레이트 리미터 | Leaky Bucket 알고리즘으로 API 호출 제한 | -| 토큰 자동 갱신 | 만료 1분 전 자동으로 Access Token 재발급 | +- `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`: 알림 및 명령 핸들러 -## 빠른 시작 +## 실행 -### 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 +python -m src.main --mode=paper --dashboard ``` -## 텔레그램 알림 (선택사항) +또는 환경변수: -거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다. +```bash +DASHBOARD_ENABLED=true +DASHBOARD_HOST=127.0.0.1 +DASHBOARD_PORT=8080 +``` -### 빠른 설정 +## 주요 API/기능 -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` 전송) 후 에이전트 실행 +- 플레이북 저장: `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` -**상세 문서**: [src/notifications/README.md](src/notifications/README.md) +## 현재 갭 (코드 기준) -### 알림 종류 - -- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도) -- 🚨 서킷 브레이커 발동 (자동 거래 중단) -- ⚠️ 팻 핑거 차단 (과도한 주문 차단) -- ℹ️ 장 시작/종료 알림 -- 📝 시스템 시작/종료 상태 - -**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다. +- `Issue 4-1` 미구현: `/report`, `/scenarios`, `/review`, `/dashboard` Telegram 명령 미등록 +- `Issue 1-7` 일부 미완: +- `price_change_pct` 정규화 어댑터 명시 구현 없음 +- HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡 +- 시장 코드 정합성 이슈: +- 설정 기본값은 `ENABLED_MARKETS="KR,US"` +- 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심 +- 완전 통합 전 추가 정리 필요 ## 테스트 -35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다. +로컬 수집 기준: -``` -tests/test_risk.py — 서킷 브레이커, 팻 핑거, 통합 검증 (11개) -tests/test_broker.py — 토큰 관리, 타임아웃, HTTP 에러, 해시키 (6개) -tests/test_brain.py — JSON 파싱, 신뢰도 임계값, 비정상 응답 처리 (15개) +```bash +pytest --collect-only -q +# 538 tests collected ``` -## 기술 스택 +권장 검증: -- **언어**: 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 # 의존성 및 도구 설정 +```bash +pytest -v --cov=src +ruff check src/ tests/ +mypy src/ --strict ``` -## 라이선스 +## 문서 -이 프로젝트의 라이선스는 [LICENSE](LICENSE) 파일을 참조하세요. +- 아키텍처: `docs/architecture.md` +- 컨텍스트 트리: `docs/context-tree.md` +- 워크플로우: `docs/workflow.md` +- 요구사항 로그: `docs/requirements-log.md` +- 명령 레퍼런스: `docs/commands.md` diff --git a/docs/architecture.md b/docs/architecture.md index e31ea9c..ba94f50 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,342 +2,110 @@ ## Overview -Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates four components across multiple markets with two trading modes: daily (batch API calls) or realtime (per-stock decisions). +The Ouroboros V2는 `Proactive` 구조를 중심으로 동작합니다. -## Trading Modes +- 장전: Gemini 1회 호출로 시장별 `DayPlaybook` 생성 +- 장중: `ScenarioEngine`이 로컬 조건 매칭으로 의사결정 +- 장후: `ContextAggregator` + `DailyReviewer`로 성과 집계/교훈 생성 -The system supports two trading frequency modes controlled by the `TRADE_MODE` environment variable: +`main.py`가 아래 컴포넌트를 오케스트레이션합니다. -### Daily Mode (default) +- `KISBroker` / `OverseasBroker` +- `PreMarketPlanner` / `ScenarioEngine` / `PlaybookStore` +- `ContextStore` / `ContextAggregator` / `ContextScheduler` +- `DailyReviewer` / `EvolutionOptimizer` +- `TelegramClient` / `TelegramCommandHandler` -Optimized for Gemini Free tier API limits (20 calls/day): +## Market Scope -- **Batch decisions**: 1 API call per market per session -- **Fixed schedule**: 4 sessions per day at 6-hour intervals (configurable) -- **API efficiency**: Processes all stocks in a market simultaneously -- **Use case**: Free tier users, cost-conscious deployments -- **Configuration**: - ```bash - TRADE_MODE=daily - DAILY_SESSIONS=4 # Sessions per day (1-10) - SESSION_INTERVAL_HOURS=6 # Hours between sessions (1-24) - ``` +V2 기본 설정은 `ENABLED_MARKETS="KR,US"` 입니다. -**Example**: With 2 markets (US, KR) and 4 sessions/day = 8 API calls/day (within 20 call limit) +현재 코드 기준 주의점: -### Realtime Mode +- 설정은 `KR,US`를 기본값으로 사용 +- 스케줄 레이어(`src/markets/schedule.py`)는 `US_NASDAQ`, `US_NYSE` 구조를 아직 유지 +- 완전한 `US` 단일 코드 통합은 추가 정리 필요 -High-frequency trading with individual stock analysis: +## Decision Flow -- **Per-stock decisions**: 1 API call per stock per cycle -- **60-second interval**: Continuous monitoring -- **Use case**: Production deployments with Gemini paid tier -- **Configuration**: - ```bash - TRADE_MODE=realtime - ``` +### 1) Pre-market -**Note**: Realtime mode requires Gemini API subscription due to high call volume. +1. `SmartVolatilityScanner.scan()`으로 후보 종목 수집 +2. `PreMarketPlanner.generate_playbook(market, candidates)` 호출 +3. 결과를 `PlaybookStore.save()`로 DB 저장 +4. 실패 시 empty/defensive playbook 사용 -## Core Components +### 2) In-market -### 1. Broker (`src/broker/`) +1. 시장 데이터 + 스캐너 메트릭(`rsi`, `volume_ratio`) 구성 +2. `ScenarioEngine.evaluate(playbook, stock_code, market_data, portfolio_data)` +3. `TradeDecision` 변환 후 주문/로그/알림 처리 +4. `decision_logs`와 `trades`를 `decision_id`로 연결 -**KISBroker** (`kis_api.py`) — Async KIS API client for domestic Korean market +### 3) End-of-day -- Automatic OAuth token refresh (valid for 24 hours) -- Leaky-bucket rate limiter (10 requests per second) -- POST body hash-key signing for order authentication -- Custom SSL context with disabled hostname verification for VTS (virtual trading) endpoint due to known certificate mismatch +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()` 실행 -**OverseasBroker** (`overseas.py`) — KIS overseas stock API wrapper +## Context Tree -- Reuses KISBroker infrastructure (session, token, rate limiter) via composition -- Supports 9 global markets: US (NASDAQ/NYSE/AMEX), Japan, Hong Kong, China (Shanghai/Shenzhen), Vietnam (Hanoi/HCM) -- Different API endpoints for overseas price/balance/order operations +레이어 전략: -**Market Schedule** (`src/markets/schedule.py`) — Timezone-aware market management +- `L7~L5`: 시장별 키 +- `L4~L1`: 글로벌 통합 롤업 -- `MarketInfo` dataclass with timezone, trading hours, lunch breaks -- Automatic DST handling via `zoneinfo.ZoneInfo` -- `is_market_open()` checks weekends, trading hours, lunch breaks -- `get_open_markets()` returns currently active markets -- `get_next_market_open()` finds next market to open and when +구현 포인트: -**New API Methods** (added in v0.9.0): -- `fetch_market_rankings()` — Fetch volume surge rankings from KIS API -- `get_daily_prices()` — Fetch OHLCV history for technical analysis +- `L7` 쓰기: `volatility_{market}_{stock}` 등 +- `L6` 집계: `total_pnl_KR`, `trade_count_US` 등 +- `ContextScheduler.run_if_due()`: +- 주간/월간/분기/연간/legacy 집계 +- 일 1회 `cleanup_expired_contexts()` 호출 -### 2. Analysis (`src/analysis/`) +## Data Model (핵심) -**VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations +### `trades` -- ATR (Average True Range) for volatility measurement -- RSI (Relative Strength Index) using Wilder's smoothing method -- Price change percentages across multiple timeframes -- Volume surge ratios and price-volume divergence -- Momentum scoring (0-100 scale) -- Breakout/breakdown pattern detection - -**SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline - -- **Step 1**: Fetch volume rankings from KIS API (top 30 stocks) -- **Step 2**: Calculate RSI and volume ratio for each stock -- **Step 3**: Apply filters: - - Volume ratio >= `VOL_MULTIPLIER` (default 2.0x previous day) - - RSI < `RSI_OVERSOLD_THRESHOLD` (30) OR RSI > `RSI_MOMENTUM_THRESHOLD` (70) -- **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%) -- **Step 5**: Return top N candidates (default 3) for AI analysis -- **Fallback**: Uses static watchlist if ranking API unavailable -- **Realtime mode only**: Daily mode uses batch processing for API efficiency - -**Benefits:** -- Reduces Gemini API calls from 20-30 stocks to 1-3 qualified candidates -- Fast Python-based filtering before expensive AI judgment -- Logs selection context (RSI, volume_ratio, signal, score) for Evolution system - -### 3. Brain (`src/brain/gemini_client.py`) - -**GeminiClient** — AI decision engine powered by Google Gemini - -- Constructs structured prompts from market data -- Parses JSON responses into `TradeDecision` objects (`action`, `confidence`, `rationale`) -- Forces HOLD when confidence < threshold (default 80) -- Falls back to safe HOLD on any parse/API error -- Handles markdown-wrapped JSON, malformed responses, invalid actions - -### 4. Risk Manager (`src/core/risk_manager.py`) - -**RiskManager** — Safety circuit breaker and order validation - -⚠️ **READ-ONLY by policy** (see [`docs/agents.md`](./agents.md)) - -- **Circuit Breaker**: Halts all trading via `SystemExit` when daily P&L drops below -3.0% - - Threshold may only be made stricter, never relaxed - - Calculated as `(total_eval - purchase_total) / purchase_total * 100` -- **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash - - Must always be enforced, cannot be disabled - -### 5. Notifications (`src/notifications/telegram_client.py`) - -**TelegramClient** — Real-time event notifications via Telegram Bot API - -- Sends alerts for trades, circuit breakers, fat-finger rejections, system events -- Non-blocking: failures are logged but never crash trading -- Rate-limited: 1 message/second default to respect Telegram API limits -- Auto-disabled when credentials missing -- Gracefully handles API errors, network timeouts, invalid tokens - -**Notification Types:** -- Trade execution (BUY/SELL with confidence) -- Circuit breaker trips (critical alert) -- Fat-finger protection triggers (order rejection) -- Market open/close events -- System startup/shutdown status - -**Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration. - -### 6. Evolution (`src/evolution/optimizer.py`) - -**StrategyOptimizer** — Self-improvement loop - -- Analyzes high-confidence losing trades from SQLite -- Asks Gemini to generate new `BaseStrategy` subclasses -- Validates generated strategies by running full pytest suite -- Simulates PR creation for human review -- Only activates strategies that pass all tests - -## Data Flow - -### Realtime Mode (with Smart Scanner) - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Main Loop (60s cycle per market) │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Market Schedule Check │ - │ - Get open markets │ - │ - Filter by enabled markets │ - │ - Wait if all closed │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Smart Scanner (Python-first) │ - │ - Fetch volume rankings (KIS) │ - │ - Get 20d price history per stock│ - │ - Calculate RSI(14) + vol ratio │ - │ - Filter: vol>2x AND RSI extreme │ - │ - Return top 3 qualified stocks │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ For Each Qualified Candidate │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Broker: Fetch Market Data │ - │ - Domestic: orderbook + balance │ - │ - Overseas: price + balance │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Calculate P&L │ - │ pnl_pct = (eval - cost) / cost │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Brain: Get Decision (AI) │ - │ - Build prompt with market data │ - │ - Call Gemini API │ - │ - Parse JSON response │ - │ - Return TradeDecision │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Risk Manager: Validate Order │ - │ - Check circuit breaker │ - │ - Check fat-finger limit │ - │ - Raise if validation fails │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Broker: Execute Order │ - │ - Domestic: send_order() │ - │ - Overseas: send_overseas_order() │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Notifications: Send Alert │ - │ - Trade execution notification │ - │ - Non-blocking (errors logged) │ - │ - Rate-limited to 1/sec │ - └──────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Database: Log Trade │ - │ - SQLite (data/trades.db) │ - │ - Track: action, confidence, │ - │ rationale, market, exchange │ - │ - NEW: selection_context (JSON) │ - │ - RSI, volume_ratio, signal │ - │ - For Evolution optimization │ - └───────────────────────────────────┘ -``` - -## Database Schema - -**SQLite** (`src/db.py`) - -```sql -CREATE TABLE trades ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - timestamp TEXT NOT NULL, - stock_code TEXT NOT NULL, - action TEXT NOT NULL, -- BUY | SELL | HOLD - confidence INTEGER NOT NULL, -- 0-100 - rationale TEXT, - quantity INTEGER, - price REAL, - pnl REAL DEFAULT 0.0, - market TEXT DEFAULT 'KR', -- KR | US_NASDAQ | JP | etc. - exchange_code TEXT DEFAULT 'KRX', -- KRX | NASD | NYSE | etc. - selection_context TEXT -- JSON: {rsi, volume_ratio, signal, score} -); -``` - -**Selection Context** (new in v0.9.0): Stores scanner selection criteria as JSON: -```json -{ - "rsi": 28.5, - "volume_ratio": 2.7, - "signal": "oversold", - "score": 85.2 -} -``` - -Enables Evolution system to analyze correlation between selection criteria and trade outcomes. - -Auto-migration: Adds `market`, `exchange_code`, and `selection_context` columns if missing for backward compatibility. - -## Configuration - -**Pydantic Settings** (`src/config.py`) - -Loaded from `.env` file: - -```bash -# Required -KIS_APP_KEY=your_app_key -KIS_APP_SECRET=your_app_secret -KIS_ACCOUNT_NO=XXXXXXXX-XX -GEMINI_API_KEY=your_gemini_key - -# Optional -MODE=paper # paper | live -DB_PATH=data/trades.db -CONFIDENCE_THRESHOLD=80 -MAX_LOSS_PCT=3.0 -MAX_ORDER_PCT=30.0 -ENABLED_MARKETS=KR,US_NASDAQ # Comma-separated market codes - -# Trading Mode (API efficiency) -TRADE_MODE=daily # daily | realtime -DAILY_SESSIONS=4 # Sessions per day (daily mode only) -SESSION_INTERVAL_HOURS=6 # Hours between sessions (daily mode only) - -# Telegram Notifications (optional) -TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz -TELEGRAM_CHAT_ID=123456789 -TELEGRAM_ENABLED=true - -# Smart Scanner (optional, realtime mode only) -RSI_OVERSOLD_THRESHOLD=30 # 0-50, oversold threshold -RSI_MOMENTUM_THRESHOLD=70 # 50-100, momentum threshold -VOL_MULTIPLIER=2.0 # Minimum volume ratio (2.0 = 200%) -SCANNER_TOP_N=3 # Max qualified candidates per scan -``` - -Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`. - -## Error Handling - -### Connection Errors (Broker API) -- Retry with exponential backoff (2^attempt seconds) -- Max 3 retries per stock -- After exhaustion, skip stock and continue with next - -### API Quota Errors (Gemini) -- Return safe HOLD decision with confidence=0 -- Log error but don't crash -- Agent continues trading on next cycle - -### Circuit Breaker Tripped -- Immediately halt via `SystemExit` -- Log critical message -- Requires manual intervention to restart - -### Market Closed -- Wait until next market opens -- Use `get_next_market_open()` to calculate wait time -- Sleep until market open time - -### Telegram API Errors -- Log warning but continue trading -- Missing credentials → auto-disable notifications -- Network timeout → skip notification, no retry -- Invalid token → log error, trading unaffected -- Rate limit exceeded → queued via rate limiter - -**Guarantee**: Notification failures never interrupt trading operations. +- `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` 정규화 계층 명시 미흡 +- HOLD 시 별도 손절 모니터링 플래그 처리 미완 +- US 스캐닝 확장(`fetch_overseas_rankings`) 미구현 diff --git a/docs/commands.md b/docs/commands.md index 1053ac5..3549283 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,156 +1,82 @@ # Command Reference -## Common Command Failures - -**Critical: Learn from failures. Never repeat the same failed command without modification.** - -### tea CLI (Gitea Command Line Tool) - -#### ❌ TTY Error - Interactive Confirmation Fails -```bash -~/bin/tea issues create --repo X --title "Y" --description "Z" -# Error: huh: could not open a new TTY: open /dev/tty: no such device or address -``` -**💡 Reason:** tea tries to open `/dev/tty` for interactive confirmation prompts, which is unavailable in non-interactive environments. - -**✅ Solution:** Use `YES=""` environment variable to bypass confirmation -```bash -YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "Title" --description "Body" -YES="" ~/bin/tea issues edit --repo jihoson/The-Ouroboros --description "Updated body" -YES="" ~/bin/tea pulls create --repo jihoson/The-Ouroboros --head feature-branch --base main --title "Title" --description "Body" -``` - -**📝 Notes:** -- Always set default login: `~/bin/tea login default local` -- Use `--repo jihoson/The-Ouroboros` when outside repo directory -- tea is preferred over direct Gitea API calls for consistency - -#### ❌ Wrong Parameter Name -```bash -tea issues create --body "text" -# Error: flag provided but not defined: -body -``` -**💡 Reason:** Parameter is `--description`, not `--body`. - -**✅ Solution:** Use correct parameter name -```bash -YES="" ~/bin/tea issues create --description "text" -``` - -### Gitea API (Direct HTTP Calls) - -#### ❌ Wrong Hostname -```bash -curl http://gitea.local:3000/api/v1/... -# Error: Could not resolve host: gitea.local -``` -**💡 Reason:** Gitea instance runs on `localhost:3000`, not `gitea.local`. - -**✅ Solution:** Use correct hostname (but prefer tea CLI) -```bash -curl http://localhost:3000/api/v1/repos/jihoson/The-Ouroboros/issues \ - -H "Authorization: token $GITEA_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"title":"...", "body":"..."}' -``` - -**📝 Notes:** -- Prefer `tea` CLI over direct API calls -- Only use curl for operations tea doesn't support - -### Git Commands - -#### ❌ User Not Configured -```bash -git commit -m "message" -# Error: Author identity unknown -``` -**💡 Reason:** Git user.name and user.email not set. - -**✅ Solution:** Configure git user -```bash -git config user.name "agentson" -git config user.email "agentson@localhost" -``` - -#### ❌ Permission Denied on Push -```bash -git push origin branch -# Error: User permission denied for writing -``` -**💡 Reason:** Repository access token lacks write permissions or user lacks repo write access. - -**✅ Solution:** -1. Verify user has write access to repository (admin grants this) -2. Ensure git credential has correct token with `write:repository` scope -3. Check remote URL uses correct authentication - -### Python/Pytest - -#### ❌ Module Import Error -```bash -pytest tests/test_foo.py -# ModuleNotFoundError: No module named 'src' -``` -**💡 Reason:** Package not installed in development mode. - -**✅ Solution:** Install package with dev dependencies -```bash -pip install -e ".[dev]" -``` - -#### ❌ Async Test Hangs -```python -async def test_something(): # Hangs forever - result = await async_function() -``` -**💡 Reason:** Missing pytest-asyncio or wrong configuration. - -**✅ Solution:** Already configured in pyproject.toml -```toml -[tool.pytest.ini_options] -asyncio_mode = "auto" -``` -No decorator needed for async tests. - -## Build & Test Commands +## Core Runtime Commands ```bash -# Install all dependencies (production + dev) -pip install -e ".[dev]" - -# Run full test suite with coverage -pytest -v --cov=src --cov-report=term-missing - -# Run a single test file -pytest tests/test_risk.py -v - -# Run a single test by name -pytest tests/test_brain.py -k "test_parse_valid_json" -v - -# Lint -ruff check src/ tests/ - -# Type check (strict mode, non-blocking in CI) -mypy src/ --strict - -# Run the trading agent +# run (paper) python -m src.main --mode=paper -# Docker -docker compose up -d ouroboros # Run agent -docker compose --profile test up test # Run tests in container +# run with dashboard thread +python -m src.main --mode=paper --dashboard + +# tests +pytest -v --cov=src + +# lint +ruff check src/ tests/ + +# type-check +mypy src/ --strict ``` -## Environment Setup +## Dashboard Runtime Controls + +`Issue 4-3` 기준 반영: + +- CLI: `--dashboard` +- ENV: `DASHBOARD_ENABLED=true` +- Host/Port: +- `DASHBOARD_HOST` (default `127.0.0.1`) +- `DASHBOARD_PORT` (default `8080`) + +## Telegram Commands (현재 구현) + +`main.py` 등록 기준: + +- `/help` +- `/status` +- `/positions` +- `/stop` +- `/resume` + +## Telegram Commands (미구현 상태) + +V2 플랜 `Issue 4-1` 항목은 아직 미구현: + +- `/report [KR|US]` +- `/scenarios [KR|US]` +- `/review [KR|US]` +- `/dashboard` + +## Gitea / tea Workflow Commands + +이슈 선등록 후 작업 시작: ```bash -# Create .env file from example -cp .env.example .env - -# Edit .env with your credentials -# Required: KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NO, GEMINI_API_KEY - -# Verify configuration -python -c "from src.config import Settings; print(Settings())" +YES="" ~/bin/tea issues create \ + --repo jihoson/The-Ouroboros \ + --title "..." \ + --description "..." ``` + +작업은 `worktree` 기준 권장: + +```bash +git worktree add ../The-Ouroboros-issue- feature/issue-- +``` + +PR 생성: + +```bash +YES="" ~/bin/tea pulls create \ + --repo jihoson/The-Ouroboros \ + --head feature/issue-- \ + --base main \ + --title "..." \ + --description "..." +``` + +## Known tea CLI Gotcha + +TTY 없는 환경에서는 `tea` 확인 프롬프트가 실패할 수 있습니다. +항상 `YES=""`를 붙여 비대화식으로 실행하세요. diff --git a/docs/context-tree.md b/docs/context-tree.md index f3474e4..522f712 100644 --- a/docs/context-tree.md +++ b/docs/context-tree.md @@ -1,243 +1,81 @@ # Context Tree: Multi-Layered Memory Management -The context tree implements **Pillar 2** of The Ouroboros: hierarchical memory management across 7 time horizons, from real-time market data to generational trading wisdom. +## Summary -## Overview +컨텍스트 트리는 L7(실시간)부터 L1(레거시)까지 계층화된 메모리 구조입니다. -Instead of a flat memory structure, The Ouroboros maintains a **7-tier context tree** where each layer represents a different time horizon and level of abstraction: +- L7~L5: 시장별 독립 데이터 중심 +- L4~L1: 글로벌 포트폴리오 통합 데이터 -``` -L1 (Legacy) ← Cumulative wisdom across generations - ↑ -L2 (Annual) ← Yearly performance metrics - ↑ -L3 (Quarterly) ← Quarterly strategy adjustments - ↑ -L4 (Monthly) ← Monthly portfolio rebalancing - ↑ -L5 (Weekly) ← Weekly stock selection - ↑ -L6 (Daily) ← Daily trade logs - ↑ -L7 (Real-time) ← Live market data -``` +## Layer Policy -Data flows **bottom-up**: real-time trades aggregate into daily summaries, which roll up to weekly, then monthly, quarterly, annual, and finally into permanent legacy knowledge. +### L7_REALTIME (시장+종목 스코프) -## The 7 Layers +- 주요 키 패턴: +- `volatility_{market}_{stock_code}` +- `price_{market}_{stock_code}` +- `rsi_{market}_{stock_code}` +- `volume_ratio_{market}_{stock_code}` -### L7: Real-time -**Retention**: 7 days -**Timeframe format**: `YYYY-MM-DD` (same-day) -**Content**: Current positions, live quotes, orderbook snapshots, tick-by-tick volatility +`trading_cycle()`에서 실시간으로 기록합니다. -**Use cases**: -- Immediate execution decisions -- Stop-loss triggers -- Real-time P&L tracking +### L6_DAILY (시장 스코프) -**Example keys**: -- `current_position_{stock_code}`: Current holdings -- `live_price_{stock_code}`: Latest quote -- `volatility_5m_{stock_code}`: 5-minute rolling volatility +EOD 집계 결과를 시장별 키로 저장합니다. -### L6: Daily -**Retention**: 90 days -**Timeframe format**: `YYYY-MM-DD` -**Content**: Daily trade logs, end-of-day P&L, market summaries, decision accuracy +- `trade_count_KR`, `buys_KR`, `sells_KR`, `holds_KR` +- `avg_confidence_US`, `total_pnl_US`, `win_rate_US` +- scorecard 저장 키: `scorecard_KR`, `scorecard_US` -**Use cases**: -- Daily performance review -- Identify patterns in recent trading -- Backtest strategy adjustments +### L5_WEEKLY -**Example keys**: -- `total_pnl`: Daily profit/loss -- `trade_count`: Number of trades -- `win_rate`: Percentage of profitable trades -- `avg_confidence`: Average Gemini confidence +L6 일일 데이터에서 시장별 주간 합계를 생성합니다. -### L5: Weekly -**Retention**: 1 year -**Timeframe format**: `YYYY-Www` (ISO week, e.g., `2026-W06`) -**Content**: Weekly stock selection, sector rotation, volatility regime classification +- `weekly_pnl_KR`, `weekly_pnl_US` +- `avg_confidence_KR`, `avg_confidence_US` -**Use cases**: -- Weekly strategy adjustment -- Sector momentum tracking -- Identify hot/cold markets +### L4_MONTHLY 이상 -**Example keys**: -- `weekly_pnl`: Week's total P&L -- `top_performers`: Best-performing stocks -- `sector_focus`: Dominant sectors -- `avg_confidence`: Weekly average confidence +글로벌 통합 롤업입니다. -### L4: Monthly -**Retention**: 2 years -**Timeframe format**: `YYYY-MM` -**Content**: Monthly portfolio rebalancing, risk exposure analysis, drawdown recovery +- L5 → L4: `monthly_pnl` +- L4 → L3: `quarterly_pnl` +- L3 → L2: `annual_pnl` +- L2 → L1: `total_pnl`, `years_traded`, `avg_annual_pnl` -**Use cases**: -- Monthly performance reporting -- Risk exposure adjustment -- Correlation analysis +## Aggregation Flow -**Example keys**: -- `monthly_pnl`: Month's total P&L -- `sharpe_ratio`: Risk-adjusted return -- `max_drawdown`: Largest peak-to-trough decline -- `rebalancing_notes`: Manual insights +- EOD: `ContextAggregator.aggregate_daily_from_trades(date, market)` +- 주기 롤업: `ContextScheduler.run_if_due()` -### L3: Quarterly -**Retention**: 3 years -**Timeframe format**: `YYYY-Qn` (e.g., `2026-Q1`) -**Content**: Quarterly strategy pivots, market phase detection (bull/bear/sideways), macro regime changes +`ContextScheduler`는 다음을 처리합니다. -**Use cases**: -- Strategic pivots (e.g., growth → value) -- Macro regime classification -- Long-term pattern recognition - -**Example keys**: -- `quarterly_pnl`: Quarter's total P&L -- `market_phase`: Bull/Bear/Sideways -- `strategy_adjustments`: Major changes made -- `lessons_learned`: Key insights - -### L2: Annual -**Retention**: 10 years -**Timeframe format**: `YYYY` -**Content**: Yearly returns, Sharpe ratio, max drawdown, win rate, strategy effectiveness - -**Use cases**: -- Annual performance review -- Multi-year trend analysis -- Strategy benchmarking - -**Example keys**: -- `annual_pnl`: Year's total P&L -- `sharpe_ratio`: Annual risk-adjusted return -- `win_rate`: Yearly win percentage -- `best_strategy`: Most successful strategy -- `worst_mistake`: Biggest lesson learned - -### L1: Legacy -**Retention**: Forever -**Timeframe format**: `LEGACY` (single timeframe) -**Content**: Cumulative trading history, core principles, generational wisdom - -**Use cases**: -- Long-term philosophy -- Foundational rules -- Lessons that transcend market cycles - -**Example keys**: -- `total_pnl`: All-time profit/loss -- `years_traded`: Trading longevity -- `avg_annual_pnl`: Long-term average return -- `core_principles`: Immutable trading rules -- `greatest_trades`: Hall of fame -- `never_again`: Permanent warnings +- weekly/monthly/quarterly/annual/legacy 집계 +- 일 1회 `ContextStore.cleanup_expired_contexts()` 실행 +- 동일 날짜 중복 실행 방지(`_last_run`) ## Usage -### Setting Context - ```python -from src.context import ContextLayer, ContextStore -from src.db import init_db +from datetime import UTC, datetime -conn = init_db("data/ouroboros.db") -store = ContextStore(conn) - -# Store daily P&L -store.set_context( - layer=ContextLayer.L6_DAILY, - timeframe="2026-02-04", - key="total_pnl", - value=1234.56 -) - -# Store weekly insight -store.set_context( - layer=ContextLayer.L5_WEEKLY, - timeframe="2026-W06", - key="top_performers", - value=["005930", "000660", "035720"] # JSON-serializable -) - -# Store legacy wisdom -store.set_context( - layer=ContextLayer.L1_LEGACY, - timeframe="LEGACY", - key="core_principles", - value=[ - "Cut losses fast", - "Let winners run", - "Never average down on losing positions" - ] -) -``` - -### Retrieving Context - -```python -# Get a specific value -pnl = store.get_context(ContextLayer.L6_DAILY, "2026-02-04", "total_pnl") -# Returns: 1234.56 - -# Get all keys for a timeframe -daily_summary = store.get_all_contexts(ContextLayer.L6_DAILY, "2026-02-04") -# Returns: {"total_pnl": 1234.56, "trade_count": 10, "win_rate": 60.0, ...} - -# Get all data for a layer (any timeframe) -all_daily = store.get_all_contexts(ContextLayer.L6_DAILY) -# Returns: {"total_pnl": 1234.56, "trade_count": 10, ...} (latest timeframes first) - -# Get the latest timeframe -latest = store.get_latest_timeframe(ContextLayer.L6_DAILY) -# Returns: "2026-02-04" -``` - -### Automatic Aggregation - -The `ContextAggregator` rolls up data from lower to higher layers: - -```python from src.context.aggregator import ContextAggregator +from src.context.scheduler import ContextScheduler aggregator = ContextAggregator(conn) +scheduler = ContextScheduler(aggregator=aggregator, store=context_store) -# Aggregate daily metrics from trades -aggregator.aggregate_daily_from_trades("2026-02-04") +# EOD market-scoped daily aggregation +aggregator.aggregate_daily_from_trades(date="2026-02-16", market="KR") -# Roll up weekly from daily -aggregator.aggregate_weekly_from_daily("2026-W06") - -# Roll up all layers at once (bottom-up) -aggregator.run_all_aggregations() +# Run scheduled rollups when due +scheduler.run_if_due(now=datetime.now(UTC)) ``` -**Aggregation schedule** (recommended): -- **L7 → L6**: Every midnight (daily rollup) -- **L6 → L5**: Every Sunday (weekly rollup) -- **L5 → L4**: First day of each month (monthly rollup) -- **L4 → L3**: First day of quarter (quarterly rollup) -- **L3 → L2**: January 1st (annual rollup) -- **L2 → L1**: On demand (major milestones) +## Retention -### Context Cleanup +`src/context/layer.py` 기준: -Expired contexts are automatically deleted based on retention policies: - -```python -# Manual cleanup -deleted = store.cleanup_expired_contexts() -# Returns: {ContextLayer.L7_REALTIME: 42, ContextLayer.L6_DAILY: 15, ...} -``` - -**Retention policies** (defined in `src/context/layer.py`): - L1: Forever - L2: 10 years - L3: 3 years @@ -246,93 +84,8 @@ deleted = store.cleanup_expired_contexts() - L6: 90 days - L7: 7 days -## Integration with Gemini Brain +## Current Notes (2026-02-16) -The context tree provides hierarchical memory for decision-making: - -```python -from src.brain.gemini_client import GeminiClient - -# Build prompt with multi-layer context -def build_enhanced_prompt(stock_code: str, store: ContextStore) -> str: - # L7: Real-time data - current_price = store.get_context(ContextLayer.L7_REALTIME, "2026-02-04", f"live_price_{stock_code}") - - # L6: Recent daily performance - yesterday_pnl = store.get_context(ContextLayer.L6_DAILY, "2026-02-03", "total_pnl") - - # L5: Weekly trend - weekly_data = store.get_all_contexts(ContextLayer.L5_WEEKLY, "2026-W06") - - # L1: Core principles - principles = store.get_context(ContextLayer.L1_LEGACY, "LEGACY", "core_principles") - - return f""" - Analyze {stock_code} for trading decision. - - Current price: {current_price} - Yesterday's P&L: {yesterday_pnl} - This week: {weekly_data} - - Core principles: - {chr(10).join(f'- {p}' for p in principles)} - - Decision (BUY/SELL/HOLD): - """ -``` - -## Database Schema - -```sql --- Context storage -CREATE TABLE contexts ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - layer TEXT NOT NULL, -- L1_LEGACY, L2_ANNUAL, ..., L7_REALTIME - timeframe TEXT NOT NULL, -- "LEGACY", "2026", "2026-Q1", "2026-02", "2026-W06", "2026-02-04" - key TEXT NOT NULL, -- "total_pnl", "win_rate", "core_principles", etc. - value TEXT NOT NULL, -- JSON-serialized value - created_at TEXT NOT NULL, -- ISO 8601 timestamp - updated_at TEXT NOT NULL, -- ISO 8601 timestamp - UNIQUE(layer, timeframe, key) -); - --- Layer metadata -CREATE TABLE context_metadata ( - layer TEXT PRIMARY KEY, - description TEXT NOT NULL, - retention_days INTEGER, -- NULL = keep forever - aggregation_source TEXT -- Parent layer for rollup -); - --- Indices for fast queries -CREATE INDEX idx_contexts_layer ON contexts(layer); -CREATE INDEX idx_contexts_timeframe ON contexts(timeframe); -CREATE INDEX idx_contexts_updated ON contexts(updated_at); -``` - -## Best Practices - -1. **Write to leaf layers only** — Never manually write to L1-L5; let aggregation populate them -2. **Aggregate regularly** — Schedule aggregation jobs to keep higher layers fresh -3. **Query specific timeframes** — Use `get_context(layer, timeframe, key)` for precise retrieval -4. **Clean up periodically** — Run `cleanup_expired_contexts()` weekly to free space -5. **Preserve L1 forever** — Legacy wisdom should never expire -6. **Use JSON-serializable values** — Store dicts, lists, strings, numbers (not custom objects) - -## Testing - -See `tests/test_context.py` for comprehensive test coverage (18 tests, 100% coverage on context modules). - -```bash -pytest tests/test_context.py -v -``` - -## References - -- **Implementation**: `src/context/` - - `layer.py`: Layer definitions and metadata - - `store.py`: CRUD operations - - `aggregator.py`: Bottom-up aggregation logic -- **Database**: `src/db.py` (table initialization) -- **Tests**: `tests/test_context.py` -- **Related**: Pillar 2 (Multi-layered Context Management) +- L7 쓰기와 L6 시장별 집계는 `main.py`에 연결됨 +- scheduler 기반 cleanup/rollup도 연결됨 +- cross-market scorecard 조회는 `PreMarketPlanner`에서 사용 중 diff --git a/docs/requirements-log.md b/docs/requirements-log.md index 59a0eae..74f5a63 100644 --- a/docs/requirements-log.md +++ b/docs/requirements-log.md @@ -86,3 +86,36 @@ - Plan Consistency (필수), Safety & Constraints, Quality, Workflow 4개 카테고리 **이슈/PR:** #114 + +--- + +## 2026-02-16 + +### V2 진행상태 재정렬 + 문서 동기화 + +**배경:** +- V2 이슈 다수가 병렬로 진행되며 구현/문서 간 상태 불일치가 발생 +- 사용자 요청으로 "현재 코드 기준 사실"에 맞춘 전면 문서 갱신 필요 + +**확인된 상태(코드 기준):** +- 완료: 18/20 +- 부분 완료: `1-7` +- 미완료: `4-1` + +**핵심 반영 사항:** +1. 대시보드 실행 통합(`Issue 4-3`) 반영 + - `--dashboard` 플래그 + - `DASHBOARD_ENABLED`, `DASHBOARD_HOST`, `DASHBOARD_PORT` +2. 컨텍스트 스케줄러 및 시장 스코프 키 정책 반영 +3. scorecard/review/evolution 연결 상태 반영 +4. 미완료 갭 명시 + - Telegram 확장 명령어(`4-1`) 미구현 + - `1-7` 잔여 항목(키 정규화/HOLD 손절 모니터링/US 코드 정합성) + +**프로세스 요구사항 강화:** +- 모든 문서 작업도 Gitea 이슈 선등록 후 진행 +- 병렬 작업 후 상태 정합성 점검 결과를 `requirements-log`에 기록 + +**이슈/브랜치:** +- Issue: #131 +- Branch(worktree): `feature/issue-131-docs-v2-status-sync` diff --git a/docs/testing.md b/docs/testing.md index b65d35e..ee6a414 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,213 +1,56 @@ # Testing Guidelines -## Test Structure +## Current Test Baseline (2026-02-16) -**54 tests** across four files. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator. - -The `settings` fixture in `conftest.py` provides safe defaults with test credentials and in-memory DB. - -### Test Files - -#### `tests/test_risk.py` (11 tests) -- Circuit breaker boundaries -- Fat-finger edge cases -- P&L calculation edge cases -- Order validation logic - -**Example:** -```python -def test_circuit_breaker_exact_threshold(risk_manager): - """Circuit breaker should trip at exactly -3.0%.""" - with pytest.raises(CircuitBreakerTripped): - risk_manager.validate_order( - current_pnl_pct=-3.0, - order_amount=1000, - total_cash=10000 - ) -``` - -#### `tests/test_broker.py` (6 tests) -- OAuth token lifecycle -- Rate limiting enforcement -- Hash key generation -- Network error handling -- SSL context configuration - -**Example:** -```python -async def test_rate_limiter(broker): - """Rate limiter should delay requests to stay under 10 RPS.""" - start = time.monotonic() - for _ in range(15): # 15 requests - await broker._rate_limiter.acquire() - elapsed = time.monotonic() - start - assert elapsed >= 1.0 # Should take at least 1 second -``` - -#### `tests/test_brain.py` (18 tests) -- Valid JSON parsing -- Markdown-wrapped JSON handling -- Malformed JSON fallback -- Missing fields handling -- Invalid action validation -- Confidence threshold enforcement -- Empty response handling -- Prompt construction for different markets - -**Example:** -```python -async def test_confidence_below_threshold_forces_hold(brain): - """Decisions below confidence threshold should force HOLD.""" - decision = brain.parse_response('{"action":"BUY","confidence":70,"rationale":"test"}') - assert decision.action == "HOLD" - assert decision.confidence == 70 -``` - -#### `tests/test_market_schedule.py` (19 tests) -- Market open/close logic -- Timezone handling (UTC, Asia/Seoul, America/New_York, etc.) -- DST (Daylight Saving Time) transitions -- Weekend handling -- Lunch break logic -- Multiple market filtering -- Next market open calculation - -**Example:** -```python -def test_is_market_open_during_trading_hours(): - """Market should be open during regular trading hours.""" - # KRX: 9:00-15:30 KST, no lunch break - market = MARKETS["KR"] - trading_time = datetime(2026, 2, 3, 10, 0, tzinfo=ZoneInfo("Asia/Seoul")) # Monday 10:00 - assert is_market_open(market, trading_time) is True -``` - -## Coverage Requirements - -**Minimum coverage: 80%** - -Check coverage: -```bash -pytest -v --cov=src --cov-report=term-missing -``` - -Expected output: -``` -Name Stmts Miss Cover Missing ------------------------------------------------------------ -src/brain/gemini_client.py 85 5 94% 165-169 -src/broker/kis_api.py 120 12 90% ... -src/core/risk_manager.py 35 2 94% ... -src/db.py 25 1 96% ... -src/main.py 150 80 47% (excluded from CI) -src/markets/schedule.py 95 3 97% ... ------------------------------------------------------------ -TOTAL 510 103 80% -``` - -**Note:** `main.py` has lower coverage as it contains the main loop which is tested via integration/manual testing. - -## Test Configuration - -### `pyproject.toml` -```toml -[tool.pytest.ini_options] -asyncio_mode = "auto" -testpaths = ["tests"] -python_files = ["test_*.py"] -``` - -### `tests/conftest.py` -```python -@pytest.fixture -def settings() -> Settings: - """Provide test settings with safe defaults.""" - return Settings( - KIS_APP_KEY="test_key", - KIS_APP_SECRET="test_secret", - KIS_ACCOUNT_NO="12345678-01", - GEMINI_API_KEY="test_gemini_key", - MODE="paper", - DB_PATH=":memory:", # In-memory SQLite - CONFIDENCE_THRESHOLD=80, - ENABLED_MARKETS="KR", - ) -``` - -## Writing New Tests - -### Naming Convention -- Test files: `test_.py` -- Test functions: `test__()` -- Use descriptive names that explain what is being tested - -### Good Test Example -```python -async def test_send_order_with_market_price(broker, settings): - """Market orders should use price=0 and ORD_DVSN='01'.""" - # Arrange - stock_code = "005930" - order_type = "BUY" - quantity = 10 - - # Act - with patch.object(broker._session, 'post') as mock_post: - mock_post.return_value.__aenter__.return_value.status = 200 - mock_post.return_value.__aenter__.return_value.json = AsyncMock( - return_value={"rt_cd": "0", "msg1": "OK"} - ) - - await broker.send_order(stock_code, order_type, quantity, price=0) - - # Assert - call_args = mock_post.call_args - body = call_args.kwargs['json'] - assert body['ORD_DVSN'] == '01' # Market order - assert body['ORD_UNPR'] == '0' # Price 0 -``` - -### Test Checklist -- [ ] Test passes in isolation (`pytest tests/test_foo.py::test_bar -v`) -- [ ] Test has clear docstring explaining what it tests -- [ ] Arrange-Act-Assert structure -- [ ] Uses appropriate fixtures from conftest.py -- [ ] Mocks external dependencies (API calls, network) -- [ ] Tests edge cases and error conditions -- [ ] Doesn't rely on test execution order - -## Running Tests +수집 기준: ```bash -# All tests -pytest -v - -# Specific file -pytest tests/test_risk.py -v - -# Specific test -pytest tests/test_brain.py::test_parse_valid_json -v - -# With coverage -pytest -v --cov=src --cov-report=term-missing - -# Stop on first failure -pytest -x - -# Verbose output with print statements -pytest -v -s +pytest --collect-only -q +# 538 tests collected ``` -## CI/CD Integration +V2 핵심 영역 테스트가 포함되어 있습니다. -Tests run automatically on: -- Every commit to feature branches -- Every PR to main -- Scheduled daily runs +- `tests/test_strategy_models.py` +- `tests/test_pre_market_planner.py` +- `tests/test_scenario_engine.py` +- `tests/test_playbook_store.py` +- `tests/test_context_scheduler.py` +- `tests/test_daily_review.py` +- `tests/test_scorecard.py` +- `tests/test_dashboard.py` +- `tests/test_main.py` -**Blocking conditions:** -- Test failures → PR blocked -- Coverage < 80% → PR blocked (warning only for main.py) +## Required Checks -**Non-blocking:** -- `mypy --strict` errors (type hints encouraged but not enforced) -- `ruff check` warnings (must be acknowledged) +```bash +pytest -v --cov=src +ruff check src/ tests/ +mypy src/ --strict +``` + +## FastAPI Note + +대시보드 테스트(`tests/test_dashboard.py`)는 `fastapi`가 환경에 없으면 skip될 수 있습니다. +의도된 동작이며 CI/개발환경에서 의존성 설치 여부를 확인하세요. + +## Targeted Smoke Commands + +```bash +# dashboard integration +pytest -q tests/test_main.py -k "dashboard" + +# planner/scenario/review paths +pytest -q tests/test_pre_market_planner.py tests/test_scenario_engine.py tests/test_daily_review.py + +# context rollup/scheduler +pytest -q tests/test_context.py tests/test_context_scheduler.py +``` + +## Review Checklist (테스트 관점) + +- 플랜 항목별 테스트 존재 여부 확인 +- 시장 스코프 키(`*_KR`, `*_US`) 검증 확인 +- EOD 흐름(`aggregate_daily_from_trades`, `scorecard_{market}` 저장) 검증 +- decision outcome 연결(`decision_id`) 검증 +- 대시보드 API market filter 검증 diff --git a/docs/workflow.md b/docs/workflow.md index 0183368..ecb1f26 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -8,8 +8,9 @@ 2. **Create Feature Branch** — Branch from `main` using format `feature/issue-{N}-{short-description}` - After creating the branch, run `git pull origin main` and rebase to ensure the branch is up to date 3. **Implement Changes** — Write code, tests, and documentation on the feature branch -4. **Create Pull Request** — Submit PR to `main` branch referencing the issue number -5. **Review & Merge** — After approval, merge via PR (squash or merge commit) +4. **Sync Status Docs** — Before PR, update `README.md` and relevant `docs/*.md` so implementation status/gaps are explicit +5. **Create Pull Request** — Submit PR to `main` branch referencing the issue number +6. **Review & Merge** — After approval, merge via PR (squash or merge commit) **Never commit directly to `main`.** This policy applies to all changes, no exceptions.