Merge pull request 'fix: add token refresh lock to prevent concurrent API calls (issue #42)' (#46) from feature/issue-42-token-refresh-lock into main

Reviewed-on: #46

.env.example

@@ -21,3 +21,15 @@ RATE_LIMIT_RPS=10.0
 
 # Trading Mode (paper / live)
 MODE=paper
+
+# External Data APIs (optional — for enhanced decision-making)
+# NEWS_API_KEY=your_news_api_key_here
+# NEWS_API_PROVIDER=alphavantage
+# MARKET_DATA_API_KEY=your_market_data_key_here
+
+# Telegram Notifications (optional)
+# Get bot token from @BotFather on Telegram
+# Get chat ID from @userinfobot or your chat
+# TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+# TELEGRAM_CHAT_ID=123456789
+# TELEGRAM_ENABLED=true

.gitignore

@@ -174,4 +174,7 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+# Data files (trade logs, databases)
+# But NOT src/data/ which contains source code
 data/
+!src/data/

CLAUDE.md

@@ -17,6 +17,34 @@ pytest -v --cov=src
 python -m src.main --mode=paper
 ```
 
+## Telegram Notifications (Optional)
+
+Get real-time alerts for trades, circuit breakers, and system events via Telegram.
+
+### Quick Setup
+
+1. **Create bot**: Message [@BotFather](https://t.me/BotFather) on Telegram → `/newbot`
+2. **Get chat ID**: Message [@userinfobot](https://t.me/userinfobot) → `/start`
+3. **Configure**: Add to `.env`:
+   ```bash
+   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+   TELEGRAM_CHAT_ID=123456789
+   TELEGRAM_ENABLED=true
+   ```
+4. **Test**: Start bot conversation (`/start`), then run the agent
+
+**Full documentation**: [src/notifications/README.md](src/notifications/README.md)
+
+### What You'll Get
+
+- 🟢 Trade execution alerts (BUY/SELL with confidence)
+- 🚨 Circuit breaker trips (automatic trading halt)
+- ⚠️ Fat-finger rejections (oversized orders blocked)
+- ℹ️ Market open/close notifications
+- 📝 System startup/shutdown status
+
+**Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.
+
 ## Documentation
 
 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
@@ -42,11 +70,12 @@ src/
 ├── core/            # Risk manager (READ-ONLY)
 ├── evolution/       # Self-improvement optimizer
 ├── markets/         # Market schedules and timezone handling
+├── notifications/   # Telegram real-time alerts
 ├── db.py            # SQLite trade logging
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)
 
-tests/               # 54 tests across 4 files
+tests/               # 273 tests across 13 files
 docs/                # Extended documentation
 ```
 

README.md

@@ -29,6 +29,7 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 | 브로커 | `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 거래 로그 기록 |
 
@@ -75,6 +76,34 @@ python -m src.main --mode=paper
 docker compose up -d ouroboros
 ```
 
+## 텔레그램 알림 (선택사항)
+
+거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
+
+### 빠른 설정
+
+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` 전송) 후 에이전트 실행
+
+**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
+
+### 알림 종류
+
+- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
+- 🚨 서킷 브레이커 발동 (자동 거래 중단)
+- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
+- ℹ️ 장 시작/종료 알림
+- 📝 시스템 시작/종료 상태
+
+**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+
 ## 테스트
 
 35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
@@ -104,15 +133,16 @@ The-Ouroboros/
 │   ├── agents.md                # AI 에이전트 페르소나 정의
 │   └── skills.md                # 사용 가능한 도구 목록
 ├── src/
-│   ├── config.py                # Pydantic 설정
+│   ├── config.py                      # Pydantic 설정
-│   ├── logging_config.py        # JSON 구조화 로깅
+│   ├── logging_config.py              # JSON 구조화 로깅
-│   ├── db.py                    # SQLite 거래 기록
+│   ├── db.py                          # SQLite 거래 기록
-│   ├── main.py                  # 비동기 거래 루프
+│   ├── main.py                        # 비동기 거래 루프
-│   ├── broker/kis_api.py        # KIS API 클라이언트
+│   ├── broker/kis_api.py              # KIS API 클라이언트
-│   ├── brain/gemini_client.py   # Gemini 의사결정 엔진
+│   ├── brain/gemini_client.py         # Gemini 의사결정 엔진
-│   ├── core/risk_manager.py     # 리스크 관리
+│   ├── core/risk_manager.py           # 리스크 관리
-│   ├── evolution/optimizer.py   # 전략 진화 엔진
+│   ├── notifications/telegram_client.py # 텔레그램 알림
-│   └── strategies/base.py       # 전략 베이스 클래스
+│   ├── evolution/optimizer.py         # 전략 진화 엔진
+│   └── strategies/base.py             # 전략 베이스 클래스
 ├── tests/                       # TDD 테스트 스위트
 ├── Dockerfile                   # 멀티스테이지 빌드
 ├── docker-compose.yml           # 서비스 오케스트레이션

docs/architecture.md

@@ -51,7 +51,26 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
   - Must always be enforced, cannot be disabled
 
-### 4. Evolution (`src/evolution/optimizer.py`)
+### 4. 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.
+
+### 5. Evolution (`src/evolution/optimizer.py`)
 
 **StrategyOptimizer** — Self-improvement loop
 
@@ -115,6 +134,14 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
                            │
                            ▼
         ┌──────────────────────────────────┐
+        │ 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,      │
@@ -164,6 +191,11 @@ CONFIDENCE_THRESHOLD=80
 MAX_LOSS_PCT=3.0
 MAX_ORDER_PCT=30.0
 ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
+
+# Telegram Notifications (optional)
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=123456789
+TELEGRAM_ENABLED=true
 ```
 
 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.
@@ -189,3 +221,12 @@ Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tes
 - 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.

docs/disaster_recovery.md

@@ -0,0 +1,348 @@
+# Disaster Recovery Guide
+
+Complete guide for backing up and restoring The Ouroboros trading system.
+
+## Table of Contents
+
+- [Backup Strategy](#backup-strategy)
+- [Creating Backups](#creating-backups)
+- [Restoring from Backup](#restoring-from-backup)
+- [Health Monitoring](#health-monitoring)
+- [Export Formats](#export-formats)
+- [RTO/RPO](#rtorpo)
+- [Testing Recovery](#testing-recovery)
+
+## Backup Strategy
+
+The system implements a 3-tier backup retention policy:
+
+| Policy | Frequency | Retention | Purpose |
+|--------|-----------|-----------|---------|
+| **Daily** | Every day | 30 days | Quick recovery from recent issues |
+| **Weekly** | Sunday | 1 year | Medium-term historical analysis |
+| **Monthly** | 1st of month | Forever | Long-term archival |
+
+### Storage Structure
+
+```
+data/backups/
+├── daily/          # Last 30 days
+├── weekly/         # Last 52 weeks
+└── monthly/        # Forever (cold storage)
+```
+
+## Creating Backups
+
+### Automated Backups (Recommended)
+
+Set up a cron job to run daily:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Run backup at 2 AM every day
+0 2 * * * cd /path/to/The-Ouroboros && ./scripts/backup.sh >> logs/backup.log 2>&1
+```
+
+### Manual Backups
+
+```bash
+# Run backup script
+./scripts/backup.sh
+
+# Or use Python directly
+python3 -c "
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler, BackupPolicy
+
+scheduler = BackupScheduler('data/trade_logs.db', Path('data/backups'))
+metadata = scheduler.create_backup(BackupPolicy.DAILY, verify=True)
+print(f'Backup created: {metadata.file_path}')
+"
+```
+
+### Export to Other Formats
+
+```bash
+python3 -c "
+from pathlib import Path
+from src.backup.exporter import BackupExporter, ExportFormat
+
+exporter = BackupExporter('data/trade_logs.db')
+results = exporter.export_all(
+    Path('exports'),
+    formats=[ExportFormat.JSON, ExportFormat.CSV],
+    compress=True
+)
+"
+```
+
+## Restoring from Backup
+
+### Interactive Restoration
+
+```bash
+./scripts/restore.sh
+```
+
+The script will:
+1. List available backups
+2. Ask you to select one
+3. Create a safety backup of current database
+4. Restore the selected backup
+5. Verify database integrity
+
+### Manual Restoration
+
+```python
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler
+
+scheduler = BackupScheduler('data/trade_logs.db', Path('data/backups'))
+
+# List backups
+backups = scheduler.list_backups()
+for backup in backups:
+    print(f"{backup.timestamp}: {backup.file_path}")
+
+# Restore specific backup
+scheduler.restore_backup(backups[0], verify=True)
+```
+
+## Health Monitoring
+
+### Check System Health
+
+```python
+from pathlib import Path
+from src.backup.health_monitor import HealthMonitor
+
+monitor = HealthMonitor('data/trade_logs.db', Path('data/backups'))
+
+# Run all checks
+report = monitor.get_health_report()
+print(f"Overall status: {report['overall_status']}")
+
+# Individual checks
+checks = monitor.run_all_checks()
+for name, result in checks.items():
+    print(f"{name}: {result.status.value} - {result.message}")
+```
+
+### Health Checks
+
+The system monitors:
+
+- **Database Health**: Accessibility, integrity, size
+- **Disk Space**: Available storage (alerts if < 10 GB)
+- **Backup Recency**: Ensures backups are < 25 hours old
+
+### Health Status Levels
+
+- **HEALTHY**: All systems operational
+- **DEGRADED**: Warning condition (e.g., low disk space)
+- **UNHEALTHY**: Critical issue (e.g., database corrupted, no backups)
+
+## Export Formats
+
+### JSON (Human-Readable)
+
+```json
+{
+  "export_timestamp": "2024-01-15T10:30:00Z",
+  "record_count": 150,
+  "trades": [
+    {
+      "timestamp": "2024-01-15T09:00:00Z",
+      "stock_code": "005930",
+      "action": "BUY",
+      "quantity": 10,
+      "price": 70000.0,
+      "confidence": 85,
+      "rationale": "Strong momentum",
+      "pnl": 0.0
+    }
+  ]
+}
+```
+
+### CSV (Analysis Tools)
+
+Compatible with Excel, pandas, R:
+
+```csv
+timestamp,stock_code,action,quantity,price,confidence,rationale,pnl
+2024-01-15T09:00:00Z,005930,BUY,10,70000.0,85,Strong momentum,0.0
+```
+
+### Parquet (Big Data)
+
+Columnar format for Spark, DuckDB:
+
+```python
+import pandas as pd
+df = pd.read_parquet('exports/trades_20240115.parquet')
+```
+
+## RTO/RPO
+
+### Recovery Time Objective (RTO)
+
+**Target: < 5 minutes**
+
+Time to restore trading operations:
+1. Identify backup to restore (1 min)
+2. Run restore script (2 min)
+3. Verify database integrity (1 min)
+4. Restart trading system (1 min)
+
+### Recovery Point Objective (RPO)
+
+**Target: < 24 hours**
+
+Maximum acceptable data loss:
+- Daily backups ensure ≤ 24-hour data loss
+- For critical periods, run backups more frequently
+
+## Testing Recovery
+
+### Quarterly Recovery Test
+
+Perform full disaster recovery test every quarter:
+
+1. **Create test backup**
+   ```bash
+   ./scripts/backup.sh
+   ```
+
+2. **Simulate disaster** (use test database)
+   ```bash
+   cp data/trade_logs.db data/trade_logs_test.db
+   rm data/trade_logs_test.db  # Simulate data loss
+   ```
+
+3. **Restore from backup**
+   ```bash
+   DB_PATH=data/trade_logs_test.db ./scripts/restore.sh
+   ```
+
+4. **Verify data integrity**
+   ```python
+   import sqlite3
+   conn = sqlite3.connect('data/trade_logs_test.db')
+   cursor = conn.execute('SELECT COUNT(*) FROM trades')
+   print(f"Restored {cursor.fetchone()[0]} trades")
+   ```
+
+5. **Document results** in `logs/recovery_test_YYYYMMDD.md`
+
+### Backup Verification
+
+Always verify backups after creation:
+
+```python
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler
+
+scheduler = BackupScheduler('data/trade_logs.db', Path('data/backups'))
+
+# Create and verify
+metadata = scheduler.create_backup(BackupPolicy.DAILY, verify=True)
+print(f"Checksum: {metadata.checksum}")  # Should not be None
+```
+
+## Emergency Procedures
+
+### Database Corrupted
+
+1. Stop trading system immediately
+2. Check most recent backup age: `ls -lht data/backups/daily/`
+3. Restore: `./scripts/restore.sh`
+4. Verify: Run health check
+5. Resume trading
+
+### Disk Full
+
+1. Check disk space: `df -h`
+2. Clean old backups: Run cleanup manually
+   ```python
+   from pathlib import Path
+   from src.backup.scheduler import BackupScheduler
+   scheduler = BackupScheduler('data/trade_logs.db', Path('data/backups'))
+   scheduler.cleanup_old_backups()
+   ```
+3. Consider archiving old monthly backups to external storage
+4. Increase disk space if needed
+
+### Lost All Backups
+
+If local backups are lost:
+1. Check if exports exist in `exports/` directory
+2. Reconstruct database from CSV/JSON exports
+3. If no exports: Check broker API for trade history
+4. Manual reconstruction as last resort
+
+## Best Practices
+
+1. **Test Restores Regularly**: Don't wait for disaster
+2. **Monitor Disk Space**: Set up alerts at 80% usage
+3. **Keep Multiple Generations**: Never delete all backups at once
+4. **Verify Checksums**: Always verify backup integrity
+5. **Document Changes**: Update this guide when backup strategy changes
+6. **Off-Site Storage**: Consider external backup for monthly archives
+
+## Troubleshooting
+
+### Backup Script Fails
+
+```bash
+# Check database file permissions
+ls -l data/trade_logs.db
+
+# Check disk space
+df -h data/
+
+# Run backup manually with debug
+python3 -c "
+import logging
+logging.basicConfig(level=logging.DEBUG)
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler, BackupPolicy
+scheduler = BackupScheduler('data/trade_logs.db', Path('data/backups'))
+scheduler.create_backup(BackupPolicy.DAILY, verify=True)
+"
+```
+
+### Restore Fails Verification
+
+```bash
+# Check backup file integrity
+python3 -c "
+import sqlite3
+conn = sqlite3.connect('data/backups/daily/trade_logs_daily_20240115.db')
+cursor = conn.execute('PRAGMA integrity_check')
+print(cursor.fetchone()[0])
+"
+```
+
+### Health Check Fails
+
+```python
+from pathlib import Path
+from src.backup.health_monitor import HealthMonitor
+
+monitor = HealthMonitor('data/trade_logs.db', Path('data/backups'))
+
+# Check each component individually
+print("Database:", monitor.check_database_health())
+print("Disk Space:", monitor.check_disk_space())
+print("Backup Recency:", monitor.check_backup_recency())
+```
+
+## Contact
+
+For backup/recovery issues:
+- Check logs: `logs/backup.log`
+- Review health status: Run health monitor
+- Raise issue on GitHub if automated recovery fails

pyproject.toml

@@ -8,6 +8,7 @@ dependencies = [
     "pydantic>=2.5,<3",
     "pydantic-settings>=2.1,<3",
     "google-genai>=1.0,<2",
+    "scipy>=1.11,<2",
 ]
 
 [project.optional-dependencies]

scripts/backup.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Automated backup script for The Ouroboros trading system
+# Runs daily/weekly/monthly backups
+
+set -euo pipefail
+
+# Configuration
+DB_PATH="${DB_PATH:-data/trade_logs.db}"
+BACKUP_DIR="${BACKUP_DIR:-data/backups}"
+PYTHON="${PYTHON:-python3}"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if database exists
+if [ ! -f "$DB_PATH" ]; then
+    log_error "Database not found: $DB_PATH"
+    exit 1
+fi
+
+# Create backup directory
+mkdir -p "$BACKUP_DIR"
+
+log_info "Starting backup process..."
+log_info "Database: $DB_PATH"
+log_info "Backup directory: $BACKUP_DIR"
+
+# Determine backup policy based on day of week and month
+DAY_OF_WEEK=$(date +%u)  # 1-7 (Monday-Sunday)
+DAY_OF_MONTH=$(date +%d)
+
+if [ "$DAY_OF_MONTH" == "01" ]; then
+    POLICY="monthly"
+    log_info "Running MONTHLY backup (first day of month)"
+elif [ "$DAY_OF_WEEK" == "7" ]; then
+    POLICY="weekly"
+    log_info "Running WEEKLY backup (Sunday)"
+else
+    POLICY="daily"
+    log_info "Running DAILY backup"
+fi
+
+# Run Python backup script
+$PYTHON -c "
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler, BackupPolicy
+from src.backup.health_monitor import HealthMonitor
+
+# Create scheduler
+scheduler = BackupScheduler(
+    db_path='$DB_PATH',
+    backup_dir=Path('$BACKUP_DIR')
+)
+
+# Create backup
+policy = BackupPolicy.$POLICY.upper()
+metadata = scheduler.create_backup(policy, verify=True)
+print(f'Backup created: {metadata.file_path}')
+print(f'Size: {metadata.size_bytes / 1024 / 1024:.2f} MB')
+print(f'Checksum: {metadata.checksum}')
+
+# Cleanup old backups
+removed = scheduler.cleanup_old_backups()
+total_removed = sum(removed.values())
+if total_removed > 0:
+    print(f'Removed {total_removed} old backup(s)')
+
+# Health check
+monitor = HealthMonitor('$DB_PATH', Path('$BACKUP_DIR'))
+status = monitor.get_overall_status()
+print(f'System health: {status.value}')
+"
+
+if [ $? -eq 0 ]; then
+    log_info "Backup completed successfully"
+else
+    log_error "Backup failed"
+    exit 1
+fi
+
+log_info "Backup process finished"

scripts/restore.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Restore script for The Ouroboros trading system
+# Restores database from a backup file
+
+set -euo pipefail
+
+# Configuration
+DB_PATH="${DB_PATH:-data/trade_logs.db}"
+BACKUP_DIR="${BACKUP_DIR:-data/backups}"
+PYTHON="${PYTHON:-python3}"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if backup directory exists
+if [ ! -d "$BACKUP_DIR" ]; then
+    log_error "Backup directory not found: $BACKUP_DIR"
+    exit 1
+fi
+
+log_info "Available backups:"
+log_info "=================="
+
+# List available backups
+$PYTHON -c "
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler
+
+scheduler = BackupScheduler(
+    db_path='$DB_PATH',
+    backup_dir=Path('$BACKUP_DIR')
+)
+
+backups = scheduler.list_backups()
+
+if not backups:
+    print('No backups found.')
+    exit(1)
+
+for i, backup in enumerate(backups, 1):
+    size_mb = backup.size_bytes / 1024 / 1024
+    print(f'{i}. [{backup.policy.value.upper()}] {backup.file_path.name}')
+    print(f'   Date: {backup.timestamp.strftime(\"%Y-%m-%d %H:%M:%S UTC\")}')
+    print(f'   Size: {size_mb:.2f} MB')
+    print()
+"
+
+# Ask user to select backup
+echo ""
+read -p "Enter backup number to restore (or 'q' to quit): " BACKUP_NUM
+
+if [ "$BACKUP_NUM" == "q" ]; then
+    log_info "Restore cancelled"
+    exit 0
+fi
+
+# Confirm restoration
+log_warn "WARNING: This will replace the current database!"
+log_warn "Current database will be backed up to: ${DB_PATH}.before_restore"
+read -p "Are you sure you want to continue? (yes/no): " CONFIRM
+
+if [ "$CONFIRM" != "yes" ]; then
+    log_info "Restore cancelled"
+    exit 0
+fi
+
+# Perform restoration
+$PYTHON -c "
+from pathlib import Path
+from src.backup.scheduler import BackupScheduler
+
+scheduler = BackupScheduler(
+    db_path='$DB_PATH',
+    backup_dir=Path('$BACKUP_DIR')
+)
+
+backups = scheduler.list_backups()
+backup_index = int('$BACKUP_NUM') - 1
+
+if backup_index < 0 or backup_index >= len(backups):
+    print('Invalid backup number')
+    exit(1)
+
+selected = backups[backup_index]
+print(f'Restoring: {selected.file_path.name}')
+
+scheduler.restore_backup(selected, verify=True)
+print('Restore completed successfully')
+"
+
+if [ $? -eq 0 ]; then
+    log_info "Database restored successfully"
+else
+    log_error "Restore failed"
+    exit 1
+fi

src/backup/__init__.py

@@ -0,0 +1,21 @@
+"""Backup and disaster recovery system for long-term sustainability.
+
+This module provides:
+- Automated database backups (daily, weekly, monthly)
+- Multi-format exports (JSON, CSV, Parquet)
+- Cloud storage integration (S3-compatible)
+- Health monitoring and alerts
+"""
+
+from src.backup.exporter import BackupExporter, ExportFormat
+from src.backup.scheduler import BackupScheduler, BackupPolicy
+from src.backup.cloud_storage import CloudStorage, S3Config
+
+__all__ = [
+    "BackupExporter",
+    "ExportFormat",
+    "BackupScheduler",
+    "BackupPolicy",
+    "CloudStorage",
+    "S3Config",
+]

src/backup/cloud_storage.py

@@ -0,0 +1,274 @@
+"""Cloud storage integration for off-site backups.
+
+Supports S3-compatible storage providers:
+- AWS S3
+- MinIO
+- Backblaze B2
+- DigitalOcean Spaces
+- Cloudflare R2
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class S3Config:
+    """Configuration for S3-compatible storage."""
+
+    endpoint_url: str | None  # None for AWS S3, custom URL for others
+    access_key: str
+    secret_key: str
+    bucket_name: str
+    region: str = "us-east-1"
+    use_ssl: bool = True
+
+
+class CloudStorage:
+    """Upload backups to S3-compatible cloud storage."""
+
+    def __init__(self, config: S3Config) -> None:
+        """Initialize cloud storage client.
+
+        Args:
+            config: S3 configuration
+
+        Raises:
+            ImportError: If boto3 is not installed
+        """
+        try:
+            import boto3
+        except ImportError:
+            raise ImportError(
+                "boto3 is required for cloud storage. Install with: pip install boto3"
+            )
+
+        self.config = config
+        self.client = boto3.client(
+            "s3",
+            endpoint_url=config.endpoint_url,
+            aws_access_key_id=config.access_key,
+            aws_secret_access_key=config.secret_key,
+            region_name=config.region,
+            use_ssl=config.use_ssl,
+        )
+
+    def upload_file(
+        self,
+        file_path: Path,
+        object_key: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> str:
+        """Upload a file to cloud storage.
+
+        Args:
+            file_path: Local file to upload
+            object_key: S3 object key (default: filename)
+            metadata: Optional metadata to attach
+
+        Returns:
+            S3 object key
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            Exception: If upload fails
+        """
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if object_key is None:
+            object_key = file_path.name
+
+        extra_args: dict[str, Any] = {}
+
+        # Add server-side encryption
+        extra_args["ServerSideEncryption"] = "AES256"
+
+        # Add metadata if provided
+        if metadata:
+            extra_args["Metadata"] = metadata
+
+        logger.info("Uploading %s to s3://%s/%s", file_path.name, self.config.bucket_name, object_key)
+
+        try:
+            self.client.upload_file(
+                str(file_path),
+                self.config.bucket_name,
+                object_key,
+                ExtraArgs=extra_args,
+            )
+            logger.info("Upload successful: %s", object_key)
+            return object_key
+        except Exception as exc:
+            logger.error("Upload failed: %s", exc)
+            raise
+
+    def download_file(self, object_key: str, local_path: Path) -> Path:
+        """Download a file from cloud storage.
+
+        Args:
+            object_key: S3 object key
+            local_path: Local destination path
+
+        Returns:
+            Path to downloaded file
+
+        Raises:
+            Exception: If download fails
+        """
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+
+        logger.info("Downloading s3://%s/%s to %s", self.config.bucket_name, object_key, local_path)
+
+        try:
+            self.client.download_file(
+                self.config.bucket_name,
+                object_key,
+                str(local_path),
+            )
+            logger.info("Download successful: %s", local_path)
+            return local_path
+        except Exception as exc:
+            logger.error("Download failed: %s", exc)
+            raise
+
+    def list_files(self, prefix: str = "") -> list[dict[str, Any]]:
+        """List files in cloud storage.
+
+        Args:
+            prefix: Filter by object key prefix
+
+        Returns:
+            List of file metadata dictionaries
+        """
+        try:
+            response = self.client.list_objects_v2(
+                Bucket=self.config.bucket_name,
+                Prefix=prefix,
+            )
+
+            if "Contents" not in response:
+                return []
+
+            files = []
+            for obj in response["Contents"]:
+                files.append(
+                    {
+                        "key": obj["Key"],
+                        "size_bytes": obj["Size"],
+                        "last_modified": obj["LastModified"],
+                        "etag": obj["ETag"],
+                    }
+                )
+
+            return files
+        except Exception as exc:
+            logger.error("Failed to list files: %s", exc)
+            raise
+
+    def delete_file(self, object_key: str) -> None:
+        """Delete a file from cloud storage.
+
+        Args:
+            object_key: S3 object key
+
+        Raises:
+            Exception: If deletion fails
+        """
+        logger.info("Deleting s3://%s/%s", self.config.bucket_name, object_key)
+
+        try:
+            self.client.delete_object(
+                Bucket=self.config.bucket_name,
+                Key=object_key,
+            )
+            logger.info("Deletion successful: %s", object_key)
+        except Exception as exc:
+            logger.error("Deletion failed: %s", exc)
+            raise
+
+    def get_storage_stats(self) -> dict[str, Any]:
+        """Get cloud storage statistics.
+
+        Returns:
+            Dictionary with storage stats
+        """
+        try:
+            files = self.list_files()
+
+            total_size = sum(f["size_bytes"] for f in files)
+            total_count = len(files)
+
+            return {
+                "total_files": total_count,
+                "total_size_bytes": total_size,
+                "total_size_mb": total_size / 1024 / 1024,
+                "total_size_gb": total_size / 1024 / 1024 / 1024,
+            }
+        except Exception as exc:
+            logger.error("Failed to get storage stats: %s", exc)
+            return {
+                "error": str(exc),
+                "total_files": 0,
+                "total_size_bytes": 0,
+            }
+
+    def verify_connection(self) -> bool:
+        """Verify connection to cloud storage.
+
+        Returns:
+            True if connection is successful
+        """
+        try:
+            self.client.head_bucket(Bucket=self.config.bucket_name)
+            logger.info("Cloud storage connection verified")
+            return True
+        except Exception as exc:
+            logger.error("Cloud storage connection failed: %s", exc)
+            return False
+
+    def create_bucket_if_not_exists(self) -> None:
+        """Create storage bucket if it doesn't exist.
+
+        Raises:
+            Exception: If bucket creation fails
+        """
+        try:
+            self.client.head_bucket(Bucket=self.config.bucket_name)
+            logger.info("Bucket already exists: %s", self.config.bucket_name)
+        except self.client.exceptions.NoSuchBucket:
+            logger.info("Creating bucket: %s", self.config.bucket_name)
+            if self.config.region == "us-east-1":
+                # us-east-1 requires special handling
+                self.client.create_bucket(Bucket=self.config.bucket_name)
+            else:
+                self.client.create_bucket(
+                    Bucket=self.config.bucket_name,
+                    CreateBucketConfiguration={"LocationConstraint": self.config.region},
+                )
+            logger.info("Bucket created successfully")
+        except Exception as exc:
+            logger.error("Failed to verify/create bucket: %s", exc)
+            raise
+
+    def enable_versioning(self) -> None:
+        """Enable versioning on the bucket.
+
+        Raises:
+            Exception: If versioning enablement fails
+        """
+        try:
+            self.client.put_bucket_versioning(
+                Bucket=self.config.bucket_name,
+                VersioningConfiguration={"Status": "Enabled"},
+            )
+            logger.info("Versioning enabled for bucket: %s", self.config.bucket_name)
+        except Exception as exc:
+            logger.error("Failed to enable versioning: %s", exc)
+            raise

src/backup/exporter.py

@@ -0,0 +1,326 @@
+"""Multi-format database exporter for backups.
+
+Supports JSON, CSV, and Parquet formats for different use cases:
+- JSON: Human-readable, easy to inspect
+- CSV: Analysis tools (Excel, pandas)
+- Parquet: Big data tools (Spark, DuckDB)
+"""
+
+from __future__ import annotations
+
+import csv
+import gzip
+import json
+import logging
+import sqlite3
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ExportFormat(str, Enum):
+    """Supported export formats."""
+
+    JSON = "json"
+    CSV = "csv"
+    PARQUET = "parquet"
+
+
+class BackupExporter:
+    """Export database to multiple formats."""
+
+    def __init__(self, db_path: str) -> None:
+        """Initialize the exporter.
+
+        Args:
+            db_path: Path to SQLite database
+        """
+        self.db_path = db_path
+
+    def export_all(
+        self,
+        output_dir: Path,
+        formats: list[ExportFormat] | None = None,
+        compress: bool = True,
+        incremental_since: datetime | None = None,
+    ) -> dict[ExportFormat, Path]:
+        """Export database to multiple formats.
+
+        Args:
+            output_dir: Directory to write export files
+            formats: List of formats to export (default: all)
+            compress: Whether to gzip compress exports
+            incremental_since: Only export records after this timestamp
+
+        Returns:
+            Dictionary mapping format to output file path
+        """
+        if formats is None:
+            formats = [ExportFormat.JSON, ExportFormat.CSV, ExportFormat.PARQUET]
+
+        output_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+
+        results: dict[ExportFormat, Path] = {}
+
+        for fmt in formats:
+            try:
+                output_file = self._export_format(
+                    fmt, output_dir, timestamp, compress, incremental_since
+                )
+                results[fmt] = output_file
+                logger.info("Exported to %s: %s", fmt.value, output_file)
+            except Exception as exc:
+                logger.error("Failed to export to %s: %s", fmt.value, exc)
+
+        return results
+
+    def _export_format(
+        self,
+        fmt: ExportFormat,
+        output_dir: Path,
+        timestamp: str,
+        compress: bool,
+        incremental_since: datetime | None,
+    ) -> Path:
+        """Export to a specific format.
+
+        Args:
+            fmt: Export format
+            output_dir: Output directory
+            timestamp: Timestamp string for filename
+            compress: Whether to compress
+            incremental_since: Incremental export cutoff
+
+        Returns:
+            Path to output file
+        """
+        if fmt == ExportFormat.JSON:
+            return self._export_json(output_dir, timestamp, compress, incremental_since)
+        elif fmt == ExportFormat.CSV:
+            return self._export_csv(output_dir, timestamp, compress, incremental_since)
+        elif fmt == ExportFormat.PARQUET:
+            return self._export_parquet(
+                output_dir, timestamp, compress, incremental_since
+            )
+        else:
+            raise ValueError(f"Unsupported format: {fmt}")
+
+    def _get_trades(
+        self, incremental_since: datetime | None = None
+    ) -> list[dict[str, Any]]:
+        """Fetch trades from database.
+
+        Args:
+            incremental_since: Only fetch trades after this timestamp
+
+        Returns:
+            List of trade records
+        """
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+
+        if incremental_since:
+            cursor = conn.execute(
+                "SELECT * FROM trades WHERE timestamp > ?",
+                (incremental_since.isoformat(),),
+            )
+        else:
+            cursor = conn.execute("SELECT * FROM trades")
+
+        trades = [dict(row) for row in cursor.fetchall()]
+        conn.close()
+
+        return trades
+
+    def _export_json(
+        self,
+        output_dir: Path,
+        timestamp: str,
+        compress: bool,
+        incremental_since: datetime | None,
+    ) -> Path:
+        """Export to JSON format.
+
+        Args:
+            output_dir: Output directory
+            timestamp: Timestamp for filename
+            compress: Whether to gzip
+            incremental_since: Incremental cutoff
+
+        Returns:
+            Path to output file
+        """
+        trades = self._get_trades(incremental_since)
+
+        filename = f"trades_{timestamp}.json"
+        if compress:
+            filename += ".gz"
+
+        output_file = output_dir / filename
+
+        data = {
+            "export_timestamp": datetime.now(UTC).isoformat(),
+            "incremental_since": (
+                incremental_since.isoformat() if incremental_since else None
+            ),
+            "record_count": len(trades),
+            "trades": trades,
+        }
+
+        if compress:
+            with gzip.open(output_file, "wt", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+        else:
+            with open(output_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+
+        return output_file
+
+    def _export_csv(
+        self,
+        output_dir: Path,
+        timestamp: str,
+        compress: bool,
+        incremental_since: datetime | None,
+    ) -> Path:
+        """Export to CSV format.
+
+        Args:
+            output_dir: Output directory
+            timestamp: Timestamp for filename
+            compress: Whether to gzip
+            incremental_since: Incremental cutoff
+
+        Returns:
+            Path to output file
+        """
+        trades = self._get_trades(incremental_since)
+
+        filename = f"trades_{timestamp}.csv"
+        if compress:
+            filename += ".gz"
+
+        output_file = output_dir / filename
+
+        if not trades:
+            # Write empty CSV with headers
+            if compress:
+                with gzip.open(output_file, "wt", encoding="utf-8", newline="") as f:
+                    writer = csv.writer(f)
+                    writer.writerow(
+                        [
+                            "timestamp",
+                            "stock_code",
+                            "action",
+                            "quantity",
+                            "price",
+                            "confidence",
+                            "rationale",
+                            "pnl",
+                        ]
+                    )
+            else:
+                with open(output_file, "w", encoding="utf-8", newline="") as f:
+                    writer = csv.writer(f)
+                    writer.writerow(
+                        [
+                            "timestamp",
+                            "stock_code",
+                            "action",
+                            "quantity",
+                            "price",
+                            "confidence",
+                            "rationale",
+                            "pnl",
+                        ]
+                    )
+            return output_file
+
+        # Get column names from first trade
+        fieldnames = list(trades[0].keys())
+
+        if compress:
+            with gzip.open(output_file, "wt", encoding="utf-8", newline="") as f:
+                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                writer.writeheader()
+                writer.writerows(trades)
+        else:
+            with open(output_file, "w", encoding="utf-8", newline="") as f:
+                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                writer.writeheader()
+                writer.writerows(trades)
+
+        return output_file
+
+    def _export_parquet(
+        self,
+        output_dir: Path,
+        timestamp: str,
+        compress: bool,
+        incremental_since: datetime | None,
+    ) -> Path:
+        """Export to Parquet format.
+
+        Args:
+            output_dir: Output directory
+            timestamp: Timestamp for filename
+            compress: Whether to compress (Parquet has built-in compression)
+            incremental_since: Incremental cutoff
+
+        Returns:
+            Path to output file
+        """
+        trades = self._get_trades(incremental_since)
+
+        filename = f"trades_{timestamp}.parquet"
+        output_file = output_dir / filename
+
+        try:
+            import pyarrow as pa
+            import pyarrow.parquet as pq
+        except ImportError:
+            raise ImportError(
+                "pyarrow is required for Parquet export. "
+                "Install with: pip install pyarrow"
+            )
+
+        # Convert to pyarrow table
+        table = pa.Table.from_pylist(trades)
+
+        # Write with compression
+        compression = "gzip" if compress else "none"
+        pq.write_table(table, output_file, compression=compression)
+
+        return output_file
+
+    def get_export_stats(self) -> dict[str, Any]:
+        """Get statistics about exportable data.
+
+        Returns:
+            Dictionary with data statistics
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        stats = {}
+
+        # Total trades
+        cursor.execute("SELECT COUNT(*) FROM trades")
+        stats["total_trades"] = cursor.fetchone()[0]
+
+        # Date range
+        cursor.execute("SELECT MIN(timestamp), MAX(timestamp) FROM trades")
+        min_date, max_date = cursor.fetchone()
+        stats["date_range"] = {"earliest": min_date, "latest": max_date}
+
+        # Database size
+        cursor.execute("SELECT page_count * page_size FROM pragma_page_count(), pragma_page_size()")
+        stats["db_size_bytes"] = cursor.fetchone()[0]
+
+        conn.close()
+
+        return stats

src/backup/health_monitor.py

@@ -0,0 +1,282 @@
+"""Health monitoring for backup system.
+
+Checks:
+- Database accessibility and integrity
+- Disk space availability
+- Backup success/failure tracking
+- Self-healing capabilities
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class HealthStatus(str, Enum):
+    """Health check status."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a health check."""
+
+    status: HealthStatus
+    message: str
+    details: dict[str, Any] | None = None
+    timestamp: datetime | None = None
+
+    def __post_init__(self) -> None:
+        if self.timestamp is None:
+            self.timestamp = datetime.now(UTC)
+
+
+class HealthMonitor:
+    """Monitor system health and backup status."""
+
+    def __init__(
+        self,
+        db_path: str,
+        backup_dir: Path,
+        min_disk_space_gb: float = 10.0,
+        max_backup_age_hours: int = 25,  # Daily backups should be < 25 hours old
+    ) -> None:
+        """Initialize health monitor.
+
+        Args:
+            db_path: Path to SQLite database
+            backup_dir: Backup directory
+            min_disk_space_gb: Minimum required disk space in GB
+            max_backup_age_hours: Maximum acceptable backup age in hours
+        """
+        self.db_path = Path(db_path)
+        self.backup_dir = backup_dir
+        self.min_disk_space_bytes = int(min_disk_space_gb * 1024 * 1024 * 1024)
+        self.max_backup_age = timedelta(hours=max_backup_age_hours)
+
+    def check_database_health(self) -> HealthCheckResult:
+        """Check database accessibility and integrity.
+
+        Returns:
+            HealthCheckResult
+        """
+        # Check if database exists
+        if not self.db_path.exists():
+            return HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                message=f"Database not found: {self.db_path}",
+            )
+
+        # Check if database is accessible
+        try:
+            conn = sqlite3.connect(str(self.db_path))
+            cursor = conn.cursor()
+
+            # Run integrity check
+            cursor.execute("PRAGMA integrity_check")
+            result = cursor.fetchone()[0]
+
+            if result != "ok":
+                conn.close()
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    message=f"Database integrity check failed: {result}",
+                )
+
+            # Get database size
+            cursor.execute(
+                "SELECT page_count * page_size FROM pragma_page_count(), pragma_page_size()"
+            )
+            db_size = cursor.fetchone()[0]
+
+            # Get row counts
+            cursor.execute("SELECT COUNT(*) FROM trades")
+            trade_count = cursor.fetchone()[0]
+
+            conn.close()
+
+            return HealthCheckResult(
+                status=HealthStatus.HEALTHY,
+                message="Database is healthy",
+                details={
+                    "size_bytes": db_size,
+                    "size_mb": db_size / 1024 / 1024,
+                    "trade_count": trade_count,
+                },
+            )
+
+        except sqlite3.Error as exc:
+            return HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                message=f"Database access error: {exc}",
+            )
+
+    def check_disk_space(self) -> HealthCheckResult:
+        """Check available disk space.
+
+        Returns:
+            HealthCheckResult
+        """
+        try:
+            stat = shutil.disk_usage(self.backup_dir)
+
+            free_gb = stat.free / 1024 / 1024 / 1024
+            total_gb = stat.total / 1024 / 1024 / 1024
+            used_percent = (stat.used / stat.total) * 100
+
+            if stat.free < self.min_disk_space_bytes:
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    message=f"Low disk space: {free_gb:.2f} GB free (minimum: {self.min_disk_space_bytes / 1024 / 1024 / 1024:.2f} GB)",
+                    details={
+                        "free_gb": free_gb,
+                        "total_gb": total_gb,
+                        "used_percent": used_percent,
+                    },
+                )
+            elif stat.free < self.min_disk_space_bytes * 2:
+                return HealthCheckResult(
+                    status=HealthStatus.DEGRADED,
+                    message=f"Disk space low: {free_gb:.2f} GB free",
+                    details={
+                        "free_gb": free_gb,
+                        "total_gb": total_gb,
+                        "used_percent": used_percent,
+                    },
+                )
+            else:
+                return HealthCheckResult(
+                    status=HealthStatus.HEALTHY,
+                    message=f"Disk space healthy: {free_gb:.2f} GB free",
+                    details={
+                        "free_gb": free_gb,
+                        "total_gb": total_gb,
+                        "used_percent": used_percent,
+                    },
+                )
+
+        except Exception as exc:
+            return HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                message=f"Failed to check disk space: {exc}",
+            )
+
+    def check_backup_recency(self) -> HealthCheckResult:
+        """Check if backups are recent enough.
+
+        Returns:
+            HealthCheckResult
+        """
+        daily_dir = self.backup_dir / "daily"
+
+        if not daily_dir.exists():
+            return HealthCheckResult(
+                status=HealthStatus.DEGRADED,
+                message="Daily backup directory not found",
+            )
+
+        # Find most recent backup
+        backups = sorted(daily_dir.glob("*.db"), key=lambda p: p.stat().st_mtime, reverse=True)
+
+        if not backups:
+            return HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                message="No daily backups found",
+            )
+
+        most_recent = backups[0]
+        mtime = datetime.fromtimestamp(most_recent.stat().st_mtime, tz=UTC)
+        age = datetime.now(UTC) - mtime
+
+        if age > self.max_backup_age:
+            return HealthCheckResult(
+                status=HealthStatus.DEGRADED,
+                message=f"Most recent backup is {age.total_seconds() / 3600:.1f} hours old",
+                details={
+                    "backup_file": most_recent.name,
+                    "age_hours": age.total_seconds() / 3600,
+                    "threshold_hours": self.max_backup_age.total_seconds() / 3600,
+                },
+            )
+        else:
+            return HealthCheckResult(
+                status=HealthStatus.HEALTHY,
+                message=f"Recent backup found ({age.total_seconds() / 3600:.1f} hours old)",
+                details={
+                    "backup_file": most_recent.name,
+                    "age_hours": age.total_seconds() / 3600,
+                },
+            )
+
+    def run_all_checks(self) -> dict[str, HealthCheckResult]:
+        """Run all health checks.
+
+        Returns:
+            Dictionary mapping check name to result
+        """
+        checks = {
+            "database": self.check_database_health(),
+            "disk_space": self.check_disk_space(),
+            "backup_recency": self.check_backup_recency(),
+        }
+
+        # Log results
+        for check_name, result in checks.items():
+            if result.status == HealthStatus.UNHEALTHY:
+                logger.error("[%s] %s: %s", check_name, result.status.value, result.message)
+            elif result.status == HealthStatus.DEGRADED:
+                logger.warning("[%s] %s: %s", check_name, result.status.value, result.message)
+            else:
+                logger.info("[%s] %s: %s", check_name, result.status.value, result.message)
+
+        return checks
+
+    def get_overall_status(self) -> HealthStatus:
+        """Get overall system health status.
+
+        Returns:
+            HealthStatus (worst status from all checks)
+        """
+        checks = self.run_all_checks()
+
+        # Return worst status
+        if any(c.status == HealthStatus.UNHEALTHY for c in checks.values()):
+            return HealthStatus.UNHEALTHY
+        elif any(c.status == HealthStatus.DEGRADED for c in checks.values()):
+            return HealthStatus.DEGRADED
+        else:
+            return HealthStatus.HEALTHY
+
+    def get_health_report(self) -> dict[str, Any]:
+        """Get comprehensive health report.
+
+        Returns:
+            Dictionary with health report
+        """
+        checks = self.run_all_checks()
+        overall = self.get_overall_status()
+
+        return {
+            "overall_status": overall.value,
+            "timestamp": datetime.now(UTC).isoformat(),
+            "checks": {
+                name: {
+                    "status": result.status.value,
+                    "message": result.message,
+                    "details": result.details,
+                }
+                for name, result in checks.items()
+            },
+        }

src/backup/scheduler.py

@@ -0,0 +1,336 @@
+"""Backup scheduler for automated database backups.
+
+Implements backup policies:
+- Daily: Keep for 30 days (hot storage)
+- Weekly: Keep for 1 year (warm storage)
+- Monthly: Keep forever (cold storage)
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class BackupPolicy(str, Enum):
+    """Backup retention policies."""
+
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+
+
+@dataclass
+class BackupMetadata:
+    """Metadata for a backup."""
+
+    timestamp: datetime
+    policy: BackupPolicy
+    file_path: Path
+    size_bytes: int
+    checksum: str | None = None
+
+
+class BackupScheduler:
+    """Manage automated database backups with retention policies."""
+
+    def __init__(
+        self,
+        db_path: str,
+        backup_dir: Path,
+        daily_retention_days: int = 30,
+        weekly_retention_days: int = 365,
+    ) -> None:
+        """Initialize the backup scheduler.
+
+        Args:
+            db_path: Path to SQLite database
+            backup_dir: Root directory for backups
+            daily_retention_days: Days to keep daily backups
+            weekly_retention_days: Days to keep weekly backups
+        """
+        self.db_path = Path(db_path)
+        self.backup_dir = backup_dir
+        self.daily_retention = timedelta(days=daily_retention_days)
+        self.weekly_retention = timedelta(days=weekly_retention_days)
+
+        # Create policy-specific directories
+        self.daily_dir = backup_dir / "daily"
+        self.weekly_dir = backup_dir / "weekly"
+        self.monthly_dir = backup_dir / "monthly"
+
+        for d in [self.daily_dir, self.weekly_dir, self.monthly_dir]:
+            d.mkdir(parents=True, exist_ok=True)
+
+    def create_backup(
+        self, policy: BackupPolicy, verify: bool = True
+    ) -> BackupMetadata:
+        """Create a database backup.
+
+        Args:
+            policy: Backup policy (daily/weekly/monthly)
+            verify: Whether to verify backup integrity
+
+        Returns:
+            BackupMetadata object
+
+        Raises:
+            FileNotFoundError: If database doesn't exist
+            OSError: If backup fails
+        """
+        if not self.db_path.exists():
+            raise FileNotFoundError(f"Database not found: {self.db_path}")
+
+        timestamp = datetime.now(UTC)
+        backup_filename = self._get_backup_filename(timestamp, policy)
+
+        # Determine output directory
+        if policy == BackupPolicy.DAILY:
+            output_dir = self.daily_dir
+        elif policy == BackupPolicy.WEEKLY:
+            output_dir = self.weekly_dir
+        else:  # MONTHLY
+            output_dir = self.monthly_dir
+
+        backup_path = output_dir / backup_filename
+
+        # Create backup (copy database file)
+        logger.info("Creating %s backup: %s", policy.value, backup_path)
+        shutil.copy2(self.db_path, backup_path)
+
+        # Get file size
+        size_bytes = backup_path.stat().st_size
+
+        # Verify backup if requested
+        checksum = None
+        if verify:
+            checksum = self._verify_backup(backup_path)
+
+        metadata = BackupMetadata(
+            timestamp=timestamp,
+            policy=policy,
+            file_path=backup_path,
+            size_bytes=size_bytes,
+            checksum=checksum,
+        )
+
+        logger.info(
+            "Backup created: %s (%.2f MB)",
+            backup_path.name,
+            size_bytes / 1024 / 1024,
+        )
+
+        return metadata
+
+    def _get_backup_filename(self, timestamp: datetime, policy: BackupPolicy) -> str:
+        """Generate backup filename.
+
+        Args:
+            timestamp: Backup timestamp
+            policy: Backup policy
+
+        Returns:
+            Filename string
+        """
+        ts_str = timestamp.strftime("%Y%m%d_%H%M%S")
+        return f"trade_logs_{policy.value}_{ts_str}.db"
+
+    def _verify_backup(self, backup_path: Path) -> str:
+        """Verify backup integrity using SQLite integrity check.
+
+        Args:
+            backup_path: Path to backup file
+
+        Returns:
+            Checksum string (MD5 hash)
+
+        Raises:
+            RuntimeError: If integrity check fails
+        """
+        import hashlib
+        import sqlite3
+
+        # Integrity check
+        try:
+            conn = sqlite3.connect(str(backup_path))
+            cursor = conn.cursor()
+            cursor.execute("PRAGMA integrity_check")
+            result = cursor.fetchone()[0]
+            conn.close()
+
+            if result != "ok":
+                raise RuntimeError(f"Integrity check failed: {result}")
+        except sqlite3.Error as exc:
+            raise RuntimeError(f"Failed to verify backup: {exc}")
+
+        # Calculate MD5 checksum
+        md5 = hashlib.md5()
+        with open(backup_path, "rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                md5.update(chunk)
+
+        return md5.hexdigest()
+
+    def cleanup_old_backups(self) -> dict[BackupPolicy, int]:
+        """Remove backups older than retention policies.
+
+        Returns:
+            Dictionary mapping policy to number of backups removed
+        """
+        now = datetime.now(UTC)
+        removed_counts: dict[BackupPolicy, int] = {}
+
+        # Daily backups: remove older than retention
+        removed_counts[BackupPolicy.DAILY] = self._cleanup_directory(
+            self.daily_dir, now - self.daily_retention
+        )
+
+        # Weekly backups: remove older than retention
+        removed_counts[BackupPolicy.WEEKLY] = self._cleanup_directory(
+            self.weekly_dir, now - self.weekly_retention
+        )
+
+        # Monthly backups: never remove (kept forever)
+        removed_counts[BackupPolicy.MONTHLY] = 0
+
+        total = sum(removed_counts.values())
+        if total > 0:
+            logger.info("Cleaned up %d old backup(s)", total)
+
+        return removed_counts
+
+    def _cleanup_directory(self, directory: Path, cutoff: datetime) -> int:
+        """Remove backups older than cutoff date.
+
+        Args:
+            directory: Directory to clean
+            cutoff: Remove files older than this
+
+        Returns:
+            Number of files removed
+        """
+        removed = 0
+
+        for backup_file in directory.glob("*.db"):
+            # Get file modification time
+            mtime = datetime.fromtimestamp(backup_file.stat().st_mtime, tz=UTC)
+
+            if mtime < cutoff:
+                logger.debug("Removing old backup: %s", backup_file.name)
+                backup_file.unlink()
+                removed += 1
+
+        return removed
+
+    def list_backups(
+        self, policy: BackupPolicy | None = None
+    ) -> list[BackupMetadata]:
+        """List available backups.
+
+        Args:
+            policy: Filter by policy (None for all)
+
+        Returns:
+            List of BackupMetadata objects
+        """
+        backups: list[BackupMetadata] = []
+
+        policies_to_check = (
+            [policy] if policy else [BackupPolicy.DAILY, BackupPolicy.WEEKLY, BackupPolicy.MONTHLY]
+        )
+
+        for pol in policies_to_check:
+            if pol == BackupPolicy.DAILY:
+                directory = self.daily_dir
+            elif pol == BackupPolicy.WEEKLY:
+                directory = self.weekly_dir
+            else:
+                directory = self.monthly_dir
+
+            for backup_file in sorted(directory.glob("*.db")):
+                mtime = datetime.fromtimestamp(backup_file.stat().st_mtime, tz=UTC)
+                size = backup_file.stat().st_size
+
+                backups.append(
+                    BackupMetadata(
+                        timestamp=mtime,
+                        policy=pol,
+                        file_path=backup_file,
+                        size_bytes=size,
+                    )
+                )
+
+        # Sort by timestamp (newest first)
+        backups.sort(key=lambda b: b.timestamp, reverse=True)
+
+        return backups
+
+    def get_backup_stats(self) -> dict[str, Any]:
+        """Get backup statistics.
+
+        Returns:
+            Dictionary with backup stats
+        """
+        stats: dict[str, Any] = {}
+
+        for policy in BackupPolicy:
+            if policy == BackupPolicy.DAILY:
+                directory = self.daily_dir
+            elif policy == BackupPolicy.WEEKLY:
+                directory = self.weekly_dir
+            else:
+                directory = self.monthly_dir
+
+            backups = list(directory.glob("*.db"))
+            total_size = sum(b.stat().st_size for b in backups)
+
+            stats[policy.value] = {
+                "count": len(backups),
+                "total_size_bytes": total_size,
+                "total_size_mb": total_size / 1024 / 1024,
+            }
+
+        return stats
+
+    def restore_backup(self, backup_metadata: BackupMetadata, verify: bool = True) -> None:
+        """Restore database from backup.
+
+        Args:
+            backup_metadata: Backup to restore
+            verify: Whether to verify restored database
+
+        Raises:
+            FileNotFoundError: If backup file doesn't exist
+            RuntimeError: If verification fails
+        """
+        if not backup_metadata.file_path.exists():
+            raise FileNotFoundError(f"Backup not found: {backup_metadata.file_path}")
+
+        # Create backup of current database
+        if self.db_path.exists():
+            backup_current = self.db_path.with_suffix(".db.before_restore")
+            logger.info("Backing up current database to: %s", backup_current)
+            shutil.copy2(self.db_path, backup_current)
+
+        # Restore backup
+        logger.info("Restoring backup: %s", backup_metadata.file_path.name)
+        shutil.copy2(backup_metadata.file_path, self.db_path)
+
+        # Verify restored database
+        if verify:
+            try:
+                self._verify_backup(self.db_path)
+                logger.info("Backup restored and verified successfully")
+            except RuntimeError as exc:
+                # Restore failed, revert to backup
+                if backup_current.exists():
+                    logger.error("Restore verification failed, reverting: %s", exc)
+                    shutil.copy2(backup_current, self.db_path)
+                raise

src/brain/cache.py

@@ -0,0 +1,293 @@
+"""Response caching system for reducing redundant LLM calls.
+
+This module provides caching for common trading scenarios:
+- TTL-based cache invalidation
+- Cache key based on market conditions
+- Cache hit rate monitoring
+- Special handling for HOLD decisions in quiet markets
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from src.brain.gemini_client import TradeDecision
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CacheEntry:
+    """Cached decision with metadata."""
+
+    decision: "TradeDecision"
+    cached_at: float  # Unix timestamp
+    hit_count: int = 0
+    market_data_hash: str = ""
+
+
+@dataclass
+class CacheMetrics:
+    """Metrics for cache performance monitoring."""
+
+    total_requests: int = 0
+    cache_hits: int = 0
+    cache_misses: int = 0
+    evictions: int = 0
+    total_entries: int = 0
+
+    @property
+    def hit_rate(self) -> float:
+        """Calculate cache hit rate."""
+        if self.total_requests == 0:
+            return 0.0
+        return self.cache_hits / self.total_requests
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert metrics to dictionary."""
+        return {
+            "total_requests": self.total_requests,
+            "cache_hits": self.cache_hits,
+            "cache_misses": self.cache_misses,
+            "hit_rate": self.hit_rate,
+            "evictions": self.evictions,
+            "total_entries": self.total_entries,
+        }
+
+
+class DecisionCache:
+    """TTL-based cache for trade decisions."""
+
+    def __init__(self, ttl_seconds: int = 300, max_size: int = 1000) -> None:
+        """Initialize the decision cache.
+
+        Args:
+            ttl_seconds: Time-to-live for cache entries in seconds (default: 5 minutes)
+            max_size: Maximum number of cache entries
+        """
+        self.ttl_seconds = ttl_seconds
+        self.max_size = max_size
+        self._cache: dict[str, CacheEntry] = {}
+        self._metrics = CacheMetrics()
+
+    def _generate_cache_key(self, market_data: dict[str, Any]) -> str:
+        """Generate cache key from market data.
+
+        Key is based on:
+        - Stock code
+        - Current price (rounded to reduce sensitivity)
+        - Market conditions (orderbook snapshot)
+
+        Args:
+            market_data: Market data dictionary
+
+        Returns:
+            Cache key string
+        """
+        # Extract key components
+        stock_code = market_data.get("stock_code", "UNKNOWN")
+        current_price = market_data.get("current_price", 0)
+
+        # Round price to reduce sensitivity (cache hits for similar prices)
+        # For prices > 1000, round to nearest 10
+        # For prices < 1000, round to nearest 1
+        if current_price > 1000:
+            price_rounded = round(current_price / 10) * 10
+        else:
+            price_rounded = round(current_price)
+
+        # Include orderbook snapshot (if available)
+        orderbook_key = ""
+        if "orderbook" in market_data and market_data["orderbook"]:
+            ob = market_data["orderbook"]
+            # Just use bid/ask spread as indicator
+            if "bid" in ob and "ask" in ob and ob["bid"] and ob["ask"]:
+                bid_price = ob["bid"][0].get("price", 0) if ob["bid"] else 0
+                ask_price = ob["ask"][0].get("price", 0) if ob["ask"] else 0
+                spread = ask_price - bid_price
+                orderbook_key = f"_spread{spread}"
+
+        # Generate cache key
+        key_str = f"{stock_code}_{price_rounded}{orderbook_key}"
+
+        return key_str
+
+    def _generate_market_hash(self, market_data: dict[str, Any]) -> str:
+        """Generate hash of full market data for invalidation checks.
+
+        Args:
+            market_data: Market data dictionary
+
+        Returns:
+            Hash string
+        """
+        # Create stable JSON representation
+        stable_json = json.dumps(market_data, sort_keys=True, ensure_ascii=False)
+        return hashlib.md5(stable_json.encode()).hexdigest()
+
+    def get(self, market_data: dict[str, Any]) -> TradeDecision | None:
+        """Retrieve cached decision if valid.
+
+        Args:
+            market_data: Market data dictionary
+
+        Returns:
+            Cached TradeDecision if valid, None otherwise
+        """
+        self._metrics.total_requests += 1
+
+        cache_key = self._generate_cache_key(market_data)
+
+        if cache_key not in self._cache:
+            self._metrics.cache_misses += 1
+            return None
+
+        entry = self._cache[cache_key]
+        current_time = time.time()
+
+        # Check TTL
+        if current_time - entry.cached_at > self.ttl_seconds:
+            # Expired
+            del self._cache[cache_key]
+            self._metrics.cache_misses += 1
+            self._metrics.evictions += 1
+            logger.debug("Cache expired for key: %s", cache_key)
+            return None
+
+        # Cache hit
+        entry.hit_count += 1
+        self._metrics.cache_hits += 1
+        logger.debug("Cache hit for key: %s (hits: %d)", cache_key, entry.hit_count)
+
+        return entry.decision
+
+    def set(
+        self,
+        market_data: dict[str, Any],
+        decision: TradeDecision,
+    ) -> None:
+        """Store decision in cache.
+
+        Args:
+            market_data: Market data dictionary
+            decision: TradeDecision to cache
+        """
+        cache_key = self._generate_cache_key(market_data)
+        market_hash = self._generate_market_hash(market_data)
+
+        # Enforce max size (evict oldest if full)
+        if len(self._cache) >= self.max_size:
+            # Find oldest entry
+            oldest_key = min(self._cache.keys(), key=lambda k: self._cache[k].cached_at)
+            del self._cache[oldest_key]
+            self._metrics.evictions += 1
+            logger.debug("Cache full, evicted key: %s", oldest_key)
+
+        # Store entry
+        entry = CacheEntry(
+            decision=decision,
+            cached_at=time.time(),
+            market_data_hash=market_hash,
+        )
+        self._cache[cache_key] = entry
+        self._metrics.total_entries = len(self._cache)
+
+        logger.debug("Cached decision for key: %s", cache_key)
+
+    def invalidate(self, stock_code: str | None = None) -> int:
+        """Invalidate cache entries.
+
+        Args:
+            stock_code: Specific stock code to invalidate, or None for all
+
+        Returns:
+            Number of entries invalidated
+        """
+        if stock_code is None:
+            # Clear all
+            count = len(self._cache)
+            self._cache.clear()
+            self._metrics.evictions += count
+            self._metrics.total_entries = 0
+            logger.info("Invalidated all cache entries (%d)", count)
+            return count
+
+        # Invalidate specific stock
+        keys_to_remove = [k for k in self._cache.keys() if k.startswith(f"{stock_code}_")]
+        count = len(keys_to_remove)
+
+        for key in keys_to_remove:
+            del self._cache[key]
+
+        self._metrics.evictions += count
+        self._metrics.total_entries = len(self._cache)
+        logger.info("Invalidated %d cache entries for stock: %s", count, stock_code)
+
+        return count
+
+    def cleanup_expired(self) -> int:
+        """Remove expired entries from cache.
+
+        Returns:
+            Number of entries removed
+        """
+        current_time = time.time()
+        expired_keys = [
+            k
+            for k, v in self._cache.items()
+            if current_time - v.cached_at > self.ttl_seconds
+        ]
+
+        count = len(expired_keys)
+        for key in expired_keys:
+            del self._cache[key]
+
+        self._metrics.evictions += count
+        self._metrics.total_entries = len(self._cache)
+
+        if count > 0:
+            logger.debug("Cleaned up %d expired cache entries", count)
+
+        return count
+
+    def get_metrics(self) -> CacheMetrics:
+        """Get current cache metrics.
+
+        Returns:
+            CacheMetrics object with current statistics
+        """
+        return self._metrics
+
+    def reset_metrics(self) -> None:
+        """Reset cache metrics."""
+        self._metrics = CacheMetrics(total_entries=len(self._cache))
+        logger.info("Cache metrics reset")
+
+    def should_cache_decision(self, decision: TradeDecision) -> bool:
+        """Determine if a decision should be cached.
+
+        HOLD decisions with low confidence are good candidates for caching,
+        as they're likely to recur in quiet markets.
+
+        Args:
+            decision: TradeDecision to evaluate
+
+        Returns:
+            True if decision should be cached
+        """
+        # Cache HOLD decisions (common in quiet markets)
+        if decision.action == "HOLD":
+            return True
+
+        # Cache high-confidence decisions (stable signals)
+        if decision.confidence >= 90:
+            return True
+
+        # Don't cache low-confidence BUY/SELL (volatile signals)
+        return False

src/brain/context_selector.py

@@ -0,0 +1,296 @@
+"""Smart context selection for optimizing token usage.
+
+This module implements intelligent selection of context layers (L1-L7) based on
+decision type and market conditions:
+- L7 (real-time) for normal trading decisions
+- L6-L5 (daily/weekly) for strategic decisions
+- L4-L1 (monthly/legacy) only for major events or policy changes
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from src.context.layer import ContextLayer
+from src.context.store import ContextStore
+
+
+class DecisionType(str, Enum):
+    """Type of trading decision being made."""
+
+    NORMAL = "normal"  # Regular trade decision
+    STRATEGIC = "strategic"  # Strategy adjustment
+    MAJOR_EVENT = "major_event"  # Portfolio rebalancing, policy change
+
+
+@dataclass(frozen=True)
+class ContextSelection:
+    """Selected context layers and their relevance scores."""
+
+    layers: list[ContextLayer]
+    relevance_scores: dict[ContextLayer, float]
+    total_score: float
+
+
+class ContextSelector:
+    """Selects optimal context layers to minimize token usage."""
+
+    def __init__(self, store: ContextStore) -> None:
+        """Initialize the context selector.
+
+        Args:
+            store: ContextStore instance for retrieving context data
+        """
+        self.store = store
+
+    def select_layers(
+        self,
+        decision_type: DecisionType = DecisionType.NORMAL,
+        include_realtime: bool = True,
+    ) -> list[ContextLayer]:
+        """Select context layers based on decision type.
+
+        Strategy:
+        - NORMAL: L7 (real-time) only
+        - STRATEGIC: L7 + L6 + L5 (real-time + daily + weekly)
+        - MAJOR_EVENT: All layers L1-L7
+
+        Args:
+            decision_type: Type of decision being made
+            include_realtime: Whether to include L7 real-time data
+
+        Returns:
+            List of context layers to use (ordered by priority)
+        """
+        if decision_type == DecisionType.NORMAL:
+            # Normal trading: only real-time data
+            return [ContextLayer.L7_REALTIME] if include_realtime else []
+
+        elif decision_type == DecisionType.STRATEGIC:
+            # Strategic decisions: real-time + recent history
+            layers = []
+            if include_realtime:
+                layers.append(ContextLayer.L7_REALTIME)
+            layers.extend([ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY])
+            return layers
+
+        else:  # MAJOR_EVENT
+            # Major events: all layers for comprehensive context
+            layers = []
+            if include_realtime:
+                layers.append(ContextLayer.L7_REALTIME)
+            layers.extend(
+                [
+                    ContextLayer.L6_DAILY,
+                    ContextLayer.L5_WEEKLY,
+                    ContextLayer.L4_MONTHLY,
+                    ContextLayer.L3_QUARTERLY,
+                    ContextLayer.L2_ANNUAL,
+                    ContextLayer.L1_LEGACY,
+                ]
+            )
+            return layers
+
+    def score_layer_relevance(
+        self,
+        layer: ContextLayer,
+        decision_type: DecisionType,
+        current_time: datetime | None = None,
+    ) -> float:
+        """Calculate relevance score for a context layer.
+
+        Relevance is based on:
+        1. Decision type (normal, strategic, major event)
+        2. Layer recency (L7 > L6 > ... > L1)
+        3. Data availability
+
+        Args:
+            layer: Context layer to score
+            decision_type: Type of decision being made
+            current_time: Current time (defaults to now)
+
+        Returns:
+            Relevance score (0.0 to 1.0)
+        """
+        if current_time is None:
+            current_time = datetime.now(UTC)
+
+        # Base scores by decision type
+        base_scores = {
+            DecisionType.NORMAL: {
+                ContextLayer.L7_REALTIME: 1.0,
+                ContextLayer.L6_DAILY: 0.1,
+                ContextLayer.L5_WEEKLY: 0.05,
+                ContextLayer.L4_MONTHLY: 0.01,
+                ContextLayer.L3_QUARTERLY: 0.0,
+                ContextLayer.L2_ANNUAL: 0.0,
+                ContextLayer.L1_LEGACY: 0.0,
+            },
+            DecisionType.STRATEGIC: {
+                ContextLayer.L7_REALTIME: 0.9,
+                ContextLayer.L6_DAILY: 0.8,
+                ContextLayer.L5_WEEKLY: 0.7,
+                ContextLayer.L4_MONTHLY: 0.3,
+                ContextLayer.L3_QUARTERLY: 0.2,
+                ContextLayer.L2_ANNUAL: 0.1,
+                ContextLayer.L1_LEGACY: 0.05,
+            },
+            DecisionType.MAJOR_EVENT: {
+                ContextLayer.L7_REALTIME: 0.7,
+                ContextLayer.L6_DAILY: 0.7,
+                ContextLayer.L5_WEEKLY: 0.7,
+                ContextLayer.L4_MONTHLY: 0.8,
+                ContextLayer.L3_QUARTERLY: 0.8,
+                ContextLayer.L2_ANNUAL: 0.9,
+                ContextLayer.L1_LEGACY: 1.0,
+            },
+        }
+
+        score = base_scores[decision_type].get(layer, 0.0)
+
+        # Check data availability
+        latest_timeframe = self.store.get_latest_timeframe(layer)
+        if latest_timeframe is None:
+            # No data available - reduce score significantly
+            score *= 0.1
+
+        return score
+
+    def select_with_scoring(
+        self,
+        decision_type: DecisionType = DecisionType.NORMAL,
+        min_score: float = 0.5,
+    ) -> ContextSelection:
+        """Select context layers with relevance scoring.
+
+        Args:
+            decision_type: Type of decision being made
+            min_score: Minimum relevance score to include a layer
+
+        Returns:
+            ContextSelection with selected layers and scores
+        """
+        all_layers = [
+            ContextLayer.L7_REALTIME,
+            ContextLayer.L6_DAILY,
+            ContextLayer.L5_WEEKLY,
+            ContextLayer.L4_MONTHLY,
+            ContextLayer.L3_QUARTERLY,
+            ContextLayer.L2_ANNUAL,
+            ContextLayer.L1_LEGACY,
+        ]
+
+        scores = {
+            layer: self.score_layer_relevance(layer, decision_type) for layer in all_layers
+        }
+
+        # Filter by minimum score
+        selected_layers = [layer for layer, score in scores.items() if score >= min_score]
+
+        # Sort by score (descending)
+        selected_layers.sort(key=lambda layer: scores[layer], reverse=True)
+
+        total_score = sum(scores[layer] for layer in selected_layers)
+
+        return ContextSelection(
+            layers=selected_layers,
+            relevance_scores=scores,
+            total_score=total_score,
+        )
+
+    def get_context_data(
+        self,
+        layers: list[ContextLayer],
+        max_items_per_layer: int = 10,
+    ) -> dict[str, Any]:
+        """Retrieve context data for selected layers.
+
+        Args:
+            layers: List of context layers to retrieve
+            max_items_per_layer: Maximum number of items per layer
+
+        Returns:
+            Dictionary with context data organized by layer
+        """
+        result: dict[str, Any] = {}
+
+        for layer in layers:
+            # Get latest timeframe for this layer
+            latest_timeframe = self.store.get_latest_timeframe(layer)
+            if latest_timeframe:
+                # Get all contexts for latest timeframe
+                contexts = self.store.get_all_contexts(layer, latest_timeframe)
+
+                # Limit number of items
+                if len(contexts) > max_items_per_layer:
+                    # Keep only first N items
+                    contexts = dict(list(contexts.items())[:max_items_per_layer])
+
+                result[layer.value] = contexts
+
+        return result
+
+    def estimate_context_tokens(self, context_data: dict[str, Any]) -> int:
+        """Estimate total tokens for context data.
+
+        Args:
+            context_data: Context data dictionary
+
+        Returns:
+            Estimated token count
+        """
+        import json
+
+        from src.brain.prompt_optimizer import PromptOptimizer
+
+        # Serialize to JSON and estimate tokens
+        json_str = json.dumps(context_data, ensure_ascii=False)
+        return PromptOptimizer.estimate_tokens(json_str)
+
+    def optimize_context_for_budget(
+        self,
+        decision_type: DecisionType,
+        max_tokens: int,
+    ) -> dict[str, Any]:
+        """Select and retrieve context data within a token budget.
+
+        Args:
+            decision_type: Type of decision being made
+            max_tokens: Maximum token budget for context
+
+        Returns:
+            Optimized context data within budget
+        """
+        # Start with minimal selection
+        selection = self.select_with_scoring(decision_type, min_score=0.5)
+
+        # Retrieve data
+        context_data = self.get_context_data(selection.layers)
+
+        # Check if within budget
+        estimated_tokens = self.estimate_context_tokens(context_data)
+
+        if estimated_tokens <= max_tokens:
+            return context_data
+
+        # If over budget, progressively reduce
+        # 1. Reduce items per layer
+        for max_items in [5, 3, 1]:
+            context_data = self.get_context_data(selection.layers, max_items)
+            estimated_tokens = self.estimate_context_tokens(context_data)
+            if estimated_tokens <= max_tokens:
+                return context_data
+
+        # 2. Remove lower-priority layers
+        for min_score in [0.6, 0.7, 0.8, 0.9]:
+            selection = self.select_with_scoring(decision_type, min_score=min_score)
+            context_data = self.get_context_data(selection.layers, max_items_per_layer=1)
+            estimated_tokens = self.estimate_context_tokens(context_data)
+            if estimated_tokens <= max_tokens:
+                return context_data
+
+        # Last resort: return only L7 with minimal data
+        return self.get_context_data([ContextLayer.L7_REALTIME], max_items_per_layer=1)

src/brain/gemini_client.py

@@ -2,6 +2,17 @@
 
 Constructs prompts from market data, calls Gemini, and parses structured
 JSON responses into validated TradeDecision objects.
+
+Includes token efficiency optimizations:
+- Prompt compression and abbreviation
+- Response caching for common scenarios
+- Smart context selection
+- Token usage tracking and metrics
+
+Includes external data integration:
+- News sentiment analysis
+- Economic calendar events
+- Market indicators
 """
 
 from __future__ import annotations
@@ -15,6 +26,11 @@ from typing import Any
 from google import genai
 
 from src.config import Settings
+from src.data.news_api import NewsAPI, NewsSentiment
+from src.data.economic_calendar import EconomicCalendar
+from src.data.market_data import MarketData
+from src.brain.cache import DecisionCache
+from src.brain.prompt_optimizer import PromptOptimizer
 
 logger = logging.getLogger(__name__)
 
@@ -28,23 +44,176 @@ class TradeDecision:
     action: str  # "BUY" | "SELL" | "HOLD"
     confidence: int  # 0-100
     rationale: str
+    token_count: int = 0  # Estimated tokens used
+    cached: bool = False  # Whether decision came from cache
 
 
 class GeminiClient:
     """Wraps the Gemini API for trade decision-making."""
 
-    def __init__(self, settings: Settings) -> None:
+    def __init__(
+        self,
+        settings: Settings,
+        news_api: NewsAPI | None = None,
+        economic_calendar: EconomicCalendar | None = None,
+        market_data: MarketData | None = None,
+        enable_cache: bool = True,
+        enable_optimization: bool = True,
+    ) -> None:
         self._settings = settings
         self._confidence_threshold = settings.CONFIDENCE_THRESHOLD
         self._client = genai.Client(api_key=settings.GEMINI_API_KEY)
         self._model_name = settings.GEMINI_MODEL
 
+        # External data sources (optional)
+        self._news_api = news_api
+        self._economic_calendar = economic_calendar
+        self._market_data = market_data
+
+        # Token efficiency features
+        self._enable_cache = enable_cache
+        self._enable_optimization = enable_optimization
+        self._cache = DecisionCache(ttl_seconds=300) if enable_cache else None
+        self._optimizer = PromptOptimizer()
+
+        # Token usage metrics
+        self._total_tokens_used = 0
+        self._total_decisions = 0
+        self._total_cached_decisions = 0
+
+    # ------------------------------------------------------------------
+    # External Data Integration
+    # ------------------------------------------------------------------
+
+    async def _build_external_context(
+        self, stock_code: str, news_sentiment: NewsSentiment | None = None
+    ) -> str:
+        """Build external data context for the prompt.
+
+        Args:
+            stock_code: Stock ticker symbol
+            news_sentiment: Optional pre-fetched news sentiment
+
+        Returns:
+            Formatted string with external data context
+        """
+        context_parts: list[str] = []
+
+        # News sentiment
+        if news_sentiment is not None:
+            sentiment_str = self._format_news_sentiment(news_sentiment)
+            if sentiment_str:
+                context_parts.append(sentiment_str)
+        elif self._news_api is not None:
+            # Fetch news sentiment if not provided
+            try:
+                sentiment = await self._news_api.get_news_sentiment(stock_code)
+                if sentiment is not None:
+                    sentiment_str = self._format_news_sentiment(sentiment)
+                    if sentiment_str:
+                        context_parts.append(sentiment_str)
+            except Exception as exc:
+                logger.warning("Failed to fetch news sentiment: %s", exc)
+
+        # Economic events
+        if self._economic_calendar is not None:
+            events_str = self._format_economic_events(stock_code)
+            if events_str:
+                context_parts.append(events_str)
+
+        # Market indicators
+        if self._market_data is not None:
+            indicators_str = self._format_market_indicators()
+            if indicators_str:
+                context_parts.append(indicators_str)
+
+        if not context_parts:
+            return ""
+
+        return "EXTERNAL DATA:\n" + "\n\n".join(context_parts)
+
+    def _format_news_sentiment(self, sentiment: NewsSentiment) -> str:
+        """Format news sentiment for prompt."""
+        if sentiment.article_count == 0:
+            return ""
+
+        # Select top 3 most relevant articles
+        top_articles = sentiment.articles[:3]
+
+        lines = [
+            f"News Sentiment: {sentiment.avg_sentiment:.2f} "
+            f"(from {sentiment.article_count} articles)",
+        ]
+
+        for i, article in enumerate(top_articles, 1):
+            lines.append(
+                f"  {i}. [{article.source}] {article.title} "
+                f"(sentiment: {article.sentiment_score:.2f})"
+            )
+
+        return "\n".join(lines)
+
+    def _format_economic_events(self, stock_code: str) -> str:
+        """Format upcoming economic events for prompt."""
+        if self._economic_calendar is None:
+            return ""
+
+        # Check for upcoming high-impact events
+        upcoming = self._economic_calendar.get_upcoming_events(
+            days_ahead=7, min_impact="HIGH"
+        )
+
+        if upcoming.high_impact_count == 0:
+            return ""
+
+        lines = [
+            f"Upcoming High-Impact Events: {upcoming.high_impact_count} in next 7 days"
+        ]
+
+        if upcoming.next_major_event is not None:
+            event = upcoming.next_major_event
+            lines.append(
+                f"  Next: {event.name} ({event.event_type}) "
+                f"on {event.datetime.strftime('%Y-%m-%d')}"
+            )
+
+        # Check for earnings
+        earnings_date = self._economic_calendar.get_earnings_date(stock_code)
+        if earnings_date is not None:
+            lines.append(
+                f"  Earnings: {stock_code} on {earnings_date.strftime('%Y-%m-%d')}"
+            )
+
+        return "\n".join(lines)
+
+    def _format_market_indicators(self) -> str:
+        """Format market indicators for prompt."""
+        if self._market_data is None:
+            return ""
+
+        try:
+            indicators = self._market_data.get_market_indicators()
+            lines = [f"Market Sentiment: {indicators.sentiment.name}"]
+
+            # Add breadth if meaningful
+            if indicators.breadth.advance_decline_ratio != 1.0:
+                lines.append(
+                    f"Advance/Decline Ratio: {indicators.breadth.advance_decline_ratio:.2f}"
+                )
+
+            return "\n".join(lines)
+        except Exception as exc:
+            logger.warning("Failed to get market indicators: %s", exc)
+            return ""
+
     # ------------------------------------------------------------------
     # Prompt Construction
     # ------------------------------------------------------------------
 
-    def build_prompt(self, market_data: dict[str, Any]) -> str:
+    async def build_prompt(
-        """Build a structured prompt from market data.
+        self, market_data: dict[str, Any], news_sentiment: NewsSentiment | None = None
+    ) -> str:
+        """Build a structured prompt from market data and external sources.
 
         The prompt instructs Gemini to return valid JSON with action,
         confidence, and rationale fields.
@@ -72,6 +241,60 @@ class GeminiClient:
 
         market_info = "\n".join(market_info_lines)
 
+        # Add external data context if available
+        external_context = await self._build_external_context(
+            market_data["stock_code"], news_sentiment
+        )
+        if external_context:
+            market_info += f"\n\n{external_context}"
+
+        json_format = (
+            '{"action": "BUY"|"SELL"|"HOLD", '
+            '"confidence": <int 0-100>, "rationale": "<string>"}'
+        )
+        return (
+            f"You are a professional {market_name} trading analyst.\n"
+            "Analyze the following market data and decide whether to "
+            "BUY, SELL, or HOLD.\n\n"
+            f"{market_info}\n\n"
+            "You MUST respond with ONLY valid JSON in the following format:\n"
+            f"{json_format}\n\n"
+            "Rules:\n"
+            "- action must be exactly one of: BUY, SELL, HOLD\n"
+            "- confidence must be an integer from 0 to 100\n"
+            "- rationale must explain your reasoning concisely\n"
+            "- Do NOT wrap the JSON in markdown code blocks\n"
+        )
+
+    def build_prompt_sync(self, market_data: dict[str, Any]) -> str:
+        """Synchronous version of build_prompt (for backward compatibility).
+
+        This version does NOT include external data integration.
+        Use async build_prompt() for full functionality.
+        """
+        market_name = market_data.get("market_name", "Korean stock market")
+
+        # Build market data section dynamically based on available fields
+        market_info_lines = [
+            f"Market: {market_name}",
+            f"Stock Code: {market_data['stock_code']}",
+            f"Current Price: {market_data['current_price']}",
+        ]
+
+        # Add orderbook if available (domestic markets)
+        if "orderbook" in market_data:
+            market_info_lines.append(
+                f"Orderbook: {json.dumps(market_data['orderbook'], ensure_ascii=False)}"
+            )
+
+        # Add foreigner net if non-zero
+        if market_data.get("foreigner_net", 0) != 0:
+            market_info_lines.append(
+                f"Foreigner Net Buy/Sell: {market_data['foreigner_net']}"
+            )
+
+        market_info = "\n".join(market_info_lines)
+
         json_format = (
             '{"action": "BUY"|"SELL"|"HOLD", '
             '"confidence": <int 0-100>, "rationale": "<string>"}'
@@ -152,28 +375,153 @@ class GeminiClient:
     # API Call
     # ------------------------------------------------------------------
 
-    async def decide(self, market_data: dict[str, Any]) -> TradeDecision:
+    async def decide(
-        """Build prompt, call Gemini, and return a parsed decision."""
+        self, market_data: dict[str, Any], news_sentiment: NewsSentiment | None = None
-        prompt = self.build_prompt(market_data)
+    ) -> TradeDecision:
-        logger.info("Requesting trade decision from Gemini")
+        """Build prompt, call Gemini, and return a parsed decision.
+
+        Args:
+            market_data: Market data dictionary with price, orderbook, etc.
+            news_sentiment: Optional pre-fetched news sentiment
+
+        Returns:
+            Parsed TradeDecision
+        """
+        # Check cache first
+        if self._cache:
+            cached_decision = self._cache.get(market_data)
+            if cached_decision:
+                self._total_cached_decisions += 1
+                self._total_decisions += 1
+                logger.info(
+                    "Cache hit for decision",
+                    extra={
+                        "action": cached_decision.action,
+                        "confidence": cached_decision.confidence,
+                        "cache_hit_rate": self.get_cache_hit_rate(),
+                    },
+                )
+                # Return cached decision with cached flag
+                return TradeDecision(
+                    action=cached_decision.action,
+                    confidence=cached_decision.confidence,
+                    rationale=cached_decision.rationale,
+                    token_count=0,
+                    cached=True,
+                )
+
+        # Build optimized prompt
+        if self._enable_optimization:
+            prompt = self._optimizer.build_compressed_prompt(market_data)
+        else:
+            prompt = await self.build_prompt(market_data, news_sentiment)
+
+        # Estimate tokens
+        token_count = self._optimizer.estimate_tokens(prompt)
+        self._total_tokens_used += token_count
+
+        logger.info(
+            "Requesting trade decision from Gemini",
+            extra={"estimated_tokens": token_count, "optimized": self._enable_optimization},
+        )
 
         try:
             response = await self._client.aio.models.generate_content(
-                model=self._model_name, contents=prompt,
+                model=self._model_name,
+                contents=prompt,
             )
             raw = response.text
         except Exception as exc:
             logger.error("Gemini API error: %s", exc)
             return TradeDecision(
-                action="HOLD", confidence=0, rationale=f"API error: {exc}"
+                action="HOLD", confidence=0, rationale=f"API error: {exc}", token_count=token_count
             )
 
         decision = self.parse_response(raw)
+        self._total_decisions += 1
+
+        # Add token count to decision
+        decision_with_tokens = TradeDecision(
+            action=decision.action,
+            confidence=decision.confidence,
+            rationale=decision.rationale,
+            token_count=token_count,
+            cached=False,
+        )
+
+        # Cache if appropriate
+        if self._cache and self._cache.should_cache_decision(decision):
+            self._cache.set(market_data, decision)
+
         logger.info(
             "Gemini decision",
             extra={
                 "action": decision.action,
                 "confidence": decision.confidence,
+                "tokens": token_count,
+                "avg_tokens": self.get_avg_tokens_per_decision(),
             },
         )
-        return decision
+
+        return decision_with_tokens
+
+    # ------------------------------------------------------------------
+    # Token Efficiency Metrics
+    # ------------------------------------------------------------------
+
+    def get_token_metrics(self) -> dict[str, Any]:
+        """Get token usage metrics.
+
+        Returns:
+            Dictionary with token usage statistics
+        """
+        metrics = {
+            "total_tokens_used": self._total_tokens_used,
+            "total_decisions": self._total_decisions,
+            "total_cached_decisions": self._total_cached_decisions,
+            "avg_tokens_per_decision": self.get_avg_tokens_per_decision(),
+            "cache_hit_rate": self.get_cache_hit_rate(),
+        }
+
+        if self._cache:
+            cache_metrics = self._cache.get_metrics()
+            metrics["cache_metrics"] = cache_metrics.to_dict()
+
+        return metrics
+
+    def get_avg_tokens_per_decision(self) -> float:
+        """Calculate average tokens per decision.
+
+        Returns:
+            Average tokens per decision
+        """
+        if self._total_decisions == 0:
+            return 0.0
+        return self._total_tokens_used / self._total_decisions
+
+    def get_cache_hit_rate(self) -> float:
+        """Calculate cache hit rate.
+
+        Returns:
+            Cache hit rate (0.0 to 1.0)
+        """
+        if self._total_decisions == 0:
+            return 0.0
+        return self._total_cached_decisions / self._total_decisions
+
+    def reset_metrics(self) -> None:
+        """Reset token usage metrics."""
+        self._total_tokens_used = 0
+        self._total_decisions = 0
+        self._total_cached_decisions = 0
+        if self._cache:
+            self._cache.reset_metrics()
+        logger.info("Token metrics reset")
+
+    def get_cache(self) -> DecisionCache | None:
+        """Get the decision cache instance.
+
+        Returns:
+            DecisionCache instance or None if caching disabled
+        """
+        return self._cache

src/brain/prompt_optimizer.py

@@ -0,0 +1,267 @@
+"""Prompt optimization utilities for reducing token usage.
+
+This module provides tools to compress prompts while maintaining decision quality:
+- Token counting
+- Text compression and abbreviation
+- Template-based prompts with variable slots
+- Priority-based context truncation
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+# Abbreviation mapping for common terms
+ABBREVIATIONS = {
+    "price": "P",
+    "volume": "V",
+    "current": "cur",
+    "previous": "prev",
+    "change": "chg",
+    "percentage": "pct",
+    "market": "mkt",
+    "orderbook": "ob",
+    "foreigner": "fgn",
+    "buy": "B",
+    "sell": "S",
+    "hold": "H",
+    "confidence": "conf",
+    "rationale": "reason",
+    "action": "act",
+    "net": "net",
+}
+
+# Reverse mapping for decompression
+REVERSE_ABBREVIATIONS = {v: k for k, v in ABBREVIATIONS.items()}
+
+
+@dataclass(frozen=True)
+class TokenMetrics:
+    """Metrics about token usage in a prompt."""
+
+    char_count: int
+    word_count: int
+    estimated_tokens: int  # Rough estimate: ~4 chars per token
+    compression_ratio: float = 1.0  # Original / Compressed
+
+
+class PromptOptimizer:
+    """Optimizes prompts to reduce token usage while maintaining quality."""
+
+    @staticmethod
+    def estimate_tokens(text: str) -> int:
+        """Estimate token count for text.
+
+        Uses a simple heuristic: ~4 characters per token for English.
+        This is approximate but sufficient for optimization purposes.
+
+        Args:
+            text: Input text to estimate tokens for
+
+        Returns:
+            Estimated token count
+        """
+        if not text:
+            return 0
+        # Simple estimate: 1 token ≈ 4 characters
+        return max(1, len(text) // 4)
+
+    @staticmethod
+    def count_tokens(text: str) -> TokenMetrics:
+        """Count various metrics for a text.
+
+        Args:
+            text: Input text to analyze
+
+        Returns:
+            TokenMetrics with character, word, and estimated token counts
+        """
+        char_count = len(text)
+        word_count = len(text.split())
+        estimated_tokens = PromptOptimizer.estimate_tokens(text)
+
+        return TokenMetrics(
+            char_count=char_count,
+            word_count=word_count,
+            estimated_tokens=estimated_tokens,
+        )
+
+    @staticmethod
+    def compress_json(data: dict[str, Any]) -> str:
+        """Compress JSON by removing whitespace.
+
+        Args:
+            data: Dictionary to serialize
+
+        Returns:
+            Compact JSON string without whitespace
+        """
+        return json.dumps(data, separators=(",", ":"), ensure_ascii=False)
+
+    @staticmethod
+    def abbreviate_text(text: str, aggressive: bool = False) -> str:
+        """Apply abbreviations to reduce text length.
+
+        Args:
+            text: Input text to abbreviate
+            aggressive: If True, apply more aggressive compression
+
+        Returns:
+            Abbreviated text
+        """
+        result = text
+
+        # Apply word-level abbreviations (case-insensitive)
+        for full, abbr in ABBREVIATIONS.items():
+            # Word boundaries to avoid partial replacements
+            pattern = r"\b" + re.escape(full) + r"\b"
+            result = re.sub(pattern, abbr, result, flags=re.IGNORECASE)
+
+        if aggressive:
+            # Remove articles and filler words
+            result = re.sub(r"\b(a|an|the)\b", "", result, flags=re.IGNORECASE)
+            result = re.sub(r"\b(is|are|was|were)\b", "", result, flags=re.IGNORECASE)
+            # Collapse multiple spaces
+            result = re.sub(r"\s+", " ", result)
+
+        return result.strip()
+
+    @staticmethod
+    def build_compressed_prompt(
+        market_data: dict[str, Any],
+        include_instructions: bool = True,
+        max_length: int | None = None,
+    ) -> str:
+        """Build a compressed prompt from market data.
+
+        Args:
+            market_data: Market data dictionary with stock info
+            include_instructions: Whether to include full instructions
+            max_length: Maximum character length (truncates if needed)
+
+        Returns:
+            Compressed prompt string
+        """
+        # Abbreviated market name
+        market_name = market_data.get("market_name", "KR")
+        if "Korea" in market_name:
+            market_name = "KR"
+        elif "United States" in market_name or "US" in market_name:
+            market_name = "US"
+
+        # Core data - always included
+        core_info = {
+            "mkt": market_name,
+            "code": market_data["stock_code"],
+            "P": market_data["current_price"],
+        }
+
+        # Optional fields
+        if "orderbook" in market_data and market_data["orderbook"]:
+            ob = market_data["orderbook"]
+            # Compress orderbook: keep only top 3 levels
+            compressed_ob = {
+                "bid": ob.get("bid", [])[:3],
+                "ask": ob.get("ask", [])[:3],
+            }
+            core_info["ob"] = compressed_ob
+
+        if market_data.get("foreigner_net", 0) != 0:
+            core_info["fgn_net"] = market_data["foreigner_net"]
+
+        # Compress to JSON
+        data_str = PromptOptimizer.compress_json(core_info)
+
+        if include_instructions:
+            # Minimal instructions
+            prompt = (
+                f"{market_name} trader. Analyze:\n{data_str}\n\n"
+                'Return JSON: {"act":"BUY"|"SELL"|"HOLD","conf":<0-100>,"reason":"<text>"}\n'
+                "Rules: act=BUY/SELL/HOLD, conf=0-100, reason=concise. No markdown."
+            )
+        else:
+            # Data only (for cached contexts where instructions are known)
+            prompt = data_str
+
+        # Truncate if needed
+        if max_length and len(prompt) > max_length:
+            prompt = prompt[:max_length] + "..."
+
+        return prompt
+
+    @staticmethod
+    def truncate_context(
+        context: dict[str, Any],
+        max_tokens: int,
+        priority_keys: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Truncate context data to fit within token budget.
+
+        Keeps high-priority keys first, then truncates less important data.
+
+        Args:
+            context: Context dictionary to truncate
+            max_tokens: Maximum token budget
+            priority_keys: List of keys to keep (in order of priority)
+
+        Returns:
+            Truncated context dictionary
+        """
+        if not context:
+            return {}
+
+        if priority_keys is None:
+            priority_keys = []
+
+        result: dict[str, Any] = {}
+        current_tokens = 0
+
+        # Add priority keys first
+        for key in priority_keys:
+            if key in context:
+                value_str = json.dumps(context[key])
+                tokens = PromptOptimizer.estimate_tokens(value_str)
+
+                if current_tokens + tokens <= max_tokens:
+                    result[key] = context[key]
+                    current_tokens += tokens
+                else:
+                    break
+
+        # Add remaining keys if space available
+        for key, value in context.items():
+            if key in result:
+                continue
+
+            value_str = json.dumps(value)
+            tokens = PromptOptimizer.estimate_tokens(value_str)
+
+            if current_tokens + tokens <= max_tokens:
+                result[key] = value
+                current_tokens += tokens
+            else:
+                break
+
+        return result
+
+    @staticmethod
+    def calculate_compression_ratio(original: str, compressed: str) -> float:
+        """Calculate compression ratio between original and compressed text.
+
+        Args:
+            original: Original text
+            compressed: Compressed text
+
+        Returns:
+            Compression ratio (original_tokens / compressed_tokens)
+        """
+        original_tokens = PromptOptimizer.estimate_tokens(original)
+        compressed_tokens = PromptOptimizer.estimate_tokens(compressed)
+
+        if compressed_tokens == 0:
+            return 1.0
+
+        return original_tokens / compressed_tokens

src/broker/kis_api.py

@@ -55,6 +55,7 @@ class KISBroker:
         self._session: aiohttp.ClientSession | None = None
         self._access_token: str | None = None
         self._token_expires_at: float = 0.0
+        self._token_lock = asyncio.Lock()
         self._rate_limiter = LeakyBucket(settings.RATE_LIMIT_RPS)
 
     def _get_session(self) -> aiohttp.ClientSession:
@@ -80,30 +81,42 @@ class KISBroker:
     # ------------------------------------------------------------------
 
     async def _ensure_token(self) -> str:
-        """Return a valid access token, refreshing if expired."""
+        """Return a valid access token, refreshing if expired.
+
+        Uses a lock to prevent concurrent token refresh attempts that would
+        hit the API's 1-per-minute rate limit (EGW00133).
+        """
+        # Fast path: check without lock
         now = asyncio.get_event_loop().time()
         if self._access_token and now < self._token_expires_at:
             return self._access_token
 
-        logger.info("Refreshing KIS access token")
+        # Slow path: acquire lock and refresh
-        session = self._get_session()
+        async with self._token_lock:
-        url = f"{self._base_url}/oauth2/tokenP"
+            # Re-check after acquiring lock (another coroutine may have refreshed)
-        body = {
+            now = asyncio.get_event_loop().time()
-            "grant_type": "client_credentials",
+            if self._access_token and now < self._token_expires_at:
-            "appkey": self._app_key,
+                return self._access_token
-            "appsecret": self._app_secret,
-        }
 
-        async with session.post(url, json=body) as resp:
+            logger.info("Refreshing KIS access token")
-            if resp.status != 200:
+            session = self._get_session()
-                text = await resp.text()
+            url = f"{self._base_url}/oauth2/tokenP"
-                raise ConnectionError(f"Token refresh failed ({resp.status}): {text}")
+            body = {
-            data = await resp.json()
+                "grant_type": "client_credentials",
+                "appkey": self._app_key,
+                "appsecret": self._app_secret,
+            }
 
-        self._access_token = data["access_token"]
+            async with session.post(url, json=body) as resp:
-        self._token_expires_at = now + data.get("expires_in", 86400) - 60  # 1-min buffer
+                if resp.status != 200:
-        logger.info("Token refreshed successfully")
+                    text = await resp.text()
-        return self._access_token
+                    raise ConnectionError(f"Token refresh failed ({resp.status}): {text}")
+                data = await resp.json()
+
+            self._access_token = data["access_token"]
+            self._token_expires_at = now + data.get("expires_in", 86400) - 60  # 1-min buffer
+            logger.info("Token refreshed successfully")
+            return self._access_token
 
     # ------------------------------------------------------------------
     # Hash Key (required for POST bodies)

src/config.py

@@ -19,6 +19,15 @@ class Settings(BaseSettings):
     GEMINI_API_KEY: str
     GEMINI_MODEL: str = "gemini-pro"
 
+    # External Data APIs (optional — for data-driven decisions)
+    NEWS_API_KEY: str | None = None
+    NEWS_API_PROVIDER: str = "alphavantage"  # "alphavantage" or "newsapi"
+    MARKET_DATA_API_KEY: str | None = None
+
+    # Legacy field names (for backward compatibility)
+    ALPHA_VANTAGE_API_KEY: str | None = None
+    NEWSAPI_KEY: str | None = None
+
     # Risk Management
     CIRCUIT_BREAKER_PCT: float = Field(default=-3.0, le=0.0)
     FAT_FINGER_PCT: float = Field(default=30.0, gt=0.0, le=100.0)
@@ -36,6 +45,20 @@ class Settings(BaseSettings):
     # Market selection (comma-separated market codes)
     ENABLED_MARKETS: str = "KR"
 
+    # Backup and Disaster Recovery (optional)
+    BACKUP_ENABLED: bool = True
+    BACKUP_DIR: str = "data/backups"
+    S3_ENDPOINT_URL: str | None = None  # For MinIO, Backblaze B2, etc.
+    S3_ACCESS_KEY: str | None = None
+    S3_SECRET_KEY: str | None = None
+    S3_BUCKET_NAME: str | None = None
+    S3_REGION: str = "us-east-1"
+
+    # Telegram Notifications (optional)
+    TELEGRAM_BOT_TOKEN: str | None = None
+    TELEGRAM_CHAT_ID: str | None = None
+    TELEGRAM_ENABLED: bool = True
+
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
     @property

src/context/summarizer.py

@@ -0,0 +1,328 @@
+"""Context summarization for efficient historical data representation.
+
+This module summarizes old context data instead of including raw details:
+- Key metrics only (averages, trends, not details)
+- Rolling window (keep last N days detailed, summarize older)
+- Aggregate historical data efficiently
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from src.context.layer import ContextLayer
+from src.context.store import ContextStore
+
+
+@dataclass(frozen=True)
+class SummaryStats:
+    """Statistical summary of historical data."""
+
+    count: int
+    mean: float | None = None
+    min: float | None = None
+    max: float | None = None
+    std: float | None = None
+    trend: str | None = None  # "up", "down", "flat"
+
+
+class ContextSummarizer:
+    """Summarizes historical context data to reduce token usage."""
+
+    def __init__(self, store: ContextStore) -> None:
+        """Initialize the context summarizer.
+
+        Args:
+            store: ContextStore instance for retrieving context data
+        """
+        self.store = store
+
+    def summarize_numeric_values(self, values: list[float]) -> SummaryStats:
+        """Summarize a list of numeric values.
+
+        Args:
+            values: List of numeric values to summarize
+
+        Returns:
+            SummaryStats with mean, min, max, std, and trend
+        """
+        if not values:
+            return SummaryStats(count=0)
+
+        count = len(values)
+        mean = sum(values) / count
+        min_val = min(values)
+        max_val = max(values)
+
+        # Calculate standard deviation
+        if count > 1:
+            variance = sum((x - mean) ** 2 for x in values) / (count - 1)
+            std = variance**0.5
+        else:
+            std = 0.0
+
+        # Determine trend
+        trend = "flat"
+        if count >= 3:
+            # Simple trend: compare first third vs last third
+            first_third = values[: count // 3]
+            last_third = values[-(count // 3) :]
+            first_avg = sum(first_third) / len(first_third)
+            last_avg = sum(last_third) / len(last_third)
+
+            # Trend threshold: 5% change
+            threshold = 0.05 * abs(first_avg) if first_avg != 0 else 0.01
+
+            if last_avg > first_avg + threshold:
+                trend = "up"
+            elif last_avg < first_avg - threshold:
+                trend = "down"
+
+        return SummaryStats(
+            count=count,
+            mean=round(mean, 4),
+            min=round(min_val, 4),
+            max=round(max_val, 4),
+            std=round(std, 4),
+            trend=trend,
+        )
+
+    def summarize_layer(
+        self,
+        layer: ContextLayer,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+    ) -> dict[str, Any]:
+        """Summarize all context data for a layer within a date range.
+
+        Args:
+            layer: Context layer to summarize
+            start_date: Start date (inclusive), None for all
+            end_date: End date (inclusive), None for now
+
+        Returns:
+            Dictionary with summarized metrics
+        """
+        if end_date is None:
+            end_date = datetime.now(UTC)
+
+        # Get all contexts for this layer
+        all_contexts = self.store.get_all_contexts(layer)
+
+        if not all_contexts:
+            return {"summary": "No data available", "count": 0}
+
+        # Group numeric values by key
+        numeric_data: dict[str, list[float]] = {}
+        text_data: dict[str, list[str]] = {}
+
+        for key, value in all_contexts.items():
+            # Try to extract numeric values
+            if isinstance(value, (int, float)):
+                if key not in numeric_data:
+                    numeric_data[key] = []
+                numeric_data[key].append(float(value))
+            elif isinstance(value, dict):
+                # Extract numeric fields from dict
+                for subkey, subvalue in value.items():
+                    if isinstance(subvalue, (int, float)):
+                        full_key = f"{key}.{subkey}"
+                        if full_key not in numeric_data:
+                            numeric_data[full_key] = []
+                        numeric_data[full_key].append(float(subvalue))
+            elif isinstance(value, str):
+                if key not in text_data:
+                    text_data[key] = []
+                text_data[key].append(value)
+
+        # Summarize numeric data
+        summary: dict[str, Any] = {}
+
+        for key, values in numeric_data.items():
+            stats = self.summarize_numeric_values(values)
+            summary[key] = {
+                "count": stats.count,
+                "avg": stats.mean,
+                "range": [stats.min, stats.max],
+                "trend": stats.trend,
+            }
+
+        # Summarize text data (just counts)
+        for key, values in text_data.items():
+            summary[f"{key}_count"] = len(values)
+
+        summary["total_entries"] = len(all_contexts)
+
+        return summary
+
+    def rolling_window_summary(
+        self,
+        layer: ContextLayer,
+        window_days: int = 30,
+        summarize_older: bool = True,
+    ) -> dict[str, Any]:
+        """Create a rolling window summary.
+
+        Recent data (within window) is kept detailed.
+        Older data is summarized to key metrics.
+
+        Args:
+            layer: Context layer to summarize
+            window_days: Number of days to keep detailed
+            summarize_older: Whether to summarize data older than window
+
+        Returns:
+            Dictionary with recent (detailed) and historical (summary) data
+        """
+        result: dict[str, Any] = {
+            "window_days": window_days,
+            "recent_data": {},
+            "historical_summary": {},
+        }
+
+        # Get all contexts
+        all_contexts = self.store.get_all_contexts(layer)
+
+        recent_values: dict[str, list[float]] = {}
+        historical_values: dict[str, list[float]] = {}
+
+        for key, value in all_contexts.items():
+            # For simplicity, treat all numeric values
+            if isinstance(value, (int, float)):
+                # Note: We don't have timestamps in context keys
+                # This is a simplified implementation
+                # In practice, would need to check timeframe field
+
+                # For now, put recent data in window
+                if key not in recent_values:
+                    recent_values[key] = []
+                recent_values[key].append(float(value))
+
+        # Detailed recent data
+        result["recent_data"] = {key: values[-10:] for key, values in recent_values.items()}
+
+        # Summarized historical data
+        if summarize_older:
+            for key, values in historical_values.items():
+                stats = self.summarize_numeric_values(values)
+                result["historical_summary"][key] = {
+                    "count": stats.count,
+                    "avg": stats.mean,
+                    "trend": stats.trend,
+                }
+
+        return result
+
+    def aggregate_to_higher_layer(
+        self,
+        source_layer: ContextLayer,
+        target_layer: ContextLayer,
+        metric_key: str,
+        aggregation_func: str = "mean",
+    ) -> float | None:
+        """Aggregate data from source layer to target layer.
+
+        Args:
+            source_layer: Source context layer (more granular)
+            target_layer: Target context layer (less granular)
+            metric_key: Key of metric to aggregate
+            aggregation_func: Aggregation function ("mean", "sum", "max", "min")
+
+        Returns:
+            Aggregated value, or None if no data available
+        """
+        # Get all contexts from source layer
+        source_contexts = self.store.get_all_contexts(source_layer)
+
+        # Extract values for metric_key
+        values = []
+        for key, value in source_contexts.items():
+            if key == metric_key and isinstance(value, (int, float)):
+                values.append(float(value))
+            elif isinstance(value, dict) and metric_key in value:
+                subvalue = value[metric_key]
+                if isinstance(subvalue, (int, float)):
+                    values.append(float(subvalue))
+
+        if not values:
+            return None
+
+        # Apply aggregation function
+        if aggregation_func == "mean":
+            return sum(values) / len(values)
+        elif aggregation_func == "sum":
+            return sum(values)
+        elif aggregation_func == "max":
+            return max(values)
+        elif aggregation_func == "min":
+            return min(values)
+        else:
+            return sum(values) / len(values)  # Default to mean
+
+    def create_compact_summary(
+        self,
+        layers: list[ContextLayer],
+        top_n_metrics: int = 5,
+    ) -> dict[str, Any]:
+        """Create a compact summary across multiple layers.
+
+        Args:
+            layers: List of context layers to summarize
+            top_n_metrics: Number of top metrics to include per layer
+
+        Returns:
+            Compact summary dictionary
+        """
+        summary: dict[str, Any] = {}
+
+        for layer in layers:
+            layer_summary = self.summarize_layer(layer)
+
+            # Keep only top N metrics (by count/relevance)
+            metrics = []
+            for key, value in layer_summary.items():
+                if isinstance(value, dict) and "count" in value:
+                    metrics.append((key, value, value["count"]))
+
+            # Sort by count (descending)
+            metrics.sort(key=lambda x: x[2], reverse=True)
+
+            # Keep top N
+            top_metrics = {m[0]: m[1] for m in metrics[:top_n_metrics]}
+
+            summary[layer.value] = top_metrics
+
+        return summary
+
+    def format_summary_for_prompt(self, summary: dict[str, Any]) -> str:
+        """Format summary for inclusion in a prompt.
+
+        Args:
+            summary: Summary dictionary
+
+        Returns:
+            Formatted string for prompt
+        """
+        lines = []
+
+        for layer, metrics in summary.items():
+            if not metrics:
+                continue
+
+            lines.append(f"{layer}:")
+            for key, value in metrics.items():
+                if isinstance(value, dict):
+                    # Format as: key: avg=X, trend=Y
+                    parts = []
+                    if "avg" in value and value["avg"] is not None:
+                        parts.append(f"avg={value['avg']:.2f}")
+                    if "trend" in value and value["trend"]:
+                        parts.append(f"trend={value['trend']}")
+                    if parts:
+                        lines.append(f"  {key}: {', '.join(parts)}")
+                else:
+                    lines.append(f"  {key}: {value}")
+
+        return "\n".join(lines)

src/core/criticality.py

@@ -0,0 +1,110 @@
+"""Criticality assessment for urgency-based response system.
+
+Evaluates market conditions to determine response urgency and enable
+faster reactions in critical situations.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class CriticalityLevel(StrEnum):
+    """Urgency levels for market conditions and trading decisions."""
+
+    CRITICAL = "CRITICAL"  # <5s timeout - Emergency response required
+    HIGH = "HIGH"  # <30s timeout - Elevated priority
+    NORMAL = "NORMAL"  # <60s timeout - Standard processing
+    LOW = "LOW"  # No timeout - Batch processing
+
+
+class CriticalityAssessor:
+    """Assesses market conditions to determine response criticality level."""
+
+    def __init__(
+        self,
+        critical_pnl_threshold: float = -2.5,
+        critical_price_change_threshold: float = 5.0,
+        critical_volume_surge_threshold: float = 10.0,
+        high_volatility_threshold: float = 70.0,
+        low_volatility_threshold: float = 30.0,
+    ) -> None:
+        """Initialize the criticality assessor.
+
+        Args:
+            critical_pnl_threshold: P&L % that triggers CRITICAL (default -2.5%)
+            critical_price_change_threshold: Price change % that triggers CRITICAL
+                (default 5.0% in 1 minute)
+            critical_volume_surge_threshold: Volume surge ratio that triggers CRITICAL
+                (default 10x average)
+            high_volatility_threshold: Volatility score that triggers HIGH
+                (default 70.0)
+            low_volatility_threshold: Volatility score below which is LOW
+                (default 30.0)
+        """
+        self.critical_pnl_threshold = critical_pnl_threshold
+        self.critical_price_change_threshold = critical_price_change_threshold
+        self.critical_volume_surge_threshold = critical_volume_surge_threshold
+        self.high_volatility_threshold = high_volatility_threshold
+        self.low_volatility_threshold = low_volatility_threshold
+
+    def assess_market_conditions(
+        self,
+        pnl_pct: float,
+        volatility_score: float,
+        volume_surge: float,
+        price_change_1m: float = 0.0,
+        is_market_open: bool = True,
+    ) -> CriticalityLevel:
+        """Assess criticality level based on market conditions.
+
+        Args:
+            pnl_pct: Current P&L percentage
+            volatility_score: Momentum score from VolatilityAnalyzer (0-100)
+            volume_surge: Volume surge ratio (current / average)
+            price_change_1m: 1-minute price change percentage
+            is_market_open: Whether the market is currently open
+
+        Returns:
+            CriticalityLevel indicating required response urgency
+        """
+        # Market closed or very quiet → LOW priority (batch processing)
+        if not is_market_open or volatility_score < self.low_volatility_threshold:
+            return CriticalityLevel.LOW
+
+        # CRITICAL conditions: immediate action required
+        # 1. P&L near circuit breaker (-2.5% is close to -3.0% breaker)
+        if pnl_pct <= self.critical_pnl_threshold:
+            return CriticalityLevel.CRITICAL
+
+        # 2. Large sudden price movement (>5% in 1 minute)
+        if abs(price_change_1m) >= self.critical_price_change_threshold:
+            return CriticalityLevel.CRITICAL
+
+        # 3. Extreme volume surge (>10x average) indicates major event
+        if volume_surge >= self.critical_volume_surge_threshold:
+            return CriticalityLevel.CRITICAL
+
+        # HIGH priority: elevated volatility requires faster response
+        if volatility_score >= self.high_volatility_threshold:
+            return CriticalityLevel.HIGH
+
+        # NORMAL: standard trading conditions
+        return CriticalityLevel.NORMAL
+
+    def get_timeout(self, level: CriticalityLevel) -> float | None:
+        """Get timeout in seconds for a given criticality level.
+
+        Args:
+            level: Criticality level
+
+        Returns:
+            Timeout in seconds, or None for no timeout (LOW priority)
+        """
+        timeout_map = {
+            CriticalityLevel.CRITICAL: 5.0,
+            CriticalityLevel.HIGH: 30.0,
+            CriticalityLevel.NORMAL: 60.0,
+            CriticalityLevel.LOW: None,
+        }
+        return timeout_map[level]

src/core/priority_queue.py

@@ -0,0 +1,291 @@
+"""Priority-based task queue for latency control.
+
+Implements a thread-safe priority queue with timeout enforcement and metrics tracking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import heapq
+import logging
+import time
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from typing import Any
+
+from src.core.criticality import CriticalityLevel
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(order=True)
+class PriorityTask:
+    """Task with priority and timestamp for queue ordering."""
+
+    # Lower priority value = higher urgency (CRITICAL=0, HIGH=1, NORMAL=2, LOW=3)
+    priority: int
+    timestamp: float
+    # Task data not used in comparison
+    task_id: str = field(compare=False)
+    task_data: dict[str, Any] = field(compare=False, default_factory=dict)
+    callback: Callable[[], Coroutine[Any, Any, Any]] | None = field(
+        compare=False, default=None
+    )
+
+
+@dataclass
+class QueueMetrics:
+    """Metrics for priority queue performance monitoring."""
+
+    total_enqueued: int = 0
+    total_dequeued: int = 0
+    total_timeouts: int = 0
+    total_errors: int = 0
+    current_size: int = 0
+    # Average wait time per criticality level (in seconds)
+    avg_wait_time: dict[CriticalityLevel, float] = field(default_factory=dict)
+    # P95 wait time per criticality level
+    p95_wait_time: dict[CriticalityLevel, float] = field(default_factory=dict)
+
+
+class PriorityTaskQueue:
+    """Thread-safe priority queue with timeout enforcement."""
+
+    # Priority mapping for criticality levels
+    PRIORITY_MAP = {
+        CriticalityLevel.CRITICAL: 0,
+        CriticalityLevel.HIGH: 1,
+        CriticalityLevel.NORMAL: 2,
+        CriticalityLevel.LOW: 3,
+    }
+
+    def __init__(self, max_size: int = 1000) -> None:
+        """Initialize the priority task queue.
+
+        Args:
+            max_size: Maximum queue size (default 1000)
+        """
+        self._queue: list[PriorityTask] = []
+        self._lock = asyncio.Lock()
+        self._max_size = max_size
+        self._metrics = QueueMetrics()
+        # Track wait times for metrics
+        self._wait_times: dict[CriticalityLevel, list[float]] = {
+            level: [] for level in CriticalityLevel
+        }
+
+    async def enqueue(
+        self,
+        task_id: str,
+        criticality: CriticalityLevel,
+        task_data: dict[str, Any],
+        callback: Callable[[], Coroutine[Any, Any, Any]] | None = None,
+    ) -> bool:
+        """Add a task to the priority queue.
+
+        Args:
+            task_id: Unique identifier for the task
+            criticality: Criticality level determining priority
+            task_data: Data associated with the task
+            callback: Optional async callback to execute
+
+        Returns:
+            True if enqueued successfully, False if queue is full
+        """
+        async with self._lock:
+            if len(self._queue) >= self._max_size:
+                logger.warning(
+                    "Priority queue full (size=%d), rejecting task %s",
+                    len(self._queue),
+                    task_id,
+                )
+                return False
+
+            priority = self.PRIORITY_MAP[criticality]
+            timestamp = time.time()
+
+            task = PriorityTask(
+                priority=priority,
+                timestamp=timestamp,
+                task_id=task_id,
+                task_data=task_data,
+                callback=callback,
+            )
+
+            heapq.heappush(self._queue, task)
+            self._metrics.total_enqueued += 1
+            self._metrics.current_size = len(self._queue)
+
+            logger.debug(
+                "Enqueued task %s with criticality %s (priority=%d, queue_size=%d)",
+                task_id,
+                criticality.value,
+                priority,
+                len(self._queue),
+            )
+
+            return True
+
+    async def dequeue(self, timeout: float | None = None) -> PriorityTask | None:
+        """Remove and return the highest priority task from the queue.
+
+        Args:
+            timeout: Maximum time to wait for a task (seconds)
+
+        Returns:
+            PriorityTask if available, None if queue is empty or timeout
+        """
+        start_time = time.time()
+        deadline = start_time + timeout if timeout else None
+
+        while True:
+            async with self._lock:
+                if self._queue:
+                    task = heapq.heappop(self._queue)
+                    self._metrics.total_dequeued += 1
+                    self._metrics.current_size = len(self._queue)
+
+                    # Calculate wait time
+                    wait_time = time.time() - task.timestamp
+                    criticality = self._get_criticality_from_priority(task.priority)
+                    self._wait_times[criticality].append(wait_time)
+                    self._update_wait_time_metrics()
+
+                    logger.debug(
+                        "Dequeued task %s (priority=%d, wait_time=%.2fs, queue_size=%d)",
+                        task.task_id,
+                        task.priority,
+                        wait_time,
+                        len(self._queue),
+                    )
+
+                    return task
+
+            # Queue is empty
+            if deadline and time.time() >= deadline:
+                return None
+
+            # Wait a bit before checking again
+            await asyncio.sleep(0.1)
+
+    async def execute_with_timeout(
+        self,
+        task: PriorityTask,
+        timeout: float | None,
+    ) -> Any:
+        """Execute a task with timeout enforcement.
+
+        Args:
+            task: Task to execute
+            timeout: Timeout in seconds (None = no timeout)
+
+        Returns:
+            Result from task callback
+
+        Raises:
+            asyncio.TimeoutError: If task exceeds timeout
+            Exception: Any exception raised by the task callback
+        """
+        if not task.callback:
+            logger.warning("Task %s has no callback, skipping execution", task.task_id)
+            return None
+
+        criticality = self._get_criticality_from_priority(task.priority)
+
+        try:
+            if timeout:
+                result = await asyncio.wait_for(task.callback(), timeout=timeout)
+            else:
+                result = await task.callback()
+
+            logger.debug(
+                "Task %s completed successfully (criticality=%s)",
+                task.task_id,
+                criticality.value,
+            )
+            return result
+
+        except TimeoutError:
+            self._metrics.total_timeouts += 1
+            logger.error(
+                "Task %s timed out after %.2fs (criticality=%s)",
+                task.task_id,
+                timeout or 0.0,
+                criticality.value,
+            )
+            raise
+
+        except Exception as exc:
+            self._metrics.total_errors += 1
+            logger.exception(
+                "Task %s failed with error (criticality=%s): %s",
+                task.task_id,
+                criticality.value,
+                exc,
+            )
+            raise
+
+    def _get_criticality_from_priority(self, priority: int) -> CriticalityLevel:
+        """Convert priority back to criticality level."""
+        for level, prio in self.PRIORITY_MAP.items():
+            if prio == priority:
+                return level
+        return CriticalityLevel.NORMAL
+
+    def _update_wait_time_metrics(self) -> None:
+        """Update average and p95 wait time metrics."""
+        for level, times in self._wait_times.items():
+            if not times:
+                continue
+
+            # Keep only last 1000 measurements to avoid memory bloat
+            if len(times) > 1000:
+                self._wait_times[level] = times[-1000:]
+                times = self._wait_times[level]
+
+            # Calculate average
+            self._metrics.avg_wait_time[level] = sum(times) / len(times)
+
+            # Calculate P95
+            sorted_times = sorted(times)
+            p95_idx = int(len(sorted_times) * 0.95)
+            self._metrics.p95_wait_time[level] = sorted_times[p95_idx]
+
+    async def get_metrics(self) -> QueueMetrics:
+        """Get current queue metrics.
+
+        Returns:
+            QueueMetrics with current statistics
+        """
+        async with self._lock:
+            return QueueMetrics(
+                total_enqueued=self._metrics.total_enqueued,
+                total_dequeued=self._metrics.total_dequeued,
+                total_timeouts=self._metrics.total_timeouts,
+                total_errors=self._metrics.total_errors,
+                current_size=self._metrics.current_size,
+                avg_wait_time=dict(self._metrics.avg_wait_time),
+                p95_wait_time=dict(self._metrics.p95_wait_time),
+            )
+
+    async def size(self) -> int:
+        """Get current queue size.
+
+        Returns:
+            Number of tasks in queue
+        """
+        async with self._lock:
+            return len(self._queue)
+
+    async def clear(self) -> int:
+        """Clear all tasks from the queue.
+
+        Returns:
+            Number of tasks cleared
+        """
+        async with self._lock:
+            count = len(self._queue)
+            self._queue.clear()
+            self._metrics.current_size = 0
+            logger.info("Cleared %d tasks from priority queue", count)
+            return count

src/data/README.md

@@ -0,0 +1,205 @@
+# External Data Integration
+
+This module provides objective external data sources to enhance trading decisions beyond just market prices and user input.
+
+## Modules
+
+### `news_api.py` - News Sentiment Analysis
+
+Fetches real-time news for stocks with sentiment scoring.
+
+**Features:**
+- Alpha Vantage and NewsAPI.org support
+- Sentiment scoring (-1.0 to +1.0)
+- 5-minute caching to minimize API quota usage
+- Graceful fallback when API unavailable
+
+**Usage:**
+```python
+from src.data.news_api import NewsAPI
+
+# Initialize with API key
+news_api = NewsAPI(api_key="your_key", provider="alphavantage")
+
+# Fetch news sentiment
+sentiment = await news_api.get_news_sentiment("AAPL")
+if sentiment:
+    print(f"Average sentiment: {sentiment.avg_sentiment}")
+    for article in sentiment.articles[:3]:
+        print(f"{article.title} ({article.sentiment_score})")
+```
+
+### `economic_calendar.py` - Major Economic Events
+
+Tracks FOMC meetings, GDP releases, CPI, earnings calendars, and other market-moving events.
+
+**Features:**
+- High-impact event tracking (FOMC, GDP, CPI)
+- Earnings calendar per stock
+- Event proximity checking
+- Hardcoded major events for 2026 (no API required)
+
+**Usage:**
+```python
+from src.data.economic_calendar import EconomicCalendar
+
+calendar = EconomicCalendar()
+calendar.load_hardcoded_events()
+
+# Get upcoming high-impact events
+upcoming = calendar.get_upcoming_events(days_ahead=7, min_impact="HIGH")
+print(f"High-impact events: {upcoming.high_impact_count}")
+
+# Check if near earnings
+earnings_date = calendar.get_earnings_date("AAPL")
+if earnings_date:
+    print(f"Next earnings: {earnings_date}")
+
+# Check for high volatility period
+if calendar.is_high_volatility_period(hours_ahead=24):
+    print("High-impact event imminent!")
+```
+
+### `market_data.py` - Market Indicators
+
+Provides market breadth, sector performance, and sentiment indicators.
+
+**Features:**
+- Market sentiment levels (Fear & Greed equivalent)
+- Market breadth (advancing/declining stocks)
+- Sector performance tracking
+- Fear/Greed score calculation
+
+**Usage:**
+```python
+from src.data.market_data import MarketData
+
+market_data = MarketData(api_key="your_key")
+
+# Get market sentiment
+sentiment = market_data.get_market_sentiment()
+print(f"Market sentiment: {sentiment.name}")
+
+# Get full indicators
+indicators = market_data.get_market_indicators("US")
+print(f"Sentiment: {indicators.sentiment.name}")
+print(f"A/D Ratio: {indicators.breadth.advance_decline_ratio}")
+```
+
+## Integration with GeminiClient
+
+The external data sources are seamlessly integrated into the AI decision engine:
+
+```python
+from src.brain.gemini_client import GeminiClient
+from src.data.news_api import NewsAPI
+from src.data.economic_calendar import EconomicCalendar
+from src.data.market_data import MarketData
+from src.config import Settings
+
+settings = Settings()
+
+# Initialize data sources
+news_api = NewsAPI(api_key=settings.NEWS_API_KEY, provider=settings.NEWS_API_PROVIDER)
+calendar = EconomicCalendar()
+calendar.load_hardcoded_events()
+market_data = MarketData(api_key=settings.MARKET_DATA_API_KEY)
+
+# Create enhanced client
+client = GeminiClient(
+    settings,
+    news_api=news_api,
+    economic_calendar=calendar,
+    market_data=market_data
+)
+
+# Make decision with external context
+market_data_dict = {
+    "stock_code": "AAPL",
+    "current_price": 180.0,
+    "market_name": "US stock market"
+}
+
+decision = await client.decide(market_data_dict)
+```
+
+The external data is automatically included in the prompt sent to Gemini:
+
+```
+Market: US stock market
+Stock Code: AAPL
+Current Price: 180.0
+
+EXTERNAL DATA:
+News Sentiment: 0.85 (from 10 articles)
+  1. [Reuters] Apple hits record high (sentiment: 0.92)
+  2. [Bloomberg] Strong iPhone sales (sentiment: 0.78)
+  3. [CNBC] Tech sector rallying (sentiment: 0.85)
+
+Upcoming High-Impact Events: 2 in next 7 days
+  Next: FOMC Meeting (FOMC) on 2026-03-18
+  Earnings: AAPL on 2026-02-10
+
+Market Sentiment: GREED
+Advance/Decline Ratio: 2.35
+```
+
+## Configuration
+
+Add these to your `.env` file:
+
+```bash
+# External Data APIs (optional)
+NEWS_API_KEY=your_alpha_vantage_key
+NEWS_API_PROVIDER=alphavantage  # or "newsapi"
+MARKET_DATA_API_KEY=your_market_data_key
+```
+
+## API Recommendations
+
+### Alpha Vantage (News)
+- **Free tier:** 5 calls/min, 500 calls/day
+- **Pros:** Provides sentiment scores, no credit card required
+- **URL:** https://www.alphavantage.co/
+
+### NewsAPI.org
+- **Free tier:** 100 requests/day
+- **Pros:** Large news coverage, easy to use
+- **Cons:** No sentiment scores (we use keyword heuristics)
+- **URL:** https://newsapi.org/
+
+## Caching Strategy
+
+To minimize API quota usage:
+
+1. **News:** 5-minute TTL cache per stock
+2. **Economic Calendar:** Loaded once at startup (hardcoded events)
+3. **Market Data:** Fetched per decision (lightweight)
+
+## Graceful Degradation
+
+The system works gracefully without external data:
+
+- If no API keys provided → decisions work with just market prices
+- If API fails → decision continues without external context
+- If cache expired → attempts refetch, falls back to no data
+- Errors are logged but never block trading decisions
+
+## Testing
+
+All modules have comprehensive test coverage (81%+):
+
+```bash
+pytest tests/test_data_integration.py -v --cov=src/data
+```
+
+Tests use mocks to avoid requiring real API keys.
+
+## Future Enhancements
+
+- Twitter/X sentiment analysis
+- Reddit WallStreetBets sentiment
+- Options flow data
+- Insider trading activity
+- Analyst upgrades/downgrades
+- Real-time economic data APIs

src/data/__init__.py

@@ -0,0 +1,5 @@
+"""External data integration for objective decision-making."""
+
+from __future__ import annotations
+
+__all__ = ["NewsAPI", "EconomicCalendar", "MarketData"]

src/data/economic_calendar.py

@@ -0,0 +1,219 @@
+"""Economic calendar integration for major market events.
+
+Tracks FOMC meetings, GDP releases, CPI, earnings calendars, and other
+market-moving events.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EconomicEvent:
+    """Single economic event."""
+
+    name: str
+    event_type: str  # "FOMC", "GDP", "CPI", "EARNINGS", etc.
+    datetime: datetime
+    impact: str  # "HIGH", "MEDIUM", "LOW"
+    country: str
+    description: str
+
+
+@dataclass
+class UpcomingEvents:
+    """Collection of upcoming economic events."""
+
+    events: list[EconomicEvent]
+    high_impact_count: int
+    next_major_event: EconomicEvent | None
+
+
+class EconomicCalendar:
+    """Economic calendar with event tracking and impact scoring."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize economic calendar.
+
+        Args:
+            api_key: API key for calendar provider (None for testing/hardcoded)
+        """
+        self._api_key = api_key
+        # For now, use hardcoded major events (can be extended with API)
+        self._events: list[EconomicEvent] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_upcoming_events(
+        self, days_ahead: int = 7, min_impact: str = "MEDIUM"
+    ) -> UpcomingEvents:
+        """Get upcoming economic events within specified timeframe.
+
+        Args:
+            days_ahead: Number of days to look ahead
+            min_impact: Minimum impact level ("LOW", "MEDIUM", "HIGH")
+
+        Returns:
+            UpcomingEvents with filtered events
+        """
+        now = datetime.now()
+        end_date = now + timedelta(days=days_ahead)
+
+        # Filter events by timeframe and impact
+        upcoming = [
+            event
+            for event in self._events
+            if now <= event.datetime <= end_date
+            and self._impact_level(event.impact) >= self._impact_level(min_impact)
+        ]
+
+        # Sort by datetime
+        upcoming.sort(key=lambda e: e.datetime)
+
+        # Count high-impact events
+        high_impact_count = sum(1 for e in upcoming if e.impact == "HIGH")
+
+        # Get next major event
+        next_major = None
+        for event in upcoming:
+            if event.impact == "HIGH":
+                next_major = event
+                break
+
+        return UpcomingEvents(
+            events=upcoming,
+            high_impact_count=high_impact_count,
+            next_major_event=next_major,
+        )
+
+    def add_event(self, event: EconomicEvent) -> None:
+        """Add an economic event to the calendar."""
+        self._events.append(event)
+
+    def clear_events(self) -> None:
+        """Clear all events (useful for testing)."""
+        self._events.clear()
+
+    def get_earnings_date(self, stock_code: str) -> datetime | None:
+        """Get next earnings date for a stock.
+
+        Args:
+            stock_code: Stock ticker symbol
+
+        Returns:
+            Next earnings datetime or None if not found
+        """
+        now = datetime.now()
+        earnings_events = [
+            event
+            for event in self._events
+            if event.event_type == "EARNINGS"
+            and stock_code.upper() in event.name.upper()
+            and event.datetime > now
+        ]
+
+        if not earnings_events:
+            return None
+
+        # Return earliest upcoming earnings
+        earnings_events.sort(key=lambda e: e.datetime)
+        return earnings_events[0].datetime
+
+    def load_hardcoded_events(self) -> None:
+        """Load hardcoded major economic events for 2026.
+
+        This is a fallback when no API is available.
+        """
+        # Major FOMC meetings in 2026 (estimated)
+        fomc_dates = [
+            datetime(2026, 3, 18),
+            datetime(2026, 5, 6),
+            datetime(2026, 6, 17),
+            datetime(2026, 7, 29),
+            datetime(2026, 9, 16),
+            datetime(2026, 11, 4),
+            datetime(2026, 12, 16),
+        ]
+
+        for date in fomc_dates:
+            self.add_event(
+                EconomicEvent(
+                    name="FOMC Meeting",
+                    event_type="FOMC",
+                    datetime=date,
+                    impact="HIGH",
+                    country="US",
+                    description="Federal Reserve interest rate decision",
+                )
+            )
+
+        # Quarterly GDP releases (estimated)
+        gdp_dates = [
+            datetime(2026, 4, 28),
+            datetime(2026, 7, 30),
+            datetime(2026, 10, 29),
+        ]
+
+        for date in gdp_dates:
+            self.add_event(
+                EconomicEvent(
+                    name="US GDP Release",
+                    event_type="GDP",
+                    datetime=date,
+                    impact="HIGH",
+                    country="US",
+                    description="Quarterly GDP growth rate",
+                )
+            )
+
+        # Monthly CPI releases (12th of each month, estimated)
+        for month in range(1, 13):
+            try:
+                cpi_date = datetime(2026, month, 12)
+                self.add_event(
+                    EconomicEvent(
+                        name="US CPI Release",
+                        event_type="CPI",
+                        datetime=cpi_date,
+                        impact="HIGH",
+                        country="US",
+                        description="Consumer Price Index inflation data",
+                    )
+                )
+            except ValueError:
+                continue
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _impact_level(self, impact: str) -> int:
+        """Convert impact string to numeric level."""
+        levels = {"LOW": 1, "MEDIUM": 2, "HIGH": 3}
+        return levels.get(impact.upper(), 0)
+
+    def is_high_volatility_period(self, hours_ahead: int = 24) -> bool:
+        """Check if we're near a high-impact event.
+
+        Args:
+            hours_ahead: Number of hours to look ahead
+
+        Returns:
+            True if high-impact event is imminent
+        """
+        now = datetime.now()
+        threshold = now + timedelta(hours=hours_ahead)
+
+        for event in self._events:
+            if event.impact == "HIGH" and now <= event.datetime <= threshold:
+                return True
+
+        return False

src/data/market_data.py

@@ -0,0 +1,198 @@
+"""Additional market data indicators beyond basic price data.
+
+Provides market breadth, sector performance, and market sentiment indicators.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class MarketSentiment(Enum):
+    """Overall market sentiment levels."""
+
+    EXTREME_FEAR = 1
+    FEAR = 2
+    NEUTRAL = 3
+    GREED = 4
+    EXTREME_GREED = 5
+
+
+@dataclass
+class SectorPerformance:
+    """Performance metrics for a market sector."""
+
+    sector_name: str
+    daily_change_pct: float
+    weekly_change_pct: float
+    leader_stock: str  # Best performing stock in sector
+    laggard_stock: str  # Worst performing stock in sector
+
+
+@dataclass
+class MarketBreadth:
+    """Market breadth indicators."""
+
+    advancing_stocks: int
+    declining_stocks: int
+    unchanged_stocks: int
+    new_highs: int
+    new_lows: int
+    advance_decline_ratio: float
+
+
+@dataclass
+class MarketIndicators:
+    """Aggregated market indicators."""
+
+    sentiment: MarketSentiment
+    breadth: MarketBreadth
+    sector_performance: list[SectorPerformance]
+    vix_level: float | None  # Volatility index if available
+
+
+class MarketData:
+    """Market data provider for additional indicators."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize market data provider.
+
+        Args:
+            api_key: API key for data provider (None for testing)
+        """
+        self._api_key = api_key
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_market_sentiment(self) -> MarketSentiment:
+        """Get current market sentiment level.
+
+        This is a simplified version. In production, this would integrate
+        with Fear & Greed Index or similar sentiment indicators.
+
+        Returns:
+            MarketSentiment enum value
+        """
+        # Default to neutral when API not available
+        if self._api_key is None:
+            logger.debug("No market data API key — returning NEUTRAL sentiment")
+            return MarketSentiment.NEUTRAL
+
+        # TODO: Integrate with actual sentiment API
+        return MarketSentiment.NEUTRAL
+
+    def get_market_breadth(self, market: str = "US") -> MarketBreadth | None:
+        """Get market breadth indicators.
+
+        Args:
+            market: Market code ("US", "KR", etc.)
+
+        Returns:
+            MarketBreadth object or None if unavailable
+        """
+        if self._api_key is None:
+            logger.debug("No market data API key — returning None for breadth")
+            return None
+
+        # TODO: Integrate with actual market breadth API
+        return None
+
+    def get_sector_performance(
+        self, market: str = "US"
+    ) -> list[SectorPerformance]:
+        """Get sector performance rankings.
+
+        Args:
+            market: Market code ("US", "KR", etc.)
+
+        Returns:
+            List of SectorPerformance objects, sorted by daily change
+        """
+        if self._api_key is None:
+            logger.debug("No market data API key — returning empty sector list")
+            return []
+
+        # TODO: Integrate with actual sector performance API
+        return []
+
+    def get_market_indicators(self, market: str = "US") -> MarketIndicators:
+        """Get aggregated market indicators.
+
+        Args:
+            market: Market code ("US", "KR", etc.)
+
+        Returns:
+            MarketIndicators with all available data
+        """
+        sentiment = self.get_market_sentiment()
+        breadth = self.get_market_breadth(market)
+        sectors = self.get_sector_performance(market)
+
+        # Default breadth if unavailable
+        if breadth is None:
+            breadth = MarketBreadth(
+                advancing_stocks=0,
+                declining_stocks=0,
+                unchanged_stocks=0,
+                new_highs=0,
+                new_lows=0,
+                advance_decline_ratio=1.0,
+            )
+
+        return MarketIndicators(
+            sentiment=sentiment,
+            breadth=breadth,
+            sector_performance=sectors,
+            vix_level=None,  # TODO: Add VIX integration
+        )
+
+    # ------------------------------------------------------------------
+    # Helper Methods
+    # ------------------------------------------------------------------
+
+    def calculate_fear_greed_score(
+        self, breadth: MarketBreadth, vix: float | None = None
+    ) -> int:
+        """Calculate a simple fear/greed score (0-100).
+
+        Args:
+            breadth: Market breadth data
+            vix: VIX level (optional)
+
+        Returns:
+            Score from 0 (extreme fear) to 100 (extreme greed)
+        """
+        # Start at neutral
+        score = 50
+
+        # Adjust based on advance/decline ratio
+        if breadth.advance_decline_ratio > 1.5:
+            score += 20
+        elif breadth.advance_decline_ratio > 1.0:
+            score += 10
+        elif breadth.advance_decline_ratio < 0.5:
+            score -= 20
+        elif breadth.advance_decline_ratio < 1.0:
+            score -= 10
+
+        # Adjust based on new highs/lows
+        if breadth.new_highs > breadth.new_lows * 2:
+            score += 15
+        elif breadth.new_lows > breadth.new_highs * 2:
+            score -= 15
+
+        # Adjust based on VIX if available
+        if vix is not None:
+            if vix > 30:  # High volatility = fear
+                score -= 15
+            elif vix < 15:  # Low volatility = complacency/greed
+                score += 10
+
+        # Clamp to 0-100
+        return max(0, min(100, score))

src/data/news_api.py

@@ -0,0 +1,316 @@
+"""News API integration with sentiment analysis and caching.
+
+Fetches real-time news for stocks using free-tier APIs (Alpha Vantage or NewsAPI).
+Includes 5-minute caching to minimize API quota usage.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import aiohttp
+
+logger = logging.getLogger(__name__)
+
+# Cache entries expire after 5 minutes
+CACHE_TTL_SECONDS = 300
+
+
+@dataclass
+class NewsArticle:
+    """Single news article with sentiment."""
+
+    title: str
+    summary: str
+    source: str
+    published_at: str
+    sentiment_score: float  # -1.0 (negative) to +1.0 (positive)
+    url: str
+
+
+@dataclass
+class NewsSentiment:
+    """Aggregated news sentiment for a stock."""
+
+    stock_code: str
+    articles: list[NewsArticle]
+    avg_sentiment: float  # Average sentiment across all articles
+    article_count: int
+    fetched_at: float  # Unix timestamp
+
+
+class NewsAPI:
+    """News API client with sentiment analysis and caching."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        provider: str = "alphavantage",
+        cache_ttl: int = CACHE_TTL_SECONDS,
+    ) -> None:
+        """Initialize NewsAPI client.
+
+        Args:
+            api_key: API key for the news provider (None for testing)
+            provider: News provider ("alphavantage" or "newsapi")
+            cache_ttl: Cache time-to-live in seconds
+        """
+        self._api_key = api_key
+        self._provider = provider
+        self._cache_ttl = cache_ttl
+        self._cache: dict[str, NewsSentiment] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def get_news_sentiment(self, stock_code: str) -> NewsSentiment | None:
+        """Fetch news sentiment for a stock with caching.
+
+        Args:
+            stock_code: Stock ticker symbol (e.g., "AAPL", "005930")
+
+        Returns:
+            NewsSentiment object or None if fetch fails or API unavailable
+        """
+        # Check cache first
+        cached = self._get_from_cache(stock_code)
+        if cached is not None:
+            logger.debug("News cache hit for %s", stock_code)
+            return cached
+
+        # API key required for real requests
+        if self._api_key is None:
+            logger.warning("No news API key provided — returning None")
+            return None
+
+        # Fetch from API
+        try:
+            sentiment = await self._fetch_news(stock_code)
+            if sentiment is not None:
+                self._cache[stock_code] = sentiment
+            return sentiment
+        except Exception as exc:
+            logger.error("Failed to fetch news for %s: %s", stock_code, exc)
+            return None
+
+    def clear_cache(self) -> None:
+        """Clear the news cache (useful for testing)."""
+        self._cache.clear()
+
+    # ------------------------------------------------------------------
+    # Cache Management
+    # ------------------------------------------------------------------
+
+    def _get_from_cache(self, stock_code: str) -> NewsSentiment | None:
+        """Retrieve cached sentiment if not expired."""
+        if stock_code not in self._cache:
+            return None
+
+        cached = self._cache[stock_code]
+        age = time.time() - cached.fetched_at
+
+        if age > self._cache_ttl:
+            logger.debug("News cache expired for %s (age: %.1fs)", stock_code, age)
+            del self._cache[stock_code]
+            return None
+
+        return cached
+
+    # ------------------------------------------------------------------
+    # API Fetching
+    # ------------------------------------------------------------------
+
+    async def _fetch_news(self, stock_code: str) -> NewsSentiment | None:
+        """Fetch news from the provider API."""
+        if self._provider == "alphavantage":
+            return await self._fetch_alphavantage(stock_code)
+        elif self._provider == "newsapi":
+            return await self._fetch_newsapi(stock_code)
+        else:
+            logger.error("Unknown news provider: %s", self._provider)
+            return None
+
+    async def _fetch_alphavantage(self, stock_code: str) -> NewsSentiment | None:
+        """Fetch news from Alpha Vantage News Sentiment API."""
+        url = "https://www.alphavantage.co/query"
+        params = {
+            "function": "NEWS_SENTIMENT",
+            "tickers": stock_code,
+            "apikey": self._api_key,
+            "limit": 10,  # Fetch top 10 articles
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, params=params, timeout=10) as resp:
+                    if resp.status != 200:
+                        logger.error(
+                            "Alpha Vantage API error: HTTP %d", resp.status
+                        )
+                        return None
+
+                    data = await resp.json()
+                    return self._parse_alphavantage_response(stock_code, data)
+
+        except Exception as exc:
+            logger.error("Alpha Vantage request failed: %s", exc)
+            return None
+
+    async def _fetch_newsapi(self, stock_code: str) -> NewsSentiment | None:
+        """Fetch news from NewsAPI.org."""
+        url = "https://newsapi.org/v2/everything"
+        params = {
+            "q": stock_code,
+            "apiKey": self._api_key,
+            "pageSize": 10,
+            "sortBy": "publishedAt",
+            "language": "en",
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, params=params, timeout=10) as resp:
+                    if resp.status != 200:
+                        logger.error("NewsAPI error: HTTP %d", resp.status)
+                        return None
+
+                    data = await resp.json()
+                    return self._parse_newsapi_response(stock_code, data)
+
+        except Exception as exc:
+            logger.error("NewsAPI request failed: %s", exc)
+            return None
+
+    # ------------------------------------------------------------------
+    # Response Parsing
+    # ------------------------------------------------------------------
+
+    def _parse_alphavantage_response(
+        self, stock_code: str, data: dict[str, Any]
+    ) -> NewsSentiment | None:
+        """Parse Alpha Vantage API response."""
+        if "feed" not in data:
+            logger.warning("No 'feed' key in Alpha Vantage response")
+            return None
+
+        articles: list[NewsArticle] = []
+        for item in data["feed"]:
+            # Extract sentiment for this specific ticker
+            ticker_sentiment = self._extract_ticker_sentiment(item, stock_code)
+
+            article = NewsArticle(
+                title=item.get("title", ""),
+                summary=item.get("summary", "")[:200],  # Truncate long summaries
+                source=item.get("source", "Unknown"),
+                published_at=item.get("time_published", ""),
+                sentiment_score=ticker_sentiment,
+                url=item.get("url", ""),
+            )
+            articles.append(article)
+
+        if not articles:
+            return None
+
+        avg_sentiment = sum(a.sentiment_score for a in articles) / len(articles)
+
+        return NewsSentiment(
+            stock_code=stock_code,
+            articles=articles,
+            avg_sentiment=avg_sentiment,
+            article_count=len(articles),
+            fetched_at=time.time(),
+        )
+
+    def _extract_ticker_sentiment(
+        self, item: dict[str, Any], stock_code: str
+    ) -> float:
+        """Extract sentiment score for specific ticker from article."""
+        ticker_sentiments = item.get("ticker_sentiment", [])
+        for ts in ticker_sentiments:
+            if ts.get("ticker", "").upper() == stock_code.upper():
+                # Alpha Vantage provides sentiment_score as string
+                score_str = ts.get("ticker_sentiment_score", "0")
+                try:
+                    return float(score_str)
+                except ValueError:
+                    return 0.0
+
+        # Fallback to overall sentiment if ticker-specific not found
+        overall_sentiment = item.get("overall_sentiment_score", "0")
+        try:
+            return float(overall_sentiment)
+        except ValueError:
+            return 0.0
+
+    def _parse_newsapi_response(
+        self, stock_code: str, data: dict[str, Any]
+    ) -> NewsSentiment | None:
+        """Parse NewsAPI.org response.
+
+        Note: NewsAPI doesn't provide sentiment scores, so we use a
+        simple heuristic based on title keywords.
+        """
+        if data.get("status") != "ok" or "articles" not in data:
+            logger.warning("Invalid NewsAPI response")
+            return None
+
+        articles: list[NewsArticle] = []
+        for item in data["articles"]:
+            # Simple sentiment heuristic based on keywords
+            sentiment = self._estimate_sentiment_from_text(
+                item.get("title", "") + " " + item.get("description", "")
+            )
+
+            article = NewsArticle(
+                title=item.get("title", ""),
+                summary=item.get("description", "")[:200],
+                source=item.get("source", {}).get("name", "Unknown"),
+                published_at=item.get("publishedAt", ""),
+                sentiment_score=sentiment,
+                url=item.get("url", ""),
+            )
+            articles.append(article)
+
+        if not articles:
+            return None
+
+        avg_sentiment = sum(a.sentiment_score for a in articles) / len(articles)
+
+        return NewsSentiment(
+            stock_code=stock_code,
+            articles=articles,
+            avg_sentiment=avg_sentiment,
+            article_count=len(articles),
+            fetched_at=time.time(),
+        )
+
+    def _estimate_sentiment_from_text(self, text: str) -> float:
+        """Simple keyword-based sentiment estimation.
+
+        This is a fallback for APIs that don't provide sentiment scores.
+        Returns a score between -1.0 and +1.0.
+        """
+        text_lower = text.lower()
+
+        positive_keywords = [
+            "surge", "jump", "gain", "rise", "soar", "rally", "profit",
+            "growth", "upgrade", "beat", "strong", "bullish", "breakthrough",
+        ]
+        negative_keywords = [
+            "plunge", "fall", "drop", "decline", "crash", "loss", "weak",
+            "downgrade", "miss", "bearish", "concern", "risk", "warning",
+        ]
+
+        positive_count = sum(1 for kw in positive_keywords if kw in text_lower)
+        negative_count = sum(1 for kw in negative_keywords if kw in text_lower)
+
+        total = positive_count + negative_count
+        if total == 0:
+            return 0.0
+
+        # Normalize to -1.0 to +1.0 range
+        return (positive_count - negative_count) / total

src/evolution/__init__.py

@@ -0,0 +1,19 @@
+"""Evolution engine for self-improving trading strategies."""
+
+from src.evolution.ab_test import ABTester, ABTestResult, StrategyPerformance
+from src.evolution.optimizer import EvolutionOptimizer
+from src.evolution.performance_tracker import (
+    PerformanceDashboard,
+    PerformanceTracker,
+    StrategyMetrics,
+)
+
+__all__ = [
+    "EvolutionOptimizer",
+    "ABTester",
+    "ABTestResult",
+    "StrategyPerformance",
+    "PerformanceTracker",
+    "PerformanceDashboard",
+    "StrategyMetrics",
+]

src/evolution/ab_test.py

@@ -0,0 +1,220 @@
+"""A/B Testing framework for strategy comparison.
+
+Runs multiple strategies in parallel, tracks their performance,
+and uses statistical significance testing to determine winners.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import scipy.stats as stats
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StrategyPerformance:
+    """Performance metrics for a single strategy."""
+
+    strategy_name: str
+    total_trades: int
+    wins: int
+    losses: int
+    total_pnl: float
+    avg_pnl: float
+    win_rate: float
+    sharpe_ratio: float | None = None
+
+
+@dataclass
+class ABTestResult:
+    """Result of an A/B test between two strategies."""
+
+    strategy_a: str
+    strategy_b: str
+    winner: str | None
+    p_value: float
+    confidence_level: float
+    is_significant: bool
+    performance_a: StrategyPerformance
+    performance_b: StrategyPerformance
+
+
+class ABTester:
+    """A/B testing framework for comparing trading strategies."""
+
+    def __init__(self, significance_level: float = 0.05) -> None:
+        """Initialize A/B tester.
+
+        Args:
+            significance_level: P-value threshold for statistical significance (default 0.05)
+        """
+        self._significance_level = significance_level
+
+    def calculate_performance(
+        self, trades: list[dict[str, Any]], strategy_name: str
+    ) -> StrategyPerformance:
+        """Calculate performance metrics for a strategy.
+
+        Args:
+            trades: List of trade records with pnl values
+            strategy_name: Name of the strategy
+
+        Returns:
+            StrategyPerformance object with calculated metrics
+        """
+        if not trades:
+            return StrategyPerformance(
+                strategy_name=strategy_name,
+                total_trades=0,
+                wins=0,
+                losses=0,
+                total_pnl=0.0,
+                avg_pnl=0.0,
+                win_rate=0.0,
+                sharpe_ratio=None,
+            )
+
+        total_trades = len(trades)
+        wins = sum(1 for t in trades if t.get("pnl", 0) > 0)
+        losses = sum(1 for t in trades if t.get("pnl", 0) < 0)
+        pnls = [t.get("pnl", 0.0) for t in trades]
+        total_pnl = sum(pnls)
+        avg_pnl = total_pnl / total_trades if total_trades > 0 else 0.0
+        win_rate = (wins / total_trades * 100) if total_trades > 0 else 0.0
+
+        # Calculate Sharpe ratio (risk-adjusted return)
+        sharpe_ratio = None
+        if len(pnls) > 1:
+            mean_return = avg_pnl
+            std_return = (
+                sum((p - mean_return) ** 2 for p in pnls) / (len(pnls) - 1)
+            ) ** 0.5
+            if std_return > 0:
+                sharpe_ratio = mean_return / std_return
+
+        return StrategyPerformance(
+            strategy_name=strategy_name,
+            total_trades=total_trades,
+            wins=wins,
+            losses=losses,
+            total_pnl=round(total_pnl, 2),
+            avg_pnl=round(avg_pnl, 2),
+            win_rate=round(win_rate, 2),
+            sharpe_ratio=round(sharpe_ratio, 4) if sharpe_ratio else None,
+        )
+
+    def compare_strategies(
+        self,
+        trades_a: list[dict[str, Any]],
+        trades_b: list[dict[str, Any]],
+        strategy_a_name: str = "Strategy A",
+        strategy_b_name: str = "Strategy B",
+    ) -> ABTestResult:
+        """Compare two strategies using statistical testing.
+
+        Uses a two-sample t-test to determine if performance difference is significant.
+
+        Args:
+            trades_a: List of trades from strategy A
+            trades_b: List of trades from strategy B
+            strategy_a_name: Name of strategy A
+            strategy_b_name: Name of strategy B
+
+        Returns:
+            ABTestResult with comparison details
+        """
+        perf_a = self.calculate_performance(trades_a, strategy_a_name)
+        perf_b = self.calculate_performance(trades_b, strategy_b_name)
+
+        # Extract PnL arrays for statistical testing
+        pnls_a = [t.get("pnl", 0.0) for t in trades_a]
+        pnls_b = [t.get("pnl", 0.0) for t in trades_b]
+
+        # Perform two-sample t-test
+        if len(pnls_a) > 1 and len(pnls_b) > 1:
+            t_stat, p_value = stats.ttest_ind(pnls_a, pnls_b, equal_var=False)
+            is_significant = p_value < self._significance_level
+            confidence_level = (1 - p_value) * 100
+        else:
+            # Not enough data for statistical test
+            p_value = 1.0
+            is_significant = False
+            confidence_level = 0.0
+
+        # Determine winner based on average PnL
+        winner = None
+        if is_significant:
+            if perf_a.avg_pnl > perf_b.avg_pnl:
+                winner = strategy_a_name
+            elif perf_b.avg_pnl > perf_a.avg_pnl:
+                winner = strategy_b_name
+
+        return ABTestResult(
+            strategy_a=strategy_a_name,
+            strategy_b=strategy_b_name,
+            winner=winner,
+            p_value=round(p_value, 4),
+            confidence_level=round(confidence_level, 2),
+            is_significant=is_significant,
+            performance_a=perf_a,
+            performance_b=perf_b,
+        )
+
+    def should_deploy(
+        self,
+        result: ABTestResult,
+        min_win_rate: float = 60.0,
+        min_trades: int = 20,
+    ) -> bool:
+        """Determine if a winning strategy should be deployed.
+
+        Args:
+            result: A/B test result
+            min_win_rate: Minimum win rate percentage for deployment (default 60%)
+            min_trades: Minimum number of trades required (default 20)
+
+        Returns:
+            True if the winning strategy meets deployment criteria
+        """
+        if not result.is_significant or result.winner is None:
+            return False
+
+        # Get performance of winning strategy
+        if result.winner == result.strategy_a:
+            winning_perf = result.performance_a
+        else:
+            winning_perf = result.performance_b
+
+        # Check deployment criteria
+        has_enough_trades = winning_perf.total_trades >= min_trades
+        has_good_win_rate = winning_perf.win_rate >= min_win_rate
+        is_profitable = winning_perf.avg_pnl > 0
+
+        meets_criteria = has_enough_trades and has_good_win_rate and is_profitable
+
+        if meets_criteria:
+            logger.info(
+                "Strategy '%s' meets deployment criteria: "
+                "win_rate=%.2f%%, trades=%d, avg_pnl=%.2f",
+                result.winner,
+                winning_perf.win_rate,
+                winning_perf.total_trades,
+                winning_perf.avg_pnl,
+            )
+        else:
+            logger.info(
+                "Strategy '%s' does NOT meet deployment criteria: "
+                "win_rate=%.2f%% (min %.2f%%), trades=%d (min %d), avg_pnl=%.2f",
+                result.winner if result.winner else "unknown",
+                winning_perf.win_rate if result.winner else 0.0,
+                min_win_rate,
+                winning_perf.total_trades if result.winner else 0,
+                min_trades,
+                winning_perf.avg_pnl if result.winner else 0.0,
+            )
+
+        return meets_criteria

src/evolution/optimizer.py

@@ -1,10 +1,10 @@
 """Evolution Engine — analyzes trade logs and generates new strategies.
 
 This module:
-1. Reads trade_logs.db to identify failing patterns
+1. Uses DecisionLogger.get_losing_decisions() to identify failing patterns
-2. Asks Gemini to generate a new strategy class
+2. Analyzes failure patterns by time, market conditions, stock characteristics
-3. Runs pytest on the generated file
+3. Asks Gemini to generate improved strategy recommendations
-4. Creates a simulated PR if tests pass
+4. Generates new strategy classes with enhanced decision-making logic
 """
 
 from __future__ import annotations
@@ -14,6 +14,7 @@ import logging
 import sqlite3
 import subprocess
 import textwrap
+from collections import Counter
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -21,6 +22,8 @@ from typing import Any
 from google import genai
 
 from src.config import Settings
+from src.db import init_db
+from src.logging.decision_logger import DecisionLogger
 
 logger = logging.getLogger(__name__)
 
@@ -53,29 +56,105 @@ class EvolutionOptimizer:
         self._db_path = settings.DB_PATH
         self._client = genai.Client(api_key=settings.GEMINI_API_KEY)
         self._model_name = settings.GEMINI_MODEL
+        self._conn = init_db(self._db_path)
+        self._decision_logger = DecisionLogger(self._conn)
 
     # ------------------------------------------------------------------
     # Analysis
     # ------------------------------------------------------------------
 
     def analyze_failures(self, limit: int = 50) -> list[dict[str, Any]]:
-        """Find trades where high confidence led to losses."""
+        """Find high-confidence decisions that resulted in losses.
-        conn = sqlite3.connect(self._db_path)
+
-        conn.row_factory = sqlite3.Row
+        Uses DecisionLogger.get_losing_decisions() to retrieve failures.
-        try:
+        """
-            rows = conn.execute(
+        losing_decisions = self._decision_logger.get_losing_decisions(
-                """
+            min_confidence=80, min_loss=-100.0
-                SELECT stock_code, action, confidence, pnl, rationale, timestamp
+        )
-                FROM trades
+
-                WHERE confidence >= 80 AND pnl < 0
+        # Limit results
-                ORDER BY pnl ASC
+        if len(losing_decisions) > limit:
-                LIMIT ?
+            losing_decisions = losing_decisions[:limit]
-                """,
+
-                (limit,),
+        # Convert to dict format for analysis
-            ).fetchall()
+        failures = []
-            return [dict(r) for r in rows]
+        for decision in losing_decisions:
-        finally:
+            failures.append({
-            conn.close()
+                "decision_id": decision.decision_id,
+                "timestamp": decision.timestamp,
+                "stock_code": decision.stock_code,
+                "market": decision.market,
+                "exchange_code": decision.exchange_code,
+                "action": decision.action,
+                "confidence": decision.confidence,
+                "rationale": decision.rationale,
+                "outcome_pnl": decision.outcome_pnl,
+                "outcome_accuracy": decision.outcome_accuracy,
+                "context_snapshot": decision.context_snapshot,
+                "input_data": decision.input_data,
+            })
+
+        return failures
+
+    def identify_failure_patterns(
+        self, failures: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """Identify patterns in losing decisions.
+
+        Analyzes:
+        - Time patterns (hour of day, day of week)
+        - Market conditions (volatility, volume)
+        - Stock characteristics (price range, market)
+        - Common failure modes in rationale
+        """
+        if not failures:
+            return {"pattern_count": 0, "patterns": {}}
+
+        patterns = {
+            "markets": Counter(),
+            "actions": Counter(),
+            "hours": Counter(),
+            "avg_confidence": 0.0,
+            "avg_loss": 0.0,
+            "total_failures": len(failures),
+        }
+
+        total_confidence = 0
+        total_loss = 0.0
+
+        for failure in failures:
+            # Market distribution
+            patterns["markets"][failure.get("market", "UNKNOWN")] += 1
+
+            # Action distribution
+            patterns["actions"][failure.get("action", "UNKNOWN")] += 1
+
+            # Time pattern (extract hour from ISO timestamp)
+            timestamp = failure.get("timestamp", "")
+            if timestamp:
+                try:
+                    dt = datetime.fromisoformat(timestamp)
+                    patterns["hours"][dt.hour] += 1
+                except (ValueError, AttributeError):
+                    pass
+
+            # Aggregate metrics
+            total_confidence += failure.get("confidence", 0)
+            total_loss += failure.get("outcome_pnl", 0.0)
+
+        patterns["avg_confidence"] = (
+            round(total_confidence / len(failures), 2) if failures else 0.0
+        )
+        patterns["avg_loss"] = (
+            round(total_loss / len(failures), 2) if failures else 0.0
+        )
+
+        # Convert Counters to regular dicts for JSON serialization
+        patterns["markets"] = dict(patterns["markets"])
+        patterns["actions"] = dict(patterns["actions"])
+        patterns["hours"] = dict(patterns["hours"])
+
+        return patterns
 
     def get_performance_summary(self) -> dict[str, Any]:
         """Return aggregate performance metrics from trade logs."""
@@ -109,14 +188,25 @@ class EvolutionOptimizer:
     async def generate_strategy(self, failures: list[dict[str, Any]]) -> Path | None:
         """Ask Gemini to generate a new strategy based on failure analysis.
 
+        Integrates failure patterns and market conditions to create improved strategies.
         Returns the path to the generated strategy file, or None on failure.
         """
+        # Identify failure patterns first
+        patterns = self.identify_failure_patterns(failures)
+
         prompt = (
             "You are a quantitative trading strategy developer.\n"
-            "Analyze these failed trades and generate an improved strategy.\n\n"
+            "Analyze these failed trades and their patterns, then generate an improved strategy.\n\n"
-            f"Failed trades:\n{json.dumps(failures, indent=2, default=str)}\n\n"
+            f"Failure Patterns:\n{json.dumps(patterns, indent=2)}\n\n"
-            "Generate a Python class that inherits from BaseStrategy.\n"
+            f"Sample Failed Trades (first 5):\n"
-            "The class must have an `evaluate(self, market_data: dict) -> dict` method.\n"
+            f"{json.dumps(failures[:5], indent=2, default=str)}\n\n"
+            "Based on these patterns, generate an improved trading strategy.\n"
+            "The strategy should:\n"
+            "1. Avoid the identified failure patterns\n"
+            "2. Consider market-specific conditions\n"
+            "3. Adjust confidence based on historical performance\n\n"
+            "Generate a Python method body that inherits from BaseStrategy.\n"
+            "The method signature is: evaluate(self, market_data: dict) -> dict\n"
             "The method must return a dict with keys: action, confidence, rationale.\n"
             "Respond with ONLY the method body (Python code), no class definition.\n"
         )
@@ -147,10 +237,15 @@ class EvolutionOptimizer:
         # Indent the body for the class method
         indented_body = textwrap.indent(body, "            ")
 
+        # Generate rationale from patterns
+        rationale = f"Auto-evolved from {len(failures)} failures. "
+        rationale += f"Primary failure markets: {list(patterns.get('markets', {}).keys())}. "
+        rationale += f"Average loss: {patterns.get('avg_loss', 0.0)}"
+
         content = STRATEGY_TEMPLATE.format(
             name=version,
             timestamp=datetime.now(UTC).isoformat(),
-            rationale="Auto-evolved from failure analysis",
+            rationale=rationale,
             class_name=class_name,
             body=indented_body.strip(),
         )

src/evolution/performance_tracker.py

@@ -0,0 +1,303 @@
+"""Performance tracking system for strategy monitoring.
+
+Tracks win rates, monitors improvement over time,
+and provides performance metrics dashboard.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StrategyMetrics:
+    """Performance metrics for a strategy over a time period."""
+
+    strategy_name: str
+    period_start: str
+    period_end: str
+    total_trades: int
+    wins: int
+    losses: int
+    holds: int
+    win_rate: float
+    avg_pnl: float
+    total_pnl: float
+    best_trade: float
+    worst_trade: float
+    avg_confidence: float
+
+
+@dataclass
+class PerformanceDashboard:
+    """Comprehensive performance dashboard."""
+
+    generated_at: str
+    overall_metrics: StrategyMetrics
+    daily_metrics: list[StrategyMetrics]
+    weekly_metrics: list[StrategyMetrics]
+    improvement_trend: dict[str, Any]
+
+
+class PerformanceTracker:
+    """Tracks and monitors strategy performance over time."""
+
+    def __init__(self, db_path: str) -> None:
+        """Initialize performance tracker.
+
+        Args:
+            db_path: Path to the trade logs database
+        """
+        self._db_path = db_path
+
+    def get_strategy_metrics(
+        self,
+        strategy_name: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> StrategyMetrics:
+        """Get performance metrics for a strategy over a time period.
+
+        Args:
+            strategy_name: Name of the strategy (None = all strategies)
+            start_date: Start date in ISO format (None = beginning of time)
+            end_date: End date in ISO format (None = now)
+
+        Returns:
+            StrategyMetrics object with performance data
+        """
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+
+        try:
+            # Build query with optional filters
+            query = """
+                SELECT
+                    COUNT(*) as total_trades,
+                    SUM(CASE WHEN pnl > 0 THEN 1 ELSE 0 END) as wins,
+                    SUM(CASE WHEN pnl < 0 THEN 1 ELSE 0 END) as losses,
+                    SUM(CASE WHEN action = 'HOLD' THEN 1 ELSE 0 END) as holds,
+                    COALESCE(AVG(CASE WHEN pnl IS NOT NULL THEN pnl END), 0) as avg_pnl,
+                    COALESCE(SUM(CASE WHEN pnl IS NOT NULL THEN pnl ELSE 0 END), 0) as total_pnl,
+                    COALESCE(MAX(pnl), 0) as best_trade,
+                    COALESCE(MIN(pnl), 0) as worst_trade,
+                    COALESCE(AVG(confidence), 0) as avg_confidence,
+                    MIN(timestamp) as period_start,
+                    MAX(timestamp) as period_end
+                FROM trades
+                WHERE 1=1
+            """
+            params: list[Any] = []
+
+            if start_date:
+                query += " AND timestamp >= ?"
+                params.append(start_date)
+
+            if end_date:
+                query += " AND timestamp <= ?"
+                params.append(end_date)
+
+            # Note: Currently trades table doesn't have strategy_name column
+            # This is a placeholder for future extension
+
+            row = conn.execute(query, params).fetchone()
+
+            total_trades = row["total_trades"] or 0
+            wins = row["wins"] or 0
+            win_rate = (wins / total_trades * 100) if total_trades > 0 else 0.0
+
+            return StrategyMetrics(
+                strategy_name=strategy_name or "default",
+                period_start=row["period_start"] or "",
+                period_end=row["period_end"] or "",
+                total_trades=total_trades,
+                wins=wins,
+                losses=row["losses"] or 0,
+                holds=row["holds"] or 0,
+                win_rate=round(win_rate, 2),
+                avg_pnl=round(row["avg_pnl"], 2),
+                total_pnl=round(row["total_pnl"], 2),
+                best_trade=round(row["best_trade"], 2),
+                worst_trade=round(row["worst_trade"], 2),
+                avg_confidence=round(row["avg_confidence"], 2),
+            )
+        finally:
+            conn.close()
+
+    def get_daily_metrics(
+        self, days: int = 7, strategy_name: str | None = None
+    ) -> list[StrategyMetrics]:
+        """Get daily performance metrics for the last N days.
+
+        Args:
+            days: Number of days to retrieve (default 7)
+            strategy_name: Name of the strategy (None = all strategies)
+
+        Returns:
+            List of StrategyMetrics, one per day
+        """
+        metrics = []
+        end_date = datetime.now(UTC)
+
+        for i in range(days):
+            day_end = end_date - timedelta(days=i)
+            day_start = day_end - timedelta(days=1)
+
+            day_metrics = self.get_strategy_metrics(
+                strategy_name=strategy_name,
+                start_date=day_start.isoformat(),
+                end_date=day_end.isoformat(),
+            )
+            metrics.append(day_metrics)
+
+        return metrics
+
+    def get_weekly_metrics(
+        self, weeks: int = 4, strategy_name: str | None = None
+    ) -> list[StrategyMetrics]:
+        """Get weekly performance metrics for the last N weeks.
+
+        Args:
+            weeks: Number of weeks to retrieve (default 4)
+            strategy_name: Name of the strategy (None = all strategies)
+
+        Returns:
+            List of StrategyMetrics, one per week
+        """
+        metrics = []
+        end_date = datetime.now(UTC)
+
+        for i in range(weeks):
+            week_end = end_date - timedelta(weeks=i)
+            week_start = week_end - timedelta(weeks=1)
+
+            week_metrics = self.get_strategy_metrics(
+                strategy_name=strategy_name,
+                start_date=week_start.isoformat(),
+                end_date=week_end.isoformat(),
+            )
+            metrics.append(week_metrics)
+
+        return metrics
+
+    def calculate_improvement_trend(
+        self, metrics_history: list[StrategyMetrics]
+    ) -> dict[str, Any]:
+        """Calculate improvement trend from historical metrics.
+
+        Args:
+            metrics_history: List of StrategyMetrics ordered from oldest to newest
+
+        Returns:
+            Dictionary with trend analysis
+        """
+        if len(metrics_history) < 2:
+            return {
+                "trend": "insufficient_data",
+                "win_rate_change": 0.0,
+                "pnl_change": 0.0,
+                "confidence_change": 0.0,
+            }
+
+        oldest = metrics_history[0]
+        newest = metrics_history[-1]
+
+        win_rate_change = newest.win_rate - oldest.win_rate
+        pnl_change = newest.avg_pnl - oldest.avg_pnl
+        confidence_change = newest.avg_confidence - oldest.avg_confidence
+
+        # Determine overall trend
+        if win_rate_change > 5.0 and pnl_change > 0:
+            trend = "improving"
+        elif win_rate_change < -5.0 or pnl_change < 0:
+            trend = "declining"
+        else:
+            trend = "stable"
+
+        return {
+            "trend": trend,
+            "win_rate_change": round(win_rate_change, 2),
+            "pnl_change": round(pnl_change, 2),
+            "confidence_change": round(confidence_change, 2),
+            "period_count": len(metrics_history),
+        }
+
+    def generate_dashboard(
+        self, strategy_name: str | None = None
+    ) -> PerformanceDashboard:
+        """Generate a comprehensive performance dashboard.
+
+        Args:
+            strategy_name: Name of the strategy (None = all strategies)
+
+        Returns:
+            PerformanceDashboard with all metrics
+        """
+        # Get overall metrics
+        overall_metrics = self.get_strategy_metrics(strategy_name=strategy_name)
+
+        # Get daily metrics (last 7 days)
+        daily_metrics = self.get_daily_metrics(days=7, strategy_name=strategy_name)
+
+        # Get weekly metrics (last 4 weeks)
+        weekly_metrics = self.get_weekly_metrics(weeks=4, strategy_name=strategy_name)
+
+        # Calculate improvement trend
+        improvement_trend = self.calculate_improvement_trend(weekly_metrics[::-1])
+
+        return PerformanceDashboard(
+            generated_at=datetime.now(UTC).isoformat(),
+            overall_metrics=overall_metrics,
+            daily_metrics=daily_metrics,
+            weekly_metrics=weekly_metrics,
+            improvement_trend=improvement_trend,
+        )
+
+    def export_dashboard_json(
+        self, dashboard: PerformanceDashboard
+    ) -> str:
+        """Export dashboard as JSON string.
+
+        Args:
+            dashboard: PerformanceDashboard object
+
+        Returns:
+            JSON string representation
+        """
+        data = {
+            "generated_at": dashboard.generated_at,
+            "overall_metrics": asdict(dashboard.overall_metrics),
+            "daily_metrics": [asdict(m) for m in dashboard.daily_metrics],
+            "weekly_metrics": [asdict(m) for m in dashboard.weekly_metrics],
+            "improvement_trend": dashboard.improvement_trend,
+        }
+        return json.dumps(data, indent=2)
+
+    def log_dashboard(self, dashboard: PerformanceDashboard) -> None:
+        """Log dashboard summary to logger.
+
+        Args:
+            dashboard: PerformanceDashboard object
+        """
+        logger.info("=" * 60)
+        logger.info("PERFORMANCE DASHBOARD")
+        logger.info("=" * 60)
+        logger.info("Generated: %s", dashboard.generated_at)
+        logger.info("")
+        logger.info("Overall Performance:")
+        logger.info("  Total Trades: %d", dashboard.overall_metrics.total_trades)
+        logger.info("  Win Rate: %.2f%%", dashboard.overall_metrics.win_rate)
+        logger.info("  Average P&L: %.2f", dashboard.overall_metrics.avg_pnl)
+        logger.info("  Total P&L: %.2f", dashboard.overall_metrics.total_pnl)
+        logger.info("")
+        logger.info("Improvement Trend (%s):", dashboard.improvement_trend["trend"])
+        logger.info("  Win Rate Change: %+.2f%%", dashboard.improvement_trend["win_rate_change"])
+        logger.info("  P&L Change: %+.2f", dashboard.improvement_trend["pnl_change"])
+        logger.info("=" * 60)

src/main.py

@@ -10,6 +10,7 @@ import argparse
 import asyncio
 import logging
 import signal
+import sys
 from datetime import UTC, datetime
 from typing import Any
 
@@ -19,12 +20,16 @@ from src.brain.gemini_client import GeminiClient
 from src.broker.kis_api import KISBroker
 from src.broker.overseas import OverseasBroker
 from src.config import Settings
+from src.context.layer import ContextLayer
 from src.context.store import ContextStore
-from src.core.risk_manager import CircuitBreakerTripped, RiskManager
+from src.core.criticality import CriticalityAssessor
+from src.core.priority_queue import PriorityTaskQueue
+from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected, RiskManager
 from src.db import init_db, log_trade
 from src.logging.decision_logger import DecisionLogger
 from src.logging_config import setup_logging
 from src.markets.schedule import MarketInfo, get_next_market_open, get_open_markets
+from src.notifications.telegram_client import TelegramClient
 
 logger = logging.getLogger(__name__)
 
@@ -57,10 +62,15 @@ async def trading_cycle(
     risk: RiskManager,
     db_conn: Any,
     decision_logger: DecisionLogger,
+    context_store: ContextStore,
+    criticality_assessor: CriticalityAssessor,
+    telegram: TelegramClient,
     market: MarketInfo,
     stock_code: str,
 ) -> None:
     """Execute one trading cycle for a single stock."""
+    cycle_start_time = asyncio.get_event_loop().time()
+
     # 1. Fetch market data
     if market.is_domestic:
         orderbook = await broker.get_orderbook(stock_code)
@@ -85,9 +95,17 @@ async def trading_cycle(
         balance_data = await overseas_broker.get_overseas_balance(market.exchange_code)
 
         output2 = balance_data.get("output2", [{}])
-        total_eval = float(output2[0].get("frcr_evlu_tota", "0")) if output2 else 0
+        # Handle both list and dict response formats
-        total_cash = float(output2[0].get("frcr_dncl_amt_2", "0")) if output2 else 0
+        if isinstance(output2, list) and output2:
-        purchase_total = float(output2[0].get("frcr_buy_amt_smtl", "0")) if output2 else 0
+            balance_info = output2[0]
+        elif isinstance(output2, dict):
+            balance_info = output2
+        else:
+            balance_info = {}
+
+        total_eval = float(balance_info.get("frcr_evlu_tota", "0") or "0")
+        total_cash = float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
+        purchase_total = float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
 
         current_price = float(price_data.get("output", {}).get("last", "0"))
         foreigner_net = 0.0  # Not available for overseas
@@ -106,6 +124,42 @@ async def trading_cycle(
         "foreigner_net": foreigner_net,
     }
 
+    # 1.5. Get volatility metrics from context store (L7_REALTIME)
+    latest_timeframe = context_store.get_latest_timeframe(ContextLayer.L7_REALTIME)
+    volatility_score = 50.0  # Default normal volatility
+    volume_surge = 1.0
+    price_change_1m = 0.0
+
+    if latest_timeframe:
+        volatility_data = context_store.get_context(
+            ContextLayer.L7_REALTIME,
+            latest_timeframe,
+            f"volatility_{stock_code}",
+        )
+        if volatility_data:
+            volatility_score = volatility_data.get("momentum_score", 50.0)
+            volume_surge = volatility_data.get("volume_surge", 1.0)
+            price_change_1m = volatility_data.get("price_change_1m", 0.0)
+
+    # 1.6. Assess criticality based on market conditions
+    criticality = criticality_assessor.assess_market_conditions(
+        pnl_pct=pnl_pct,
+        volatility_score=volatility_score,
+        volume_surge=volume_surge,
+        price_change_1m=price_change_1m,
+        is_market_open=True,
+    )
+
+    logger.info(
+        "Criticality for %s (%s): %s (pnl=%.2f%%, volatility=%.1f, volume_surge=%.1fx)",
+        stock_code,
+        market.name,
+        criticality.value,
+        pnl_pct,
+        volatility_score,
+        volume_surge,
+    )
+
     # 2. Ask the brain for a decision
     decision = await brain.decide(market_data)
     logger.info(
@@ -156,11 +210,23 @@ async def trading_cycle(
         order_amount = current_price * quantity
 
         # 4. Risk check BEFORE order
-        risk.validate_order(
+        try:
-            current_pnl_pct=pnl_pct,
+            risk.validate_order(
-            order_amount=order_amount,
+                current_pnl_pct=pnl_pct,
-            total_cash=total_cash,
+                order_amount=order_amount,
-        )
+                total_cash=total_cash,
+            )
+        except FatFingerRejected as exc:
+            try:
+                await telegram.notify_fat_finger(
+                    stock_code=stock_code,
+                    order_amount=exc.order_amount,
+                    total_cash=exc.total_cash,
+                    max_pct=exc.max_pct,
+                )
+            except Exception as notify_exc:
+                logger.warning("Fat finger notification failed: %s", notify_exc)
+            raise  # Re-raise to prevent trade
 
         # 5. Send order
         if market.is_domestic:
@@ -180,6 +246,19 @@ async def trading_cycle(
             )
         logger.info("Order result: %s", result.get("msg1", "OK"))
 
+        # 5.5. Notify trade execution
+        try:
+            await telegram.notify_trade_execution(
+                stock_code=stock_code,
+                market=market.name,
+                action=decision.action,
+                quantity=quantity,
+                price=current_price,
+                confidence=decision.confidence,
+            )
+        except Exception as exc:
+            logger.warning("Telegram notification failed: %s", exc)
+
     # 6. Log trade
     log_trade(
         conn=db_conn,
@@ -191,6 +270,27 @@ async def trading_cycle(
         exchange_code=market.exchange_code,
     )
 
+    # 7. Latency monitoring
+    cycle_end_time = asyncio.get_event_loop().time()
+    cycle_latency = cycle_end_time - cycle_start_time
+    timeout = criticality_assessor.get_timeout(criticality)
+
+    if timeout and cycle_latency > timeout:
+        logger.warning(
+            "Trading cycle exceeded timeout for %s (criticality=%s, latency=%.2fs, timeout=%.2fs)",
+            stock_code,
+            criticality.value,
+            cycle_latency,
+            timeout,
+        )
+    else:
+        logger.debug(
+            "Trading cycle completed within timeout for %s (criticality=%s, latency=%.2fs)",
+            stock_code,
+            criticality.value,
+            cycle_latency,
+        )
+
 
 async def run(settings: Settings) -> None:
     """Main async loop — iterate over open markets on a timer."""
@@ -202,6 +302,13 @@ async def run(settings: Settings) -> None:
     decision_logger = DecisionLogger(db_conn)
     context_store = ContextStore(db_conn)
 
+    # Initialize Telegram notifications
+    telegram = TelegramClient(
+        bot_token=settings.TELEGRAM_BOT_TOKEN,
+        chat_id=settings.TELEGRAM_CHAT_ID,
+        enabled=settings.TELEGRAM_ENABLED,
+    )
+
     # Initialize volatility hunter
     volatility_analyzer = VolatilityAnalyzer(min_volume_surge=2.0, min_price_change=1.0)
     market_scanner = MarketScanner(
@@ -212,9 +319,22 @@ async def run(settings: Settings) -> None:
         top_n=5,
     )
 
+    # Initialize latency control system
+    criticality_assessor = CriticalityAssessor(
+        critical_pnl_threshold=-2.5,  # Near circuit breaker at -3.0%
+        critical_price_change_threshold=5.0,  # 5% in 1 minute
+        critical_volume_surge_threshold=10.0,  # 10x average
+        high_volatility_threshold=70.0,
+        low_volatility_threshold=30.0,
+    )
+    priority_queue = PriorityTaskQueue(max_size=1000)
+
     # Track last scan time for each market
     last_scan_time: dict[str, float] = {}
 
+    # Track market open/close state for notifications
+    _market_states: dict[str, bool] = {}  # market_code -> is_open
+
     shutdown = asyncio.Event()
 
     def _signal_handler() -> None:
@@ -228,12 +348,31 @@ async def run(settings: Settings) -> None:
     logger.info("The Ouroboros is alive. Mode: %s", settings.MODE)
     logger.info("Enabled markets: %s", settings.enabled_market_list)
 
+    # Notify system startup
+    try:
+        await telegram.notify_system_start(settings.MODE, settings.enabled_market_list)
+    except Exception as exc:
+        logger.warning("System startup notification failed: %s", exc)
+
     try:
         while not shutdown.is_set():
             # Get currently open markets
             open_markets = get_open_markets(settings.enabled_market_list)
 
             if not open_markets:
+                # Notify market close for any markets that were open
+                for market_code, is_open in list(_market_states.items()):
+                    if is_open:
+                        try:
+                            from src.markets.schedule import MARKETS
+
+                            market_info = MARKETS.get(market_code)
+                            if market_info:
+                                await telegram.notify_market_close(market_info.name, 0.0)
+                        except Exception as exc:
+                            logger.warning("Market close notification failed: %s", exc)
+                        _market_states[market_code] = False
+
                 # No markets open — wait until next market opens
                 try:
                     next_market, next_open_time = get_next_market_open(
@@ -259,6 +398,14 @@ async def run(settings: Settings) -> None:
                 if shutdown.is_set():
                     break
 
+                # Notify market open if it just opened
+                if not _market_states.get(market.code, False):
+                    try:
+                        await telegram.notify_market_open(market.name)
+                    except Exception as exc:
+                        logger.warning("Market open notification failed: %s", exc)
+                    _market_states[market.code] = True
+
                 # Volatility Hunter: Scan market periodically to update watchlist
                 now_timestamp = asyncio.get_event_loop().time()
                 last_scan = last_scan_time.get(market.code, 0.0)
@@ -315,12 +462,24 @@ async def run(settings: Settings) -> None:
                                 risk,
                                 db_conn,
                                 decision_logger,
+                                context_store,
+                                criticality_assessor,
+                                telegram,
                                 market,
                                 stock_code,
                             )
                             break  # Success — exit retry loop
-                        except CircuitBreakerTripped:
+                        except CircuitBreakerTripped as exc:
                             logger.critical("Circuit breaker tripped — shutting down")
+                            try:
+                                await telegram.notify_circuit_breaker(
+                                    pnl_pct=exc.pnl_pct,
+                                    threshold=exc.threshold,
+                                )
+                            except Exception as notify_exc:
+                                logger.warning(
+                                    "Circuit breaker notification failed: %s", notify_exc
+                                )
                             raise
                         except ConnectionError as exc:
                             if attempt < MAX_CONNECTION_RETRIES:
@@ -343,6 +502,18 @@ async def run(settings: Settings) -> None:
                             logger.exception("Unexpected error for %s: %s", stock_code, exc)
                             break  # Don't retry on unexpected errors
 
+            # Log priority queue metrics periodically
+            metrics = await priority_queue.get_metrics()
+            if metrics.total_enqueued > 0:
+                logger.info(
+                    "Priority queue metrics: enqueued=%d, dequeued=%d, size=%d, timeouts=%d, errors=%d",
+                    metrics.total_enqueued,
+                    metrics.total_dequeued,
+                    metrics.current_size,
+                    metrics.total_timeouts,
+                    metrics.total_errors,
+                )
+
             # Wait for next cycle or shutdown
             try:
                 await asyncio.wait_for(shutdown.wait(), timeout=TRADE_INTERVAL_SECONDS)

src/notifications/README.md

@@ -0,0 +1,213 @@
+# Telegram Notifications
+
+Real-time trading event notifications via Telegram Bot API.
+
+## Setup
+
+### 1. Create a Telegram Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` command
+3. Follow prompts to name your bot
+4. Save the **bot token** (looks like `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+### 2. Get Your Chat ID
+
+**Option A: Using @userinfobot**
+1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+2. Send `/start`
+3. Save your numeric **chat ID** (e.g., `123456789`)
+
+**Option B: Using @RawDataBot**
+1. Message [@RawDataBot](https://t.me/rawdatabot) on Telegram
+2. Look for `"id":` in the JSON response
+3. Save your numeric **chat ID**
+
+### 3. Configure Environment
+
+Add to your `.env` file:
+
+```bash
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=123456789
+TELEGRAM_ENABLED=true
+```
+
+### 4. Test the Bot
+
+Start a conversation with your bot on Telegram first (send `/start`), then run:
+
+```bash
+python -m src.main --mode=paper
+```
+
+You should receive a startup notification.
+
+## Message Examples
+
+### Trade Execution
+```
+🟢 BUY
+Symbol: AAPL (United States)
+Quantity: 10 shares
+Price: 150.25
+Confidence: 85%
+```
+
+### Circuit Breaker
+```
+🚨 CIRCUIT BREAKER TRIPPED
+P&L: -3.15% (threshold: -3.0%)
+Trading halted for safety
+```
+
+### Fat-Finger Protection
+```
+⚠️ Fat-Finger Protection
+Order rejected: TSLA
+Attempted: 45.0% of cash
+Max allowed: 30%
+Amount: 45,000 / 100,000
+```
+
+### Market Open/Close
+```
+ℹ️ Market Open
+Korea trading session started
+
+ℹ️ Market Close
+Korea trading session ended
+📈 P&L: +1.25%
+```
+
+### System Status
+```
+📝 System Started
+Mode: PAPER
+Markets: KRX, NASDAQ
+
+System Shutdown
+Normal shutdown
+```
+
+## Notification Priorities
+
+| Priority | Emoji | Use Case |
+|----------|-------|----------|
+| LOW | ℹ️ | Market open/close |
+| MEDIUM | 📊 | Trade execution, system start/stop |
+| HIGH | ⚠️ | Fat-finger protection, errors |
+| CRITICAL | 🚨 | Circuit breaker trips |
+
+## Rate Limiting
+
+- Default: 1 message per second
+- Prevents hitting Telegram's global rate limits
+- Configurable via `rate_limit` parameter
+
+## Troubleshooting
+
+### No notifications received
+
+1. **Check bot configuration**
+   ```bash
+   # Verify env variables are set
+   grep TELEGRAM .env
+   ```
+
+2. **Start conversation with bot**
+   - Open bot in Telegram
+   - Send `/start` command
+   - Bot cannot message users who haven't started a conversation
+
+3. **Check logs**
+   ```bash
+   # Look for Telegram-related errors
+   python -m src.main --mode=paper 2>&1 | grep -i telegram
+   ```
+
+4. **Verify bot token**
+   ```bash
+   curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
+   # Should return bot info (not 401 error)
+   ```
+
+5. **Verify chat ID**
+   ```bash
+   curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
+     -H 'Content-Type: application/json' \
+     -d '{"chat_id": "<YOUR_CHAT_ID>", "text": "Test"}'
+   # Should send a test message
+   ```
+
+### Notifications delayed
+
+- Check rate limiter settings
+- Verify network connection
+- Look for timeout errors in logs
+
+### "Chat not found" error
+
+- Incorrect chat ID
+- Bot blocked by user
+- Need to send `/start` to bot first
+
+### "Unauthorized" error
+
+- Invalid bot token
+- Token revoked (regenerate with @BotFather)
+
+## Graceful Degradation
+
+The system works without Telegram notifications:
+
+- Missing credentials → notifications disabled automatically
+- API errors → logged but trading continues
+- Network timeouts → trading loop unaffected
+- Rate limiting → messages queued, trading proceeds
+
+**Notifications never crash the trading system.**
+
+## Security Notes
+
+- Never commit `.env` file with credentials
+- Bot token grants full bot control
+- Chat ID is not sensitive (just a number)
+- Messages are sent over HTTPS
+- No trading credentials in notifications
+
+## Advanced Usage
+
+### Group Notifications
+
+1. Add bot to Telegram group
+2. Get group chat ID (negative number like `-123456789`)
+3. Use group chat ID in `TELEGRAM_CHAT_ID`
+
+### Multiple Recipients
+
+Create multiple bots or use a broadcast group with multiple members.
+
+### Custom Rate Limits
+
+Not currently exposed in config, but can be modified in code:
+
+```python
+telegram = TelegramClient(
+    bot_token=settings.TELEGRAM_BOT_TOKEN,
+    chat_id=settings.TELEGRAM_CHAT_ID,
+    rate_limit=2.0,  # 2 messages per second
+)
+```
+
+## API Reference
+
+See `telegram_client.py` for full API documentation.
+
+Key methods:
+- `notify_trade_execution()` - Trade alerts
+- `notify_circuit_breaker()` - Emergency stops
+- `notify_fat_finger()` - Order rejections
+- `notify_market_open/close()` - Session tracking
+- `notify_system_start/shutdown()` - Lifecycle events
+- `notify_error()` - Error alerts

src/notifications/__init__.py

@@ -0,0 +1,5 @@
+"""Real-time notifications for trading events."""
+
+from src.notifications.telegram_client import TelegramClient
+
+__all__ = ["TelegramClient"]

src/notifications/telegram_client.py

@@ -0,0 +1,325 @@
+"""Telegram notification client for real-time trading alerts."""
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from enum import Enum
+
+import aiohttp
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationPriority(Enum):
+    """Priority levels for notifications with emoji indicators."""
+
+    LOW = ("ℹ️", "info")
+    MEDIUM = ("📊", "medium")
+    HIGH = ("⚠️", "warning")
+    CRITICAL = ("🚨", "critical")
+
+    def __init__(self, emoji: str, label: str) -> None:
+        self.emoji = emoji
+        self.label = label
+
+
+class LeakyBucket:
+    """Rate limiter using leaky bucket algorithm."""
+
+    def __init__(self, rate: float, capacity: int = 1) -> None:
+        """
+        Initialize rate limiter.
+
+        Args:
+            rate: Maximum requests per second
+            capacity: Bucket capacity (burst size)
+        """
+        self._rate = rate
+        self._capacity = capacity
+        self._tokens = float(capacity)
+        self._last_update = time.monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Wait until a token is available, then consume it."""
+        async with self._lock:
+            now = time.monotonic()
+            elapsed = now - self._last_update
+            self._tokens = min(self._capacity, self._tokens + elapsed * self._rate)
+            self._last_update = now
+
+            if self._tokens < 1.0:
+                wait_time = (1.0 - self._tokens) / self._rate
+                await asyncio.sleep(wait_time)
+                self._tokens = 0.0
+            else:
+                self._tokens -= 1.0
+
+
+@dataclass
+class NotificationMessage:
+    """Internal notification message structure."""
+
+    priority: NotificationPriority
+    message: str
+
+
+class TelegramClient:
+    """Telegram Bot API client for sending trading notifications."""
+
+    API_BASE = "https://api.telegram.org/bot{token}"
+    DEFAULT_TIMEOUT = 5.0  # seconds
+    DEFAULT_RATE = 1.0  # messages per second
+
+    def __init__(
+        self,
+        bot_token: str | None = None,
+        chat_id: str | None = None,
+        enabled: bool = True,
+        rate_limit: float = DEFAULT_RATE,
+    ) -> None:
+        """
+        Initialize Telegram client.
+
+        Args:
+            bot_token: Telegram bot token from @BotFather
+            chat_id: Target chat ID (user or group)
+            enabled: Enable/disable notifications globally
+            rate_limit: Maximum messages per second
+        """
+        self._bot_token = bot_token
+        self._chat_id = chat_id
+        self._enabled = enabled
+        self._rate_limiter = LeakyBucket(rate=rate_limit)
+        self._session: aiohttp.ClientSession | None = None
+
+        if not enabled:
+            logger.info("Telegram notifications disabled via configuration")
+        elif bot_token is None or chat_id is None:
+            logger.warning(
+                "Telegram notifications disabled (missing bot_token or chat_id)"
+            )
+            self._enabled = False
+        else:
+            logger.info("Telegram notifications enabled for chat_id=%s", chat_id)
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create aiohttp session."""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=self.DEFAULT_TIMEOUT)
+            )
+        return self._session
+
+    async def close(self) -> None:
+        """Close HTTP session."""
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+
+    async def _send_notification(self, msg: NotificationMessage) -> None:
+        """
+        Send notification to Telegram with graceful degradation.
+
+        Args:
+            msg: Notification message to send
+        """
+        if not self._enabled:
+            return
+
+        try:
+            await self._rate_limiter.acquire()
+
+            formatted_message = f"{msg.priority.emoji} {msg.message}"
+            url = f"{self.API_BASE.format(token=self._bot_token)}/sendMessage"
+
+            payload = {
+                "chat_id": self._chat_id,
+                "text": formatted_message,
+                "parse_mode": "HTML",
+            }
+
+            session = self._get_session()
+            async with session.post(url, json=payload) as resp:
+                if resp.status != 200:
+                    error_text = await resp.text()
+                    logger.error(
+                        "Telegram API error (status=%d): %s", resp.status, error_text
+                    )
+                else:
+                    logger.debug("Telegram notification sent: %s", msg.message[:50])
+
+        except asyncio.TimeoutError:
+            logger.error("Telegram notification timeout")
+        except aiohttp.ClientError as exc:
+            logger.error("Telegram notification failed: %s", exc)
+        except Exception as exc:
+            logger.error("Unexpected error sending notification: %s", exc)
+
+    async def notify_trade_execution(
+        self,
+        stock_code: str,
+        market: str,
+        action: str,
+        quantity: int,
+        price: float,
+        confidence: float,
+    ) -> None:
+        """
+        Notify trade execution.
+
+        Args:
+            stock_code: Stock ticker symbol
+            market: Market name (e.g., "Korea", "United States")
+            action: "BUY" or "SELL"
+            quantity: Number of shares
+            price: Execution price
+            confidence: AI confidence level (0-100)
+        """
+        emoji = "🟢" if action == "BUY" else "🔴"
+        message = (
+            f"<b>{emoji} {action}</b>\n"
+            f"Symbol: <code>{stock_code}</code> ({market})\n"
+            f"Quantity: {quantity:,} shares\n"
+            f"Price: {price:,.2f}\n"
+            f"Confidence: {confidence:.0f}%"
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.MEDIUM, message=message)
+        )
+
+    async def notify_market_open(self, market_name: str) -> None:
+        """
+        Notify market opening.
+
+        Args:
+            market_name: Name of the market (e.g., "Korea", "United States")
+        """
+        message = f"<b>Market Open</b>\n{market_name} trading session started"
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.LOW, message=message)
+        )
+
+    async def notify_market_close(self, market_name: str, pnl_pct: float) -> None:
+        """
+        Notify market closing.
+
+        Args:
+            market_name: Name of the market
+            pnl_pct: Final P&L percentage for the session
+        """
+        pnl_sign = "+" if pnl_pct >= 0 else ""
+        pnl_emoji = "📈" if pnl_pct >= 0 else "📉"
+        message = (
+            f"<b>Market Close</b>\n"
+            f"{market_name} trading session ended\n"
+            f"{pnl_emoji} P&L: {pnl_sign}{pnl_pct:.2f}%"
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.LOW, message=message)
+        )
+
+    async def notify_circuit_breaker(
+        self, pnl_pct: float, threshold: float
+    ) -> None:
+        """
+        Notify circuit breaker activation.
+
+        Args:
+            pnl_pct: Current P&L percentage
+            threshold: Circuit breaker threshold
+        """
+        message = (
+            f"<b>CIRCUIT BREAKER TRIPPED</b>\n"
+            f"P&L: {pnl_pct:.2f}% (threshold: {threshold:.1f}%)\n"
+            f"Trading halted for safety"
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.CRITICAL, message=message)
+        )
+
+    async def notify_fat_finger(
+        self,
+        stock_code: str,
+        order_amount: float,
+        total_cash: float,
+        max_pct: float,
+    ) -> None:
+        """
+        Notify fat-finger protection rejection.
+
+        Args:
+            stock_code: Stock ticker symbol
+            order_amount: Attempted order amount
+            total_cash: Total available cash
+            max_pct: Maximum allowed percentage
+        """
+        attempted_pct = (order_amount / total_cash) * 100 if total_cash > 0 else 0
+        message = (
+            f"<b>Fat-Finger Protection</b>\n"
+            f"Order rejected: <code>{stock_code}</code>\n"
+            f"Attempted: {attempted_pct:.1f}% of cash\n"
+            f"Max allowed: {max_pct:.0f}%\n"
+            f"Amount: {order_amount:,.0f} / {total_cash:,.0f}"
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.HIGH, message=message)
+        )
+
+    async def notify_system_start(
+        self, mode: str, enabled_markets: list[str]
+    ) -> None:
+        """
+        Notify system startup.
+
+        Args:
+            mode: Trading mode ("paper" or "live")
+            enabled_markets: List of enabled market codes
+        """
+        mode_emoji = "📝" if mode == "paper" else "💰"
+        markets_str = ", ".join(enabled_markets)
+        message = (
+            f"<b>{mode_emoji} System Started</b>\n"
+            f"Mode: {mode.upper()}\n"
+            f"Markets: {markets_str}"
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.MEDIUM, message=message)
+        )
+
+    async def notify_system_shutdown(self, reason: str) -> None:
+        """
+        Notify system shutdown.
+
+        Args:
+            reason: Reason for shutdown (e.g., "Normal shutdown", "Circuit breaker")
+        """
+        message = f"<b>System Shutdown</b>\n{reason}"
+        priority = (
+            NotificationPriority.CRITICAL
+            if "circuit breaker" in reason.lower()
+            else NotificationPriority.MEDIUM
+        )
+        await self._send_notification(
+            NotificationMessage(priority=priority, message=message)
+        )
+
+    async def notify_error(
+        self, error_type: str, error_msg: str, context: str
+    ) -> None:
+        """
+        Notify system error.
+
+        Args:
+            error_type: Type of error (e.g., "Connection Error")
+            error_msg: Error message
+            context: Error context (e.g., stock code, market)
+        """
+        message = (
+            f"<b>Error: {error_type}</b>\n"
+            f"Context: {context}\n"
+            f"Message: {error_msg[:200]}"  # Truncate long errors
+        )
+        await self._send_notification(
+            NotificationMessage(priority=NotificationPriority.HIGH, message=message)
+        )

tests/test_backup.py

@@ -0,0 +1,365 @@
+"""Tests for backup and disaster recovery system."""
+
+from __future__ import annotations
+
+import sqlite3
+import tempfile
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import pytest
+
+from src.backup.exporter import BackupExporter, ExportFormat
+from src.backup.health_monitor import HealthMonitor, HealthStatus
+from src.backup.scheduler import BackupPolicy, BackupScheduler
+
+
+@pytest.fixture
+def temp_db(tmp_path: Path) -> Path:
+    """Create a temporary test database."""
+    db_path = tmp_path / "test_trades.db"
+
+    conn = sqlite3.connect(str(db_path))
+    cursor = conn.cursor()
+
+    # Create trades table
+    cursor.execute("""
+        CREATE TABLE trades (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT NOT NULL,
+            stock_code TEXT NOT NULL,
+            action TEXT NOT NULL,
+            quantity INTEGER NOT NULL,
+            price REAL NOT NULL,
+            confidence INTEGER NOT NULL,
+            rationale TEXT,
+            pnl REAL DEFAULT 0.0
+        )
+    """)
+
+    # Insert test data
+    test_trades = [
+        ("2024-01-01T10:00:00Z", "005930", "BUY", 10, 70000.0, 85, "Test buy", 0.0),
+        ("2024-01-01T11:00:00Z", "005930", "SELL", 10, 71000.0, 90, "Test sell", 10000.0),
+        ("2024-01-02T10:00:00Z", "AAPL", "BUY", 5, 180.0, 88, "Tech buy", 0.0),
+    ]
+
+    cursor.executemany(
+        """
+        INSERT INTO trades (timestamp, stock_code, action, quantity, price, confidence, rationale, pnl)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        test_trades,
+    )
+
+    conn.commit()
+    conn.close()
+
+    return db_path
+
+
+class TestBackupExporter:
+    """Test BackupExporter functionality."""
+
+    def test_exporter_init(self, temp_db: Path) -> None:
+        """Test exporter initialization."""
+        exporter = BackupExporter(str(temp_db))
+        assert exporter.db_path == str(temp_db)
+
+    def test_export_json(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test JSON export."""
+        exporter = BackupExporter(str(temp_db))
+        output_dir = tmp_path / "exports"
+
+        results = exporter.export_all(
+            output_dir, formats=[ExportFormat.JSON], compress=False
+        )
+
+        assert ExportFormat.JSON in results
+        assert results[ExportFormat.JSON].exists()
+        assert results[ExportFormat.JSON].suffix == ".json"
+
+    def test_export_json_compressed(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test compressed JSON export."""
+        exporter = BackupExporter(str(temp_db))
+        output_dir = tmp_path / "exports"
+
+        results = exporter.export_all(
+            output_dir, formats=[ExportFormat.JSON], compress=True
+        )
+
+        assert ExportFormat.JSON in results
+        assert results[ExportFormat.JSON].suffix == ".gz"
+
+    def test_export_csv(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test CSV export."""
+        exporter = BackupExporter(str(temp_db))
+        output_dir = tmp_path / "exports"
+
+        results = exporter.export_all(
+            output_dir, formats=[ExportFormat.CSV], compress=False
+        )
+
+        assert ExportFormat.CSV in results
+        assert results[ExportFormat.CSV].exists()
+
+        # Verify CSV content
+        with open(results[ExportFormat.CSV], "r") as f:
+            lines = f.readlines()
+            assert len(lines) == 4  # Header + 3 rows
+
+    def test_export_all_formats(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test exporting all formats."""
+        exporter = BackupExporter(str(temp_db))
+        output_dir = tmp_path / "exports"
+
+        # Skip Parquet if pyarrow not available
+        try:
+            import pyarrow  # noqa: F401
+
+            formats = [ExportFormat.JSON, ExportFormat.CSV, ExportFormat.PARQUET]
+        except ImportError:
+            formats = [ExportFormat.JSON, ExportFormat.CSV]
+
+        results = exporter.export_all(output_dir, formats=formats, compress=False)
+
+        for fmt in formats:
+            assert fmt in results
+            assert results[fmt].exists()
+
+    def test_incremental_export(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test incremental export."""
+        exporter = BackupExporter(str(temp_db))
+        output_dir = tmp_path / "exports"
+
+        # Export only trades after Jan 2
+        cutoff = datetime(2024, 1, 2, tzinfo=UTC)
+        results = exporter.export_all(
+            output_dir,
+            formats=[ExportFormat.JSON],
+            compress=False,
+            incremental_since=cutoff,
+        )
+
+        # Should only have 1 trade (AAPL on Jan 2)
+        import json
+
+        with open(results[ExportFormat.JSON], "r") as f:
+            data = json.load(f)
+            assert data["record_count"] == 1
+            assert data["trades"][0]["stock_code"] == "AAPL"
+
+    def test_get_export_stats(self, temp_db: Path) -> None:
+        """Test export statistics."""
+        exporter = BackupExporter(str(temp_db))
+        stats = exporter.get_export_stats()
+
+        assert stats["total_trades"] == 3
+        assert "date_range" in stats
+        assert "db_size_bytes" in stats
+
+
+class TestBackupScheduler:
+    """Test BackupScheduler functionality."""
+
+    def test_scheduler_init(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test scheduler initialization."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        assert scheduler.db_path == temp_db
+        assert (backup_dir / "daily").exists()
+        assert (backup_dir / "weekly").exists()
+        assert (backup_dir / "monthly").exists()
+
+    def test_create_daily_backup(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test daily backup creation."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        metadata = scheduler.create_backup(BackupPolicy.DAILY, verify=True)
+
+        assert metadata.policy == BackupPolicy.DAILY
+        assert metadata.file_path.exists()
+        assert metadata.size_bytes > 0
+        assert metadata.checksum is not None
+
+    def test_create_weekly_backup(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test weekly backup creation."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        metadata = scheduler.create_backup(BackupPolicy.WEEKLY, verify=False)
+
+        assert metadata.policy == BackupPolicy.WEEKLY
+        assert metadata.file_path.exists()
+        assert metadata.checksum is None  # verify=False
+
+    def test_list_backups(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test listing backups."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        scheduler.create_backup(BackupPolicy.DAILY)
+        scheduler.create_backup(BackupPolicy.WEEKLY)
+
+        backups = scheduler.list_backups()
+        assert len(backups) == 2
+
+        daily_backups = scheduler.list_backups(BackupPolicy.DAILY)
+        assert len(daily_backups) == 1
+        assert daily_backups[0].policy == BackupPolicy.DAILY
+
+    def test_cleanup_old_backups(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test cleanup of old backups."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir, daily_retention_days=0)
+
+        # Create a backup
+        scheduler.create_backup(BackupPolicy.DAILY)
+
+        # Cleanup should remove it (0 day retention)
+        removed = scheduler.cleanup_old_backups()
+        assert removed[BackupPolicy.DAILY] >= 1
+
+    def test_backup_stats(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test backup statistics."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        scheduler.create_backup(BackupPolicy.DAILY)
+        scheduler.create_backup(BackupPolicy.MONTHLY)
+
+        stats = scheduler.get_backup_stats()
+
+        assert stats["daily"]["count"] == 1
+        assert stats["monthly"]["count"] == 1
+        assert stats["daily"]["total_size_bytes"] > 0
+
+    def test_restore_backup(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test backup restoration."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+
+        # Create backup
+        metadata = scheduler.create_backup(BackupPolicy.DAILY)
+
+        # Modify database
+        conn = sqlite3.connect(str(temp_db))
+        conn.execute("DELETE FROM trades")
+        conn.commit()
+        conn.close()
+
+        # Restore
+        scheduler.restore_backup(metadata, verify=True)
+
+        # Verify restoration
+        conn = sqlite3.connect(str(temp_db))
+        cursor = conn.execute("SELECT COUNT(*) FROM trades")
+        count = cursor.fetchone()[0]
+        conn.close()
+
+        assert count == 3  # Original 3 trades restored
+
+
+class TestHealthMonitor:
+    """Test HealthMonitor functionality."""
+
+    def test_monitor_init(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test monitor initialization."""
+        backup_dir = tmp_path / "backups"
+        monitor = HealthMonitor(str(temp_db), backup_dir)
+
+        assert monitor.db_path == temp_db
+
+    def test_check_database_health_ok(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test database health check (healthy)."""
+        monitor = HealthMonitor(str(temp_db), tmp_path / "backups")
+        result = monitor.check_database_health()
+
+        assert result.status == HealthStatus.HEALTHY
+        assert "healthy" in result.message.lower()
+        assert result.details is not None
+        assert result.details["trade_count"] == 3
+
+    def test_check_database_health_missing(self, tmp_path: Path) -> None:
+        """Test database health check (missing file)."""
+        non_existent = tmp_path / "missing.db"
+        monitor = HealthMonitor(str(non_existent), tmp_path / "backups")
+        result = monitor.check_database_health()
+
+        assert result.status == HealthStatus.UNHEALTHY
+        assert "not found" in result.message.lower()
+
+    def test_check_disk_space(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test disk space check."""
+        monitor = HealthMonitor(str(temp_db), tmp_path, min_disk_space_gb=0.001)
+        result = monitor.check_disk_space()
+
+        # Should be healthy with minimal requirement
+        assert result.status in [HealthStatus.HEALTHY, HealthStatus.DEGRADED]
+        assert result.details is not None
+        assert "free_gb" in result.details
+
+    def test_check_backup_recency_no_backups(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test backup recency check (no backups)."""
+        backup_dir = tmp_path / "backups"
+        backup_dir.mkdir()
+        (backup_dir / "daily").mkdir()
+
+        monitor = HealthMonitor(str(temp_db), backup_dir)
+        result = monitor.check_backup_recency()
+
+        assert result.status == HealthStatus.UNHEALTHY
+        assert "no" in result.message.lower()
+
+    def test_check_backup_recency_recent(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test backup recency check (recent backup)."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+        scheduler.create_backup(BackupPolicy.DAILY)
+
+        monitor = HealthMonitor(str(temp_db), backup_dir)
+        result = monitor.check_backup_recency()
+
+        assert result.status == HealthStatus.HEALTHY
+        assert "recent" in result.message.lower()
+
+    def test_run_all_checks(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test running all health checks."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+        scheduler.create_backup(BackupPolicy.DAILY)
+
+        monitor = HealthMonitor(str(temp_db), backup_dir, min_disk_space_gb=0.001)
+        checks = monitor.run_all_checks()
+
+        assert "database" in checks
+        assert "disk_space" in checks
+        assert "backup_recency" in checks
+        assert checks["database"].status == HealthStatus.HEALTHY
+
+    def test_get_overall_status(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test overall health status."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+        scheduler.create_backup(BackupPolicy.DAILY)
+
+        monitor = HealthMonitor(str(temp_db), backup_dir, min_disk_space_gb=0.001)
+        status = monitor.get_overall_status()
+
+        assert status in [HealthStatus.HEALTHY, HealthStatus.DEGRADED]
+
+    def test_get_health_report(self, temp_db: Path, tmp_path: Path) -> None:
+        """Test health report generation."""
+        backup_dir = tmp_path / "backups"
+        scheduler = BackupScheduler(str(temp_db), backup_dir)
+        scheduler.create_backup(BackupPolicy.DAILY)
+
+        monitor = HealthMonitor(str(temp_db), backup_dir, min_disk_space_gb=0.001)
+        report = monitor.get_health_report()
+
+        assert "overall_status" in report
+        assert "timestamp" in report
+        assert "checks" in report
+        assert len(report["checks"]) == 3

tests/test_brain.py

@@ -126,7 +126,7 @@ class TestPromptConstruction:
             "orderbook": {"asks": [], "bids": []},
             "foreigner_net": -50000,
         }
-        prompt = client.build_prompt(market_data)
+        prompt = client.build_prompt_sync(market_data)
         assert "005930" in prompt
 
     def test_prompt_contains_price(self, settings):
@@ -137,7 +137,7 @@ class TestPromptConstruction:
             "orderbook": {"asks": [], "bids": []},
             "foreigner_net": -50000,
         }
-        prompt = client.build_prompt(market_data)
+        prompt = client.build_prompt_sync(market_data)
         assert "72000" in prompt
 
     def test_prompt_enforces_json_output_format(self, settings):
@@ -148,7 +148,7 @@ class TestPromptConstruction:
             "orderbook": {"asks": [], "bids": []},
             "foreigner_net": 0,
         }
-        prompt = client.build_prompt(market_data)
+        prompt = client.build_prompt_sync(market_data)
         assert "JSON" in prompt
         assert "action" in prompt
         assert "confidence" in prompt

tests/test_broker.py

@@ -49,6 +49,46 @@ class TestTokenManagement:
 
         await broker.close()
 
+    @pytest.mark.asyncio
+    async def test_concurrent_token_refresh_calls_api_once(self, settings):
+        """Multiple concurrent token requests should only call API once."""
+        broker = KISBroker(settings)
+
+        # Track how many times the mock API is called
+        call_count = [0]
+
+        def create_mock_resp():
+            call_count[0] += 1
+            mock_resp = AsyncMock()
+            mock_resp.status = 200
+            mock_resp.json = AsyncMock(
+                return_value={
+                    "access_token": "tok_concurrent",
+                    "token_type": "Bearer",
+                    "expires_in": 86400,
+                }
+            )
+            mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+            mock_resp.__aexit__ = AsyncMock(return_value=False)
+            return mock_resp
+
+        with patch("aiohttp.ClientSession.post", return_value=create_mock_resp()):
+            # Launch 5 concurrent token requests
+            tokens = await asyncio.gather(
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+            )
+
+            # All should get the same token
+            assert all(t == "tok_concurrent" for t in tokens)
+            # API should be called only once (due to lock)
+            assert call_count[0] == 1
+
+        await broker.close()
+
 
 # ---------------------------------------------------------------------------
 # Network Error Handling

tests/test_data_integration.py

@@ -0,0 +1,673 @@
+"""Tests for external data integration (news, economic calendar, market data)."""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from src.brain.gemini_client import GeminiClient
+from src.data.economic_calendar import EconomicCalendar, EconomicEvent
+from src.data.market_data import MarketBreadth, MarketData, MarketSentiment
+from src.data.news_api import NewsAPI, NewsArticle, NewsSentiment
+
+# ---------------------------------------------------------------------------
+# NewsAPI Tests
+# ---------------------------------------------------------------------------
+
+
+class TestNewsAPI:
+    """Test news API integration with caching."""
+
+    def test_news_api_init_without_key(self):
+        """NewsAPI should initialize without API key for testing."""
+        api = NewsAPI(api_key=None)
+        assert api._api_key is None
+        assert api._provider == "alphavantage"
+        assert api._cache_ttl == 300
+
+    def test_news_api_init_with_custom_settings(self):
+        """NewsAPI should accept custom provider and cache TTL."""
+        api = NewsAPI(api_key="test_key", provider="newsapi", cache_ttl=600)
+        assert api._api_key == "test_key"
+        assert api._provider == "newsapi"
+        assert api._cache_ttl == 600
+
+    @pytest.mark.asyncio
+    async def test_get_news_sentiment_without_api_key_returns_none(self):
+        """Without API key, get_news_sentiment should return None."""
+        api = NewsAPI(api_key=None)
+        result = await api.get_news_sentiment("AAPL")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_cache_hit_returns_cached_sentiment(self):
+        """Cache hit should return cached sentiment without API call."""
+        api = NewsAPI(api_key="test_key")
+
+        # Manually populate cache
+        cached_sentiment = NewsSentiment(
+            stock_code="AAPL",
+            articles=[],
+            avg_sentiment=0.5,
+            article_count=0,
+            fetched_at=time.time(),
+        )
+        api._cache["AAPL"] = cached_sentiment
+
+        result = await api.get_news_sentiment("AAPL")
+        assert result is cached_sentiment
+        assert result.stock_code == "AAPL"
+
+    @pytest.mark.asyncio
+    async def test_cache_expiry_triggers_refetch(self):
+        """Expired cache entry should trigger refetch."""
+        api = NewsAPI(api_key="test_key", cache_ttl=1)
+
+        # Add expired cache entry
+        expired_sentiment = NewsSentiment(
+            stock_code="AAPL",
+            articles=[],
+            avg_sentiment=0.5,
+            article_count=0,
+            fetched_at=time.time() - 10,  # 10 seconds ago
+        )
+        api._cache["AAPL"] = expired_sentiment
+
+        # Mock the fetch to avoid real API call
+        with patch.object(api, "_fetch_news", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.return_value = None
+            result = await api.get_news_sentiment("AAPL")
+
+            # Should have attempted refetch since cache expired
+            mock_fetch.assert_called_once_with("AAPL")
+
+    def test_clear_cache(self):
+        """clear_cache should empty the cache."""
+        api = NewsAPI(api_key="test_key")
+        api._cache["AAPL"] = NewsSentiment(
+            stock_code="AAPL",
+            articles=[],
+            avg_sentiment=0.0,
+            article_count=0,
+            fetched_at=time.time(),
+        )
+        assert len(api._cache) == 1
+
+        api.clear_cache()
+        assert len(api._cache) == 0
+
+    def test_parse_alphavantage_response_with_valid_data(self):
+        """Should parse Alpha Vantage response correctly."""
+        api = NewsAPI(api_key="test_key", provider="alphavantage")
+
+        mock_response = {
+            "feed": [
+                {
+                    "title": "Apple hits new high",
+                    "summary": "Apple stock surges to record levels",
+                    "source": "Reuters",
+                    "time_published": "2026-02-04T10:00:00",
+                    "url": "https://example.com/1",
+                    "ticker_sentiment": [
+                        {"ticker": "AAPL", "ticker_sentiment_score": "0.85"}
+                    ],
+                    "overall_sentiment_score": "0.75",
+                },
+                {
+                    "title": "Market volatility rises",
+                    "summary": "Tech stocks face headwinds",
+                    "source": "Bloomberg",
+                    "time_published": "2026-02-04T09:00:00",
+                    "url": "https://example.com/2",
+                    "ticker_sentiment": [
+                        {"ticker": "AAPL", "ticker_sentiment_score": "-0.3"}
+                    ],
+                    "overall_sentiment_score": "-0.2",
+                },
+            ]
+        }
+
+        result = api._parse_alphavantage_response("AAPL", mock_response)
+
+        assert result is not None
+        assert result.stock_code == "AAPL"
+        assert result.article_count == 2
+        assert len(result.articles) == 2
+        assert result.articles[0].title == "Apple hits new high"
+        assert result.articles[0].sentiment_score == 0.85
+        assert result.articles[1].sentiment_score == -0.3
+        # Average: (0.85 - 0.3) / 2 = 0.275
+        assert abs(result.avg_sentiment - 0.275) < 0.01
+
+    def test_parse_alphavantage_response_without_feed_returns_none(self):
+        """Should return None if 'feed' key is missing."""
+        api = NewsAPI(api_key="test_key", provider="alphavantage")
+        result = api._parse_alphavantage_response("AAPL", {})
+        assert result is None
+
+    def test_parse_newsapi_response_with_valid_data(self):
+        """Should parse NewsAPI.org response correctly."""
+        api = NewsAPI(api_key="test_key", provider="newsapi")
+
+        mock_response = {
+            "status": "ok",
+            "articles": [
+                {
+                    "title": "Apple stock surges",
+                    "description": "Strong earnings beat expectations",
+                    "source": {"name": "TechCrunch"},
+                    "publishedAt": "2026-02-04T10:00:00Z",
+                    "url": "https://example.com/1",
+                },
+                {
+                    "title": "Tech sector faces risks",
+                    "description": "Concerns over market downturn",
+                    "source": {"name": "CNBC"},
+                    "publishedAt": "2026-02-04T09:00:00Z",
+                    "url": "https://example.com/2",
+                },
+            ],
+        }
+
+        result = api._parse_newsapi_response("AAPL", mock_response)
+
+        assert result is not None
+        assert result.stock_code == "AAPL"
+        assert result.article_count == 2
+        assert len(result.articles) == 2
+        assert result.articles[0].title == "Apple stock surges"
+        assert result.articles[0].source == "TechCrunch"
+
+    def test_estimate_sentiment_from_text_positive(self):
+        """Should detect positive sentiment from keywords."""
+        api = NewsAPI()
+        text = "Stock price surges with strong profit growth and upgrade"
+        sentiment = api._estimate_sentiment_from_text(text)
+        assert sentiment > 0.5
+
+    def test_estimate_sentiment_from_text_negative(self):
+        """Should detect negative sentiment from keywords."""
+        api = NewsAPI()
+        text = "Stock plunges on weak earnings, downgrade warning"
+        sentiment = api._estimate_sentiment_from_text(text)
+        assert sentiment < -0.5
+
+    def test_estimate_sentiment_from_text_neutral(self):
+        """Should return neutral sentiment without keywords."""
+        api = NewsAPI()
+        text = "Company announces quarterly report"
+        sentiment = api._estimate_sentiment_from_text(text)
+        assert abs(sentiment) < 0.1
+
+
+# ---------------------------------------------------------------------------
+# EconomicCalendar Tests
+# ---------------------------------------------------------------------------
+
+
+class TestEconomicCalendar:
+    """Test economic calendar functionality."""
+
+    def test_economic_calendar_init(self):
+        """EconomicCalendar should initialize correctly."""
+        calendar = EconomicCalendar(api_key="test_key")
+        assert calendar._api_key == "test_key"
+        assert len(calendar._events) == 0
+
+    def test_add_event(self):
+        """Should be able to add events to calendar."""
+        calendar = EconomicCalendar()
+        event = EconomicEvent(
+            name="FOMC Meeting",
+            event_type="FOMC",
+            datetime=datetime(2026, 3, 18),
+            impact="HIGH",
+            country="US",
+            description="Interest rate decision",
+        )
+        calendar.add_event(event)
+        assert len(calendar._events) == 1
+        assert calendar._events[0].name == "FOMC Meeting"
+
+    def test_get_upcoming_events_filters_by_timeframe(self):
+        """Should only return events within specified timeframe."""
+        calendar = EconomicCalendar()
+
+        # Add events at different times
+        now = datetime.now()
+        calendar.add_event(
+            EconomicEvent(
+                name="Event Tomorrow",
+                event_type="GDP",
+                datetime=now + timedelta(days=1),
+                impact="HIGH",
+                country="US",
+                description="Test event",
+            )
+        )
+        calendar.add_event(
+            EconomicEvent(
+                name="Event Next Month",
+                event_type="CPI",
+                datetime=now + timedelta(days=30),
+                impact="HIGH",
+                country="US",
+                description="Test event",
+            )
+        )
+
+        # Get events for next 7 days
+        upcoming = calendar.get_upcoming_events(days_ahead=7, min_impact="HIGH")
+        assert upcoming.high_impact_count == 1
+        assert upcoming.events[0].name == "Event Tomorrow"
+
+    def test_get_upcoming_events_filters_by_impact(self):
+        """Should filter events by minimum impact level."""
+        calendar = EconomicCalendar()
+
+        now = datetime.now()
+        calendar.add_event(
+            EconomicEvent(
+                name="High Impact Event",
+                event_type="FOMC",
+                datetime=now + timedelta(days=1),
+                impact="HIGH",
+                country="US",
+                description="Test",
+            )
+        )
+        calendar.add_event(
+            EconomicEvent(
+                name="Low Impact Event",
+                event_type="OTHER",
+                datetime=now + timedelta(days=1),
+                impact="LOW",
+                country="US",
+                description="Test",
+            )
+        )
+
+        # Filter for HIGH impact only
+        upcoming = calendar.get_upcoming_events(days_ahead=7, min_impact="HIGH")
+        assert upcoming.high_impact_count == 1
+        assert upcoming.events[0].name == "High Impact Event"
+
+        # Filter for MEDIUM and above (should still get HIGH)
+        upcoming = calendar.get_upcoming_events(days_ahead=7, min_impact="MEDIUM")
+        assert len(upcoming.events) == 1
+
+        # Filter for LOW and above (should get both)
+        upcoming = calendar.get_upcoming_events(days_ahead=7, min_impact="LOW")
+        assert len(upcoming.events) == 2
+
+    def test_get_earnings_date_returns_next_earnings(self):
+        """Should return next earnings date for a stock."""
+        calendar = EconomicCalendar()
+
+        now = datetime.now()
+        earnings_date = now + timedelta(days=5)
+
+        calendar.add_event(
+            EconomicEvent(
+                name="AAPL Earnings",
+                event_type="EARNINGS",
+                datetime=earnings_date,
+                impact="HIGH",
+                country="US",
+                description="Apple quarterly earnings",
+            )
+        )
+
+        result = calendar.get_earnings_date("AAPL")
+        assert result == earnings_date
+
+    def test_get_earnings_date_returns_none_if_not_found(self):
+        """Should return None if no earnings found for stock."""
+        calendar = EconomicCalendar()
+        result = calendar.get_earnings_date("UNKNOWN")
+        assert result is None
+
+    def test_load_hardcoded_events(self):
+        """Should load hardcoded major economic events."""
+        calendar = EconomicCalendar()
+        calendar.load_hardcoded_events()
+
+        # Should have multiple events (FOMC, GDP, CPI)
+        assert len(calendar._events) > 10
+
+        # Check for FOMC events
+        fomc_events = [e for e in calendar._events if e.event_type == "FOMC"]
+        assert len(fomc_events) > 0
+
+        # Check for GDP events
+        gdp_events = [e for e in calendar._events if e.event_type == "GDP"]
+        assert len(gdp_events) > 0
+
+        # Check for CPI events
+        cpi_events = [e for e in calendar._events if e.event_type == "CPI"]
+        assert len(cpi_events) == 12  # Monthly CPI releases
+
+    def test_is_high_volatility_period_returns_true_near_high_impact(self):
+        """Should return True if high-impact event is within threshold."""
+        calendar = EconomicCalendar()
+
+        now = datetime.now()
+        calendar.add_event(
+            EconomicEvent(
+                name="FOMC Meeting",
+                event_type="FOMC",
+                datetime=now + timedelta(hours=12),
+                impact="HIGH",
+                country="US",
+                description="Test",
+            )
+        )
+
+        assert calendar.is_high_volatility_period(hours_ahead=24) is True
+
+    def test_is_high_volatility_period_returns_false_when_no_events(self):
+        """Should return False if no high-impact events nearby."""
+        calendar = EconomicCalendar()
+        assert calendar.is_high_volatility_period(hours_ahead=24) is False
+
+    def test_clear_events(self):
+        """Should clear all events."""
+        calendar = EconomicCalendar()
+        calendar.add_event(
+            EconomicEvent(
+                name="Test",
+                event_type="TEST",
+                datetime=datetime.now(),
+                impact="LOW",
+                country="US",
+                description="Test",
+            )
+        )
+        assert len(calendar._events) == 1
+
+        calendar.clear_events()
+        assert len(calendar._events) == 0
+
+
+# ---------------------------------------------------------------------------
+# MarketData Tests
+# ---------------------------------------------------------------------------
+
+
+class TestMarketData:
+    """Test market data indicators."""
+
+    def test_market_data_init(self):
+        """MarketData should initialize correctly."""
+        data = MarketData(api_key="test_key")
+        assert data._api_key == "test_key"
+
+    def test_get_market_sentiment_without_api_key_returns_neutral(self):
+        """Without API key, should return NEUTRAL sentiment."""
+        data = MarketData(api_key=None)
+        sentiment = data.get_market_sentiment()
+        assert sentiment == MarketSentiment.NEUTRAL
+
+    def test_get_market_breadth_without_api_key_returns_none(self):
+        """Without API key, should return None for breadth."""
+        data = MarketData(api_key=None)
+        breadth = data.get_market_breadth()
+        assert breadth is None
+
+    def test_get_sector_performance_without_api_key_returns_empty(self):
+        """Without API key, should return empty list."""
+        data = MarketData(api_key=None)
+        sectors = data.get_sector_performance()
+        assert sectors == []
+
+    def test_get_market_indicators_returns_defaults_without_api(self):
+        """Should return default indicators without API key."""
+        data = MarketData(api_key=None)
+        indicators = data.get_market_indicators()
+
+        assert indicators.sentiment == MarketSentiment.NEUTRAL
+        assert indicators.breadth.advance_decline_ratio == 1.0
+        assert indicators.sector_performance == []
+        assert indicators.vix_level is None
+
+    def test_calculate_fear_greed_score_neutral_baseline(self):
+        """Should return neutral score (50) for balanced market."""
+        data = MarketData()
+        breadth = MarketBreadth(
+            advancing_stocks=500,
+            declining_stocks=500,
+            unchanged_stocks=100,
+            new_highs=50,
+            new_lows=50,
+            advance_decline_ratio=1.0,
+        )
+
+        score = data.calculate_fear_greed_score(breadth)
+        assert score == 50
+
+    def test_calculate_fear_greed_score_greedy_market(self):
+        """Should return high score for greedy market conditions."""
+        data = MarketData()
+        breadth = MarketBreadth(
+            advancing_stocks=800,
+            declining_stocks=200,
+            unchanged_stocks=100,
+            new_highs=100,
+            new_lows=10,
+            advance_decline_ratio=4.0,
+        )
+
+        score = data.calculate_fear_greed_score(breadth, vix=12.0)
+        assert score > 70
+
+    def test_calculate_fear_greed_score_fearful_market(self):
+        """Should return low score for fearful market conditions."""
+        data = MarketData()
+        breadth = MarketBreadth(
+            advancing_stocks=200,
+            declining_stocks=800,
+            unchanged_stocks=100,
+            new_highs=10,
+            new_lows=100,
+            advance_decline_ratio=0.25,
+        )
+
+        score = data.calculate_fear_greed_score(breadth, vix=35.0)
+        assert score < 30
+
+
+# ---------------------------------------------------------------------------
+# GeminiClient Integration Tests
+# ---------------------------------------------------------------------------
+
+
+class TestGeminiClientWithExternalData:
+    """Test GeminiClient integration with external data sources."""
+
+    def test_gemini_client_accepts_optional_data_sources(self, settings):
+        """GeminiClient should accept optional external data sources."""
+        news_api = NewsAPI(api_key="test_key")
+        calendar = EconomicCalendar()
+        market_data = MarketData()
+
+        client = GeminiClient(
+            settings,
+            news_api=news_api,
+            economic_calendar=calendar,
+            market_data=market_data,
+        )
+
+        assert client._news_api is news_api
+        assert client._economic_calendar is calendar
+        assert client._market_data is market_data
+
+    def test_gemini_client_works_without_external_data(self, settings):
+        """GeminiClient should work without external data sources."""
+        client = GeminiClient(settings)
+        assert client._news_api is None
+        assert client._economic_calendar is None
+        assert client._market_data is None
+
+    @pytest.mark.asyncio
+    async def test_build_prompt_includes_news_sentiment(self, settings):
+        """build_prompt should include news sentiment when available."""
+        client = GeminiClient(settings)
+
+        market_data = {
+            "stock_code": "AAPL",
+            "current_price": 180.0,
+            "market_name": "US stock market",
+        }
+
+        sentiment = NewsSentiment(
+            stock_code="AAPL",
+            articles=[
+                NewsArticle(
+                    title="Apple hits record high",
+                    summary="Strong earnings",
+                    source="Reuters",
+                    published_at="2026-02-04",
+                    sentiment_score=0.85,
+                    url="https://example.com",
+                )
+            ],
+            avg_sentiment=0.85,
+            article_count=1,
+            fetched_at=time.time(),
+        )
+
+        prompt = await client.build_prompt(market_data, news_sentiment=sentiment)
+
+        assert "AAPL" in prompt
+        assert "180.0" in prompt
+        assert "EXTERNAL DATA" in prompt
+        assert "News Sentiment" in prompt
+        assert "0.85" in prompt
+        assert "Apple hits record high" in prompt
+
+    @pytest.mark.asyncio
+    async def test_build_prompt_with_economic_events(self, settings):
+        """build_prompt should include upcoming economic events."""
+        calendar = EconomicCalendar()
+        now = datetime.now()
+        calendar.add_event(
+            EconomicEvent(
+                name="FOMC Meeting",
+                event_type="FOMC",
+                datetime=now + timedelta(days=2),
+                impact="HIGH",
+                country="US",
+                description="Interest rate decision",
+            )
+        )
+
+        client = GeminiClient(settings, economic_calendar=calendar)
+
+        market_data = {
+            "stock_code": "AAPL",
+            "current_price": 180.0,
+            "market_name": "US stock market",
+        }
+
+        prompt = await client.build_prompt(market_data)
+
+        assert "EXTERNAL DATA" in prompt
+        assert "High-Impact Events" in prompt
+        assert "FOMC Meeting" in prompt
+
+    @pytest.mark.asyncio
+    async def test_build_prompt_with_market_indicators(self, settings):
+        """build_prompt should include market sentiment indicators."""
+        market_data_provider = MarketData(api_key="test_key")
+
+        # Mock the get_market_indicators to return test data
+        with patch.object(market_data_provider, "get_market_indicators") as mock:
+            mock.return_value = MagicMock(
+                sentiment=MarketSentiment.EXTREME_GREED,
+                breadth=MagicMock(advance_decline_ratio=2.5),
+            )
+
+            client = GeminiClient(settings, market_data=market_data_provider)
+
+            market_data = {
+                "stock_code": "AAPL",
+                "current_price": 180.0,
+                "market_name": "US stock market",
+            }
+
+            prompt = await client.build_prompt(market_data)
+
+            assert "EXTERNAL DATA" in prompt
+            assert "Market Sentiment" in prompt
+            assert "EXTREME_GREED" in prompt
+
+    @pytest.mark.asyncio
+    async def test_build_prompt_graceful_when_no_external_data(self, settings):
+        """build_prompt should work gracefully without external data."""
+        client = GeminiClient(settings)
+
+        market_data = {
+            "stock_code": "AAPL",
+            "current_price": 180.0,
+            "market_name": "US stock market",
+        }
+
+        prompt = await client.build_prompt(market_data)
+
+        assert "AAPL" in prompt
+        assert "180.0" in prompt
+        # Should NOT have external data section
+        assert "EXTERNAL DATA" not in prompt
+
+    def test_build_prompt_sync_backward_compatibility(self, settings):
+        """build_prompt_sync should maintain backward compatibility."""
+        client = GeminiClient(settings)
+
+        market_data = {
+            "stock_code": "005930",
+            "current_price": 72000,
+            "orderbook": {"asks": [], "bids": []},
+            "foreigner_net": -50000,
+        }
+
+        prompt = client.build_prompt_sync(market_data)
+
+        assert "005930" in prompt
+        assert "72000" in prompt
+        assert "JSON" in prompt
+        # Sync version should NOT have external data
+        assert "EXTERNAL DATA" not in prompt
+
+    @pytest.mark.asyncio
+    async def test_decide_with_news_sentiment_parameter(self, settings):
+        """decide should accept optional news_sentiment parameter."""
+        client = GeminiClient(settings)
+
+        market_data = {
+            "stock_code": "AAPL",
+            "current_price": 180.0,
+            "market_name": "US stock market",
+        }
+
+        sentiment = NewsSentiment(
+            stock_code="AAPL",
+            articles=[],
+            avg_sentiment=0.5,
+            article_count=1,
+            fetched_at=time.time(),
+        )
+
+        # Mock the Gemini API call
+        with patch.object(client._client.aio.models, "generate_content", new_callable=AsyncMock) as mock_gen:
+            mock_response = MagicMock()
+            mock_response.text = '{"action": "BUY", "confidence": 85, "rationale": "Good news"}'
+            mock_gen.return_value = mock_response
+
+            decision = await client.decide(market_data, news_sentiment=sentiment)
+
+            assert decision.action == "BUY"
+            assert decision.confidence == 85
+            mock_gen.assert_called_once()

tests/test_evolution.py

@@ -0,0 +1,685 @@
+"""Tests for the Evolution Engine components.
+
+Tests cover:
+- EvolutionOptimizer: failure analysis and strategy generation
+- ABTester: A/B testing and statistical comparison
+- PerformanceTracker: metrics tracking and dashboard
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from src.config import Settings
+from src.db import init_db, log_trade
+from src.evolution.ab_test import ABTester
+from src.evolution.optimizer import EvolutionOptimizer
+from src.evolution.performance_tracker import (
+    PerformanceDashboard,
+    PerformanceTracker,
+    StrategyMetrics,
+)
+from src.logging.decision_logger import DecisionLogger
+
+# ------------------------------------------------------------------
+# Fixtures
+# ------------------------------------------------------------------
+
+
+@pytest.fixture
+def db_conn() -> sqlite3.Connection:
+    """Provide an in-memory database with initialized schema."""
+    return init_db(":memory:")
+
+
+@pytest.fixture
+def settings() -> Settings:
+    """Provide test settings."""
+    return Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+        GEMINI_MODEL="gemini-pro",
+        DB_PATH=":memory:",
+    )
+
+
+@pytest.fixture
+def optimizer(settings: Settings) -> EvolutionOptimizer:
+    """Provide an EvolutionOptimizer instance."""
+    return EvolutionOptimizer(settings)
+
+
+@pytest.fixture
+def decision_logger(db_conn: sqlite3.Connection) -> DecisionLogger:
+    """Provide a DecisionLogger instance."""
+    return DecisionLogger(db_conn)
+
+
+@pytest.fixture
+def ab_tester() -> ABTester:
+    """Provide an ABTester instance."""
+    return ABTester(significance_level=0.05)
+
+
+@pytest.fixture
+def performance_tracker(settings: Settings) -> PerformanceTracker:
+    """Provide a PerformanceTracker instance."""
+    return PerformanceTracker(db_path=":memory:")
+
+
+# ------------------------------------------------------------------
+# EvolutionOptimizer Tests
+# ------------------------------------------------------------------
+
+
+def test_analyze_failures_uses_decision_logger(optimizer: EvolutionOptimizer) -> None:
+    """Test that analyze_failures uses DecisionLogger.get_losing_decisions()."""
+    # Add some losing decisions to the database
+    logger = optimizer._decision_logger
+
+    # High-confidence loss
+    id1 = logger.log_decision(
+        stock_code="005930",
+        market="KR",
+        exchange_code="KRX",
+        action="BUY",
+        confidence=85,
+        rationale="Expected growth",
+        context_snapshot={"L1": {"price": 70000}},
+        input_data={"price": 70000, "volume": 1000},
+    )
+    logger.update_outcome(id1, pnl=-2000.0, accuracy=0)
+
+    # Another high-confidence loss
+    id2 = logger.log_decision(
+        stock_code="000660",
+        market="KR",
+        exchange_code="KRX",
+        action="SELL",
+        confidence=90,
+        rationale="Expected drop",
+        context_snapshot={"L1": {"price": 100000}},
+        input_data={"price": 100000, "volume": 500},
+    )
+    logger.update_outcome(id2, pnl=-1500.0, accuracy=0)
+
+    # Low-confidence loss (should be ignored)
+    id3 = logger.log_decision(
+        stock_code="035420",
+        market="KR",
+        exchange_code="KRX",
+        action="HOLD",
+        confidence=70,
+        rationale="Uncertain",
+        context_snapshot={},
+        input_data={},
+    )
+    logger.update_outcome(id3, pnl=-500.0, accuracy=0)
+
+    # Analyze failures
+    failures = optimizer.analyze_failures(limit=10)
+
+    # Should get 2 failures (confidence >= 80)
+    assert len(failures) == 2
+    assert all(f["confidence"] >= 80 for f in failures)
+    assert all(f["outcome_pnl"] <= -100.0 for f in failures)
+
+
+def test_analyze_failures_empty_database(optimizer: EvolutionOptimizer) -> None:
+    """Test analyze_failures with no losing decisions."""
+    failures = optimizer.analyze_failures()
+    assert failures == []
+
+
+def test_identify_failure_patterns(optimizer: EvolutionOptimizer) -> None:
+    """Test identification of failure patterns."""
+    failures = [
+        {
+            "decision_id": "1",
+            "timestamp": "2024-01-15T09:30:00+00:00",
+            "stock_code": "005930",
+            "market": "KR",
+            "exchange_code": "KRX",
+            "action": "BUY",
+            "confidence": 85,
+            "rationale": "Test",
+            "outcome_pnl": -1000.0,
+            "outcome_accuracy": 0,
+            "context_snapshot": {},
+            "input_data": {},
+        },
+        {
+            "decision_id": "2",
+            "timestamp": "2024-01-15T14:30:00+00:00",
+            "stock_code": "000660",
+            "market": "KR",
+            "exchange_code": "KRX",
+            "action": "SELL",
+            "confidence": 90,
+            "rationale": "Test",
+            "outcome_pnl": -2000.0,
+            "outcome_accuracy": 0,
+            "context_snapshot": {},
+            "input_data": {},
+        },
+        {
+            "decision_id": "3",
+            "timestamp": "2024-01-15T09:45:00+00:00",
+            "stock_code": "035420",
+            "market": "US_NASDAQ",
+            "exchange_code": "NASDAQ",
+            "action": "BUY",
+            "confidence": 80,
+            "rationale": "Test",
+            "outcome_pnl": -500.0,
+            "outcome_accuracy": 0,
+            "context_snapshot": {},
+            "input_data": {},
+        },
+    ]
+
+    patterns = optimizer.identify_failure_patterns(failures)
+
+    assert patterns["total_failures"] == 3
+    assert patterns["markets"]["KR"] == 2
+    assert patterns["markets"]["US_NASDAQ"] == 1
+    assert patterns["actions"]["BUY"] == 2
+    assert patterns["actions"]["SELL"] == 1
+    assert 9 in patterns["hours"]  # 09:30 and 09:45
+    assert 14 in patterns["hours"]  # 14:30
+    assert patterns["avg_confidence"] == 85.0
+    assert patterns["avg_loss"] == -1166.67
+
+
+def test_identify_failure_patterns_empty(optimizer: EvolutionOptimizer) -> None:
+    """Test pattern identification with no failures."""
+    patterns = optimizer.identify_failure_patterns([])
+    assert patterns["pattern_count"] == 0
+    assert patterns["patterns"] == {}
+
+
+@pytest.mark.asyncio
+async def test_generate_strategy_creates_file(optimizer: EvolutionOptimizer, tmp_path: Path) -> None:
+    """Test that generate_strategy creates a strategy file."""
+    failures = [
+        {
+            "decision_id": "1",
+            "timestamp": "2024-01-15T09:30:00+00:00",
+            "stock_code": "005930",
+            "market": "KR",
+            "action": "BUY",
+            "confidence": 85,
+            "outcome_pnl": -1000.0,
+            "context_snapshot": {},
+            "input_data": {},
+        }
+    ]
+
+    # Mock Gemini response
+    mock_response = Mock()
+    mock_response.text = """
+    # Simple strategy
+    price = market_data.get("current_price", 0)
+    if price > 50000:
+        return {"action": "BUY", "confidence": 70, "rationale": "Price above threshold"}
+    return {"action": "HOLD", "confidence": 50, "rationale": "Waiting"}
+    """
+
+    with patch.object(optimizer._client.aio.models, "generate_content", new=AsyncMock(return_value=mock_response)):
+        with patch("src.evolution.optimizer.STRATEGIES_DIR", tmp_path):
+            strategy_path = await optimizer.generate_strategy(failures)
+
+    assert strategy_path is not None
+    assert strategy_path.exists()
+    assert strategy_path.suffix == ".py"
+    assert "class Strategy_" in strategy_path.read_text()
+    assert "def evaluate" in strategy_path.read_text()
+
+
+@pytest.mark.asyncio
+async def test_generate_strategy_handles_api_error(optimizer: EvolutionOptimizer) -> None:
+    """Test that generate_strategy handles Gemini API errors gracefully."""
+    failures = [{"decision_id": "1", "timestamp": "2024-01-15T09:30:00+00:00"}]
+
+    with patch.object(
+        optimizer._client.aio.models,
+        "generate_content",
+        side_effect=Exception("API Error"),
+    ):
+        strategy_path = await optimizer.generate_strategy(failures)
+
+    assert strategy_path is None
+
+
+def test_get_performance_summary() -> None:
+    """Test getting performance summary from trades table."""
+    # Create a temporary database with trades
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp:
+        tmp_path = tmp.name
+
+    conn = init_db(tmp_path)
+    log_trade(conn, "005930", "BUY", 85, "Test win", quantity=10, price=70000, pnl=1000.0)
+    log_trade(conn, "000660", "SELL", 90, "Test loss", quantity=5, price=100000, pnl=-500.0)
+    log_trade(conn, "035420", "BUY", 80, "Test win", quantity=8, price=50000, pnl=800.0)
+    conn.close()
+
+    # Create settings with temp database path
+    settings = Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+        GEMINI_MODEL="gemini-pro",
+        DB_PATH=tmp_path,
+    )
+
+    optimizer = EvolutionOptimizer(settings)
+    summary = optimizer.get_performance_summary()
+
+    assert summary["total_trades"] == 3
+    assert summary["wins"] == 2
+    assert summary["losses"] == 1
+    assert summary["total_pnl"] == 1300.0
+    assert summary["avg_pnl"] == 433.33
+
+    # Clean up
+    Path(tmp_path).unlink()
+
+
+def test_validate_strategy_success(optimizer: EvolutionOptimizer, tmp_path: Path) -> None:
+    """Test strategy validation when tests pass."""
+    strategy_file = tmp_path / "test_strategy.py"
+    strategy_file.write_text("# Valid strategy file")
+
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+        result = optimizer.validate_strategy(strategy_file)
+
+    assert result is True
+    assert strategy_file.exists()
+
+
+def test_validate_strategy_failure(optimizer: EvolutionOptimizer, tmp_path: Path) -> None:
+    """Test strategy validation when tests fail."""
+    strategy_file = tmp_path / "test_strategy.py"
+    strategy_file.write_text("# Invalid strategy file")
+
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = Mock(returncode=1, stdout="FAILED", stderr="")
+        result = optimizer.validate_strategy(strategy_file)
+
+    assert result is False
+    # File should be deleted on failure
+    assert not strategy_file.exists()
+
+
+# ------------------------------------------------------------------
+# ABTester Tests
+# ------------------------------------------------------------------
+
+
+def test_calculate_performance_basic(ab_tester: ABTester) -> None:
+    """Test basic performance calculation."""
+    trades = [
+        {"pnl": 1000.0},
+        {"pnl": -500.0},
+        {"pnl": 800.0},
+        {"pnl": 200.0},
+    ]
+
+    perf = ab_tester.calculate_performance(trades, "TestStrategy")
+
+    assert perf.strategy_name == "TestStrategy"
+    assert perf.total_trades == 4
+    assert perf.wins == 3
+    assert perf.losses == 1
+    assert perf.total_pnl == 1500.0
+    assert perf.avg_pnl == 375.0
+    assert perf.win_rate == 75.0
+    assert perf.sharpe_ratio is not None
+
+
+def test_calculate_performance_empty(ab_tester: ABTester) -> None:
+    """Test performance calculation with no trades."""
+    perf = ab_tester.calculate_performance([], "EmptyStrategy")
+
+    assert perf.total_trades == 0
+    assert perf.wins == 0
+    assert perf.losses == 0
+    assert perf.total_pnl == 0.0
+    assert perf.avg_pnl == 0.0
+    assert perf.win_rate == 0.0
+    assert perf.sharpe_ratio is None
+
+
+def test_compare_strategies_significant_difference(ab_tester: ABTester) -> None:
+    """Test strategy comparison with significant performance difference."""
+    # Strategy A: consistently profitable
+    trades_a = [{"pnl": 1000.0} for _ in range(30)]
+
+    # Strategy B: consistently losing
+    trades_b = [{"pnl": -500.0} for _ in range(30)]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "Strategy A", "Strategy B")
+
+    # scipy returns np.True_ instead of Python bool
+    assert bool(result.is_significant) is True
+    assert result.winner == "Strategy A"
+    assert result.p_value < 0.05
+    assert result.performance_a.avg_pnl > result.performance_b.avg_pnl
+
+
+def test_compare_strategies_no_difference(ab_tester: ABTester) -> None:
+    """Test strategy comparison with no significant difference."""
+    # Both strategies have similar performance
+    trades_a = [{"pnl": 100.0}, {"pnl": -50.0}, {"pnl": 80.0}]
+    trades_b = [{"pnl": 90.0}, {"pnl": -60.0}, {"pnl": 85.0}]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "Strategy A", "Strategy B")
+
+    # With small samples and similar performance, likely not significant
+    assert result.winner is None or not result.is_significant
+
+
+def test_should_deploy_meets_criteria(ab_tester: ABTester) -> None:
+    """Test deployment decision when criteria are met."""
+    # Create a winning result that meets criteria
+    trades_a = [{"pnl": 1000.0} for _ in range(25)]  # 100% win rate
+    trades_b = [{"pnl": -500.0} for _ in range(25)]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "Winner", "Loser")
+
+    should_deploy = ab_tester.should_deploy(result, min_win_rate=60.0, min_trades=20)
+
+    assert should_deploy is True
+
+
+def test_should_deploy_insufficient_trades(ab_tester: ABTester) -> None:
+    """Test deployment decision with insufficient trades."""
+    trades_a = [{"pnl": 1000.0} for _ in range(10)]  # Only 10 trades
+    trades_b = [{"pnl": -500.0} for _ in range(10)]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "Winner", "Loser")
+
+    should_deploy = ab_tester.should_deploy(result, min_win_rate=60.0, min_trades=20)
+
+    assert should_deploy is False
+
+
+def test_should_deploy_low_win_rate(ab_tester: ABTester) -> None:
+    """Test deployment decision with low win rate."""
+    # Mix of wins and losses, below 60% win rate
+    trades_a = [{"pnl": 100.0}] * 10 + [{"pnl": -100.0}] * 15  # 40% win rate
+    trades_b = [{"pnl": -500.0} for _ in range(25)]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "LowWinner", "Loser")
+
+    should_deploy = ab_tester.should_deploy(result, min_win_rate=60.0, min_trades=20)
+
+    assert should_deploy is False
+
+
+def test_should_deploy_not_significant(ab_tester: ABTester) -> None:
+    """Test deployment decision when difference is not significant."""
+    # Use more varied data to ensure statistical insignificance
+    trades_a = [{"pnl": 100.0}, {"pnl": -50.0}] * 12 + [{"pnl": 100.0}]
+    trades_b = [{"pnl": 95.0}, {"pnl": -45.0}] * 12 + [{"pnl": 95.0}]
+
+    result = ab_tester.compare_strategies(trades_a, trades_b, "A", "B")
+
+    should_deploy = ab_tester.should_deploy(result, min_win_rate=60.0, min_trades=20)
+
+    # Not significant or not profitable enough
+    # Even if significant, win rate is 50% which is below 60% threshold
+    assert should_deploy is False
+
+
+# ------------------------------------------------------------------
+# PerformanceTracker Tests
+# ------------------------------------------------------------------
+
+
+def test_get_strategy_metrics(db_conn: sqlite3.Connection) -> None:
+    """Test getting strategy metrics."""
+    # Add some trades
+    log_trade(db_conn, "005930", "BUY", 85, "Win 1", quantity=10, price=70000, pnl=1000.0)
+    log_trade(db_conn, "000660", "SELL", 90, "Loss 1", quantity=5, price=100000, pnl=-500.0)
+    log_trade(db_conn, "035420", "BUY", 80, "Win 2", quantity=8, price=50000, pnl=800.0)
+    log_trade(db_conn, "005930", "HOLD", 75, "Hold", quantity=0, price=70000, pnl=0.0)
+
+    tracker = PerformanceTracker(db_path=":memory:")
+    # Manually set connection for testing
+    tracker._db_path = db_conn
+
+    # Need to use the same connection
+    with patch("sqlite3.connect", return_value=db_conn):
+        metrics = tracker.get_strategy_metrics()
+
+    assert metrics.total_trades == 4
+    assert metrics.wins == 2
+    assert metrics.losses == 1
+    assert metrics.holds == 1
+    assert metrics.win_rate == 50.0
+    assert metrics.total_pnl == 1300.0
+
+
+def test_calculate_improvement_trend_improving(performance_tracker: PerformanceTracker) -> None:
+    """Test improvement trend calculation for improving strategy."""
+    metrics = [
+        StrategyMetrics(
+            strategy_name="test",
+            period_start="2024-01-01",
+            period_end="2024-01-07",
+            total_trades=10,
+            wins=5,
+            losses=5,
+            holds=0,
+            win_rate=50.0,
+            avg_pnl=100.0,
+            total_pnl=1000.0,
+            best_trade=500.0,
+            worst_trade=-300.0,
+            avg_confidence=75.0,
+        ),
+        StrategyMetrics(
+            strategy_name="test",
+            period_start="2024-01-08",
+            period_end="2024-01-14",
+            total_trades=10,
+            wins=7,
+            losses=3,
+            holds=0,
+            win_rate=70.0,
+            avg_pnl=200.0,
+            total_pnl=2000.0,
+            best_trade=600.0,
+            worst_trade=-200.0,
+            avg_confidence=80.0,
+        ),
+    ]
+
+    trend = performance_tracker.calculate_improvement_trend(metrics)
+
+    assert trend["trend"] == "improving"
+    assert trend["win_rate_change"] == 20.0
+    assert trend["pnl_change"] == 100.0
+    assert trend["confidence_change"] == 5.0
+
+
+def test_calculate_improvement_trend_declining(performance_tracker: PerformanceTracker) -> None:
+    """Test improvement trend calculation for declining strategy."""
+    metrics = [
+        StrategyMetrics(
+            strategy_name="test",
+            period_start="2024-01-01",
+            period_end="2024-01-07",
+            total_trades=10,
+            wins=7,
+            losses=3,
+            holds=0,
+            win_rate=70.0,
+            avg_pnl=200.0,
+            total_pnl=2000.0,
+            best_trade=600.0,
+            worst_trade=-200.0,
+            avg_confidence=80.0,
+        ),
+        StrategyMetrics(
+            strategy_name="test",
+            period_start="2024-01-08",
+            period_end="2024-01-14",
+            total_trades=10,
+            wins=4,
+            losses=6,
+            holds=0,
+            win_rate=40.0,
+            avg_pnl=-50.0,
+            total_pnl=-500.0,
+            best_trade=300.0,
+            worst_trade=-400.0,
+            avg_confidence=70.0,
+        ),
+    ]
+
+    trend = performance_tracker.calculate_improvement_trend(metrics)
+
+    assert trend["trend"] == "declining"
+    assert trend["win_rate_change"] == -30.0
+    assert trend["pnl_change"] == -250.0
+
+
+def test_calculate_improvement_trend_insufficient_data(performance_tracker: PerformanceTracker) -> None:
+    """Test improvement trend with insufficient data."""
+    metrics = [
+        StrategyMetrics(
+            strategy_name="test",
+            period_start="2024-01-01",
+            period_end="2024-01-07",
+            total_trades=10,
+            wins=5,
+            losses=5,
+            holds=0,
+            win_rate=50.0,
+            avg_pnl=100.0,
+            total_pnl=1000.0,
+            best_trade=500.0,
+            worst_trade=-300.0,
+            avg_confidence=75.0,
+        )
+    ]
+
+    trend = performance_tracker.calculate_improvement_trend(metrics)
+
+    assert trend["trend"] == "insufficient_data"
+    assert trend["win_rate_change"] == 0.0
+    assert trend["pnl_change"] == 0.0
+
+
+def test_export_dashboard_json(performance_tracker: PerformanceTracker) -> None:
+    """Test exporting dashboard as JSON."""
+    overall_metrics = StrategyMetrics(
+        strategy_name="test",
+        period_start="2024-01-01",
+        period_end="2024-01-31",
+        total_trades=100,
+        wins=60,
+        losses=40,
+        holds=10,
+        win_rate=60.0,
+        avg_pnl=150.0,
+        total_pnl=15000.0,
+        best_trade=1000.0,
+        worst_trade=-500.0,
+        avg_confidence=80.0,
+    )
+
+    dashboard = PerformanceDashboard(
+        generated_at=datetime.now(UTC).isoformat(),
+        overall_metrics=overall_metrics,
+        daily_metrics=[],
+        weekly_metrics=[],
+        improvement_trend={"trend": "improving", "win_rate_change": 10.0},
+    )
+
+    json_output = performance_tracker.export_dashboard_json(dashboard)
+
+    # Verify it's valid JSON
+    data = json.loads(json_output)
+    assert "generated_at" in data
+    assert "overall_metrics" in data
+    assert data["overall_metrics"]["total_trades"] == 100
+    assert data["overall_metrics"]["win_rate"] == 60.0
+
+
+def test_generate_dashboard() -> None:
+    """Test generating a complete dashboard."""
+    # Create tracker with temp database
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp:
+        tmp_path = tmp.name
+
+    # Initialize with data
+    conn = init_db(tmp_path)
+    log_trade(conn, "005930", "BUY", 85, "Win", quantity=10, price=70000, pnl=1000.0)
+    log_trade(conn, "000660", "SELL", 90, "Loss", quantity=5, price=100000, pnl=-500.0)
+    conn.close()
+
+    tracker = PerformanceTracker(db_path=tmp_path)
+    dashboard = tracker.generate_dashboard()
+
+    assert isinstance(dashboard, PerformanceDashboard)
+    assert dashboard.overall_metrics.total_trades == 2
+    assert len(dashboard.daily_metrics) == 7
+    assert len(dashboard.weekly_metrics) == 4
+    assert "trend" in dashboard.improvement_trend
+
+    # Clean up
+    Path(tmp_path).unlink()
+
+
+# ------------------------------------------------------------------
+# Integration Tests
+# ------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_full_evolution_pipeline(optimizer: EvolutionOptimizer, tmp_path: Path) -> None:
+    """Test the complete evolution pipeline."""
+    # Add losing decisions
+    logger = optimizer._decision_logger
+    id1 = logger.log_decision(
+        stock_code="005930",
+        market="KR",
+        exchange_code="KRX",
+        action="BUY",
+        confidence=85,
+        rationale="Expected growth",
+        context_snapshot={},
+        input_data={},
+    )
+    logger.update_outcome(id1, pnl=-2000.0, accuracy=0)
+
+    # Mock Gemini and subprocess
+    mock_response = Mock()
+    mock_response.text = 'return {"action": "HOLD", "confidence": 50, "rationale": "Test"}'
+
+    with patch.object(optimizer._client.aio.models, "generate_content", new=AsyncMock(return_value=mock_response)):
+        with patch("src.evolution.optimizer.STRATEGIES_DIR", tmp_path):
+            with patch("subprocess.run") as mock_run:
+                mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+
+                result = await optimizer.evolve()
+
+    assert result is not None
+    assert "title" in result
+    assert "branch" in result
+    assert "status" in result

tests/test_latency_control.py

@@ -0,0 +1,558 @@
+"""Tests for latency control system (criticality assessment and priority queue)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from src.core.criticality import CriticalityAssessor, CriticalityLevel
+from src.core.priority_queue import PriorityTask, PriorityTaskQueue
+
+# ---------------------------------------------------------------------------
+# CriticalityAssessor Tests
+# ---------------------------------------------------------------------------
+
+
+class TestCriticalityAssessor:
+    """Test suite for criticality assessment logic."""
+
+    def test_market_closed_returns_low(self) -> None:
+        """Market closed should return LOW priority."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            is_market_open=False,
+        )
+        assert level == CriticalityLevel.LOW
+
+    def test_very_low_volatility_returns_low(self) -> None:
+        """Very low volatility should return LOW priority."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=20.0,  # Below 30.0 threshold
+            volume_surge=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.LOW
+
+    def test_critical_pnl_threshold_triggered(self) -> None:
+        """P&L below -2.5% should trigger CRITICAL."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=-2.6,  # Below -2.5% threshold
+            volatility_score=50.0,
+            volume_surge=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_critical_pnl_at_circuit_breaker_proximity(self) -> None:
+        """P&L at exactly -2.5% (near -3.0% breaker) should be CRITICAL."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=-2.5,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_critical_price_change_positive(self) -> None:
+        """Large positive price change (>5%) should trigger CRITICAL."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            price_change_1m=5.5,  # Above 5.0% threshold
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_critical_price_change_negative(self) -> None:
+        """Large negative price change (<-5%) should trigger CRITICAL."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            price_change_1m=-6.0,  # Below -5.0% threshold
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_critical_volume_surge(self) -> None:
+        """Extreme volume surge (>10x) should trigger CRITICAL."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=50.0,
+            volume_surge=12.0,  # Above 10.0x threshold
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_high_volatility_returns_high(self) -> None:
+        """High volatility score should return HIGH priority."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=75.0,  # Above 70.0 threshold
+            volume_surge=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.HIGH
+
+    def test_normal_conditions_return_normal(self) -> None:
+        """Normal market conditions should return NORMAL priority."""
+        assessor = CriticalityAssessor()
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.5,
+            volatility_score=50.0,  # Between 30-70
+            volume_surge=1.5,
+            price_change_1m=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.NORMAL
+
+    def test_custom_thresholds(self) -> None:
+        """Custom thresholds should be respected."""
+        assessor = CriticalityAssessor(
+            critical_pnl_threshold=-1.0,
+            critical_price_change_threshold=3.0,
+            critical_volume_surge_threshold=5.0,
+            high_volatility_threshold=60.0,
+            low_volatility_threshold=20.0,
+        )
+
+        # Test custom P&L threshold
+        level = assessor.assess_market_conditions(
+            pnl_pct=-1.1,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+        # Test custom price change threshold
+        level = assessor.assess_market_conditions(
+            pnl_pct=0.0,
+            volatility_score=50.0,
+            volume_surge=1.0,
+            price_change_1m=3.5,
+            is_market_open=True,
+        )
+        assert level == CriticalityLevel.CRITICAL
+
+    def test_get_timeout_returns_correct_values(self) -> None:
+        """Timeout values should match specification."""
+        assessor = CriticalityAssessor()
+
+        assert assessor.get_timeout(CriticalityLevel.CRITICAL) == 5.0
+        assert assessor.get_timeout(CriticalityLevel.HIGH) == 30.0
+        assert assessor.get_timeout(CriticalityLevel.NORMAL) == 60.0
+        assert assessor.get_timeout(CriticalityLevel.LOW) is None
+
+
+# ---------------------------------------------------------------------------
+# PriorityTaskQueue Tests
+# ---------------------------------------------------------------------------
+
+
+class TestPriorityTaskQueue:
+    """Test suite for priority queue implementation."""
+
+    @pytest.mark.asyncio
+    async def test_enqueue_task(self) -> None:
+        """Tasks should be enqueued successfully."""
+        queue = PriorityTaskQueue()
+
+        success = await queue.enqueue(
+            task_id="test-1",
+            criticality=CriticalityLevel.NORMAL,
+            task_data={"action": "test"},
+        )
+
+        assert success is True
+        assert await queue.size() == 1
+
+    @pytest.mark.asyncio
+    async def test_enqueue_rejects_when_full(self) -> None:
+        """Queue should reject tasks when full."""
+        queue = PriorityTaskQueue(max_size=2)
+
+        # Fill the queue
+        await queue.enqueue("task-1", CriticalityLevel.NORMAL, {})
+        await queue.enqueue("task-2", CriticalityLevel.NORMAL, {})
+
+        # Third task should be rejected
+        success = await queue.enqueue("task-3", CriticalityLevel.NORMAL, {})
+        assert success is False
+        assert await queue.size() == 2
+
+    @pytest.mark.asyncio
+    async def test_dequeue_returns_highest_priority(self) -> None:
+        """Dequeue should return highest priority task first."""
+        queue = PriorityTaskQueue()
+
+        # Enqueue tasks in reverse priority order
+        await queue.enqueue("low", CriticalityLevel.LOW, {"priority": 3})
+        await queue.enqueue("normal", CriticalityLevel.NORMAL, {"priority": 2})
+        await queue.enqueue("high", CriticalityLevel.HIGH, {"priority": 1})
+        await queue.enqueue("critical", CriticalityLevel.CRITICAL, {"priority": 0})
+
+        # Dequeue should return CRITICAL first
+        task = await queue.dequeue(timeout=1.0)
+        assert task is not None
+        assert task.task_id == "critical"
+        assert task.priority == 0
+
+        # Then HIGH
+        task = await queue.dequeue(timeout=1.0)
+        assert task is not None
+        assert task.task_id == "high"
+        assert task.priority == 1
+
+    @pytest.mark.asyncio
+    async def test_dequeue_fifo_within_same_priority(self) -> None:
+        """Tasks with same priority should be FIFO."""
+        queue = PriorityTaskQueue()
+
+        # Enqueue multiple tasks with same priority
+        await queue.enqueue("task-1", CriticalityLevel.NORMAL, {})
+        await asyncio.sleep(0.01)  # Small delay to ensure different timestamps
+        await queue.enqueue("task-2", CriticalityLevel.NORMAL, {})
+        await asyncio.sleep(0.01)
+        await queue.enqueue("task-3", CriticalityLevel.NORMAL, {})
+
+        # Should dequeue in FIFO order
+        task1 = await queue.dequeue(timeout=1.0)
+        task2 = await queue.dequeue(timeout=1.0)
+        task3 = await queue.dequeue(timeout=1.0)
+
+        assert task1 is not None and task1.task_id == "task-1"
+        assert task2 is not None and task2.task_id == "task-2"
+        assert task3 is not None and task3.task_id == "task-3"
+
+    @pytest.mark.asyncio
+    async def test_dequeue_returns_none_when_empty(self) -> None:
+        """Dequeue should return None when queue is empty after timeout."""
+        queue = PriorityTaskQueue()
+
+        task = await queue.dequeue(timeout=0.1)
+        assert task is None
+
+    @pytest.mark.asyncio
+    async def test_execute_with_timeout_success(self) -> None:
+        """Task execution should succeed within timeout."""
+        queue = PriorityTaskQueue()
+
+        # Create a simple async callback
+        async def test_callback() -> str:
+            await asyncio.sleep(0.01)
+            return "success"
+
+        task = PriorityTask(
+            priority=0,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=test_callback,
+        )
+
+        result = await queue.execute_with_timeout(task, timeout=1.0)
+        assert result == "success"
+
+    @pytest.mark.asyncio
+    async def test_execute_with_timeout_raises_timeout_error(self) -> None:
+        """Task execution should raise TimeoutError if exceeds timeout."""
+        queue = PriorityTaskQueue()
+
+        # Create a slow async callback
+        async def slow_callback() -> str:
+            await asyncio.sleep(1.0)
+            return "too slow"
+
+        task = PriorityTask(
+            priority=0,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=slow_callback,
+        )
+
+        with pytest.raises(asyncio.TimeoutError):
+            await queue.execute_with_timeout(task, timeout=0.1)
+
+    @pytest.mark.asyncio
+    async def test_execute_with_timeout_propagates_exceptions(self) -> None:
+        """Task execution should propagate exceptions from callback."""
+        queue = PriorityTaskQueue()
+
+        # Create a failing async callback
+        async def failing_callback() -> None:
+            raise ValueError("Test error")
+
+        task = PriorityTask(
+            priority=0,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=failing_callback,
+        )
+
+        with pytest.raises(ValueError, match="Test error"):
+            await queue.execute_with_timeout(task, timeout=1.0)
+
+    @pytest.mark.asyncio
+    async def test_execute_without_timeout(self) -> None:
+        """Task execution should work without timeout (LOW priority)."""
+        queue = PriorityTaskQueue()
+
+        async def test_callback() -> str:
+            await asyncio.sleep(0.01)
+            return "success"
+
+        task = PriorityTask(
+            priority=3,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=test_callback,
+        )
+
+        result = await queue.execute_with_timeout(task, timeout=None)
+        assert result == "success"
+
+    @pytest.mark.asyncio
+    async def test_get_metrics(self) -> None:
+        """Queue should track metrics correctly."""
+        queue = PriorityTaskQueue()
+
+        # Enqueue and dequeue some tasks
+        await queue.enqueue("task-1", CriticalityLevel.CRITICAL, {})
+        await queue.enqueue("task-2", CriticalityLevel.HIGH, {})
+        await queue.enqueue("task-3", CriticalityLevel.NORMAL, {})
+
+        await queue.dequeue(timeout=1.0)
+        await queue.dequeue(timeout=1.0)
+
+        metrics = await queue.get_metrics()
+
+        assert metrics.total_enqueued == 3
+        assert metrics.total_dequeued == 2
+        assert metrics.current_size == 1
+
+    @pytest.mark.asyncio
+    async def test_wait_time_metrics(self) -> None:
+        """Queue should track wait times per criticality level."""
+        queue = PriorityTaskQueue()
+
+        # Enqueue tasks with different criticality
+        await queue.enqueue("critical-1", CriticalityLevel.CRITICAL, {})
+        await asyncio.sleep(0.05)  # Add some wait time
+
+        await queue.dequeue(timeout=1.0)
+
+        metrics = await queue.get_metrics()
+
+        # Should have wait time metrics for CRITICAL
+        assert CriticalityLevel.CRITICAL in metrics.avg_wait_time
+        assert metrics.avg_wait_time[CriticalityLevel.CRITICAL] > 0.0
+
+    @pytest.mark.asyncio
+    async def test_clear_queue(self) -> None:
+        """Clear should remove all tasks from queue."""
+        queue = PriorityTaskQueue()
+
+        await queue.enqueue("task-1", CriticalityLevel.NORMAL, {})
+        await queue.enqueue("task-2", CriticalityLevel.NORMAL, {})
+        await queue.enqueue("task-3", CriticalityLevel.NORMAL, {})
+
+        cleared = await queue.clear()
+
+        assert cleared == 3
+        assert await queue.size() == 0
+
+    @pytest.mark.asyncio
+    async def test_concurrent_enqueue_dequeue(self) -> None:
+        """Queue should handle concurrent operations safely."""
+        queue = PriorityTaskQueue()
+
+        # Concurrent enqueue operations
+        async def enqueue_tasks() -> None:
+            for i in range(10):
+                await queue.enqueue(
+                    f"task-{i}",
+                    CriticalityLevel.NORMAL,
+                    {"index": i},
+                )
+
+        # Concurrent dequeue operations
+        async def dequeue_tasks() -> list[str]:
+            tasks = []
+            for _ in range(10):
+                task = await queue.dequeue(timeout=1.0)
+                if task:
+                    tasks.append(task.task_id)
+                await asyncio.sleep(0.01)
+            return tasks
+
+        # Run both concurrently
+        enqueue_task = asyncio.create_task(enqueue_tasks())
+        dequeue_task = asyncio.create_task(dequeue_tasks())
+
+        await enqueue_task
+        dequeued_ids = await dequeue_task
+
+        # All tasks should be processed
+        assert len(dequeued_ids) == 10
+
+    @pytest.mark.asyncio
+    async def test_timeout_metric_tracking(self) -> None:
+        """Queue should track timeout occurrences."""
+        queue = PriorityTaskQueue()
+
+        async def slow_callback() -> str:
+            await asyncio.sleep(1.0)
+            return "too slow"
+
+        task = PriorityTask(
+            priority=0,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=slow_callback,
+        )
+
+        try:
+            await queue.execute_with_timeout(task, timeout=0.1)
+        except TimeoutError:
+            pass
+
+        metrics = await queue.get_metrics()
+        assert metrics.total_timeouts == 1
+
+    @pytest.mark.asyncio
+    async def test_error_metric_tracking(self) -> None:
+        """Queue should track execution errors."""
+        queue = PriorityTaskQueue()
+
+        async def failing_callback() -> None:
+            raise ValueError("Test error")
+
+        task = PriorityTask(
+            priority=0,
+            timestamp=0.0,
+            task_id="test",
+            task_data={},
+            callback=failing_callback,
+        )
+
+        try:
+            await queue.execute_with_timeout(task, timeout=1.0)
+        except ValueError:
+            pass
+
+        metrics = await queue.get_metrics()
+        assert metrics.total_errors == 1
+
+
+# ---------------------------------------------------------------------------
+# Integration Tests
+# ---------------------------------------------------------------------------
+
+
+class TestLatencyControlIntegration:
+    """Integration tests for criticality assessment and priority queue."""
+
+    @pytest.mark.asyncio
+    async def test_critical_task_bypass_queue(self) -> None:
+        """CRITICAL tasks should bypass lower priority tasks."""
+        queue = PriorityTaskQueue()
+
+        # Add normal priority tasks
+        await queue.enqueue("normal-1", CriticalityLevel.NORMAL, {})
+        await queue.enqueue("normal-2", CriticalityLevel.NORMAL, {})
+
+        # Add critical task (should jump to front)
+        await queue.enqueue("critical", CriticalityLevel.CRITICAL, {})
+
+        # Dequeue should return critical first
+        task = await queue.dequeue(timeout=1.0)
+        assert task is not None
+        assert task.task_id == "critical"
+
+    @pytest.mark.asyncio
+    async def test_timeout_enforcement_by_criticality(self) -> None:
+        """Timeout enforcement should match criticality level."""
+        assessor = CriticalityAssessor()
+
+        # CRITICAL should have 5s timeout
+        critical_timeout = assessor.get_timeout(CriticalityLevel.CRITICAL)
+        assert critical_timeout == 5.0
+
+        # HIGH should have 30s timeout
+        high_timeout = assessor.get_timeout(CriticalityLevel.HIGH)
+        assert high_timeout == 30.0
+
+        # NORMAL should have 60s timeout
+        normal_timeout = assessor.get_timeout(CriticalityLevel.NORMAL)
+        assert normal_timeout == 60.0
+
+        # LOW should have no timeout
+        low_timeout = assessor.get_timeout(CriticalityLevel.LOW)
+        assert low_timeout is None
+
+    @pytest.mark.asyncio
+    async def test_fast_path_execution_for_critical(self) -> None:
+        """CRITICAL tasks should complete quickly."""
+        queue = PriorityTaskQueue()
+
+        # Create a fast callback simulating fast-path execution
+        async def fast_path_callback() -> str:
+            # Simulate simplified decision flow
+            await asyncio.sleep(0.01)  # Very fast execution
+            return "fast_path_complete"
+
+        task = PriorityTask(
+            priority=0,  # CRITICAL
+            timestamp=0.0,
+            task_id="critical-fast",
+            task_data={},
+            callback=fast_path_callback,
+        )
+
+        import time
+
+        start = time.time()
+        result = await queue.execute_with_timeout(task, timeout=5.0)
+        elapsed = time.time() - start
+
+        assert result == "fast_path_complete"
+        assert elapsed < 5.0  # Should complete well under CRITICAL timeout
+
+    @pytest.mark.asyncio
+    async def test_graceful_degradation_when_queue_full(self) -> None:
+        """System should gracefully handle full queue."""
+        queue = PriorityTaskQueue(max_size=2)
+
+        # Fill the queue
+        await queue.enqueue("task-1", CriticalityLevel.NORMAL, {})
+        await queue.enqueue("task-2", CriticalityLevel.NORMAL, {})
+
+        # Try to add more tasks
+        success = await queue.enqueue("task-3", CriticalityLevel.NORMAL, {})
+        assert success is False
+
+        # Queue should still function
+        task = await queue.dequeue(timeout=1.0)
+        assert task is not None
+
+        # Now we can add another task
+        success = await queue.enqueue("task-4", CriticalityLevel.NORMAL, {})
+        assert success is True

tests/test_main.py

@@ -0,0 +1,561 @@
+"""Tests for main trading loop telegram integration."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected
+from src.main import trading_cycle
+
+
+class TestTradingCycleTelegramIntegration:
+    """Test telegram notifications in trading_cycle function."""
+
+    @pytest.fixture
+    def mock_broker(self) -> MagicMock:
+        """Create mock broker."""
+        broker = MagicMock()
+        broker.get_orderbook = AsyncMock(
+            return_value={
+                "output1": {
+                    "stck_prpr": "50000",
+                    "frgn_ntby_qty": "100",
+                }
+            }
+        )
+        broker.get_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "tot_evlu_amt": "10000000",
+                        "dnca_tot_amt": "5000000",
+                        "pchs_amt_smtl_amt": "5000000",
+                    }
+                ]
+            }
+        )
+        broker.send_order = AsyncMock(return_value={"msg1": "OK"})
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_broker(self) -> MagicMock:
+        """Create mock overseas broker."""
+        broker = MagicMock()
+        return broker
+
+    @pytest.fixture
+    def mock_brain(self) -> MagicMock:
+        """Create mock brain that decides to buy."""
+        brain = MagicMock()
+        decision = MagicMock()
+        decision.action = "BUY"
+        decision.confidence = 85
+        decision.rationale = "Test buy"
+        brain.decide = AsyncMock(return_value=decision)
+        return brain
+
+    @pytest.fixture
+    def mock_risk(self) -> MagicMock:
+        """Create mock risk manager."""
+        risk = MagicMock()
+        risk.validate_order = MagicMock()
+        return risk
+
+    @pytest.fixture
+    def mock_db(self) -> MagicMock:
+        """Create mock database connection."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_decision_logger(self) -> MagicMock:
+        """Create mock decision logger."""
+        logger = MagicMock()
+        logger.log_decision = MagicMock()
+        return logger
+
+    @pytest.fixture
+    def mock_context_store(self) -> MagicMock:
+        """Create mock context store."""
+        store = MagicMock()
+        store.get_latest_timeframe = MagicMock(return_value=None)
+        return store
+
+    @pytest.fixture
+    def mock_criticality_assessor(self) -> MagicMock:
+        """Create mock criticality assessor."""
+        assessor = MagicMock()
+        assessor.assess_market_conditions = MagicMock(
+            return_value=MagicMock(value="NORMAL")
+        )
+        assessor.get_timeout = MagicMock(return_value=5.0)
+        return assessor
+
+    @pytest.fixture
+    def mock_telegram(self) -> MagicMock:
+        """Create mock telegram client."""
+        telegram = MagicMock()
+        telegram.notify_trade_execution = AsyncMock()
+        telegram.notify_fat_finger = AsyncMock()
+        telegram.notify_circuit_breaker = AsyncMock()
+        return telegram
+
+    @pytest.fixture
+    def mock_market(self) -> MagicMock:
+        """Create mock market info."""
+        market = MagicMock()
+        market.name = "Korea"
+        market.code = "KR"
+        market.exchange_code = "KRX"
+        market.is_domestic = True
+        return market
+
+    @pytest.mark.asyncio
+    async def test_trade_execution_notification_sent(
+        self,
+        mock_broker: MagicMock,
+        mock_overseas_broker: MagicMock,
+        mock_brain: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_market: MagicMock,
+    ) -> None:
+        """Test telegram notification sent on trade execution."""
+        with patch("src.main.log_trade"):
+            await trading_cycle(
+                broker=mock_broker,
+                overseas_broker=mock_overseas_broker,
+                brain=mock_brain,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_market,
+                stock_code="005930",
+            )
+
+        # Verify notification was sent
+        mock_telegram.notify_trade_execution.assert_called_once()
+        call_kwargs = mock_telegram.notify_trade_execution.call_args.kwargs
+        assert call_kwargs["stock_code"] == "005930"
+        assert call_kwargs["market"] == "Korea"
+        assert call_kwargs["action"] == "BUY"
+        assert call_kwargs["confidence"] == 85
+
+    @pytest.mark.asyncio
+    async def test_trade_execution_notification_failure_doesnt_crash(
+        self,
+        mock_broker: MagicMock,
+        mock_overseas_broker: MagicMock,
+        mock_brain: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_market: MagicMock,
+    ) -> None:
+        """Test trading continues even if notification fails."""
+        # Make notification fail
+        mock_telegram.notify_trade_execution.side_effect = Exception("API error")
+
+        with patch("src.main.log_trade"):
+            # Should not raise exception
+            await trading_cycle(
+                broker=mock_broker,
+                overseas_broker=mock_overseas_broker,
+                brain=mock_brain,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_market,
+                stock_code="005930",
+            )
+
+        # Verify notification was attempted
+        mock_telegram.notify_trade_execution.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_fat_finger_notification_sent(
+        self,
+        mock_broker: MagicMock,
+        mock_overseas_broker: MagicMock,
+        mock_brain: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_market: MagicMock,
+    ) -> None:
+        """Test telegram notification sent on fat finger rejection."""
+        # Make risk manager reject the order
+        mock_risk.validate_order.side_effect = FatFingerRejected(
+            order_amount=2000000,
+            total_cash=5000000,
+            max_pct=30.0,
+        )
+
+        with patch("src.main.log_trade"):
+            with pytest.raises(FatFingerRejected):
+                await trading_cycle(
+                    broker=mock_broker,
+                    overseas_broker=mock_overseas_broker,
+                    brain=mock_brain,
+                    risk=mock_risk,
+                    db_conn=mock_db,
+                    decision_logger=mock_decision_logger,
+                    context_store=mock_context_store,
+                    criticality_assessor=mock_criticality_assessor,
+                    telegram=mock_telegram,
+                    market=mock_market,
+                    stock_code="005930",
+                )
+
+        # Verify notification was sent
+        mock_telegram.notify_fat_finger.assert_called_once()
+        call_kwargs = mock_telegram.notify_fat_finger.call_args.kwargs
+        assert call_kwargs["stock_code"] == "005930"
+        assert call_kwargs["order_amount"] == 2000000
+        assert call_kwargs["total_cash"] == 5000000
+        assert call_kwargs["max_pct"] == 30.0
+
+    @pytest.mark.asyncio
+    async def test_fat_finger_notification_failure_still_raises(
+        self,
+        mock_broker: MagicMock,
+        mock_overseas_broker: MagicMock,
+        mock_brain: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_market: MagicMock,
+    ) -> None:
+        """Test fat finger exception still raised even if notification fails."""
+        # Make risk manager reject the order
+        mock_risk.validate_order.side_effect = FatFingerRejected(
+            order_amount=2000000,
+            total_cash=5000000,
+            max_pct=30.0,
+        )
+        # Make notification fail
+        mock_telegram.notify_fat_finger.side_effect = Exception("API error")
+
+        with patch("src.main.log_trade"):
+            with pytest.raises(FatFingerRejected):
+                await trading_cycle(
+                    broker=mock_broker,
+                    overseas_broker=mock_overseas_broker,
+                    brain=mock_brain,
+                    risk=mock_risk,
+                    db_conn=mock_db,
+                    decision_logger=mock_decision_logger,
+                    context_store=mock_context_store,
+                    criticality_assessor=mock_criticality_assessor,
+                    telegram=mock_telegram,
+                    market=mock_market,
+                    stock_code="005930",
+                )
+
+        # Verify notification was attempted
+        mock_telegram.notify_fat_finger.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_no_notification_on_hold_decision(
+        self,
+        mock_broker: MagicMock,
+        mock_overseas_broker: MagicMock,
+        mock_brain: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_market: MagicMock,
+    ) -> None:
+        """Test no trade notification sent when decision is HOLD."""
+        # Change brain decision to HOLD
+        decision = MagicMock()
+        decision.action = "HOLD"
+        decision.confidence = 50
+        decision.rationale = "Insufficient signal"
+        mock_brain.decide = AsyncMock(return_value=decision)
+
+        with patch("src.main.log_trade"):
+            await trading_cycle(
+                broker=mock_broker,
+                overseas_broker=mock_overseas_broker,
+                brain=mock_brain,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_market,
+                stock_code="005930",
+            )
+
+        # Verify no trade notification sent
+        mock_telegram.notify_trade_execution.assert_not_called()
+
+
+class TestRunFunctionTelegramIntegration:
+    """Test telegram notifications in run function."""
+
+    @pytest.mark.asyncio
+    async def test_circuit_breaker_notification_sent(self) -> None:
+        """Test telegram notification sent when circuit breaker trips."""
+        mock_telegram = MagicMock()
+        mock_telegram.notify_circuit_breaker = AsyncMock()
+
+        # Simulate circuit breaker exception
+        exc = CircuitBreakerTripped(pnl_pct=-3.5, threshold=-3.0)
+
+        # Test the notification logic
+        try:
+            await mock_telegram.notify_circuit_breaker(
+                pnl_pct=exc.pnl_pct,
+                threshold=exc.threshold,
+            )
+        except Exception:
+            pass  # Ignore errors in notification
+
+        # Verify notification was called
+        mock_telegram.notify_circuit_breaker.assert_called_once_with(
+            pnl_pct=-3.5,
+            threshold=-3.0,
+        )
+
+
+class TestOverseasBalanceParsing:
+    """Test overseas balance output2 parsing handles different formats."""
+
+    @pytest.fixture
+    def mock_overseas_broker_with_list(self) -> MagicMock:
+        """Create mock overseas broker returning list format."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "frcr_evlu_tota": "10000.00",
+                        "frcr_dncl_amt_2": "5000.00",
+                        "frcr_buy_amt_smtl": "4500.00",
+                    }
+                ]
+            }
+        )
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_broker_with_dict(self) -> MagicMock:
+        """Create mock overseas broker returning dict format."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": {
+                    "frcr_evlu_tota": "10000.00",
+                    "frcr_dncl_amt_2": "5000.00",
+                    "frcr_buy_amt_smtl": "4500.00",
+                }
+            }
+        )
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_broker_with_empty(self) -> MagicMock:
+        """Create mock overseas broker returning empty output2."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
+        return broker
+
+    @pytest.fixture
+    def mock_domestic_broker(self) -> MagicMock:
+        """Create minimal mock domestic broker."""
+        broker = MagicMock()
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_market(self) -> MagicMock:
+        """Create mock overseas market info."""
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+        return market
+
+    @pytest.fixture
+    def mock_brain_hold(self) -> MagicMock:
+        """Create mock brain that always holds."""
+        brain = MagicMock()
+        decision = MagicMock()
+        decision.action = "HOLD"
+        decision.confidence = 50
+        decision.rationale = "Testing balance parsing"
+        brain.decide = AsyncMock(return_value=decision)
+        return brain
+
+    @pytest.fixture
+    def mock_risk(self) -> MagicMock:
+        """Create mock risk manager."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_db(self) -> MagicMock:
+        """Create mock database."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_decision_logger(self) -> MagicMock:
+        """Create mock decision logger."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_context_store(self) -> MagicMock:
+        """Create mock context store."""
+        store = MagicMock()
+        store.get_latest_timeframe = MagicMock(return_value=None)
+        return store
+
+    @pytest.fixture
+    def mock_criticality_assessor(self) -> MagicMock:
+        """Create mock criticality assessor."""
+        assessor = MagicMock()
+        assessor.assess_market_conditions = MagicMock(
+            return_value=MagicMock(value="NORMAL")
+        )
+        assessor.get_timeout = MagicMock(return_value=5.0)
+        return assessor
+
+    @pytest.fixture
+    def mock_telegram(self) -> MagicMock:
+        """Create mock telegram client."""
+        return MagicMock()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_list_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_list: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with list format (output2=[{...}])."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_list,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_list.get_overseas_balance.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_dict_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_dict: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with dict format (output2={...})."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_dict,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_dict.get_overseas_balance.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_empty_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_empty: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with empty output2."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError, should default to 0
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_empty,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_empty.get_overseas_balance.assert_called_once()

tests/test_telegram.py

@@ -0,0 +1,269 @@
+"""Tests for Telegram notification client."""
+
+from unittest.mock import AsyncMock, patch
+
+import aiohttp
+import pytest
+
+from src.notifications.telegram_client import NotificationPriority, TelegramClient
+
+
+class TestTelegramClientInit:
+    """Test client initialization scenarios."""
+
+    def test_disabled_via_flag(self) -> None:
+        """Client disabled via enabled=False flag."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=False
+        )
+        assert client._enabled is False
+
+    def test_disabled_missing_token(self) -> None:
+        """Client disabled when bot_token is None."""
+        client = TelegramClient(bot_token=None, chat_id="456", enabled=True)
+        assert client._enabled is False
+
+    def test_disabled_missing_chat_id(self) -> None:
+        """Client disabled when chat_id is None."""
+        client = TelegramClient(bot_token="123:abc", chat_id=None, enabled=True)
+        assert client._enabled is False
+
+    def test_enabled_with_credentials(self) -> None:
+        """Client enabled when credentials provided."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+        assert client._enabled is True
+
+
+class TestNotificationSending:
+    """Test notification sending behavior."""
+
+    @pytest.mark.asyncio
+    async def test_no_send_when_disabled(self) -> None:
+        """Notifications not sent when client disabled."""
+        client = TelegramClient(enabled=False)
+
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_trade_execution(
+                stock_code="AAPL",
+                market="United States",
+                action="BUY",
+                quantity=10,
+                price=150.0,
+                confidence=85.0,
+            )
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_trade_execution_format(self) -> None:
+        """Trade notification has correct format."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await client.notify_trade_execution(
+                stock_code="TSLA",
+                market="United States",
+                action="SELL",
+                quantity=5,
+                price=250.50,
+                confidence=92.0,
+            )
+
+            # Verify API call was made
+            assert mock_post.call_count == 1
+            call_args = mock_post.call_args
+
+            # Check payload structure
+            payload = call_args.kwargs["json"]
+            assert payload["chat_id"] == "456"
+            assert "TSLA" in payload["text"]
+            assert "SELL" in payload["text"]
+            assert "5" in payload["text"]
+            assert "250.50" in payload["text"]
+            assert "92%" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_circuit_breaker_priority(self) -> None:
+        """Circuit breaker uses CRITICAL priority."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await client.notify_circuit_breaker(pnl_pct=-3.15, threshold=-3.0)
+
+            payload = mock_post.call_args.kwargs["json"]
+            # CRITICAL priority has 🚨 emoji
+            assert NotificationPriority.CRITICAL.emoji in payload["text"]
+            assert "-3.15%" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_api_error_handling(self) -> None:
+        """API errors logged but don't crash."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 400
+        mock_resp.text = AsyncMock(return_value="Bad Request")
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            # Should not raise exception
+            await client.notify_system_start(mode="paper", enabled_markets=["KR"])
+
+    @pytest.mark.asyncio
+    async def test_timeout_handling(self) -> None:
+        """Timeouts logged but don't crash."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        with patch(
+            "aiohttp.ClientSession.post",
+            side_effect=aiohttp.ClientError("Connection timeout"),
+        ):
+            # Should not raise exception
+            await client.notify_error(
+                error_type="Test Error", error_msg="Test", context="test"
+            )
+
+    @pytest.mark.asyncio
+    async def test_session_management(self) -> None:
+        """Session created and reused correctly."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        # Session should be None initially
+        assert client._session is None
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            await client.notify_market_open("Korea")
+            # Session should be created
+            assert client._session is not None
+
+            session1 = client._session
+            await client.notify_market_close("Korea", 1.5)
+            # Same session should be reused
+            assert client._session is session1
+
+
+class TestRateLimiting:
+    """Test rate limiter behavior."""
+
+    @pytest.mark.asyncio
+    async def test_rate_limiter_enforced(self) -> None:
+        """Rate limiter delays rapid requests."""
+        import time
+
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, rate_limit=2.0
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            start = time.monotonic()
+
+            # Send 3 messages (rate: 2/sec = 0.5s per message)
+            await client.notify_market_open("Korea")
+            await client.notify_market_open("United States")
+            await client.notify_market_open("Japan")
+
+            elapsed = time.monotonic() - start
+
+            # Should take at least 0.4 seconds (3 msgs at 2/sec with some tolerance)
+            assert elapsed >= 0.4
+
+
+class TestMessagePriorities:
+    """Test priority-based messaging."""
+
+    @pytest.mark.asyncio
+    async def test_low_priority_uses_info_emoji(self) -> None:
+        """LOW priority uses ℹ️ emoji."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await client.notify_market_open("Korea")
+
+            payload = mock_post.call_args.kwargs["json"]
+            assert NotificationPriority.LOW.emoji in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_critical_priority_uses_alarm_emoji(self) -> None:
+        """CRITICAL priority uses 🚨 emoji."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await client.notify_system_shutdown("Circuit breaker tripped")
+
+            payload = mock_post.call_args.kwargs["json"]
+            assert NotificationPriority.CRITICAL.emoji in payload["text"]
+
+
+class TestClientCleanup:
+    """Test client cleanup behavior."""
+
+    @pytest.mark.asyncio
+    async def test_close_closes_session(self) -> None:
+        """close() closes the HTTP session."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_session = AsyncMock()
+        mock_session.closed = False
+        mock_session.close = AsyncMock()
+        client._session = mock_session
+
+        await client.close()
+        mock_session.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_close_handles_no_session(self) -> None:
+        """close() handles None session gracefully."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        # Should not raise exception
+        await client.close()

tests/test_token_efficiency.py

@@ -0,0 +1,663 @@
+"""Tests for token efficiency optimization components.
+
+Tests cover:
+- Prompt compression and optimization
+- Context selection logic
+- Summarization
+- Caching
+- Token reduction metrics
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+
+import pytest
+
+from src.brain.cache import DecisionCache
+from src.brain.context_selector import ContextSelector, DecisionType
+from src.brain.gemini_client import TradeDecision
+from src.brain.prompt_optimizer import PromptOptimizer, TokenMetrics
+from src.context.layer import ContextLayer
+from src.context.store import ContextStore
+from src.context.summarizer import ContextSummarizer, SummaryStats
+
+# ============================================================================
+# Prompt Optimizer Tests
+# ============================================================================
+
+
+class TestPromptOptimizer:
+    """Tests for PromptOptimizer."""
+
+    def test_estimate_tokens(self):
+        """Test token estimation."""
+        optimizer = PromptOptimizer()
+
+        # Empty text
+        assert optimizer.estimate_tokens("") == 0
+
+        # Short text (4 chars = 1 token estimate)
+        assert optimizer.estimate_tokens("test") == 1
+
+        # Longer text
+        text = "This is a longer piece of text for testing token estimation."
+        tokens = optimizer.estimate_tokens(text)
+        assert tokens > 0
+        assert tokens == len(text) // 4
+
+    def test_count_tokens(self):
+        """Test token counting metrics."""
+        optimizer = PromptOptimizer()
+
+        text = "Hello world, this is a test."
+        metrics = optimizer.count_tokens(text)
+
+        assert isinstance(metrics, TokenMetrics)
+        assert metrics.char_count == len(text)
+        assert metrics.word_count == 6
+        assert metrics.estimated_tokens > 0
+
+    def test_compress_json(self):
+        """Test JSON compression."""
+        optimizer = PromptOptimizer()
+
+        data = {
+            "action": "BUY",
+            "confidence": 85,
+            "rationale": "Strong uptrend",
+        }
+
+        compressed = optimizer.compress_json(data)
+
+        # Should have no newlines and minimal whitespace
+        assert "\n" not in compressed
+        # Note: JSON values may contain spaces (e.g., "Strong uptrend")
+        # but there should be no spaces around separators
+        assert ": " not in compressed
+        assert ", " not in compressed
+
+        # Should be valid JSON
+        import json
+
+        parsed = json.loads(compressed)
+        assert parsed == data
+
+    def test_abbreviate_text(self):
+        """Test text abbreviation."""
+        optimizer = PromptOptimizer()
+
+        text = "The current price is high and volume is increasing."
+        abbreviated = optimizer.abbreviate_text(text)
+
+        # Should contain abbreviations
+        assert "cur" in abbreviated or "P" in abbreviated
+        assert len(abbreviated) <= len(text)
+
+    def test_abbreviate_text_aggressive(self):
+        """Test aggressive text abbreviation."""
+        optimizer = PromptOptimizer()
+
+        text = "The price is increasing and the volume is high."
+        abbreviated = optimizer.abbreviate_text(text, aggressive=True)
+
+        # Should be shorter
+        assert len(abbreviated) < len(text)
+
+        # Should have removed articles
+        assert "the" not in abbreviated.lower()
+
+    def test_build_compressed_prompt(self):
+        """Test compressed prompt building."""
+        optimizer = PromptOptimizer()
+
+        market_data = {
+            "stock_code": "005930",
+            "current_price": 75000,
+            "market_name": "Korean stock market",
+        }
+
+        prompt = optimizer.build_compressed_prompt(market_data)
+
+        # Should be much shorter than original
+        assert len(prompt) < 300
+        assert "005930" in prompt
+        assert "75000" in prompt
+
+    def test_build_compressed_prompt_no_instructions(self):
+        """Test compressed prompt without instructions."""
+        optimizer = PromptOptimizer()
+
+        market_data = {
+            "stock_code": "AAPL",
+            "current_price": 150.5,
+            "market_name": "United States",
+        }
+
+        prompt = optimizer.build_compressed_prompt(market_data, include_instructions=False)
+
+        # Should be very short (data only)
+        assert len(prompt) < 100
+        assert "AAPL" in prompt
+
+    def test_truncate_context(self):
+        """Test context truncation."""
+        optimizer = PromptOptimizer()
+
+        context = {
+            "price": 100.5,
+            "volume": 1000000,
+            "sentiment": 0.8,
+            "extra_data": "Some long text that should be truncated",
+        }
+
+        # Truncate to small budget
+        truncated = optimizer.truncate_context(context, max_tokens=10)
+
+        # Should have fewer keys
+        assert len(truncated) <= len(context)
+
+    def test_truncate_context_with_priority(self):
+        """Test context truncation with priority keys."""
+        optimizer = PromptOptimizer()
+
+        context = {
+            "price": 100.5,
+            "volume": 1000000,
+            "sentiment": 0.8,
+            "extra_data": "Some data",
+        }
+
+        priority_keys = ["price", "sentiment"]
+        truncated = optimizer.truncate_context(context, max_tokens=20, priority_keys=priority_keys)
+
+        # Priority keys should be included
+        assert "price" in truncated
+        assert "sentiment" in truncated
+
+    def test_calculate_compression_ratio(self):
+        """Test compression ratio calculation."""
+        optimizer = PromptOptimizer()
+
+        original = "This is a very long piece of text that should be compressed significantly."
+        compressed = "Short text"
+
+        ratio = optimizer.calculate_compression_ratio(original, compressed)
+
+        # Ratio should be > 1 (original is longer)
+        assert ratio > 1.0
+
+
+# ============================================================================
+# Context Selector Tests
+# ============================================================================
+
+
+class TestContextSelector:
+    """Tests for ContextSelector."""
+
+    @pytest.fixture
+    def store(self):
+        """Create in-memory ContextStore."""
+        conn = sqlite3.connect(":memory:")
+        # Create tables
+        conn.execute(
+            """
+            CREATE TABLE context_metadata (
+                layer TEXT PRIMARY KEY,
+                description TEXT,
+                retention_days INTEGER,
+                aggregation_source TEXT
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE contexts (
+                layer TEXT,
+                timeframe TEXT,
+                key TEXT,
+                value TEXT,
+                created_at TEXT,
+                updated_at TEXT,
+                PRIMARY KEY (layer, timeframe, key)
+            )
+            """
+        )
+        conn.commit()
+        return ContextStore(conn)
+
+    def test_select_layers_normal(self, store):
+        """Test layer selection for normal decisions."""
+        selector = ContextSelector(store)
+
+        layers = selector.select_layers(DecisionType.NORMAL)
+
+        # Should only select L7 (real-time)
+        assert layers == [ContextLayer.L7_REALTIME]
+
+    def test_select_layers_strategic(self, store):
+        """Test layer selection for strategic decisions."""
+        selector = ContextSelector(store)
+
+        layers = selector.select_layers(DecisionType.STRATEGIC)
+
+        # Should select L7 + L6 + L5
+        assert ContextLayer.L7_REALTIME in layers
+        assert ContextLayer.L6_DAILY in layers
+        assert ContextLayer.L5_WEEKLY in layers
+        assert len(layers) == 3
+
+    def test_select_layers_major_event(self, store):
+        """Test layer selection for major events."""
+        selector = ContextSelector(store)
+
+        layers = selector.select_layers(DecisionType.MAJOR_EVENT)
+
+        # Should select all layers
+        assert len(layers) == 7
+        assert ContextLayer.L1_LEGACY in layers
+        assert ContextLayer.L7_REALTIME in layers
+
+    def test_score_layer_relevance(self, store):
+        """Test layer relevance scoring."""
+        selector = ContextSelector(store)
+
+        # Add some data first so scores aren't penalized
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "price", 100.5)
+        store.set_context(ContextLayer.L1_LEGACY, "legacy", "lesson", "test")
+
+        # L7 should have high score for normal decisions
+        score = selector.score_layer_relevance(ContextLayer.L7_REALTIME, DecisionType.NORMAL)
+        assert score == 1.0
+
+        # L1 should have low score for normal decisions
+        score = selector.score_layer_relevance(ContextLayer.L1_LEGACY, DecisionType.NORMAL)
+        assert score == 0.0
+
+        # L1 should have high score for major events
+        score = selector.score_layer_relevance(ContextLayer.L1_LEGACY, DecisionType.MAJOR_EVENT)
+        assert score == 1.0
+
+    def test_select_with_scoring(self, store):
+        """Test selection with relevance scoring."""
+        selector = ContextSelector(store)
+
+        # Add data so layers aren't penalized
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "price", 100.5)
+
+        selection = selector.select_with_scoring(DecisionType.NORMAL, min_score=0.5)
+
+        # Should only select high-relevance layers
+        assert len(selection.layers) >= 1
+        assert ContextLayer.L7_REALTIME in selection.layers
+        assert all(selection.relevance_scores[layer] >= 0.5 for layer in selection.layers)
+
+    def test_get_context_data(self, store):
+        """Test context data retrieval."""
+        selector = ContextSelector(store)
+
+        # Add some test data
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "price", 100.5)
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "volume", 1000000)
+
+        context_data = selector.get_context_data([ContextLayer.L7_REALTIME])
+
+        # Should retrieve data
+        assert "L7_REALTIME" in context_data
+        assert "price" in context_data["L7_REALTIME"]
+        assert context_data["L7_REALTIME"]["price"] == 100.5
+
+    def test_estimate_context_tokens(self, store):
+        """Test context token estimation."""
+        selector = ContextSelector(store)
+
+        context_data = {
+            "L7_REALTIME": {"price": 100.5, "volume": 1000000},
+            "L6_DAILY": {"avg_price": 99.8, "avg_volume": 950000},
+        }
+
+        tokens = selector.estimate_context_tokens(context_data)
+
+        # Should estimate tokens
+        assert tokens > 0
+
+    def test_optimize_context_for_budget(self, store):
+        """Test context optimization for token budget."""
+        selector = ContextSelector(store)
+
+        # Add test data
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "price", 100.5)
+
+        # Get optimized context within budget
+        context = selector.optimize_context_for_budget(DecisionType.NORMAL, max_tokens=50)
+
+        # Should return data within budget
+        tokens = selector.estimate_context_tokens(context)
+        assert tokens <= 50
+
+
+# ============================================================================
+# Context Summarizer Tests
+# ============================================================================
+
+
+class TestContextSummarizer:
+    """Tests for ContextSummarizer."""
+
+    @pytest.fixture
+    def store(self):
+        """Create in-memory ContextStore."""
+        conn = sqlite3.connect(":memory:")
+        conn.execute(
+            """
+            CREATE TABLE context_metadata (
+                layer TEXT PRIMARY KEY,
+                description TEXT,
+                retention_days INTEGER,
+                aggregation_source TEXT
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE contexts (
+                layer TEXT,
+                timeframe TEXT,
+                key TEXT,
+                value TEXT,
+                created_at TEXT,
+                updated_at TEXT,
+                PRIMARY KEY (layer, timeframe, key)
+            )
+            """
+        )
+        conn.commit()
+        return ContextStore(conn)
+
+    def test_summarize_numeric_values(self, store):
+        """Test numeric value summarization."""
+        summarizer = ContextSummarizer(store)
+
+        values = [10.0, 20.0, 30.0, 40.0, 50.0]
+        stats = summarizer.summarize_numeric_values(values)
+
+        assert isinstance(stats, SummaryStats)
+        assert stats.count == 5
+        assert stats.mean == 30.0
+        assert stats.min == 10.0
+        assert stats.max == 50.0
+        assert stats.std is not None
+
+    def test_summarize_numeric_values_trend(self, store):
+        """Test trend detection in numeric values."""
+        summarizer = ContextSummarizer(store)
+
+        # Uptrend
+        values_up = [10.0, 15.0, 20.0, 25.0, 30.0, 35.0]
+        stats_up = summarizer.summarize_numeric_values(values_up)
+        assert stats_up.trend == "up"
+
+        # Downtrend
+        values_down = [35.0, 30.0, 25.0, 20.0, 15.0, 10.0]
+        stats_down = summarizer.summarize_numeric_values(values_down)
+        assert stats_down.trend == "down"
+
+        # Flat
+        values_flat = [20.0, 20.1, 19.9, 20.0, 20.1, 19.9]
+        stats_flat = summarizer.summarize_numeric_values(values_flat)
+        assert stats_flat.trend == "flat"
+
+    def test_summarize_layer(self, store):
+        """Test layer summarization."""
+        summarizer = ContextSummarizer(store)
+
+        # Add test data
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-04", "price", 100.5)
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-04", "volume", 1000000)
+
+        summary = summarizer.summarize_layer(ContextLayer.L6_DAILY)
+
+        # Should have summary
+        assert "total_entries" in summary
+        assert summary["total_entries"] > 0
+
+    def test_create_compact_summary(self, store):
+        """Test compact summary creation."""
+        summarizer = ContextSummarizer(store)
+
+        # Add test data
+        store.set_context(ContextLayer.L7_REALTIME, "2026-02-04", "price", 100.5)
+
+        layers = [ContextLayer.L7_REALTIME, ContextLayer.L6_DAILY]
+        summary = summarizer.create_compact_summary(layers, top_n_metrics=3)
+
+        # Should have summaries for layers
+        assert "L7_REALTIME" in summary
+
+    def test_format_summary_for_prompt(self, store):
+        """Test summary formatting for prompt."""
+        summarizer = ContextSummarizer(store)
+
+        summary = {
+            "L7_REALTIME": {
+                "price": {"avg": 100.5, "trend": "up"},
+                "volume": {"avg": 1000000, "trend": "flat"},
+            }
+        }
+
+        formatted = summarizer.format_summary_for_prompt(summary)
+
+        # Should be formatted string
+        assert isinstance(formatted, str)
+        assert "L7_REALTIME" in formatted
+        assert "100.5" in formatted or "100.50" in formatted
+
+
+# ============================================================================
+# Decision Cache Tests
+# ============================================================================
+
+
+class TestDecisionCache:
+    """Tests for DecisionCache."""
+
+    def test_cache_init(self):
+        """Test cache initialization."""
+        cache = DecisionCache(ttl_seconds=60, max_size=100)
+
+        assert cache.ttl_seconds == 60
+        assert cache.max_size == 100
+
+    def test_cache_miss(self):
+        """Test cache miss."""
+        cache = DecisionCache()
+
+        market_data = {"stock_code": "005930", "current_price": 75000}
+
+        decision = cache.get(market_data)
+
+        # Should be None (cache miss)
+        assert decision is None
+
+        metrics = cache.get_metrics()
+        assert metrics.cache_misses == 1
+        assert metrics.cache_hits == 0
+
+    def test_cache_hit(self):
+        """Test cache hit."""
+        cache = DecisionCache()
+
+        market_data = {"stock_code": "005930", "current_price": 75000}
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Set cache
+        cache.set(market_data, decision)
+
+        # Get from cache
+        cached = cache.get(market_data)
+
+        assert cached is not None
+        assert cached.action == "HOLD"
+        assert cached.confidence == 50
+
+        metrics = cache.get_metrics()
+        assert metrics.cache_hits == 1
+
+    def test_cache_ttl_expiration(self):
+        """Test cache TTL expiration."""
+        cache = DecisionCache(ttl_seconds=1)  # 1 second TTL
+
+        market_data = {"stock_code": "005930", "current_price": 75000}
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Set cache
+        cache.set(market_data, decision)
+
+        # Should hit immediately
+        cached = cache.get(market_data)
+        assert cached is not None
+
+        # Wait for expiration
+        time.sleep(1.1)
+
+        # Should miss after expiration
+        cached = cache.get(market_data)
+        assert cached is None
+
+    def test_cache_max_size(self):
+        """Test cache max size eviction."""
+        cache = DecisionCache(max_size=2)
+
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Add 3 entries (exceeds max_size)
+        for i in range(3):
+            market_data = {"stock_code": f"00{i}", "current_price": 1000 * i}
+            cache.set(market_data, decision)
+
+        metrics = cache.get_metrics()
+
+        # Should have evicted 1 entry
+        assert metrics.total_entries == 2
+        assert metrics.evictions == 1
+
+    def test_invalidate_all(self):
+        """Test invalidate all cache entries."""
+        cache = DecisionCache()
+
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Add entries
+        for i in range(3):
+            market_data = {"stock_code": f"00{i}", "current_price": 1000}
+            cache.set(market_data, decision)
+
+        # Invalidate all
+        count = cache.invalidate()
+
+        assert count == 3
+
+        metrics = cache.get_metrics()
+        assert metrics.total_entries == 0
+
+    def test_invalidate_by_stock(self):
+        """Test invalidate cache by stock code."""
+        cache = DecisionCache()
+
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Add entries for different stocks
+        cache.set({"stock_code": "005930", "current_price": 75000}, decision)
+        cache.set({"stock_code": "000660", "current_price": 50000}, decision)
+
+        # Invalidate specific stock
+        count = cache.invalidate("005930")
+
+        assert count >= 1
+
+        # Other stock should still be cached
+        cached = cache.get({"stock_code": "000660", "current_price": 50000})
+        assert cached is not None
+
+    def test_cleanup_expired(self):
+        """Test cleanup of expired entries."""
+        cache = DecisionCache(ttl_seconds=1)
+
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+
+        # Add entry
+        cache.set({"stock_code": "005930", "current_price": 75000}, decision)
+
+        # Wait for expiration
+        time.sleep(1.1)
+
+        # Cleanup
+        count = cache.cleanup_expired()
+
+        assert count == 1
+
+        metrics = cache.get_metrics()
+        assert metrics.total_entries == 0
+
+    def test_should_cache_decision(self):
+        """Test decision caching criteria."""
+        cache = DecisionCache()
+
+        # HOLD decisions should be cached
+        hold_decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+        assert cache.should_cache_decision(hold_decision) is True
+
+        # High confidence BUY should be cached
+        buy_decision = TradeDecision(action="BUY", confidence=95, rationale="Test")
+        assert cache.should_cache_decision(buy_decision) is True
+
+        # Low confidence BUY should not be cached
+        low_conf_buy = TradeDecision(action="BUY", confidence=60, rationale="Test")
+        assert cache.should_cache_decision(low_conf_buy) is False
+
+    def test_cache_hit_rate(self):
+        """Test cache hit rate calculation."""
+        cache = DecisionCache()
+
+        decision = TradeDecision(action="HOLD", confidence=50, rationale="Test")
+        market_data = {"stock_code": "005930", "current_price": 75000}
+
+        # First request (miss)
+        cache.get(market_data)
+
+        # Set cache
+        cache.set(market_data, decision)
+
+        # Second request (hit)
+        cache.get(market_data)
+
+        # Third request (hit)
+        cache.get(market_data)
+
+        metrics = cache.get_metrics()
+
+        # 1 miss, 2 hits out of 3 requests
+        assert metrics.total_requests == 3
+        assert metrics.cache_hits == 2
+        assert metrics.cache_misses == 1
+        assert metrics.hit_rate == pytest.approx(2 / 3)
+
+    def test_reset_metrics(self):
+        """Test metrics reset."""
+        cache = DecisionCache()
+
+        market_data = {"stock_code": "005930", "current_price": 75000}
+
+        # Generate some activity
+        cache.get(market_data)
+        cache.get(market_data)
+
+        # Reset
+        cache.reset_metrics()
+
+        metrics = cache.get_metrics()
+        assert metrics.total_requests == 0
+        assert metrics.cache_hits == 0
+        assert metrics.cache_misses == 0