Backtest Runner

The Backtest Runner is the core simulation engine of the system. It allows you to evaluate trading strategies by running the multi-agent orchestrator against historical market data. Unlike traditional backtesters that only look at price action, this runner simulates the entire decision-making process, including agent reasoning, sentiment analysis from archived news, and risk management constraints.

Running a Simulation

Backtests are executed via the command line. The runner simulates daily or hourly intervals, feeding market context to the agents and recording their recommendations as executed trades.

Basic Usage

To run a standard backtest for the last 30 days:

python run_backtest.py --days 30

Configuration Options

Analyzing Results

Once a backtest completes, the system generates a comprehensive JSON report in the logs/ directory and updates the local database for the dashboard.

Trade Log CLI

You can quickly inspect the execution history of your most recent run using the view_trades.py utility:

python view_trades.py

Example Output:

======================================================================
TRADE LOG
======================================================================
  # 1 | 2025-01-10 | BUY    @ $94,210
  # 2 | 2025-01-15 | SELL   @ $102,500 | P/L: +8.80%
  # 3 | 2025-01-20 | BUY    @ $98,000
======================================================================

Performance Metrics

The runner calculates several institutional-grade metrics to evaluate the strategy's viability:

Total Return: Cumulative profit or loss percentage.
Sharpe Ratio: Risk-adjusted return performance.
Max Drawdown: The largest peak-to-trough decline.
Win Rate: Percentage of trades closed at a profit.
Alpha vs. Hold: Performance comparison against simply holding the asset.

Visualization via Dashboard

For a deep dive into agent behavior and equity progression, use the built-in Dashboard. It provides a visual timeline of the equity curve correlated with agent reasoning.

Start the Backend:
```
python dashboard/backend/main.py
```
Start the Frontend:
```
cd dashboard/frontend
npm run dev
```

Navigate to http://localhost:5173 to view the Equity Curve and the Trade Table, where you can click on individual trades to see the specific agent logic (Technical, Sentiment, and Fundamental) that led to that execution.

Virtual Portfolio Management

The Backtest Runner maintains a stateful virtual portfolio during the simulation:

Order Execution: Simulates market orders based on the price at the time of the agent's decision.
Position Sizing: Respects the RiskManagement agent's output (e.g., FULL, HALF, or QUARTER positions).
Constraint Checking: Prevents "over-buying" by checking available USD liquidity before executing BUY signals.
Stop-Loss/Take-Profit: Implements automated exits if price boundaries defined by the Risk agent are crossed during the simulation interval.

Data Integration

The runner automatically pulls historical data through the configured connectors:

Price Data: Fetched via CoinGecko or CCXT.
Market Sentiment: Reconstructed using the NewsAPIConnector to simulate the news environment available at that specific historical timestamp.