vault-dash/app/models/backtest.py

from __future__ import annotations

from dataclasses import dataclass, field
from datetime import date

from app.models.event_preset import EventPreset


@dataclass(frozen=True)
class BacktestPortfolioState:
    currency: str
    underlying_units: float
    entry_spot: float
    loan_amount: float
    margin_call_ltv: float
    cash_balance: float = 0.0
    financing_rate: float = 0.0

    def __post_init__(self) -> None:
        if self.currency.upper() != "USD":
            raise ValueError("USD is the only supported currency in the MVP")
        if self.underlying_units <= 0:
            raise ValueError("underlying_units must be positive")
        if self.entry_spot <= 0:
            raise ValueError("entry_spot must be positive")
        if self.loan_amount < 0:
            raise ValueError("loan_amount must be non-negative")
        if not 0 < self.margin_call_ltv < 1:
            raise ValueError("margin_call_ltv must be between 0 and 1")
        if self.loan_amount >= self.underlying_units * self.entry_spot:
            raise ValueError("loan_amount must be less than initial collateral value")

    @property
    def start_value(self) -> float:
        return self.underlying_units * self.entry_spot


@dataclass(frozen=True)
class TemplateRef:
    slug: str
    version: int

    def __post_init__(self) -> None:
        if not self.slug:
            raise ValueError("template slug is required")
        if self.version <= 0:
            raise ValueError("template version must be positive")


@dataclass(frozen=True)
class ProviderRef:
    provider_id: str
    pricing_mode: str

    def __post_init__(self) -> None:
        if not self.provider_id:
            raise ValueError("provider_id is required")
        if not self.pricing_mode:
            raise ValueError("pricing_mode is required")


@dataclass(frozen=True)
class BacktestScenario:
    scenario_id: str
    display_name: str
    symbol: str
    start_date: date
    end_date: date
    initial_portfolio: BacktestPortfolioState
    template_refs: tuple[TemplateRef, ...]
    provider_ref: ProviderRef

    def __post_init__(self) -> None:
        if not self.scenario_id:
            raise ValueError("scenario_id is required")
        if not self.display_name:
            raise ValueError("display_name is required")
        if not self.symbol:
            raise ValueError("symbol is required")
        if self.start_date > self.end_date:
            raise ValueError("start_date must be on or before end_date")
        if not self.template_refs:
            raise ValueError("at least one template ref is required")


@dataclass(frozen=True)
class BacktestDailyPoint:
    date: date
    spot_close: float
    underlying_value: float
    option_market_value: float
    premium_cashflow: float
    realized_option_cashflow: float
    net_portfolio_value: float
    loan_amount: float
    ltv_unhedged: float
    ltv_hedged: float
    margin_call_unhedged: bool
    margin_call_hedged: bool
    active_position_ids: tuple[str, ...] = field(default_factory=tuple)
    # Optional OHLC fields for worst-case margin call evaluation
    spot_low: float | None = None  # Day's low for margin call evaluation
    spot_high: float | None = None  # Day's high
    # Option position info
    option_contracts: float = 0.0  # Number of option contracts held


@dataclass(frozen=True)
class BacktestSummaryMetrics:
    start_value: float
    end_value_unhedged: float
    end_value_hedged_net: float
    total_hedge_cost: float
    total_option_payoff_realized: float
    max_ltv_unhedged: float
    max_ltv_hedged: float
    margin_call_days_unhedged: int
    margin_call_days_hedged: int
    margin_threshold_breached_unhedged: bool
    margin_threshold_breached_hedged: bool


@dataclass(frozen=True)
class TemplateBacktestResult:
    template_slug: str
    template_id: str
    template_version: int
    template_name: str
    summary_metrics: BacktestSummaryMetrics
    daily_path: tuple[BacktestDailyPoint, ...]
    warnings: tuple[str, ...] = field(default_factory=tuple)


@dataclass(frozen=True)
class BacktestRunResult:
    scenario_id: str
    template_results: tuple[TemplateBacktestResult, ...]


@dataclass(frozen=True)
class EventComparisonRanking:
    rank: int
    template_slug: str
    template_name: str
    survived_margin_call: bool
    margin_call_days_hedged: int
    max_ltv_hedged: float
    hedge_cost: float
    final_equity: float
    result: TemplateBacktestResult


@dataclass(frozen=True)
class EventComparisonReport:
    event_preset: EventPreset
    scenario: BacktestScenario
    rankings: tuple[EventComparisonRanking, ...]
    run_result: BacktestRunResult


@dataclass(frozen=True)
class BacktestPortfolioPreset:
    """User-facing preset for quick scenario configuration."""

    preset_id: str
    name: str
    description: str
    underlying_symbol: str
    start_date: date
    end_date: date
    entry_spot: float | None = None  # If None, derive from historical data
    underlying_units: float = 1000.0
    loan_amount: float = 50000.0
    margin_call_ltv: float = 0.80
    template_slug: str = "protective-put-atm-12m"
    # Event-specific overrides
    scenario_overrides: dict[str, object] | None = None