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
 ```
 

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`.

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