From 7725e7a8de96299cea335c862a8b79de3455a313 Mon Sep 17 00:00:00 2001 From: agentson Date: Fri, 6 Feb 2026 07:35:25 +0900 Subject: [PATCH] docs: update documentation for Smart Volatility Scanner MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update project documentation to reflect new Smart Volatility Scanner feature: ## CLAUDE.md - Add Smart Volatility Scanner section with configuration guide - Update project structure to include analysis/ module - Update test count (273→343 tests) ## docs/architecture.md - Add Analysis component (VolatilityAnalyzer + SmartVolatilityScanner) - Add new KIS API methods (fetch_market_rankings, get_daily_prices) - Update data flow diagram to show Python-first filtering pipeline - Add selection_context to database schema documentation - Add Smart Scanner configuration section - Renumber components (Brain 2→3, Risk Manager 3→4, etc.) ## docs/requirements-log.md - Document 2026-02-06 requirement for Smart Volatility Scanner - Explain Python-First, AI-Last pipeline rationale - Record implementation details and benefits - Reference issue #76 and PR #77 Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 36 ++++++++++++++++- docs/architecture.md | 87 ++++++++++++++++++++++++++++++++++++---- docs/requirements-log.md | 38 ++++++++++++++++++ 3 files changed, 152 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7c3a8c1..72c74c9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,39 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra **Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally. +## Smart Volatility Scanner (Optional) + +Python-first filtering pipeline that reduces Gemini API calls by pre-filtering stocks using technical indicators. + +### How It Works + +1. **Fetch Rankings** — KIS API volume surge rankings (top 30 stocks) +2. **Python Filter** — RSI + volume ratio calculations (no AI) + - Volume > 200% of previous day + - RSI(14) < 30 (oversold) OR RSI(14) > 70 (momentum) +3. **AI Judgment** — Only qualified candidates (1-3 stocks) sent to Gemini + +### Configuration + +Add to `.env` (optional, has sensible defaults): +```bash +RSI_OVERSOLD_THRESHOLD=30 # 0-50, default 30 +RSI_MOMENTUM_THRESHOLD=70 # 50-100, default 70 +VOL_MULTIPLIER=2.0 # Volume threshold (2.0 = 200%) +SCANNER_TOP_N=3 # Max candidates per scan +``` + +### Benefits + +- **Reduces API costs** — Process 1-3 stocks instead of 20-30 +- **Python-based filtering** — Fast technical analysis before AI +- **Evolution-ready** — Selection context logged for strategy optimization +- **Fault-tolerant** — Falls back to static watchlist on API failure + +### Realtime Mode Only + +Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchlists for batch efficiency. + ## Documentation - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development @@ -75,6 +108,7 @@ User requirements and feedback are tracked in [docs/requirements-log.md](docs/re ``` src/ +├── analysis/ # Technical analysis (RSI, volatility, smart scanner) ├── broker/ # KIS API client (domestic + overseas) ├── brain/ # Gemini AI decision engine ├── core/ # Risk manager (READ-ONLY) @@ -85,7 +119,7 @@ src/ ├── main.py # Trading loop orchestrator └── config.py # Settings (from .env) -tests/ # 273 tests across 13 files +tests/ # 343 tests across 14 files docs/ # Extended documentation ``` diff --git a/docs/architecture.md b/docs/architecture.md index a8e23d4..e31ea9c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -64,7 +64,39 @@ High-frequency trading with individual stock analysis: - `get_open_markets()` returns currently active markets - `get_next_market_open()` finds next market to open and when -### 2. Brain (`src/brain/gemini_client.py`) +**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 + +### 2. Analysis (`src/analysis/`) + +**VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations + +- 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 @@ -74,7 +106,7 @@ High-frequency trading with individual stock analysis: - Falls back to safe HOLD on any parse/API error - Handles markdown-wrapped JSON, malformed responses, invalid actions -### 3. Risk Manager (`src/core/risk_manager.py`) +### 4. Risk Manager (`src/core/risk_manager.py`) **RiskManager** — Safety circuit breaker and order validation @@ -86,7 +118,7 @@ High-frequency trading with individual stock analysis: - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash - Must always be enforced, cannot be disabled -### 4. Notifications (`src/notifications/telegram_client.py`) +### 5. Notifications (`src/notifications/telegram_client.py`) **TelegramClient** — Real-time event notifications via Telegram Bot API @@ -105,7 +137,7 @@ High-frequency trading with individual stock analysis: **Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration. -### 5. Evolution (`src/evolution/optimizer.py`) +### 6. Evolution (`src/evolution/optimizer.py`) **StrategyOptimizer** — Self-improvement loop @@ -117,9 +149,11 @@ High-frequency trading with individual stock analysis: ## Data Flow +### Realtime Mode (with Smart Scanner) + ``` ┌─────────────────────────────────────────────────────────────┐ -│ Main Loop (60s cycle per stock, per market) │ +│ Main Loop (60s cycle per market) │ └─────────────────────────────────────────────────────────────┘ │ ▼ @@ -132,6 +166,21 @@ High-frequency trading with individual stock analysis: │ ▼ ┌──────────────────────────────────┐ + │ 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 │ @@ -145,7 +194,7 @@ High-frequency trading with individual stock analysis: │ ▼ ┌──────────────────────────────────┐ - │ Brain: Get Decision │ + │ Brain: Get Decision (AI) │ │ - Build prompt with market data │ │ - Call Gemini API │ │ - Parse JSON response │ @@ -181,6 +230,9 @@ High-frequency trading with individual stock analysis: │ - SQLite (data/trades.db) │ │ - Track: action, confidence, │ │ rationale, market, exchange │ + │ - NEW: selection_context (JSON) │ + │ - RSI, volume_ratio, signal │ + │ - For Evolution optimization │ └───────────────────────────────────┘ ``` @@ -200,11 +252,24 @@ CREATE TABLE trades ( 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. + exchange_code TEXT DEFAULT 'KRX', -- KRX | NASD | NYSE | etc. + selection_context TEXT -- JSON: {rsi, volume_ratio, signal, score} ); ``` -Auto-migration: Adds `market` and `exchange_code` columns if missing for backward compatibility. +**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 @@ -236,6 +301,12 @@ SESSION_INTERVAL_HOURS=6 # Hours between sessions (daily mode only) 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`. diff --git a/docs/requirements-log.md b/docs/requirements-log.md index 2fbcfd8..ccc1738 100644 --- a/docs/requirements-log.md +++ b/docs/requirements-log.md @@ -26,3 +26,41 @@ ### 문서화 - 시스템 구조, 기능별 설명 등 코드 문서화 항상 신경쓸 것 - 새로운 기능 추가 시 관련 문서 업데이트 필수 + +--- + +## 2026-02-06 + +### Smart Volatility Scanner (Python-First, AI-Last 파이프라인) + +**배경:** +- 정적 종목 리스트를 순회하는 방식은 비효율적 +- KIS API 거래량 순위를 통해 시장 주도주를 자동 탐지해야 함 +- Gemini API 호출 전에 Python 기반 기술적 분석으로 필터링 필요 + +**요구사항:** +1. KIS API 거래량 순위 API 통합 (`fetch_market_rankings`) +2. 일별 가격 히스토리 API 추가 (`get_daily_prices`) +3. RSI(14) 계산 기능 구현 (Wilder's smoothing method) +4. 필터 조건: + - 거래량 > 전일 대비 200% (VOL_MULTIPLIER) + - RSI < 30 (과매도) OR RSI > 70 (모멘텀) +5. 상위 1-3개 적격 종목만 Gemini에 전달 +6. 종목 선정 배경(RSI, volume_ratio, signal, score) 데이터베이스 기록 + +**구현 결과:** +- `src/analysis/smart_scanner.py`: SmartVolatilityScanner 클래스 +- `src/analysis/volatility.py`: calculate_rsi() 메서드 추가 +- `src/broker/kis_api.py`: 2개 신규 API 메서드 +- `src/db.py`: selection_context 컬럼 추가 +- 설정 가능한 임계값: RSI_OVERSOLD_THRESHOLD, RSI_MOMENTUM_THRESHOLD, VOL_MULTIPLIER, SCANNER_TOP_N + +**효과:** +- Gemini API 호출 20-30개 → 1-3개로 감소 +- Python 기반 빠른 필터링 → 비용 절감 +- 선정 기준 추적 → Evolution 시스템 최적화 가능 +- API 장애 시 정적 watchlist로 자동 전환 + +**참고:** Realtime 모드 전용. Daily 모드는 배치 효율성을 위해 정적 watchlist 사용. + +**이슈/PR:** #76, #77