Monitoring Specification¶

def detect_performance_drift(returns, lookback=60, threshold=0.5):
    """
    Compare recent performance to historical baseline.

    Alert if recent Sharpe < threshold × historical Sharpe.
    """
    historical_sharpe = calculate_sharpe(returns[:-lookback])
    recent_sharpe = calculate_sharpe(returns[-lookback:])

    degradation = recent_sharpe / historical_sharpe
    if degradation < threshold:
        return Alert(
            level='warning',
            message=f'Performance degraded to {degradation:.0%} of baseline'
        )

def detect_regime_change(prices, volatility_window=20):
    """
    Detect significant regime shifts using:
    - Volatility regime (low/medium/high)
    - Trend regime (trending/ranging)
    - Correlation regime (correlated/decorrelated)
    """
    current_vol = prices.pct_change().rolling(volatility_window).std().iloc[-1]
    historical_vol = prices.pct_change().std()

    vol_ratio = current_vol / historical_vol

    if vol_ratio > 2.0:
        return Regime.HIGH_VOL
    elif vol_ratio < 0.5:
        return Regime.LOW_VOL
    else:
        return Regime.NORMAL

def detect_win_rate_decay(trades, baseline_win_rate, window=50):
    """
    Alert if rolling win rate drops significantly below baseline.
    """
    recent_wins = trades[-window:]['is_win'].mean()

    if recent_wins < baseline_win_rate * 0.7:  # 30% degradation
        return Alert(
            level='critical',
            message=f'Win rate dropped to {recent_wins:.0%} vs {baseline_win_rate:.0%} baseline'
        )

def detect_distribution_shift(returns, reference_returns, threshold=0.5):
    """
    Compare return distribution to reference period.
    High KL divergence indicates regime change.
    """
    from scipy.stats import entropy

    # Bin returns into histogram
    bins = np.linspace(-0.05, 0.05, 50)
    p = np.histogram(returns, bins=bins, density=True)[0] + 1e-10
    q = np.histogram(reference_returns, bins=bins, density=True)[0] + 1e-10

    kl_div = entropy(p, q)

    if kl_div > threshold:
        return Alert(
            level='warning',
            message=f'Return distribution shifted (KL={kl_div:.2f})'
        )