Add safe_float() helper function to safely convert API response values
to float, handling empty strings, None, and invalid values that cause
ValueError: "could not convert string to float: ''".
Changes:
- Add safe_float() function in src/main.py with full docstring
- Replace all float() calls with safe_float() in trading_cycle()
- Domestic market: orderbook prices, balance amounts
- Overseas market: price data, balance info
- Add 6 comprehensive unit tests for safe_float()
The function handles:
- Empty strings ("") → default (0.0)
- None values → default (0.0)
- Invalid strings ("abc") → default (0.0)
- Valid strings ("123.45") → parsed float
- Float inputs (123.45) → pass through
This prevents crashes when KIS API returns empty strings during
market closed hours or data unavailability.
Fixes: #44
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Reduce RATE_LIMIT_RPS from 10.0 to 5.0 to prevent "초당 거래건수를
초과하였습니다" (EGW00201) errors from KIS API.
Docker logs showed this was the most frequent error (70% of failures),
occurring when multiple stocks are scanned rapidly.
Changes:
- src/config.py: RATE_LIMIT_RPS 10.0 → 5.0
- .env.example: Update default and add explanation comment
Trade-off: Slower API throughput, but more reliable operation.
Can be tuned per deployment via environment variable.
Fixes: #43
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add asyncio.Lock to prevent multiple coroutines from simultaneously
refreshing the KIS access token, which hits the 1-per-minute rate
limit (EGW00133: "접근토큰 발급 잠시 후 다시 시도하세요").
Changes:
- Add self._token_lock in KISBroker.__init__
- Wrap token refresh in async with self._token_lock
- Re-check token validity after acquiring lock (double-check pattern)
- Add concurrent token refresh test (5 parallel requests → 1 API call)
The lock ensures that when multiple coroutines detect an expired token,
only the first one refreshes while others wait and reuse the result.
Fixes: #42
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add type checking for output2 response from get_overseas_balance API.
The API can return either list format [{}] or dict format {}, causing
KeyError when accessing output2[0].
Changes:
- Check isinstance before accessing output2[0]
- Handle list, dict, and empty cases
- Add safe fallback with "or" for empty strings
- Add 3 test cases for list/dict/empty formats
Fixes: #41
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Integrate Telegram notifications throughout the main trading loop to provide
real-time alerts for critical events and trading activities.
Changes:
- Add TelegramClient initialization in run() function
- Send system startup notification on agent start
- Send market open/close notifications when markets change state
- Send trade execution notifications for BUY/SELL orders
- Send fat finger rejection notifications when orders are blocked
- Send circuit breaker notifications when loss threshold is exceeded
- Pass telegram client to trading_cycle() function
- Add tests for all notification scenarios in test_main.py
All notifications wrapped in try/except to ensure trading continues even
if Telegram API fails. Notifications are non-blocking and do not affect
core trading logic.
Test coverage: 273 tests passed, overall coverage 79%
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add ALPHA_VANTAGE_API_KEY and NEWSAPI_KEY for backward compatibility
with existing .env configurations.
Fixes test failures in test_volatility.py where Settings validation
rejected extra fields from environment variables.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add objective external data sources to enhance trading decisions beyond
market prices and user input.
## New Modules
### src/data/news_api.py
- News sentiment analysis with Alpha Vantage and NewsAPI support
- Sentiment scoring (-1.0 to +1.0) per article and aggregated
- 5-minute caching to minimize API quota usage
- Graceful degradation when APIs unavailable
### src/data/economic_calendar.py
- Track major economic events (FOMC, GDP, CPI)
- Earnings calendar per stock
- Event proximity checking for high-volatility periods
- Hardcoded major events for 2026 (no API required)
### src/data/market_data.py
- Market sentiment indicators (Fear & Greed equivalent)
- Market breadth (advance/decline ratios)
- Sector performance tracking
- Fear/Greed score calculation
## Integration
Enhanced GeminiClient to seamlessly integrate external data:
- Optional news_api, economic_calendar, and market_data parameters
- Async build_prompt() includes external context when available
- Backward-compatible build_prompt_sync() for existing code
- Graceful fallback when external data unavailable
External data automatically added to AI prompts:
- News sentiment with top articles
- Upcoming high-impact economic events
- Market sentiment and breadth indicators
## Configuration
Added optional settings to config.py:
- NEWS_API_KEY: API key for news provider
- NEWS_API_PROVIDER: "alphavantage" or "newsapi"
- MARKET_DATA_API_KEY: API key for market data
## Testing
Comprehensive test suite with 38 tests:
- NewsAPI caching, sentiment parsing, API integration
- EconomicCalendar event filtering, earnings lookup
- MarketData sentiment and breadth calculations
- GeminiClient integration with external data sources
- All tests use mocks (no real API keys required)
- 81% coverage for src/data module (exceeds 80% requirement)
## Circular Import Fix
Fixed circular dependency between gemini_client.py and cache.py:
- Use TYPE_CHECKING for imports in cache.py
- String annotations for TradeDecision type hints
All 195 existing tests pass. No breaking changes to existing functionality.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Resolved conflicts in CLAUDE.md by:
- Keeping main's refactored structure (docs split into separate files)
- Added Context Tree documentation link to docs section
- Preserved all constraints and guidelines from main
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Document modern AI development workflow using specialized agents
- Add guidelines for when to use git worktree/subagents vs main conversation
- Define agent roles: ticket mgmt, design, code, test, docs, review
- Include implementation examples with Task tool
- Update test count (35 → 54) with new market_schedule tests
Closes#9
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implement comprehensive multi-market trading system with automatic
market selection based on timezone and trading hours.
## New Features
- Market schedule module with 10 global markets (KR, US, JP, HK, CN, VN)
- Overseas broker for KIS API international stock trading
- Automatic market detection based on current time and timezone
- Next market open waiting logic when all markets closed
- ConnectionError retry with exponential backoff (max 3 attempts)
## Architecture Changes
- Market-aware trading cycle with domestic/overseas broker routing
- Market context in AI prompts for better decision making
- Database schema extended with market and exchange_code columns
- Config setting ENABLED_MARKETS for market selection
## Testing
- 19 new tests for market schedule (timezone, DST, lunch breaks)
- All 54 tests passing
- Lint fixes with ruff
## Files Added
- src/markets/schedule.py - Market schedule and timezone logic
- src/broker/overseas.py - KIS overseas stock API client
- tests/test_market_schedule.py - Market schedule test suite
## Files Modified
- src/main.py - Multi-market main loop with retry logic
- src/config.py - ENABLED_MARKETS setting
- src/db.py - market/exchange_code columns with migration
- src/brain/gemini_client.py - Dynamic market context in prompts
Resolves#5
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add comprehensive Git workflow policy section to ensure all code
changes follow proper process: issue creation, feature branch,
PR, and merge. Explicitly prohibit direct pushes to main branch.
Resolves#4
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add build & test commands reference
- Document architecture and component interactions
- Include key constraints from docs/agents.md
- Provide configuration and test structure overview
Closes#2
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The KIS virtual trading server (openapivts.koreainvestment.com) serves a
certificate with a hostname mismatch. Disable SSL hostname verification
only for the VTS endpoint via a custom TCPConnector; production endpoints
remain fully verified.
Closes#1
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
