erfaniaa/llm-auto-trader

Purpose and entry points

LLM-Auto-Trader is a Python crypto-trading system where an LLM proposes actions and deterministic controls approve, resize, reject, and execute them. Primary live/paper orchestration is src/bot.py, launched through scripts/paper_trade.py; scheduled Claude Code operation is scripts/live_cycle.sh. Research/backtest entry points center on scripts/prepare_snapshots.py, scripts/dispatch_decisions.py, and scripts/run_cpcv.py.

Configuration and operating modes

Layered environment-driven settings define exchange, universe, LLM, risk, cadence, storage, and notifications in config/settings.py; symbol resolution/fallbacks live in config/symbols.py. The key boundary is BOT_MODE: paper mode simulates execution, while live mode requires exchange credentials and submits real orders. Exchange-specific fees, maintenance margin, and market conventions are centralized in src/exchange/profile.py.

Market-data and feature pipeline

Data adapters collect exchange market/derivatives data and supplemental information, then aggregate it into a decision-ready market state. Core ingestion boundaries are src/data/market.py, src/data/aggregator.py, and src/data/websocket.py; external/specialized feeds include news, on-chain, sentiment, prediction markets, and top-trader signals under src/data/. Analysis transforms inputs into indicators, statistical features, and market/risk regimes via src/analysis/indicators.py, src/analysis/market_state.py, and src/analysis/regime.py.

LLM decision subsystem

src/llm/context_builder.py composes token-budgeted context from features, positions, and memory. src/llm/client.py selects a provider through src/llm/providers/factory.py; supported external services are Anthropic, OpenAI, Google, and OpenAI-compatible endpoints. src/llm/response_parser.py converts structured model output into actions, while src/llm/cost_tracker.py enforces token-spend accounting. Prompt assets are versioned under prompts/, including prompts/decide_system_prompt.md.

Validation, risk, and execution boundary

Before any order crosses into execution, response validation and deterministic risk controls gate it. src/live/decision_validator.py validates candidate decisions; src/risk/risk_manager.py coordinates sizing, leverage/correlation constraints, circuit breakers, margin checks, stops, cooldowns, and volatility targeting using components such as src/risk/circuit_breakers.py and src/risk/position_sizer.py. Approved actions pass to src/execution/executor.py and src/execution/position_manager.py, which interact with CCXT-supported exchanges or paper simulation.

Persistence and reporting

SQLite is the default durable boundary, implemented in src/storage/database.py, with lifecycle cleanup in src/storage/retention.py. It stores operational records such as decisions, trades, prompts, and data according to retention policy. Notifications are optional and isolated in src/telegram/reporter.py, targeting the Telegram Bot API; console/logging remains local.

Historical evaluation architecture

The backtest system separates historical inputs, point-in-time snapshots, cached LLM decisions, and simulation. src/backtest/snapshot_builder.py prevents prompt lookahead; src/backtest/decision_cache.py and src/backtest/vote_cache.py make decisions reusable; src/backtest/runner.py applies fills, funding, costs, and portfolio logic. CPCV/walk-forward evaluation resides in src/backtest/cpcv.py and src/backtest/walk_forward.py, with results persisted as committed research artifacts under runs/. This isolates expensive or nondeterministic LLM generation from repeatable portfolio simulation and robustness analysis.