The-Ouroboros/CLAUDE.md

The Ouroboros

AI-powered trading agent for global stock markets with self-evolution capabilities.

Quick Start

# 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 on Telegram → /newbot
2. Get chat ID: Message @userinfobot → /start
3. Configure: Add to .env:

   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

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.

Smart Volatility Scanner (Optional)

Python-first filtering pipeline that reduces Gemini API calls by pre-filtering stocks using technical indicators.

How It Works

1. Fetch Rankings — KIS API volume surge rankings (top 30 stocks)
2. Python Filter — RSI + volume ratio calculations (no AI)
   • Volume > 200% of previous day
   • RSI(14) < 30 (oversold) OR RSI(14) > 70 (momentum)
3. AI Judgment — Only qualified candidates (1-3 stocks) sent to Gemini

Configuration

Add to .env (optional, has sensible defaults):

RSI_OVERSOLD_THRESHOLD=30    # 0-50, default 30
RSI_MOMENTUM_THRESHOLD=70    # 50-100, default 70
VOL_MULTIPLIER=2.0           # Volume threshold (2.0 = 200%)
SCANNER_TOP_N=3              # Max candidates per scan

Benefits

• Reduces API costs — Process 1-3 stocks instead of 20-30
• Python-based filtering — Fast technical analysis before AI
• Evolution-ready — Selection context logged for strategy optimization
• Fault-tolerant — Falls back to static watchlist on API failure

Realtime Mode Only

Smart Scanner runs in TRADE_MODE=realtime only. Daily mode uses static watchlists for batch efficiency.

Documentation

• Workflow Guide — Git workflow policy and agent-based development
• Command Reference — Common failures, build commands, troubleshooting
• Architecture — System design, components, data flow
• Context Tree — L1-L7 hierarchical memory system
• Testing — Test structure, coverage requirements, writing tests
• Agent Policies — Prime directives, constraints, prohibited actions
• Requirements Log — 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:

• 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/
├── analysis/        # Technical analysis (RSI, volatility, smart scanner)
├── 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/               # 343 tests across 14 files
docs/                # Extended documentation

Key Commands

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):

• 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 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