quantwise 1.2.0 → 1.2.2

package/.claude/skills/macro-regime-detector/references/indicator_interpretation_guide.md

@@ -0,0 +1,144 @@
+# Indicator Interpretation Guide
+
+Quick reference for interpreting each component's output values and signals.
+
+## Component 1: Market Concentration (RSP/SPY)
+
+**What it measures**: Relative performance of equal-weight S&P 500 vs cap-weight S&P 500.
+
+| RSP/SPY Trend | Interpretation | Regime Signal |
+|---------------|---------------|---------------|
+| Declining | Mega-caps outperforming, market narrowing | Concentration |
+| Rising | Broader participation, equal-weight catching up | Broadening |
+| Bottoming + turning | Potential regime shift from concentration to broadening | Transition |
+
+**Key levels** (approximate, varies over time):
+- 0.28-0.29: Extreme concentration (2024 lows)
+- 0.30-0.32: Moderate concentration
+- 0.33+: Broadening phase
+
+**Crossover interpretation**:
+- Golden cross (6M > 12M): Broadening gaining momentum
+- Death cross (6M < 12M): Concentration deepening
+
+## Component 2: Yield Curve (10Y-2Y Spread)
+
+**What it measures**: Shape of the Treasury yield curve, reflecting rate cycle position.
+
+| Spread Level | Curve State | Typical Environment |
+|-------------|-------------|-------------------|
+| < -0.5% | Deeply inverted | Pre-recession, aggressive tightening |
+| -0.5% to 0% | Inverted | Late-cycle, recession risk elevated |
+| 0% to 0.5% | Flat/Normalizing | Transition period |
+| 0.5% to 1.5% | Normal | Mid-cycle expansion |
+| > 1.5% | Steep | Early recovery, accommodative policy |
+
+**Direction signals**:
+- Steepening: Either rates normalizing (bull steepener) or long end rising (bear steepener)
+- Flattening: Late-cycle tightening or flight to long bonds
+
+**Fallback (SHY/TLT proxy)**: When Treasury API is unavailable, SHY/TLT ratio provides a rough proxy. Rising SHY/TLT ≈ flattening curve. Less precise than actual spread data.
+
+## Component 3: Credit Conditions (HYG/LQD)
+
+**What it measures**: Risk appetite in credit markets — willingness to hold junk bonds vs investment grade.
+
+| HYG/LQD Trend | Interpretation | Regime Signal |
+|---------------|---------------|---------------|
+| Rising | Credit risk appetite expanding | Risk-on, easing |
+| Falling | Flight to quality | Risk-off, tightening |
+| Stable | Established credit regime | No transition |
+
+**Why it matters**: Credit markets often lead equity markets. HYG/LQD deterioration preceded the 2020 crash by ~2 weeks and the 2008 crisis by ~3 months.
+
+**Warning levels**:
+- Sharp drop (ROC < -3% over 3 months): Potential credit event
+- Persistent decline with negative ROC: Late-cycle deterioration
+- Stable with positive ROC: Supportive environment for risk assets
+
+## Component 4: Size Factor (IWM/SPY)
+
+**What it measures**: Relative performance of small-caps (Russell 2000) vs large-caps (S&P 500).
+
+| IWM/SPY Trend | Interpretation | Regime Signal |
+|---------------|---------------|---------------|
+| Rising | Small-caps outperforming — economic optimism | Broadening |
+| Falling | Large-cap preference — defensive/quality bias | Concentration |
+| Diverging from RSP/SPY | Inconsistent signal — check credit conditions | Uncertain |
+
+**Cycle position**:
+- Small-cap outperformance often starts 3-6 months before economic recovery becomes consensus
+- Small-cap underperformance accelerates in late-cycle as credit conditions tighten
+- IWM/SPY and RSP/SPY usually move together; divergence warrants investigation
+
+## Component 5: Equity-Bond Relationship (SPY/TLT + Correlation)
+
+**What it measures**: Two aspects of the stock-bond relationship.
+
+### SPY/TLT Ratio
+
+| SPY/TLT Trend | Interpretation |
+|---------------|---------------|
+| Rising | Equities outperforming bonds (risk-on) |
+| Falling | Bonds outperforming equities (risk-off) |
+
+### Stock-Bond Correlation (6-month rolling)
+
+| Correlation | Regime | Implication |
+|-------------|--------|-------------|
+| < -0.3 | Negative (normal) | Bonds effectively hedge equity risk |
+| -0.3 to 0 | Mildly negative | Hedging works but weakened |
+| 0 to 0.3 | Near zero | Transitional — hedging unreliable |
+| > 0.3 | Positive (inflationary) | Both move together — diversification fails |
+
+**Critical signal**: Correlation sign change (negative → positive or vice versa) is one of the most important regime signals. Positive correlation typically occurs during:
+- Inflation shocks (2022)
+- Stagflation concerns
+- Central bank credibility crises
+
+**Correlation bonus scoring**: When 6M and 12M correlation have opposite signs, an additional 20 points are added to the component score, reflecting the significance of this regime shift.
+
+## Component 6: Sector Rotation (XLY/XLP)
+
+**What it measures**: Consumer sentiment through discretionary vs staples spending preference.
+
+| XLY/XLP Trend | Interpretation | Regime Signal |
+|---------------|---------------|---------------|
+| Rising | Consumer confidence, risk appetite | Risk-on, broadening |
+| Falling | Defensive positioning, consumer caution | Risk-off, contraction |
+| Stable | Established consumer sentiment | No transition |
+
+**Why Consumer Discretionary vs Staples**:
+- Most direct consumer-facing comparison
+- Staples demand is relatively inelastic; discretionary is highly cyclical
+- XLY includes Amazon, Tesla — captures both consumer and growth sentiment
+- XLP is pure defensive (Procter & Gamble, Coca-Cola, Costco)
+
+## Cross-Component Analysis
+
+### Confirmation Patterns
+
+**Strong Broadening Confirmation** (4+ components aligned):
+- RSP/SPY ↑ + IWM/SPY ↑ + HYG/LQD stable/↑ + XLY/XLP ↑
+
+**Strong Contraction Confirmation**:
+- HYG/LQD ↓ + XLY/XLP ↓ + SPY/TLT ↓ + Yield curve steepening
+
+**Inflationary Confirmation**:
+- Stock-bond correlation positive + SPY/TLT ↓ + Yield curve behavior unusual
+
+### Divergence Signals
+
+- **RSP/SPY ↑ but HYG/LQD ↓**: Broadening without credit support — fragile
+- **IWM/SPY ↑ but XLY/XLP ↓**: Small-cap rally without consumer backing — suspicious
+- **Yield curve steepening but HYG/LQD ↓**: Rate cuts due to crisis, not growth
+
+## Score Interpretation Quick Reference
+
+| Composite Score | Zone | Action |
+|----------------|------|--------|
+| 0-20 | Stable | Maintain current positioning |
+| 21-40 | Early Signal | Increase monitoring frequency |
+| 41-60 | Transition Zone | Begin planning adjustments |
+| 61-80 | Active Transition | Execute repositioning |
+| 81-100 | Confirmed | Complete repositioning |

