diff --git a/CLAUDE.md b/CLAUDE.md index 341f968..f081363 100644 --- a/CLAUDE.md +++ b/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 ``` diff --git a/README.md b/README.md index ff2c6c8..16a818e 100644 --- a/README.md +++ b/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 μ„€μ • -β”‚ β”œβ”€β”€ logging_config.py # JSON ꡬ쑰화 λ‘œκΉ… -β”‚ β”œβ”€β”€ db.py # SQLite 거래 기둝 -β”‚ β”œβ”€β”€ main.py # 비동기 거래 루프 -β”‚ β”œβ”€β”€ broker/kis_api.py # KIS API ν΄λΌμ΄μ–ΈνŠΈ -β”‚ β”œβ”€β”€ brain/gemini_client.py # Gemini μ˜μ‚¬κ²°μ • μ—”μ§„ -β”‚ β”œβ”€β”€ core/risk_manager.py # 리슀크 관리 -β”‚ β”œβ”€β”€ evolution/optimizer.py # μ „λž΅ μ§„ν™” μ—”μ§„ -β”‚ └── strategies/base.py # μ „λž΅ 베이슀 클래슀 +β”‚ β”œβ”€β”€ config.py # Pydantic μ„€μ • +β”‚ β”œβ”€β”€ logging_config.py # JSON ꡬ쑰화 λ‘œκΉ… +β”‚ β”œβ”€β”€ db.py # SQLite 거래 기둝 +β”‚ β”œβ”€β”€ main.py # 비동기 거래 루프 +β”‚ β”œβ”€β”€ broker/kis_api.py # KIS API ν΄λΌμ΄μ–ΈνŠΈ +β”‚ β”œβ”€β”€ brain/gemini_client.py # Gemini μ˜μ‚¬κ²°μ • μ—”μ§„ +β”‚ β”œβ”€β”€ core/risk_manager.py # 리슀크 관리 +β”‚ β”œβ”€β”€ notifications/telegram_client.py # ν…”λ ˆκ·Έλž¨ μ•Œλ¦Ό +β”‚ β”œβ”€β”€ evolution/optimizer.py # μ „λž΅ μ§„ν™” μ—”μ§„ +β”‚ └── strategies/base.py # μ „λž΅ 베이슀 클래슀 β”œβ”€β”€ tests/ # TDD ν…ŒμŠ€νŠΈ μŠ€μœ„νŠΈ β”œβ”€β”€ Dockerfile # λ©€ν‹°μŠ€ν…Œμ΄μ§€ λΉŒλ“œ β”œβ”€β”€ docker-compose.yml # μ„œλΉ„μŠ€ μ˜€μΌ€μŠ€νŠΈλ ˆμ΄μ…˜ diff --git a/docs/architecture.md b/docs/architecture.md index f1cf0a4..06bf31a 100644 --- a/docs/architecture.md +++ b/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.