From 881bbb424000c026cd67505a6a697b265e996756 Mon Sep 17 00:00:00 2001 From: agentson Date: Wed, 4 Feb 2026 23:48:01 +0900 Subject: [PATCH] docs: add Telegram notifications documentation (issue #35) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update project documentation to include Telegram notification feature that was added in issues #31-34. Changes: - CLAUDE.md: Add Telegram quick setup section with examples - README.md (Korean): Add 텔레그램 알림 section with setup guide - docs/architecture.md: Add Notifications component documentation - New section explaining TelegramClient architecture - Add notification step to data flow diagram - Add Telegram config to environment variables - Document error handling for notification failures Documentation covers: - Quick setup instructions (bot creation, chat ID, env config) - Notification types (trades, circuit breaker, fat-finger, etc.) - Fail-safe behavior (notifications never crash trading) - Links to detailed guide in src/notifications/README.md Project structure updated to reflect notifications/ directory and updated test count (273 tests). Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 31 +++++++++++++++++++++++++++- README.md | 48 +++++++++++++++++++++++++++++++++++--------- docs/architecture.md | 43 ++++++++++++++++++++++++++++++++++++++- 3 files changed, 111 insertions(+), 11 deletions(-) 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.