performance.py

from __future__ import annotations

"""
Performance Analytics Module

Reads backtest results CSV and computes:

• CAGR
• Sharpe Ratio
• Max Drawdown
• Profit Factor
• Number of Trades
• Average Holding Period

Assumptions:
------------
- Trades are sequential (no overlapping positions)
- Capital fully allocated per trade
- No compounding during trade
- Equity updated at trade exit
- Initial capital = 1.0 (normalized)
"""

from dataclasses import dataclass
from pathlib import Path
from typing import Dict

import numpy as np
import pandas as pd


@dataclass
class PerformanceReport:
    log_path: str | Path
    risk_free_rate: float = 0.0  # annual risk-free

    def generate(self) -> Dict[str, float]:
        df = pd.read_csv(self.log_path)

        if df.empty:
            raise ValueError("Log file is empty")

        df["entry_time"] = pd.to_datetime(df["entry_time"])
        df["exit_time"] = pd.to_datetime(df["exit_time"])

        df = df.sort_values("exit_time")

        # ================================
        # Basic Trade Metrics
        # ================================

        number_of_trades = len(df)
        gross_profit = df.loc[df["pnl"] > 0, "pnl"].sum()
        gross_loss = -df.loc[df["pnl"] < 0, "pnl"].sum()

        profit_factor = gross_profit / gross_loss if gross_loss != 0 else np.inf

        holding_periods = (df["exit_time"] - df["entry_time"]).dt.total_seconds() / 3600
        avg_holding_hours = holding_periods.mean()

        # ================================
        # Equity Curve Construction
        # ================================

        equity = 1.0
        equity_curve = []

        for pnl in df["pnl"]:
            equity += pnl
            equity_curve.append(equity)

        equity_curve = np.array(equity_curve)

        # ================================
        # CAGR
        # ================================

        start_date = df["entry_time"].min()
        end_date = df["exit_time"].max()
        total_years = (end_date - start_date).days / 365.25

        final_equity = equity_curve[-1]
        cagr = (final_equity / 1.0) ** (1 / total_years) - 1 if total_years > 0 else 0

        # ================================
        # Sharpe Ratio
        # ================================

        returns = np.diff(equity_curve, prepend=1.0)
        returns_pct = returns / equity_curve[:-1].mean() if len(returns) > 1 else np.array([0])

        if returns_pct.std() != 0:
            sharpe = (
                (returns_pct.mean() - self.risk_free_rate / 252)
                / returns_pct.std()
            ) * np.sqrt(252)
        else:
            sharpe = 0.0

        # ================================
        # Max Drawdown
        # ================================

        running_max = np.maximum.accumulate(equity_curve)
        drawdowns = (equity_curve - running_max) / running_max
        max_drawdown = drawdowns.min()

        return {
            "CAGR": cagr,
            "Sharpe": sharpe,
            "Max Drawdown": max_drawdown,
            "Profit Factor": profit_factor,
            "Number of Trades": number_of_trades,
            "Average Holding Period (hours)": avg_holding_hours,
        }