package/.claude/skills/macro-regime-detector/references/regime_detection_methodology.md

@@ -0,0 +1,138 @@
+# Regime Detection Methodology
+
+## Overview
+
+The Macro Regime Detector uses a 3-layer signal detection approach applied to 6 cross-asset ratios, analyzed at monthly frequency with 6-month and 12-month Simple Moving Averages.
+
+## Data Pipeline
+
+```
+Daily OHLCV (600 days, ~2.4 years)
+  → Monthly Downsampling (last business day per month, ~24 points)
+  → Ratio Calculation (e.g., RSP close / SPY close)
+  → Moving Average Computation (6M SMA, 12M SMA)
+  → Signal Detection (3 layers)
+  → Component Scoring (0-100 per component)
+  → Weighted Composite (6 components)
+  → Regime Classification (decision tree)
+  → Transition Probability Assessment
+```
+
+## Monthly Downsampling
+
+Daily data is downsampled to monthly frequency by selecting the most recent trading day in each calendar month. This filters out daily noise and focuses on structural trends.
+
+Why monthly: Regime transitions are structural (1-2 year) phenomena. Daily or weekly data introduces noise without adding signal for this time horizon.
+
+## 3-Layer Signal Detection
+
+### Layer 1: MA Crossover (0-40 points)
+
+The primary signal is the relationship between the 6-month and 12-month SMA of each ratio.
+
+- **Golden Cross**: 6M SMA crosses above 12M SMA (recent = 40pts, older = 20pts)
+- **Death Cross**: 6M SMA crosses below 12M SMA (recent = 40pts, older = 20pts)
+- **Converging**: SMAs within 1% gap, no crossover yet (0-25pts based on proximity)
+- **None**: SMAs well separated, established trend (0pts)
+
+Recency matters: A crossover 1-2 months ago is much more actionable than one 6+ months ago.
+
+### Layer 2: Momentum Shift (0-30 points)
+
+Compares 3-month Rate of Change (ROC) against 12-month ROC to detect early reversals.
+
+- **Reversal Signal**: 12M ROC negative but 3M ROC positive (or vice versa). This means the long-term trend is one direction but short-term momentum has reversed — an early warning of transition.
+- **Acceleration**: Strong 3M ROC in the same direction as 12M ROC confirms an existing move.
+
+Scoring scales linearly with the magnitude of the short-term ROC (capped at 5%).
+
+### Layer 3: Cross-Confirmation (0-30 points)
+
+Checks alignment of multiple signals for confirmation:
+
+1. Crossover is present (+10)
+2. Short-term ROC confirms the crossover direction (+10)
+3. SMA gap is widening (momentum building) (+10)
+
+When all three align, the transition signal is strong (80-100 range).
+
+## Component Scoring Scale
+
+Each component produces a score from 0 to 100, representing **transition signal strength** (not "good" or "bad"):
+
+| Range | Interpretation |
+|-------|---------------|
+| 0-20 | Stable regime, no transition signal |
+| 20-40 | Minor fluctuation, possibly noise |
+| 40-60 | Transition zone — MAs converging, potential crossover in 3-6 months |
+| 60-80 | Clear transition signal — recent crossover or sharp momentum reversal |
+| 80-100 | Strong confirmed transition — crossover + momentum + acceleration aligned |
+
+## Composite Score
+
+The 6 component scores are combined using fixed weights:
+
+| Component | Weight | Rationale |
+|-----------|--------|-----------|
+| Market Concentration (RSP/SPY) | 25% | Primary indicator of market structure |
+| Yield Curve (10Y-2Y) | 20% | Most reliable macro cycle indicator |
+| Credit Conditions (HYG/LQD) | 15% | Leading indicator of financial stress |
+| Size Factor (IWM/SPY) | 15% | Economic sentiment barometer |
+| Equity-Bond (SPY/TLT) | 15% | Cross-asset risk regime |
+| Sector Rotation (XLY/XLP) | 10% | Consumer sentiment proxy |
+
+## Regime Classification
+
+A decision-tree approach scores each of 5 possible regimes based on component directions:
+
+### Scoring Rules
+
+**Concentration** (+2 each):
+- RSP/SPY direction = "concentrating"
+- IWM/SPY direction = "large_cap_leading"
+- Credit direction = stable/easing (+1)
+
+**Broadening** (+2 each):
+- RSP/SPY direction = "broadening"
+- IWM/SPY direction = "small_cap_leading"
+- Credit direction = stable/easing (+1)
+- XLY/XLP direction = risk_on (+1)
+
+**Contraction** (+2 each):
+- Credit direction = "tightening"
+- XLY/XLP direction = "risk_off"
+- SPY/TLT direction = "risk_off" (+1)
+
+**Inflationary** (+3):
+- Stock-bond correlation = "positive"
+- SPY/TLT direction = "risk_off" (+1)
+
+**Transitional**: Assigned when 3+ components are signaling (score >= 40) but no regime scores >= 3.
+
+### Confidence Levels
+
+- **High**: Best regime score >= 4
+- **Moderate**: Best regime score >= 3
+- **Low**: Best regime score >= 2
+- **Very Low**: Best regime score < 2
+
+## Transition Probability
+
+Combines signaling count and average component scores:
+
+| Signaling Count | Avg Score | Probability |
+|----------------|-----------|-------------|
+| 4+ | >= 50 | High (70-90%) |
+| 3+ | >= 40 | Moderate (40-60%) |
+| 2+ | >= 30 | Low (20-40%) |
+| < 2 | < 30 | Minimal (<20%) |
+
+## Limitations
+
+1. **Lagging by design**: Monthly frequency means signals appear weeks to months after daily-frequency indicators. This is intentional — the goal is structural confirmation, not early detection.
+
+2. **False positives**: Converging MAs can generate transition signals that reverse before completing. Always check cross-component confirmation.
+
+3. **Regime overlap**: Real markets often exhibit characteristics of multiple regimes simultaneously. The "Transitional" classification explicitly acknowledges this.
+
+4. **Historical bias**: Regime classification rules are derived from post-2000 market patterns. Novel regimes may not fit existing categories.

