backtesting/portfolio/ — Portfolio Tracking & Performance Metrics

📚 What is this & why does it exist?

Without portfolio tracking and metrics, a backtest is just a list of decisions with no way to evaluate quality. This sub-module maintains the financial state of the simulated portfolio — tracking every position, cost basis, margin requirement, and realized/unrealized gain. The metrics module then analyzes this history using industry-standard measures. The Sharpe ratio tells you risk-adjusted return, maximum drawdown tells you worst-case loss, Sortino ratio penalizes only downside volatility, and benchmark comparison tells you whether the AI strategy beat simple index investing.

🤔 Why Is It Designed This Way?

The portfolio sub-module follows an encapsulated-state + pure-functions pattern. The Portfolio class is the only mutable component — it owns all position state and provides atomic mutation methods (apply_long_buy, apply_short_cover, etc.) that enforce invariants (can't sell more shares than held, can't spend more cash than available). Everything else is a pure function or a stateless calculator: calculate_portfolio_value takes a portfolio and prices, returns a number; compute_metrics takes value history, returns metrics. This separation makes the financial math easy to unit-test without mocking any state. The MappingProxyType wrapper on get_positions() prevents callers from accidentally mutating internal state — mutations must go through the apply_* methods.

PerformanceMetricsCalculator.compute_metrics() — Risk-Adjusted Returns

def compute_metrics(self, values: Sequence[PortfolioValuePoint]) -> PerformanceMetrics:
    import pandas as pd
    import numpy as np

    if not values:                                                  # [1]
        return {"sharpe_ratio": None, "sortino_ratio": None, "max_drawdown": None}

    df = pd.DataFrame(values)
    df = df.set_index("Date")
    df["Daily Return"] = df["Portfolio Value"].pct_change()         # [2]
    clean_returns = df["Daily Return"].dropna()
    if len(clean_returns) < 2:                                      # [3]
        return {"sharpe_ratio": None, "sortino_ratio": None, "max_drawdown": None}

    daily_rf = self.annual_rf_rate / self.annual_trading_days       # [4]
    excess = clean_returns - daily_rf                               # [5]
    mean_excess = excess.mean()
    std_excess = excess.std()

    if std_excess > 1e-12:                                          # [6]
        sharpe = float(np.sqrt(self.annual_trading_days) * (mean_excess / std_excess))
    else:
        sharpe = 0.0

    downside_diff = np.minimum(excess, 0)                           # [7]
    downside_dev = float(np.sqrt(np.mean(downside_diff**2)))
    if downside_dev > 1e-12:
        sortino = float(np.sqrt(self.annual_trading_days) * (mean_excess / downside_dev))
    else:
        sortino = float("inf") if mean_excess > 0 else 0.0         # [8]

    rolling_max = df["Portfolio Value"].cummax()                    # [9]
    drawdown = (df["Portfolio Value"] - rolling_max) / rolling_max
    max_drawdown = float(drawdown.min() * 100.0)                   # [10]

Portfolio.apply_long_buy() — Weighted-Average Cost Basis

def apply_long_buy(self, ticker: str, quantity: int, price: float) -> int:
    if quantity <= 0:
        return 0
    position = self._portfolio["positions"][ticker]
    cost = quantity * price

    if cost <= self._portfolio["cash"]:                            # [A]
        old_shares = position["long"]
        old_cost_basis = position["long_cost_basis"]
        total_shares = old_shares + quantity
        if total_shares > 0:
            total_old_cost = old_cost_basis * old_shares           # [B]
            total_new_cost = cost
            position["long_cost_basis"] = (total_old_cost + total_new_cost) / total_shares  # [C]
        position["long"] = old_shares + quantity
        self._portfolio["cash"] -= cost
        return quantity

    max_quantity = int(self._portfolio["cash"] / price)            # [D]
    if max_quantity > 0:
        # ... same cost-basis logic for partial fill ...
        return max_quantity
    return 0