Trade Logs & Reporting

After running a backtest or executing a trade, the system generates detailed logs and reports. These are designed to provide transparency into the decision-making process of the AI agents, going beyond simple price data to include the "why" behind every trade.

Logging Overview

The system stores trading activity in two primary formats:

1. JSON Reports: Local files stored in the logs/ directory, containing the raw data and agent reasoning for every step of a backtest.
2. Database Records: Structured data stored in the SQL database for the web dashboard to consume.

The view_trades CLI Utility

The project includes a dedicated CLI tool to quickly inspect backtest results without opening the full dashboard.

Basic Usage

To view the results of the most recent backtest, run:

python view_trades.py

To view a specific report file:

python view_trades.py logs/backtest_report_20231027_120000.json

Understanding the Output

The CLI utility parses the JSON report and prints a formatted table containing:

• Trade ID: The sequential number of the trade.
• Timestamp: The date/time of execution.
• Action: BUY (Open) or SELL (Close).
• Price: The execution price of the asset.
• P/L: For Sell actions, the percentage return of that specific trade.

Example Output:

======================================================================
TRADE LOG
======================================================================
  # 1 | 2023-10-01 | BUY    @ $43,500
  # 2 | 2023-10-05 | SELL   @ $45,200 | P/L: +3.91%
  # 3 | 2023-10-10 | BUY    @ $44,100
======================================================================

Interpreting JSON Reports

Each backtest generates a .json file. This file contains the complete state of the system at the time of the simulation.

Key Fields

| Field | Description | | :--- | :--- | | initial_capital | The starting balance of the backtest. | | final_value | The ending portfolio value. | | total_return_pct | Total performance percentage. | | trade_log | An array of trade objects containing entry/exit prices and timestamps. | | reasoning | (When enabled) The full text generated by the Lead Agent or Supervisor explaining the decision. |

Reasoning and Metadata

Because the system uses Pydantic schemas for agent outputs, the reports often include specialized metadata:

• Confidence: A score from 0-100 indicating the agent's certainty.
• Key Factors: A list of the primary drivers (e.g., "RSI Overbought", "Positive News Sentiment").
• Technical Metadata: Specific indicator values like RSI, MACD signals, or Support/Resistance levels.

Web Dashboard Reporting

For a visual analysis, the Trading Dashboard (built with FastAPI and React) provides a higher-level view of your reports.

Performance Metrics

The dashboard calculates and displays:

• Sharpe Ratio: Risk-adjusted return metric.
• Max Drawdown: The largest peak-to-trough decline.
• Win Rate: Percentage of profitable trades.
• Alpha vs. Hold: Comparison of the strategy performance against simply holding the asset.

Equity Curve

The dashboard plots a time-series chart showing your portfolio value over time compared to the asset's price (e.g., BTC). This helps identify if the strategy is successfully capturing trends or suffering during high volatility.

Trade Reasoning View

Unlike traditional trading platforms, you can click on any trade in the dashboard history to view the Agent Reasoning. This displays the exact logic the AI used, including technical levels and sentiment analysis that led to that specific execution.