package/.claude/skills/macro-regime-detector/scripts/calculators/__init__.py

@@ -0,0 +1 @@
+"""Macro Regime Detector - Calculator modules"""

package/.claude/skills/macro-regime-detector/scripts/calculators/concentration_calculator.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Component 1: Market Concentration (Weight: 25%)
+
+Analyzes RSP/SPY ratio to detect mega-cap concentration vs market broadening.
+
+RSP (equal-weight S&P 500) / SPY (cap-weight S&P 500):
+- Declining ratio = increasing concentration in mega-caps
+- Rising ratio = market broadening, more stocks participating
+
+Scoring (0-100 = Transition Signal Strength):
+  0-20:  Stable regime, no transition signal
+  20-40: Minor fluctuation, possibly noise
+  40-60: Transition zone (MAs converging, crossover possible in 3-6 months)
+  60-80: Clear transition signal (recent crossover or sharp momentum reversal)
+  80-100: Strong confirmed transition (crossover + momentum + acceleration aligned)
+"""
+
+from typing import Dict, List, Optional
+from .utils import (
+    downsample_to_monthly,
+    calculate_ratio,
+    compute_sma,
+    detect_crossover,
+    compute_roc,
+    compute_percentile,
+    score_transition_signal,
+    STALE_CROSSOVER_MONTHS,
+)
+
+
+def calculate_concentration(rsp_history: List[Dict],
+                            spy_history: List[Dict]) -> Dict:
+    """
+    Calculate market concentration transition signal from RSP/SPY ratio.
+
+    Args:
+        rsp_history: RSP daily OHLCV (most recent first)
+        spy_history: SPY daily OHLCV (most recent first)
+
+    Returns:
+        Dict with score (0-100), signal, ratio details, MA values, momentum
+    """
+    if not rsp_history or not spy_history:
+        return _insufficient_data("No RSP or SPY data available")
+
+    # Downsample to monthly
+    rsp_monthly = downsample_to_monthly(rsp_history)
+    spy_monthly = downsample_to_monthly(spy_history)
+
+    if len(rsp_monthly) < 12 or len(spy_monthly) < 12:
+        return _insufficient_data("Insufficient monthly data (need >= 12 months)")
+
+    # Calculate RSP/SPY ratio (monthly)
+    ratio_series = calculate_ratio(rsp_monthly, spy_monthly)
+    if len(ratio_series) < 12:
+        return _insufficient_data("Insufficient ratio data")
+
+    # Current ratio
+    current_ratio = ratio_series[0]["value"]
+    current_date = ratio_series[0]["date"]
+
+    # Compute 6M and 12M SMAs on ratio
+    ratio_values = [r["value"] for r in ratio_series]
+    sma_6m = compute_sma(ratio_values, 6)
+    sma_12m = compute_sma(ratio_values, 12)
+
+    # Crossover detection (6M vs 12M)
+    crossover = detect_crossover(ratio_values, short_period=6, long_period=12)
+
+    # Momentum: 3-month and 12-month ROC
+    roc_3m = compute_roc(ratio_values, 3)
+    roc_12m = compute_roc(ratio_values, 12)
+
+    # Percentile of current ratio within historical range
+    percentile = compute_percentile(ratio_values, current_ratio)
+
+    # Score the transition signal
+    score = score_transition_signal(
+        crossover=crossover,
+        roc_short=roc_3m,
+        roc_long=roc_12m,
+        sma_short=sma_6m,
+        sma_long=sma_12m,
+    )
+
+    # Determine signal description
+    signal = _describe_signal(score, crossover, roc_3m, roc_12m, current_ratio)
+
+    # Determine direction (concentration-specific: SMA fallback preserved)
+    bars_ago = crossover.get("bars_ago")
+    is_stale = bars_ago is not None and bars_ago >= STALE_CROSSOVER_MONTHS
+
+    if crossover["type"] == "golden_cross":
+        direction = "broadening"
+    elif crossover["type"] == "death_cross":
+        direction = "concentrating"
+    elif sma_6m is not None and sma_12m is not None:
+        direction = "broadening" if sma_6m > sma_12m else "concentrating"
+    else:
+        direction = "unknown"
+
+    # Stale crossover override: if momentum contradicts, flip direction
+    momentum_qualifier = "N/A"
+    if crossover["type"] in ("golden_cross", "death_cross"):
+        cross_dir = "broadening" if crossover["type"] == "golden_cross" else "concentrating"
+        mom_dir = ("broadening" if roc_3m is not None and roc_3m > 0
+                   else "concentrating" if roc_3m is not None and roc_3m < 0
+                   else None)
+        if is_stale and mom_dir and mom_dir != cross_dir:
+            direction = mom_dir
+            momentum_qualifier = "reversing"
+        elif mom_dir == cross_dir:
+            momentum_qualifier = "confirmed"
+        elif mom_dir and mom_dir != cross_dir:
+            momentum_qualifier = "fading"
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "direction": direction,
+        "momentum_qualifier": momentum_qualifier,
+        "current_ratio": round(current_ratio, 4),
+        "current_date": current_date,
+        "sma_6m": round(sma_6m, 4) if sma_6m is not None else None,
+        "sma_12m": round(sma_12m, 4) if sma_12m is not None else None,
+        "roc_3m": round(roc_3m, 2) if roc_3m is not None else None,
+        "roc_12m": round(roc_12m, 2) if roc_12m is not None else None,
+        "percentile": round(percentile, 1) if percentile is not None else None,
+        "crossover": crossover,
+        "monthly_points": len(ratio_series),
+    }
+
+
+def _describe_signal(score: int, crossover: Dict, roc_3m: Optional[float],
+                     roc_12m: Optional[float], ratio: float) -> str:
+    if score >= 80:
+        return f"STRONG TRANSITION: RSP/SPY {crossover['type'].replace('_', ' ')} confirmed with aligned momentum"
+    elif score >= 60:
+        return f"TRANSITION SIGNAL: RSP/SPY crossover or sharp momentum reversal detected"
+    elif score >= 40:
+        return f"TRANSITION ZONE: RSP/SPY MAs converging, potential crossover ahead"
+    elif score >= 20:
+        return f"MINOR SHIFT: RSP/SPY ratio showing slight change ({ratio:.4f})"
+    else:
+        return f"STABLE: RSP/SPY ratio in established trend ({ratio:.4f})"
+
+
+def _insufficient_data(reason: str) -> Dict:
+    return {
+        "score": 0,
+        "signal": f"INSUFFICIENT DATA: {reason}",
+        "data_available": False,
+        "direction": "unknown",
+        "current_ratio": None,
+        "current_date": None,
+        "sma_6m": None,
+        "sma_12m": None,
+        "roc_3m": None,
+        "roc_12m": None,
+        "percentile": None,
+        "crossover": {"type": "none", "bars_ago": None},
+        "monthly_points": 0,
+    }

package/.claude/skills/macro-regime-detector/scripts/calculators/credit_conditions_calculator.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Component 3: Credit Conditions (Weight: 15%)
+
+Analyzes HYG/LQD ratio to detect credit cycle transitions.
+
+HYG (high-yield corporate bonds) / LQD (investment-grade corporate bonds):
+- Rising ratio = credit risk appetite expanding, risk-on
+- Falling ratio = flight to quality, credit tightening, risk-off
+
+Transition signals:
+- HYG/LQD turning up from bottom = credit cycle easing
+- HYG/LQD turning down from top = credit cycle tightening
+"""
+
+from typing import Dict, List, Optional
+from .utils import (
+    downsample_to_monthly,
+    calculate_ratio,
+    compute_sma,
+    detect_crossover,
+    compute_roc,
+    compute_percentile,
+    score_transition_signal,
+    determine_direction,
+)
+
+
+def calculate_credit_conditions(hyg_history: List[Dict],
+                                lqd_history: List[Dict]) -> Dict:
+    """
+    Calculate credit conditions transition signal from HYG/LQD ratio.
+
+    Args:
+        hyg_history: HYG daily OHLCV (most recent first)
+        lqd_history: LQD daily OHLCV (most recent first)
+
+    Returns:
+        Dict with score (0-100), signal, ratio details
+    """
+    if not hyg_history or not lqd_history:
+        return _insufficient_data("No HYG or LQD data available")
+
+    hyg_monthly = downsample_to_monthly(hyg_history)
+    lqd_monthly = downsample_to_monthly(lqd_history)
+
+    if len(hyg_monthly) < 12 or len(lqd_monthly) < 12:
+        return _insufficient_data("Insufficient monthly data (need >= 12 months)")
+
+    ratio_series = calculate_ratio(hyg_monthly, lqd_monthly)
+    if len(ratio_series) < 12:
+        return _insufficient_data("Insufficient ratio data")
+
+    ratio_values = [r["value"] for r in ratio_series]
+    current_ratio = ratio_values[0]
+    current_date = ratio_series[0]["date"]
+
+    sma_6m = compute_sma(ratio_values, 6)
+    sma_12m = compute_sma(ratio_values, 12)
+    crossover = detect_crossover(ratio_values, short_period=6, long_period=12)
+    roc_3m = compute_roc(ratio_values, 3)
+    roc_12m = compute_roc(ratio_values, 12)
+    percentile = compute_percentile(ratio_values, current_ratio)
+
+    score = score_transition_signal(
+        crossover=crossover,
+        roc_short=roc_3m,
+        roc_long=roc_12m,
+        sma_short=sma_6m,
+        sma_long=sma_12m,
+    )
+
+    # Direction
+    direction, momentum_qualifier = determine_direction(
+        crossover, roc_3m,
+        positive_label="easing", negative_label="tightening",
+        neutral_label="stable",
+    )
+
+    signal = _describe_signal(score, direction, current_ratio)
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "direction": direction,
+        "momentum_qualifier": momentum_qualifier,
+        "current_ratio": round(current_ratio, 4),
+        "current_date": current_date,
+        "sma_6m": round(sma_6m, 4) if sma_6m is not None else None,
+        "sma_12m": round(sma_12m, 4) if sma_12m is not None else None,
+        "roc_3m": round(roc_3m, 2) if roc_3m is not None else None,
+        "roc_12m": round(roc_12m, 2) if roc_12m is not None else None,
+        "percentile": round(percentile, 1) if percentile is not None else None,
+        "crossover": crossover,
+        "monthly_points": len(ratio_series),
+    }
+
+
+def _describe_signal(score: int, direction: str, ratio: float) -> str:
+    if score >= 60:
+        return f"TRANSITION: Credit conditions {direction} (HYG/LQD={ratio:.4f})"
+    elif score >= 40:
+        return f"SHIFTING: Credit conditions {direction} (HYG/LQD={ratio:.4f})"
+    else:
+        return f"STABLE: Credit conditions stable (HYG/LQD={ratio:.4f})"
+
+
+def _insufficient_data(reason: str) -> Dict:
+    return {
+        "score": 0,
+        "signal": f"INSUFFICIENT DATA: {reason}",
+        "data_available": False,
+        "direction": "unknown",
+        "current_ratio": None,
+        "current_date": None,
+        "sma_6m": None,
+        "sma_12m": None,
+        "roc_3m": None,
+        "roc_12m": None,
+        "percentile": None,
+        "crossover": {"type": "none", "bars_ago": None},
+        "monthly_points": 0,
+    }