0057de4d12
Some checks failed
CI / test (pull_request) Has been cancelled
Add API-efficient daily trading mode for Gemini Free tier compatibility: ## Features - **Batch Decisions**: GeminiClient.decide_batch() analyzes multiple stocks in a single API call using compressed JSON format - **Daily Trading Mode**: run_daily_session() executes N sessions per day at configurable intervals (default: 4 sessions, 6 hours apart) - **Mode Selection**: TRADE_MODE env var switches between daily (batch) and realtime (per-stock) modes - **Requirements Log**: docs/requirements-log.md tracks user feedback chronologically for project evolution ## Configuration - TRADE_MODE: "daily" (default) | "realtime" - DAILY_SESSIONS: 1-10 (default: 4) - SESSION_INTERVAL_HOURS: 1-24 (default: 6) ## API Efficiency - 2 markets × 4 sessions = 8 API calls/day (within Free tier 20 calls) - 3 markets × 4 sessions = 12 API calls/day (within Free tier 20 calls) ## Testing - 9 new batch decision tests (all passing) - All existing tests maintained (298 passed) ## Documentation - docs/architecture.md: Trading Modes section with daily vs realtime - CLAUDE.md: Requirements Management section - docs/requirements-log.md: Initial entries for API efficiency needs Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
138 lines
4.8 KiB
Markdown
138 lines
4.8 KiB
Markdown
# The Ouroboros
|
||
|
||
AI-powered trading agent for global stock markets with self-evolution capabilities.
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Setup
|
||
pip install -e ".[dev]"
|
||
cp .env.example .env
|
||
# Edit .env with your KIS and Gemini API credentials
|
||
|
||
# Test
|
||
pytest -v --cov=src
|
||
|
||
# Run (paper trading)
|
||
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
|
||
- **[Command Reference](docs/commands.md)** — Common failures, build commands, troubleshooting
|
||
- **[Architecture](docs/architecture.md)** — System design, components, data flow
|
||
- **[Context Tree](docs/context-tree.md)** — L1-L7 hierarchical memory system
|
||
- **[Testing](docs/testing.md)** — Test structure, coverage requirements, writing tests
|
||
- **[Agent Policies](docs/agents.md)** — Prime directives, constraints, prohibited actions
|
||
- **[Requirements Log](docs/requirements-log.md)** — User requirements and feedback tracking
|
||
|
||
## Core Principles
|
||
|
||
1. **Safety First** — Risk manager is READ-ONLY and enforces circuit breakers
|
||
2. **Test Everything** — 80% coverage minimum, all changes require tests
|
||
3. **Issue-Driven Development** — All work goes through Gitea issues → feature branches → PRs
|
||
4. **Agent Specialization** — Use dedicated agents for design, coding, testing, docs, review
|
||
|
||
## Requirements Management
|
||
|
||
User requirements and feedback are tracked in [docs/requirements-log.md](docs/requirements-log.md):
|
||
|
||
- New requirements are added chronologically with dates
|
||
- Code changes should reference related requirements
|
||
- Helps maintain project evolution aligned with user needs
|
||
- Preserves context across conversations and development cycles
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
src/
|
||
├── broker/ # KIS API client (domestic + overseas)
|
||
├── brain/ # Gemini AI decision engine
|
||
├── 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/ # 273 tests across 13 files
|
||
docs/ # Extended documentation
|
||
```
|
||
|
||
## Key Commands
|
||
|
||
```bash
|
||
pytest -v --cov=src # Run tests with coverage
|
||
ruff check src/ tests/ # Lint
|
||
mypy src/ --strict # Type check
|
||
|
||
python -m src.main --mode=paper # Paper trading
|
||
python -m src.main --mode=live # Live trading (⚠️ real money)
|
||
|
||
# Gitea workflow (requires tea CLI)
|
||
YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "..." --description "..."
|
||
YES="" ~/bin/tea pulls create --head feature-branch --base main --title "..." --description "..."
|
||
```
|
||
|
||
## Markets Supported
|
||
|
||
- 🇰🇷 Korea (KRX)
|
||
- 🇺🇸 United States (NASDAQ, NYSE, AMEX)
|
||
- 🇯🇵 Japan (TSE)
|
||
- 🇭🇰 Hong Kong (SEHK)
|
||
- 🇨🇳 China (Shanghai, Shenzhen)
|
||
- 🇻🇳 Vietnam (Hanoi, HCM)
|
||
|
||
Markets auto-detected based on timezone and enabled in `ENABLED_MARKETS` env variable.
|
||
|
||
## Critical Constraints
|
||
|
||
⚠️ **Non-Negotiable Rules** (see [docs/agents.md](docs/agents.md)):
|
||
|
||
- `src/core/risk_manager.py` is **READ-ONLY** — changes require human approval
|
||
- Circuit breaker at -3.0% P&L — may only be made **stricter**
|
||
- Fat-finger protection: max 30% of cash per order — always enforced
|
||
- Confidence < 80 → force HOLD — cannot be weakened
|
||
- All code changes → corresponding tests → coverage ≥ 80%
|
||
|
||
## Contributing
|
||
|
||
See [docs/workflow.md](docs/workflow.md) for the complete development process.
|
||
|
||
**TL;DR:**
|
||
1. Create issue in Gitea
|
||
2. Create feature branch: `feature/issue-N-description`
|
||
3. Implement with tests
|
||
4. Open PR
|
||
5. Merge after review
|