How ethanalgox/llm-tradebot works
1. What this repo is
- A Python 3.11+ automated crypto futures trading system centered on an adversarial multi-agent decision pipeline.
- It has three operational surfaces: live/test trading, backtesting/research, and a browser dashboard.
2. Primary entrypoints
- main.py runs the full trading system and the dashboard-backed live/test loop.
- simple_cli.py is a lean headless runtime for production-style trading without the web UI.
- backtest.py and the research/ package run historical simulation, comparison, and optimization workflows.
- src/server/app.py plus web/ provide the dashboard/backend boundary.
3. Cycle orchestration
- The heart of the system is in src/runners/, which composes a per-cycle pipeline:
- data sync
- analysis
- decision
- risk audit
- execution
- cycle_pipeline_runner.py and the stage runners formalize this flow so live trading and backtesting can share the same logical stages.
4. Market-data ingestion and snapshot alignment
- src/api/ contains exchange data clients and websocket support.
- DataSyncAgent and helpers in src/utils/ align multi-timeframe snapshots, especially 5m/15m/1h data.
- This alignment is a key architectural boundary: downstream agents consume a single synchronized snapshot rather than independent time series.
5. Feature and validation layer
- src/data/ validates and processes raw market inputs.
- src/features/ builds technical features from the aligned snapshot.
- src/utils/data_alignment.py, kline_cache.py, and related helpers support consistency, caching, and auditability of the raw-to-feature transformation.
6. Multi-agent analysis layer
- src/agents/ is the main intelligence subsystem.
- Core always-on agents:
- data_sync
- quant_analyst
- decision_core
- risk_audit
- Optional agents add specialized views: symbol selection, regime detection, position analysis, trigger detection, prediction, reflection, and trend/setup/trigger semantic analysis.
- Many agents have both LLM and local/rule-based variants, which is an important runtime boundary.
7. Decision framework
- The repo’s central logic is the Adversarial Decision Framework:
- quantitative signals
- semantic analysis
- optional prediction/filtering
- multi-period summary
- final vote aggregation in DecisionCoreAgent
- Files like overtrading_guard.py, signal_weight.py, vote_result.py, and trade_record.py show that the system is explicitly modeling confidence, vetoes, and trade history, not just issuing raw buy/sell signals.
8. Risk and execution boundary
- src/risk/manager.py and src/agents/risk_audit/ provide a hard safety layer before orders are sent.
- src/execution/engine.py is the handoff point from “decision” to “order placed.”
- src/exchanges/ abstracts the broker/exchange side; Binance futures is the implemented target via binance_trader.py, with multi-account management in account_manager.py.
9. LLM integration boundary
- src/llm/ is a provider abstraction layer with clients for DeepSeek, OpenAI, Claude, Qwen, Gemini, MiniMax, GLM, OpenRouter, and Kimi.
- factory.py centralizes provider selection, so the rest of the system is insulated from vendor-specific APIs.
- Prompt templates and agent-specific prompt/config handling live in src/config/ and agent setup modules.
10. Machine-learning and strategy support
- src/models/prophet_model.py and src/agents/predict/ implement the prediction side, including a LightGBM-based probability model described in the README.
- src/strategy/ and src/strategies/ hold lower-level decision/indicator logic that can be composed into the agent pipeline.
11. Backtesting and research
- src/backtest/ mirrors the trading pipeline for simulation: replay, portfolio accounting, metrics, analytics, reporting, and storage.
- research/ contains exploratory workflows and strategy comparison tools.
- The README indicates the backtest path is intended to stay behaviorally aligned with live trading, including risk audit and multi-layer filtering.
12. Observability, state, and persistence
- Runtime state is persisted under data/ in separate folders for market data, indicators, features, decisions, and execution records.
- src/monitoring/, src/utils/logger.py, pipeline_logger.py, and trade_logger.py handle runtime logging and audit trails.
- This makes the system white-box: every cycle leaves a trace from raw candles to final order action.
13. User-facing interface
- web/ contains the dashboard frontend assets, while src/server/ provides the application state/config backend.
- The dashboard is not just cosmetic; it exposes agent outputs, configuration, mode switching, and historical traces, so it sits directly on top of the trading pipeline.
14. Operational and test boundaries
- config.example.yaml, .env.example, and config/accounts.example.json define the main configuration surface.
- tests/ covers protocols, agents, risk, execution, data flow, and backtest behavior, which suggests the repo is organized around contract-style boundaries between subsystems.
- Docker and shell scripts (Dockerfile, docker/, start.sh, install.sh, scripts/) support deployment, migration, and validation, but they do not change the core architecture.
Main entry points: runners Cycle Runners · data_sync_agent.py Data Sync Agent · engine.py Execution Engine · backtest Backtest Engine
Components 21
Entrypoints
Primary runtime and workflow entry scripts
- main.py · Full trading system entrypoint with dashboard-backed live/test loop
main.py - simple_cli.py · Headless production-style trading runtime
simple_cli.py - backtest.py · Standalone backtesting entrypoint
backtest.py
Trading Core
Live trading pipeline and orchestration
- Cycle Runners · Composes the per-cycle stages for live trading and backtesting
src/runners - Trading Bot · Coordinates symbol context, filters, and multi-agent trading flow
src/trading
Agent Intelligence
Multi-agent analysis and decision layers
- Data Sync Agent · Creates synchronized snapshots for downstream analysis
src/agents/data_sync/data_sync_agent.py - Quant Analyst · Produces quantitative signals and analysis
src/agents/quant_analyst_agent.py - Decision Core · Aggregates votes, confidence, vetoes, and trade history into final decisions
src/agents/decision_core/decision_core_agent.py - Risk Audit · Hard safety gate before execution
src/agents/risk_audit/risk_audit_agent.py - Specialist Agents · Optional symbol, regime, setup, trend, trigger, reflection, and prediction agents
src/agents
Infrastructure
Exchange, risk, LLM, storage, and server boundaries
- Market API · Exchange clients and websocket ingestion
src/api - Data Validation · Validates and normalizes raw market inputs
src/data - Feature Builder · Builds technical features from aligned snapshots
src/features - Snapshot Alignment · Aligns multi-timeframe snapshots and supports cache/audit consistency
src/utils/data_alignment.py - LLM Layer · Vendor-neutral client and factory layer for model providers
src/llm - Risk Manager · System-level risk constraints and pre-order checks
src/risk/manager.py - Execution Engine · Bridges approved decisions into exchange orders
src/execution/engine.py - Exchange Layer · Broker abstraction with Binance futures implementation and account management
src/exchanges - Dashboard · Server state/config backend and browser dashboard frontend
src/server/app.py
Research
Backtest and exploratory analysis workflows
- Backtest Engine · Replay, accounting, metrics, reporting, and storage for simulation
src/backtest - Research Tools · Strategy comparison and exploratory research workflows
research
Connections 23
- main.py → Cycle Runners: starts · Main runtime enters the shared cycle pipeline
- simple_cli.py → Trading Bot: starts · Headless runtime drives the trading bot
- backtest.py → Backtest Engine: runs · Standalone backtest entrypoint invokes simulation engine
- Trading Bot → Cycle Runners: uses · Trading bot relies on shared stage runners
- Cycle Runners → Data Sync Agent: stage 1 · Per-cycle data sync and snapshot creation
- Cycle Runners → Quant Analyst: stage 2 · Quantitative analysis stage
- Cycle Runners → Decision Core: stage 3 · Final vote aggregation and decisioning
- Cycle Runners → Risk Audit: stage 4 · Risk audit gate before execution
- Cycle Runners → Execution Engine: stage 5 · Execution handoff after approval
- Data Sync Agent → Market API: ingests · Pulls exchange data and websocket updates
- Data Sync Agent → Snapshot Alignment: aligns · Builds synchronized multi-timeframe snapshots
- Data Sync Agent → Data Validation: validates · Routes raw market inputs through validation layer
- Data Validation → Feature Builder: feeds · Validated data becomes feature inputs
- Feature Builder → Quant Analyst: signals · Technical features power quant analysis
- Specialist Agents → Decision Core: specializes · Specialist agents feed semantic and predictive views into the decision core
- LLM Layer → Specialist Agents: powers · LLM-backed variants use provider abstraction
- Risk Audit → Risk Manager: enforces · Agent-level safety checks defer to system risk manager
- Risk Manager → Execution Engine: gates · Risk manager can block or constrain order placement
- Execution Engine → Exchange Layer: routes orders · Execution engine submits orders through exchange adapters
- Exchange Layer → Market API: targets · Broker adapter depends on exchange client surface
- Cycle Runners → Backtest Engine: mirrors · Backtest reuses the live cycle structure
- Research Tools → Backtest Engine: analyzes · Research workflows use backtest engine and comparisons
- main.py → Dashboard: serves · Main runtime exposes dashboard-backed control and state