docs: update documentation for Smart Volatility Scanner
Some checks failed
CI / test (pull_request) Has been cancelled
Some checks failed
CI / test (pull_request) Has been cancelled
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 <noreply@anthropic.com>
This commit is contained in:
agentson
36
CLAUDE.md
36
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
|
||||
```
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user