backtesting/engine/ — Simulation Engine & Controller

📚 What is this & why does it exist?

The engine is the core loop of the backtesting system. It iterates through each trading day in a historical range, running the complete LangGraph agent pipeline as if it were live — agents can only see data up to that day, preventing future-data leakage. The controller manages agent invocation and output normalization, the engine manages the day loop (fetch prices, call agents, execute trades, compute value), and the trader translates decisions into portfolio changes. This three-layer separation keeps each concern clean, testable, and independently replaceable.

🤔 Why Is It Designed This Way?

The engine follows a pipeline-of-components pattern where each class owns exactly one responsibility. The BacktestEngine could have been a single monolithic class that fetches data, calls agents, executes trades, and computes metrics all in one loop body. Instead, it delegates to specialized components — AgentController for agent I/O normalization, TradeExecutor for position mutations, PerformanceMetricsCalculator for analytics, and OutputBuilder for display. This decomposition was driven by testability: each component can be unit-tested in isolation with mock inputs. The trade-off is more indirection (you must trace across 4+ files to understand one day's flow), but this is acceptable because the flow is strictly linear — no callbacks, no branching pipelines.

BacktestEngine.run_backtest() — The Day Loop

def run_backtest(self) -> PerformanceMetrics:
    self._prefetch_data()                                          # [1]

    dates = pd.date_range(self._start_date, self._end_date, freq="B")  # [2]
    if len(dates) > 0:
        self._portfolio_values = [
            {"Date": dates[0], "Portfolio Value": self._initial_capital}  # [3]
        ]

    for current_date in dates:                                     # [4]
        lookback_start = (current_date - relativedelta(months=1)).strftime("%Y-%m-%d")
        current_date_str = current_date.strftime("%Y-%m-%d")
        previous_date_str = (current_date - relativedelta(days=1)).strftime("%Y-%m-%d")

        # Fetch current prices for all tickers
        current_prices: Dict[str, float] = {}
        missing_data = False
        for ticker in self._tickers:
            try:
                price_data = get_price_data(ticker, previous_date_str, current_date_str)
                if price_data.empty:
                    missing_data = True; break
                current_prices[ticker] = float(price_data.iloc[-1]["close"])  # [5]
            except Exception:
                missing_data = True; break
        if missing_data:
            continue                                               # [6]

        agent_output = self._agent_controller.run_agent(           # [7]
            self._agent, tickers=self._tickers,
            start_date=lookback_start, end_date=current_date_str,
            portfolio=self._portfolio, ...)

        for ticker in self._tickers:                               # [8]
            d = agent_output["decisions"].get(ticker, {"action": "hold", "quantity": 0})
            executed_qty = self._executor.execute_trade(
                ticker, d["action"], d["quantity"], current_prices[ticker], self._portfolio)

        total_value = calculate_portfolio_value(self._portfolio, current_prices)  # [9]

        if len(self._portfolio_values) > 3:                        # [10]
            computed = self._perf.compute_metrics(self._portfolio_values)
            if computed:
                self._performance_metrics.update(computed)

    return self._performance_metrics