quantwise 1.2.0 → 1.2.2

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

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Shared utility functions for macro regime calculators.
+
+Provides monthly downsampling, ratio calculation, moving averages,
+crossover detection, momentum computation, and transition scoring.
+"""
+
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+
+
+def downsample_to_monthly(daily_history: List[Dict]) -> List[Dict]:
+    """
+    Downsample daily OHLCV to monthly (last business day of each month).
+
+    Args:
+        daily_history: Daily bars, most recent first.
+
+    Returns:
+        List of monthly bars (most recent first), each with 'date', 'close'.
+    """
+    if not daily_history:
+        return []
+
+    # Group by year-month, pick the most recent bar per month
+    monthly = {}
+    for bar in daily_history:
+        date_str = bar.get("date", "")
+        close = bar.get("adjClose", bar.get("close", 0))
+        if not date_str or close == 0:
+            continue
+
+        # Extract year-month key
+        ym = date_str[:7]  # "YYYY-MM"
+        if ym not in monthly:
+            monthly[ym] = {"date": date_str, "close": close}
+        else:
+            # daily_history is most recent first, so first occurrence is the latest in that month
+            # Keep the first (most recent) bar for each month
+            pass
+
+    # Sort by date descending (most recent first)
+    result = sorted(monthly.values(), key=lambda x: x["date"], reverse=True)
+    return result
+
+
+def calculate_ratio(numerator_monthly: List[Dict],
+                    denominator_monthly: List[Dict]) -> List[Dict]:
+    """
+    Calculate ratio of two monthly series aligned by date.
+
+    Args:
+        numerator_monthly: Monthly bars for numerator (most recent first)
+        denominator_monthly: Monthly bars for denominator (most recent first)
+
+    Returns:
+        List of {'date': str, 'value': float} (most recent first)
+    """
+    # Build lookup by year-month
+    denom_lookup = {}
+    for bar in denominator_monthly:
+        ym = bar["date"][:7]
+        denom_lookup[ym] = bar["close"]
+
+    result = []
+    for bar in numerator_monthly:
+        ym = bar["date"][:7]
+        if ym in denom_lookup and denom_lookup[ym] != 0:
+            ratio = bar["close"] / denom_lookup[ym]
+            result.append({"date": bar["date"], "value": ratio})
+
+    return result
+
+
+def compute_sma(values: List[float], period: int) -> Optional[float]:
+    """
+    Compute Simple Moving Average from a list of values (most recent first).
+
+    Returns SMA of the most recent `period` values, or None if insufficient data.
+    """
+    if len(values) < period:
+        return None
+    return sum(values[:period]) / period
+
+
+def detect_crossover(values: List[float], short_period: int = 6,
+                     long_period: int = 12) -> Dict:
+    """
+    Detect SMA crossover between short and long periods.
+
+    Args:
+        values: Series of values (most recent first)
+        short_period: Short-term SMA period (default 6)
+        long_period: Long-term SMA period (default 12)
+
+    Returns:
+        Dict with 'type' ('golden_cross', 'death_cross', 'converging', 'none'),
+        'bars_ago' (how many months ago the crossover occurred),
+        'gap_pct' (current gap between short and long SMA as %)
+    """
+    if len(values) < long_period + 3:
+        return {"type": "none", "bars_ago": None, "gap_pct": None}
+
+    # Compute SMAs at each point
+    max_lookback = min(len(values), long_period + 12)  # Check up to 12 months back
+    sma_pairs = []
+    for offset in range(max_lookback - long_period + 1):
+        subset = values[offset:]
+        short_sma = compute_sma(subset, short_period)
+        long_sma = compute_sma(subset, long_period)
+        if short_sma is not None and long_sma is not None:
+            sma_pairs.append((short_sma, long_sma))
+
+    if len(sma_pairs) < 2:
+        return {"type": "none", "bars_ago": None, "gap_pct": None}
+
+    # Current gap
+    current_short, current_long = sma_pairs[0]
+    if current_long != 0:
+        gap_pct = (current_short - current_long) / current_long * 100
+    else:
+        gap_pct = 0
+
+    # Look for crossover
+    for i in range(1, len(sma_pairs)):
+        prev_short, prev_long = sma_pairs[i]
+        curr_short, curr_long = sma_pairs[i - 1]
+
+        # Golden cross: short crosses above long
+        if prev_short <= prev_long and curr_short > curr_long:
+            return {
+                "type": "golden_cross",
+                "bars_ago": i - 1,
+                "gap_pct": round(gap_pct, 3),
+            }
+        # Death cross: short crosses below long
+        if prev_short >= prev_long and curr_short < curr_long:
+            return {
+                "type": "death_cross",
+                "bars_ago": i - 1,
+                "gap_pct": round(gap_pct, 3),
+            }
+
+    # No crossover found, check if converging
+    if abs(gap_pct) < 1.0:
+        return {
+            "type": "converging",
+            "bars_ago": None,
+            "gap_pct": round(gap_pct, 3),
+        }
+
+    return {
+        "type": "none",
+        "bars_ago": None,
+        "gap_pct": round(gap_pct, 3),
+    }
+
+
+def compute_roc(values: List[float], period: int) -> Optional[float]:
+    """
+    Compute Rate of Change (%) over `period` data points.
+
+    Args:
+        values: Series (most recent first)
+        period: Number of periods back to compare
+
+    Returns:
+        ROC as percentage, or None if insufficient data
+    """
+    if len(values) <= period:
+        return None
+    current = values[0]
+    past = values[period]
+    if past == 0:
+        return None
+    return (current - past) / past * 100
+
+
+def compute_percentile(values: List[float], current: float) -> Optional[float]:
+    """
+    Compute percentile rank of current value within the series.
+
+    Returns percentile (0-100), or None if insufficient data.
+    """
+    if not values:
+        return None
+    below = sum(1 for v in values if v < current)
+    return below / len(values) * 100
+
+
+def compute_rolling_correlation(series_a: List[float], series_b: List[float],
+                                window: int) -> Optional[float]:
+    """
+    Compute rolling Pearson correlation between two series over a window.
+
+    Args:
+        series_a: First series (most recent first)
+        series_b: Second series (most recent first)
+        window: Number of data points for correlation window
+
+    Returns:
+        Correlation coefficient (-1 to 1), or None if insufficient data
+    """
+    if len(series_a) < window or len(series_b) < window:
+        return None
+
+    a = series_a[:window]
+    b = series_b[:window]
+
+    n = window
+    mean_a = sum(a) / n
+    mean_b = sum(b) / n
+
+    cov = sum((a[i] - mean_a) * (b[i] - mean_b) for i in range(n)) / n
+    std_a = (sum((x - mean_a) ** 2 for x in a) / n) ** 0.5
+    std_b = (sum((x - mean_b) ** 2 for x in b) / n) ** 0.5
+
+    if std_a == 0 or std_b == 0:
+        return 0.0
+
+    return cov / (std_a * std_b)
+
+
+STALE_CROSSOVER_MONTHS = 3
+
+
+def determine_direction(crossover: Dict, roc_3m: Optional[float],
+                        positive_label: str, negative_label: str,
+                        neutral_label: str = "neutral") -> Tuple[str, str]:
+    """
+    Determine direction from crossover and momentum, accounting for stale crossovers.
+
+    When a crossover is old (>= STALE_CROSSOVER_MONTHS) and momentum contradicts it,
+    momentum takes priority ("reversing"). Recent crossovers always win.
+
+    Args:
+        crossover: Dict with 'type' and 'bars_ago'
+        roc_3m: 3-month rate of change (%)
+        positive_label: Label for positive direction (e.g., "risk_on")
+        negative_label: Label for negative direction (e.g., "risk_off")
+        neutral_label: Label when no signal (default "neutral")
+
+    Returns:
+        Tuple of (direction, momentum_qualifier)
+        momentum_qualifier: "confirmed" | "fading" | "reversing" | "N/A"
+    """
+    cross_type = crossover.get("type", "none")
+    bars_ago = crossover.get("bars_ago")
+    is_stale = bars_ago is not None and bars_ago >= STALE_CROSSOVER_MONTHS
+
+    # Crossover direction
+    cross_dir = (positive_label if cross_type == "golden_cross"
+                 else negative_label if cross_type == "death_cross"
+                 else None)
+
+    # Momentum direction
+    mom_dir = (positive_label if roc_3m is not None and roc_3m > 0
+               else negative_label if roc_3m is not None and roc_3m < 0
+               else None)
+
+    if cross_dir:
+        if is_stale and mom_dir and mom_dir != cross_dir:
+            return mom_dir, "reversing"
+        qualifier = ("confirmed" if mom_dir == cross_dir
+                     else "fading" if mom_dir and mom_dir != cross_dir
+                     else "N/A")
+        return cross_dir, qualifier
+    elif mom_dir:
+        return mom_dir, "N/A"
+    else:
+        return neutral_label, "N/A"
+
+
+def score_transition_signal(crossover: Dict,
+                            roc_short: Optional[float],
+                            roc_long: Optional[float],
+                            sma_short: Optional[float],
+                            sma_long: Optional[float]) -> int:
+    """
+    Score transition signal strength (0-100) from crossover, momentum, and MA data.
+
+    Scoring layers:
+    1. MA Crossover (0-40 base): Recent crossover = high, converging = moderate
+    2. Momentum Shift (0-30): Short ROC reversal against long trend = early warning
+    3. Confirmation (0-30): Multiple signals aligning = strong confirmation
+
+    Returns:
+        int score 0-100
+    """
+    score = 0
+
+    # Layer 1: Crossover detection (0-40)
+    cross_type = crossover.get("type", "none")
+    bars_ago = crossover.get("bars_ago")
+    gap_pct = crossover.get("gap_pct", 0) or 0
+
+    if cross_type in ("golden_cross", "death_cross"):
+        if bars_ago is not None and bars_ago <= 2:
+            score += 40  # Very recent crossover
+        elif bars_ago is not None and bars_ago <= 5:
+            score += 30  # Recent crossover
+        else:
+            score += 20  # Older crossover
+    elif cross_type == "converging":
+        # MAs getting close, crossover possible
+        closeness = max(0, 1.0 - abs(gap_pct)) * 25
+        score += int(closeness)
+    # "none" = stable, no points
+
+    # Layer 2: Momentum shift (0-30)
+    if roc_short is not None and roc_long is not None:
+        # Reversal: short-term momentum opposite to long-term trend
+        if roc_long < 0 and roc_short > 0:
+            # Declining long-term but short-term bouncing = early reversal
+            strength = min(abs(roc_short), 5.0) / 5.0 * 30
+            score += int(strength)
+        elif roc_long > 0 and roc_short < 0:
+            # Rising long-term but short-term declining = early reversal
+            strength = min(abs(roc_short), 5.0) / 5.0 * 30
+            score += int(strength)
+        elif abs(roc_short) > 3.0:
+            # Strong short-term momentum in same direction = acceleration
+            score += 10
+
+    # Layer 3: Confirmation / alignment (0-30)
+    signals_aligned = 0
+
+    # Signal 1: Crossover present
+    if cross_type in ("golden_cross", "death_cross"):
+        signals_aligned += 1
+
+    # Signal 2: Short ROC confirms direction
+    if cross_type == "golden_cross" and roc_short is not None and roc_short > 0:
+        signals_aligned += 1
+    elif cross_type == "death_cross" and roc_short is not None and roc_short < 0:
+        signals_aligned += 1
+
+    # Signal 3: SMA gap widening (momentum)
+    if sma_short is not None and sma_long is not None and sma_long != 0:
+        current_gap = abs(sma_short - sma_long) / sma_long * 100
+        if current_gap > 0.5:
+            signals_aligned += 1
+
+    score += signals_aligned * 10
+
+    return min(100, max(0, score))

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

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""
+Component 2: Yield Curve (Weight: 20%)
+
+Analyzes 10Y-2Y Treasury spread to detect interest rate cycle transitions.
+
+Primary data: Treasury API (10Y-2Y spread directly)
+Fallback: SHY/TLT ratio as proxy for yield curve shape
+
+Transition signals:
+- Inversion → Normalization: Often precedes recession end, risk-on shift
+- Steepening from flat: Economic recovery signal
+- Flattening from steep: Late-cycle tightening signal
+- Deep inversion: Recession warning
+
+Scoring (0-100 = Transition Signal Strength):
+  0-20:  Stable yield curve regime
+  20-40: Minor changes in spread
+  40-60: Transition zone (curve shape changing)
+  60-80: Clear transition (inversion/normalization crossover)
+  80-100: Strong confirmed transition
+"""
+
+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,
+)
+
+
+def calculate_yield_curve(treasury_rates: Optional[List[Dict]] = None,
+                          shy_history: Optional[List[Dict]] = None,
+                          tlt_history: Optional[List[Dict]] = None) -> Dict:
+    """
+    Calculate yield curve transition signal.
+
+    Args:
+        treasury_rates: Treasury rate data from FMP stable API (most recent first)
+        shy_history: SHY daily OHLCV (fallback, most recent first)
+        tlt_history: TLT daily OHLCV (fallback, most recent first)
+
+    Returns:
+        Dict with score, signal, spread details, curve state
+    """
+    # Try Treasury API first
+    if treasury_rates:
+        result = _analyze_treasury_spread(treasury_rates)
+        if result is not None:
+            return result
+
+    # Fallback to SHY/TLT ratio
+    if shy_history and tlt_history:
+        return _analyze_shy_tlt_proxy(shy_history, tlt_history)
+
+    return _insufficient_data("No treasury rates or SHY/TLT data available")
+
+
+def _analyze_treasury_spread(treasury_rates: List[Dict]) -> Optional[Dict]:
+    """Analyze 10Y-2Y spread from Treasury API data."""
+    # Extract 10Y-2Y spread series
+    spread_monthly = {}
+    for entry in treasury_rates:
+        date_str = entry.get("date", "")
+        year10 = entry.get("year10")
+        year2 = entry.get("year2")
+
+        if not date_str or year10 is None or year2 is None:
+            continue
+
+        try:
+            y10 = float(year10)
+            y2 = float(year2)
+        except (ValueError, TypeError):
+            continue
+
+        ym = date_str[:7]
+        if ym not in spread_monthly:
+            spread_monthly[ym] = {
+                "date": date_str,
+                "spread": y10 - y2,
+                "year10": y10,
+                "year2": y2,
+            }
+
+    if len(spread_monthly) < 12:
+        return None
+
+    # Sort most recent first
+    spread_series = sorted(spread_monthly.values(), key=lambda x: x["date"], reverse=True)
+    spread_values = [s["spread"] for s in spread_series]
+
+    current_spread = spread_values[0]
+    current_date = spread_series[0]["date"]
+    current_10y = spread_series[0]["year10"]
+    current_2y = spread_series[0]["year2"]
+
+    # Compute SMAs
+    sma_6m = compute_sma(spread_values, 6)
+    sma_12m = compute_sma(spread_values, 12)
+
+    # Crossover detection
+    crossover = detect_crossover(spread_values, short_period=6, long_period=12)
+
+    # Momentum
+    roc_3m = compute_roc(spread_values, 3)
+    roc_12m = compute_roc(spread_values, 12)
+
+    # Percentile
+    percentile = compute_percentile(spread_values, current_spread)
+
+    # Score
+    score = score_transition_signal(
+        crossover=crossover,
+        roc_short=roc_3m,
+        roc_long=roc_12m,
+        sma_short=sma_6m,
+        sma_long=sma_12m,
+    )
+
+    # Curve state
+    curve_state = _classify_curve_state(current_spread, sma_6m, roc_3m)
+
+    # Direction of transition
+    if roc_3m is not None and roc_3m > 0:
+        direction = "steepening"
+    elif roc_3m is not None and roc_3m < 0:
+        direction = "flattening"
+    else:
+        direction = "stable"
+
+    signal = _describe_signal(score, curve_state, current_spread, direction)
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "data_source": "treasury_api",
+        "direction": direction,
+        "curve_state": curve_state,
+        "current_spread": round(current_spread, 3),
+        "current_10y": current_10y,
+        "current_2y": current_2y,
+        "current_date": current_date,
+        "sma_6m": round(sma_6m, 3) if sma_6m is not None else None,
+        "sma_12m": round(sma_12m, 3) 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(spread_series),
+    }
+
+
+def _analyze_shy_tlt_proxy(shy_history: List[Dict],
+                           tlt_history: List[Dict]) -> Dict:
+    """Fallback: Use SHY/TLT ratio as yield curve proxy."""
+    shy_monthly = downsample_to_monthly(shy_history)
+    tlt_monthly = downsample_to_monthly(tlt_history)
+
+    if len(shy_monthly) < 12 or len(tlt_monthly) < 12:
+        return _insufficient_data("Insufficient SHY/TLT monthly data")
+
+    # SHY/TLT ratio: rising = curve flattening/inverting, falling = steepening
+    ratio_series = calculate_ratio(shy_monthly, tlt_monthly)
+    if len(ratio_series) < 12:
+        return _insufficient_data("Insufficient SHY/TLT 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,
+    )
+
+    # For SHY/TLT: rising ratio = flattening, falling = steepening
+    if roc_3m is not None and roc_3m < 0:
+        direction = "steepening"
+    elif roc_3m is not None and roc_3m > 0:
+        direction = "flattening"
+    else:
+        direction = "stable"
+
+    signal = f"PROXY (SHY/TLT): {direction} signal, score={score}"
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "data_source": "shy_tlt_proxy",
+        "direction": direction,
+        "curve_state": "proxy_only",
+        "current_spread": None,
+        "current_10y": None,
+        "current_2y": None,
+        "current_date": current_date,
+        "proxy_ratio": round(current_ratio, 4),
+        "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 _classify_curve_state(spread: float, sma_6m: Optional[float],
+                          roc_3m: Optional[float]) -> str:
+    """Classify current yield curve state."""
+    if spread < -0.5:
+        return "deeply_inverted"
+    elif spread < 0:
+        return "inverted"
+    elif spread < 0.5:
+        if roc_3m is not None and roc_3m > 0:
+            return "normalizing"
+        return "flat"
+    elif spread < 1.5:
+        return "normal"
+    else:
+        return "steep"
+
+
+def _describe_signal(score: int, state: str, spread: float, direction: str) -> str:
+    state_labels = {
+        "deeply_inverted": "Deeply Inverted",
+        "inverted": "Inverted",
+        "normalizing": "Normalizing",
+        "flat": "Flat",
+        "normal": "Normal",
+        "steep": "Steep",
+    }
+    state_label = state_labels.get(state, state)
+
+    if score >= 60:
+        return f"TRANSITION: Yield curve {direction} ({state_label}, spread={spread:+.3f}%)"
+    elif score >= 40:
+        return f"SHIFTING: Yield curve {direction} ({state_label}, spread={spread:+.3f}%)"
+    else:
+        return f"STABLE: Yield curve {state_label} (spread={spread:+.3f}%)"
+
+
+def _insufficient_data(reason: str) -> Dict:
+    return {
+        "score": 0,
+        "signal": f"INSUFFICIENT DATA: {reason}",
+        "data_available": False,
+        "data_source": "none",
+        "direction": "unknown",
+        "curve_state": "unknown",
+        "current_spread": None,
+        "current_10y": None,
+        "current_2y": 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,
+    }