Upload alpha_factory/deterministic/regime_tagger.py with huggingface_hub

alpha_factory/deterministic/regime_tagger.py

@@ -0,0 +1,95 @@
+"""
+Regime Tagger — deterministic regime classification for each historical year.
+Tags years with vol/trend/rate/style regimes for the Performance Surgeon.
+"""
+from dataclasses import dataclass
+
+
+@dataclass
+class RegimeProfile:
+    """Regime classification for a single year."""
+    year: int
+    vol_regime: str       # "low" (<15 VIX), "mid" (15-25), "high" (>25)
+    trend_regime: str     # "bull" (SPY 12-1 mom > 0), "bear" (< 0)
+    rate_regime: str      # "steepening", "flattening"
+    style_regime: str     # "value" or "growth" leadership
+
+
+# Historical regime data (2019-2024) — hardcoded from public market data
+# In production, compute from VIX/SPY/10Y/Russell indices
+HISTORICAL_REGIMES = {
+    2019: RegimeProfile(2019, "low", "bull", "flattening", "growth"),
+    2020: RegimeProfile(2020, "high", "bull", "flattening", "growth"),
+    2021: RegimeProfile(2021, "low", "bull", "steepening", "growth"),
+    2022: RegimeProfile(2022, "high", "bear", "steepening", "value"),
+    2023: RegimeProfile(2023, "mid", "bull", "steepening", "growth"),
+    2024: RegimeProfile(2024, "low", "bull", "flattening", "growth"),
+}
+
+
+def get_regime(year: int) -> RegimeProfile:
+    """Get regime profile for a year."""
+    return HISTORICAL_REGIMES.get(year, RegimeProfile(year, "mid", "bull", "flattening", "growth"))
+
+
+def tag_yearly_regimes(yearly_sharpe: list[float], start_year: int = 2019) -> list[dict]:
+    """
+    Tag each year's Sharpe with its regime context.
+    Returns list of {year, sharpe, vol_regime, trend_regime, ...}
+    """
+    tagged = []
+    for i, sharpe in enumerate(yearly_sharpe):
+        year = start_year + i
+        regime = get_regime(year)
+        tagged.append({
+            "year": year,
+            "sharpe": sharpe,
+            "vol_regime": regime.vol_regime,
+            "trend_regime": regime.trend_regime,
+            "rate_regime": regime.rate_regime,
+            "style_regime": regime.style_regime,
+        })
+    return tagged
+
+
+def detect_regime_dependency(yearly_sharpe: list[float], start_year: int = 2019) -> dict:
+    """
+    Detect if alpha performance is regime-dependent.
+    Returns analysis of which regimes it works/fails in.
+    """
+    tagged = tag_yearly_regimes(yearly_sharpe, start_year)
+
+    # Group by regimes
+    vol_performance = {"low": [], "mid": [], "high": []}
+    trend_performance = {"bull": [], "bear": []}
+    style_performance = {"value": [], "growth": []}
+
+    for t in tagged:
+        vol_performance[t["vol_regime"]].append(t["sharpe"])
+        trend_performance[t["trend_regime"]].append(t["sharpe"])
+        style_performance[t["style_regime"]].append(t["sharpe"])
+
+    def avg(lst):
+        return sum(lst) / len(lst) if lst else 0
+
+    analysis = {
+        "vol_sensitivity": {k: round(avg(v), 3) for k, v in vol_performance.items() if v},
+        "trend_sensitivity": {k: round(avg(v), 3) for k, v in trend_performance.items() if v},
+        "style_sensitivity": {k: round(avg(v), 3) for k, v in style_performance.items() if v},
+    }
+
+    # Detect dependency: if performance differs > 1.0 Sharpe between regimes
+    max_vol_diff = max(vol_performance.values(), key=avg, default=[0])
+    min_vol_diff = min(vol_performance.values(), key=avg, default=[0])
+    analysis["regime_dependent"] = (avg(max_vol_diff) - avg(min_vol_diff)) > 1.0
+
+    # Best/worst regime
+    all_regime_sharpes = [(f"{k}_{regime}", avg(v))
+                          for category in [vol_performance, trend_performance, style_performance]
+                          for regime, sharpes in category.items()
+                          for k, v in [(regime, sharpes)] if v]
+    if all_regime_sharpes:
+        analysis["best_regime"] = max(all_regime_sharpes, key=lambda x: x[1])
+        analysis["worst_regime"] = min(all_regime_sharpes, key=lambda x: x[1])
+
+    return analysis