Macro Regime Detector

"""Macro Regime Detector - Calculator modules"""

#!/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 Optional

from .utils import (
    STALE_CROSSOVER_MONTHS,
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_sma,
    detect_crossover,
    downsample_to_monthly,
    score_transition_signal,
)


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 "TRANSITION SIGNAL: RSP/SPY crossover or sharp momentum reversal detected"
    elif score >= 40:
        return "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,
    }

#!/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 .utils import (
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_sma,
    detect_crossover,
    determine_direction,
    downsample_to_monthly,
    score_transition_signal,
)


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,
    }

#!/usr/bin/env python3
"""
Component 5: Equity-Bond Relationship (Weight: 15%)

Analyzes SPY/TLT ratio and rolling stock-bond correlation to detect
changes in the equity-bond regime.

SPY/TLT ratio:
- Rising = equities outperforming bonds (risk-on)
- Falling = bonds outperforming equities (risk-off)

Stock-Bond Correlation:
- Negative correlation (normal): Bonds hedge equities
- Positive correlation (inflationary): Both move together, traditional hedging breaks
- Correlation sign change = major regime shift

Transition signals:
- SPY/TLT ratio crossover + correlation regime change = high confidence
"""

from typing import Optional

from .utils import (
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_rolling_correlation,
    compute_sma,
    detect_crossover,
    determine_direction,
    downsample_to_monthly,
    score_transition_signal,
)


def calculate_equity_bond(spy_history: list[dict], tlt_history: list[dict]) -> dict:
    """
    Calculate equity-bond relationship transition signal.

    Args:
        spy_history: SPY daily OHLCV (most recent first)
        tlt_history: TLT daily OHLCV (most recent first)

    Returns:
        Dict with score (0-100), signal, ratio and correlation details
    """
    if not spy_history or not tlt_history:
        return _insufficient_data("No SPY or TLT data available")

    spy_monthly = downsample_to_monthly(spy_history)
    tlt_monthly = downsample_to_monthly(tlt_history)

    if len(spy_monthly) < 12 or len(tlt_monthly) < 12:
        return _insufficient_data("Insufficient monthly data (need >= 12 months)")

    # SPY/TLT ratio analysis
    ratio_series = calculate_ratio(spy_monthly, tlt_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)

    # Ratio transition score
    ratio_score = score_transition_signal(
        crossover=crossover,
        roc_short=roc_3m,
        roc_long=roc_12m,
        sma_short=sma_6m,
        sma_long=sma_12m,
    )

    # Rolling correlation analysis (monthly returns)
    spy_returns = _compute_monthly_returns([m["close"] for m in spy_monthly])
    tlt_returns = _compute_monthly_returns([m["close"] for m in tlt_monthly])

    correlation_6m = compute_rolling_correlation(spy_returns, tlt_returns, 6)
    correlation_12m = compute_rolling_correlation(spy_returns, tlt_returns, 12)

    # Correlation regime
    corr_regime = _classify_correlation_regime(correlation_6m, correlation_12m)

    # Correlation transition bonus (0-20)
    corr_bonus = 0
    if correlation_6m is not None and correlation_12m is not None:
        # Sign change between 6M and 12M correlation = regime transition
        if (correlation_6m > 0) != (correlation_12m > 0):
            corr_bonus = 20
        elif abs(correlation_6m - correlation_12m) > 0.3:
            corr_bonus = 10

    # Combined score
    score = min(100, ratio_score + corr_bonus)

    # Direction
    direction, momentum_qualifier = determine_direction(
        crossover,
        roc_3m,
        positive_label="risk_on",
        negative_label="risk_off",
        neutral_label="neutral",
    )

    signal = _describe_signal(score, direction, corr_regime, current_ratio)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "direction": direction,
        "momentum_qualifier": momentum_qualifier,
        "correlation_regime": corr_regime,
        "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,
        "correlation_6m": round(correlation_6m, 3) if correlation_6m is not None else None,
        "correlation_12m": round(correlation_12m, 3) if correlation_12m is not None else None,
        "crossover": crossover,
        "monthly_points": len(ratio_series),
    }


def _compute_monthly_returns(closes: list[float]) -> list[float]:
    """Compute month-over-month returns from closes (most recent first)."""
    if len(closes) < 2:
        return []
    returns = []
    for i in range(len(closes) - 1):
        if closes[i + 1] != 0:
            ret = (closes[i] - closes[i + 1]) / closes[i + 1]
            returns.append(ret)
    return returns


def _classify_correlation_regime(corr_6m: Optional[float], corr_12m: Optional[float]) -> str:
    """Classify the stock-bond correlation regime."""
    if corr_6m is None:
        return "unknown"

    if corr_6m < -0.3:
        return "negative_strong"  # Normal hedging
    elif corr_6m < 0:
        return "negative_mild"  # Weak hedging
    elif corr_6m < 0.3:
        return "near_zero"  # Transitional
    else:
        return "positive"  # Inflationary regime


def _describe_signal(score: int, direction: str, corr_regime: str, ratio: float) -> str:
    corr_labels = {
        "negative_strong": "strong negative correlation (normal hedging)",
        "negative_mild": "mild negative correlation",
        "near_zero": "near-zero correlation (transitional)",
        "positive": "positive correlation (inflationary)",
        "unknown": "unknown correlation",
    }
    corr_label = corr_labels.get(corr_regime, corr_regime)

    if score >= 60:
        return f"TRANSITION: Equity-bond shift to {direction}, {corr_label} (SPY/TLT={ratio:.4f})"
    elif score >= 40:
        return f"SHIFTING: Equity-bond trending {direction}, {corr_label} (SPY/TLT={ratio:.4f})"
    else:
        return f"STABLE: Equity-bond stable, {corr_label} (SPY/TLT={ratio:.4f})"


def _insufficient_data(reason: str) -> dict:
    return {
        "score": 0,
        "signal": f"INSUFFICIENT DATA: {reason}",
        "data_available": False,
        "direction": "unknown",
        "correlation_regime": "unknown",
        "current_ratio": None,
        "current_date": None,
        "sma_6m": None,
        "sma_12m": None,
        "roc_3m": None,
        "roc_12m": None,
        "percentile": None,
        "correlation_6m": None,
        "correlation_12m": None,
        "crossover": {"type": "none", "bars_ago": None},
        "monthly_points": 0,
    }

#!/usr/bin/env python3
"""
Component 6: Sector Rotation (Weight: 10%)

Analyzes XLY/XLP ratio to detect cyclical vs defensive appetite.

XLY (Consumer Discretionary) / XLP (Consumer Staples):
- Rising ratio = risk appetite expanding, consumer confidence
- Falling ratio = defensive positioning, consumer caution

This is a classic risk-on/risk-off barometer that captures
consumer-facing economic sentiment.
"""

from .utils import (
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_sma,
    detect_crossover,
    determine_direction,
    downsample_to_monthly,
    score_transition_signal,
)


def calculate_sector_rotation(xly_history: list[dict], xlp_history: list[dict]) -> dict:
    """
    Calculate sector rotation transition signal from XLY/XLP ratio.

    Args:
        xly_history: XLY daily OHLCV (most recent first)
        xlp_history: XLP daily OHLCV (most recent first)

    Returns:
        Dict with score (0-100), signal, ratio details
    """
    if not xly_history or not xlp_history:
        return _insufficient_data("No XLY or XLP data available")

    xly_monthly = downsample_to_monthly(xly_history)
    xlp_monthly = downsample_to_monthly(xlp_history)

    if len(xly_monthly) < 12 or len(xlp_monthly) < 12:
        return _insufficient_data("Insufficient monthly data (need >= 12 months)")

    ratio_series = calculate_ratio(xly_monthly, xlp_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="risk_on",
        negative_label="risk_off",
        neutral_label="neutral",
    )

    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: Sector rotation to {direction} (XLY/XLP={ratio:.4f})"
    elif score >= 40:
        return f"SHIFTING: Sector rotation trending {direction} (XLY/XLP={ratio:.4f})"
    else:
        return f"STABLE: Sector rotation stable, {direction} (XLY/XLP={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,
    }

#!/usr/bin/env python3
"""
Component 4: Size Factor (Weight: 15%)

Analyzes IWM/SPY ratio to detect small-cap vs large-cap rotation.

IWM (Russell 2000) / SPY (S&P 500):
- Rising ratio = small-caps outperforming, risk-on, economic optimism
- Falling ratio = large-cap preference, defensive positioning

Transition signals:
- IWM/SPY turning up = broadening rally, cyclical recovery
- IWM/SPY turning down = flight to quality, narrowing leadership
"""

from .utils import (
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_sma,
    detect_crossover,
    determine_direction,
    downsample_to_monthly,
    score_transition_signal,
)


def calculate_size_factor(iwm_history: list[dict], spy_history: list[dict]) -> dict:
    """
    Calculate size factor transition signal from IWM/SPY ratio.

    Args:
        iwm_history: IWM daily OHLCV (most recent first)
        spy_history: SPY daily OHLCV (most recent first)

    Returns:
        Dict with score (0-100), signal, ratio details
    """
    if not iwm_history or not spy_history:
        return _insufficient_data("No IWM or SPY data available")

    iwm_monthly = downsample_to_monthly(iwm_history)
    spy_monthly = downsample_to_monthly(spy_history)

    if len(iwm_monthly) < 12 or len(spy_monthly) < 12:
        return _insufficient_data("Insufficient monthly data (need >= 12 months)")

    ratio_series = calculate_ratio(iwm_monthly, spy_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="small_cap_leading",
        negative_label="large_cap_leading",
        neutral_label="neutral",
    )

    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:
    direction_labels = {
        "small_cap_leading": "small-cap outperformance",
        "large_cap_leading": "large-cap outperformance",
        "neutral": "neutral size factor",
    }
    label = direction_labels.get(direction, direction)

    if score >= 60:
        return f"TRANSITION: Size factor shift to {label} (IWM/SPY={ratio:.4f})"
    elif score >= 40:
        return f"SHIFTING: Size factor trending toward {label} (IWM/SPY={ratio:.4f})"
    else:
        return f"STABLE: Size factor stable, {label} (IWM/SPY={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,
    }

#!/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 Optional


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))

#!/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 Optional

from .utils import (
    calculate_ratio,
    compute_percentile,
    compute_roc,
    compute_sma,
    detect_crossover,
    downsample_to_monthly,
    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)

    # Individual yield ROCs for steepening type classification
    y10_values = [s["year10"] for s in spread_series]
    y2_values = [s["year2"] for s in spread_series]
    roc_3m_10y = compute_roc(y10_values, 3)
    roc_3m_2y = compute_roc(y2_values, 3)

    # 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"

    # Steepening type classification
    steepening_type = None
    if direction == "steepening":
        if roc_3m_2y is not None and roc_3m_2y < 0:
            steepening_type = "bull_steepener"
        elif roc_3m_10y is not None and roc_3m_10y > 0:
            steepening_type = "bear_steepener"
        else:
            steepening_type = "mixed_steepener"

    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,
        "steepening_type": steepening_type,
        "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,
        "roc_3m_10y": round(roc_3m_10y, 2) if roc_3m_10y is not None else None,
        "roc_3m_2y": round(roc_3m_2y, 2) if roc_3m_2y 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",
        "steepening_type": None,
        "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,
    }

#!/usr/bin/env python3
# GENERATED by scripts/generate_fmp_client.py — do not edit.
# Source of truth: scripts/fmp_client/specials/ and scripts/fmp_client/registry.py.
# Regenerate: python3 scripts/generate_fmp_client.py
"""
FMP API Client for Macro Regime Detector

Provides rate-limited access to Financial Modeling Prep API endpoints
for macro regime detection analysis.

Features:
- Rate limiting (0.3s between requests)
- Automatic retry on 429 errors
- Session caching for duplicate requests
- Batch historical data support
- Treasury rates endpoint support
"""

import os
import sys
import time
from datetime import date, timedelta
from typing import Optional

try:
    import requests
except ImportError:
    print("ERROR: requests library not found. Install with: pip install requests", file=sys.stderr)
    sys.exit(1)


# --- FMP endpoint fallback: stable (new users) -> v3 (legacy users) ---


def _stable_hist_url(base, symbols_str, params):
    """stable/historical-price-eod/full?symbol=SPY&from=...&to=..."""
    params["symbol"] = symbols_str
    # New stable EOD endpoint ignores `timeseries`; convert to from/to range
    # to bound the payload. Use 2x calendar days to cover N trading days
    # (trading-day/calendar-day ratio ~252/365 ~0.69, so *2 leaves headroom).
    days = params.pop("timeseries", None)
    if days is not None:
        today = date.today()
        params["from"] = (today - timedelta(days=int(days) * 2)).isoformat()
        params["to"] = today.isoformat()
    return base, params


def _v3_hist_url(base, symbols_str, params):
    """api/v3/historical-price-full/SPY?timeseries=600"""
    return f"{base}/{symbols_str}", params


_FMP_ENDPOINTS = {
    "historical": [
        ("https://financialmodelingprep.com/stable/historical-price-eod/full", _stable_hist_url),
        ("https://financialmodelingprep.com/api/v3/historical-price-full", _v3_hist_url),
    ],
}


def _normalize_eod_flat_list(data, symbols_str: str, limit: Optional[int] = None):
    """Convert stable/historical-price-eod/full flat list to v3-compatible dict.

    Input  : [{"symbol": "SPY", "date": "...", "open": ..., ...}, ...]
    Output : {"symbol": "SPY", "historical": [{"date": ..., "open": ..., ...}, ...]}

    Returns the input unchanged if not a list (passthrough for v3 dict /
    historicalStockList responses). Returns None when no row matches the
    requested symbol; the caller will record the failure and try the next
    endpoint.

    If `limit` is provided (the original `timeseries=N` request), the
    `historical` list is truncated to the first `limit` entries. The new
    EOD endpoint ignores `timeseries` and returns the full available history,
    so the caller's date-range bounding plus this truncation together preserve
    the legacy "most-recent N rows" contract. Truncation assumes descending
    date order, which the FMP EOD endpoint provides (verified live).

    Note: empty list ``[]`` does not reach this normalizer because the caller's
    ``if not data: continue`` falsy check handles it earlier in
    ``_request_with_fallback``.
    """
    if not isinstance(data, list):
        return data
    if not data:
        return None
    norm_target = symbols_str.replace("-", ".")
    matched_symbol = None
    historical = []
    for row in data:
        if not isinstance(row, dict):
            continue
        # Be permissive: single-symbol endpoint may omit per-row "symbol".
        # Treat missing symbol as belonging to the requested symbols_str.
        row_sym = row.get("symbol") or symbols_str
        if row_sym.replace("-", ".") != norm_target:
            continue
        matched_symbol = matched_symbol or row_sym
        historical.append({k: v for k, v in row.items() if k != "symbol"})
    if not historical:
        return None
    if limit is not None and limit > 0:
        historical = historical[:limit]
    return {"symbol": matched_symbol or symbols_str, "historical": historical}


def _has_usable_history(data) -> bool:
    """True only when `data` is a dict carrying a non-empty `historical` list.

    A dict with an empty `historical` list (e.g. an ETF unavailable on the
    caller's FMP plan) is treated as unusable so the caller can fall back to
    yfinance instead of caching an empty result.
    """
    return bool(
        isinstance(data, dict) and isinstance(data.get("historical"), list) and data["historical"]
    )


class FMPClient:
    """Client for Financial Modeling Prep API with rate limiting and caching"""

    BASE_URL = "https://financialmodelingprep.com/api/v3"
    STABLE_URL = "https://financialmodelingprep.com/stable"
    RATE_LIMIT_DELAY = 0.3  # 300ms between requests
    _ENDPOINT_FAILURE_THRESHOLD = 3

    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.getenv("FMP_API_KEY")
        if not self.api_key:
            raise ValueError(
                "FMP API key required. Set FMP_API_KEY environment variable "
                "or pass api_key parameter."
            )
        self.session = requests.Session()
        self.session.headers.update({"apikey": self.api_key})
        self.cache = {}
        self.last_call_time = 0
        self.rate_limit_reached = False
        self.retry_count = 0
        self.max_retries = 1
        self.api_calls_made = 0
        self._endpoint_failures: dict[str, int] = {}
        self._disabled_endpoints: set[str] = set()

    def _rate_limited_get(
        self, url: str, params: Optional[dict] = None, quiet: bool = False
    ) -> Optional[dict]:
        if self.rate_limit_reached:
            return None

        if params is None:
            params = {}

        elapsed = time.time() - self.last_call_time
        if elapsed < self.RATE_LIMIT_DELAY:
            time.sleep(self.RATE_LIMIT_DELAY - elapsed)

        try:
            response = self.session.get(url, params=params, timeout=30)
            self.last_call_time = time.time()
            self.api_calls_made += 1

            if response.status_code == 200:
                self.retry_count = 0
                return response.json()
            elif response.status_code == 429:
                self.retry_count += 1
                if self.retry_count <= self.max_retries:
                    if not quiet:
                        print(
                            "WARNING: Rate limit exceeded. Waiting 60 seconds...", file=sys.stderr
                        )
                    time.sleep(60)
                    return self._rate_limited_get(url, params, quiet=quiet)
                else:
                    if not quiet:
                        print("ERROR: Daily API rate limit reached.", file=sys.stderr)
                    self.rate_limit_reached = True
                    return None
            else:
                if not quiet:
                    print(
                        f"ERROR: API request failed: {response.status_code} - {response.text[:200]}",
                        file=sys.stderr,
                    )
                return None
        except requests.exceptions.RequestException as e:
            if not quiet:
                print(f"ERROR: Request exception: {e}", file=sys.stderr)
            return None

    def _request_with_fallback(self, endpoint_key, symbols_str, extra_params=None):
        """Try stable endpoint first, fall back to v3 for legacy users."""
        params = dict(extra_params) if extra_params else {}
        endpoints = _FMP_ENDPOINTS[endpoint_key]
        is_single = "," not in symbols_str

        for i, (base_url, url_builder) in enumerate(endpoints):
            if base_url in self._disabled_endpoints:
                continue
            url, final_params = url_builder(base_url, symbols_str, dict(params))
            is_last = i == len(endpoints) - 1
            data = self._rate_limited_get(url, final_params, quiet=not is_last)
            if not data:
                self._record_endpoint_failure(base_url)
                continue

            # Normalize new stable EOD flat-list shape to v3-compatible dict.
            # No-op for v3 dict / historicalStockList responses.
            # `timeseries` (original request) is passed as `limit` so the
            # EOD endpoint's full-history response is truncated to the
            # legacy "most-recent N rows" contract.
            if endpoint_key == "historical":
                limit = params.get("timeseries") if isinstance(params, dict) else None
                data = _normalize_eod_flat_list(data, symbols_str, limit=limit)
                if not data:
                    self._record_endpoint_failure(base_url)
                    continue

            valid = True
            if endpoint_key == "historical":
                if not isinstance(data, dict):
                    valid = False
                elif "historicalStockList" in data:
                    norm = symbols_str.replace("-", ".")
                    found = None
                    for entry in data["historicalStockList"]:
                        if entry.get("symbol", "").replace("-", ".") == norm:
                            found = {
                                "symbol": entry.get("symbol"),
                                "historical": entry.get("historical", []),
                            }
                            break
                    if found:
                        self._endpoint_failures[base_url] = 0
                        return found
                    valid = False
                elif "historical" not in data:
                    valid = False
                elif is_single and data.get("symbol"):
                    if data["symbol"].replace("-", ".") != symbols_str.replace("-", "."):
                        valid = False

            if valid:
                self._endpoint_failures[base_url] = 0
                return data
            self._record_endpoint_failure(base_url)
        return None

    def _record_endpoint_failure(self, base_url: str) -> None:
        failures = self._endpoint_failures.get(base_url, 0) + 1
        self._endpoint_failures[base_url] = failures
        if failures >= self._ENDPOINT_FAILURE_THRESHOLD:
            self._disabled_endpoints.add(base_url)

    def get_historical_prices(self, symbol: str, days: int = 600) -> Optional[dict]:
        """Fetch historical daily OHLCV data.

        Falls back to yfinance when the FMP historical-price endpoint returns
        nothing (e.g. an ETF unavailable on the caller's FMP plan). The yfinance
        path requires no extra API key; an FMP API key is still required to
        construct this client.
        """
        cache_key = f"prices_{symbol}_{days}"
        if cache_key in self.cache:
            return self.cache[cache_key]

        data = self._request_with_fallback("historical", symbol, {"timeseries": days})
        # _request_with_fallback can return a truthy dict with an EMPTY
        # historical list (v3 `{"symbol":...,"historical":[]}` or an empty
        # historicalStockList entry) for ETFs unavailable on the caller's FMP
        # plan. A bare `if not data` check would miss that and cache the empty
        # result, defeating the fallback's purpose — so treat "no usable
        # history" the same as "no data".
        if not _has_usable_history(data):
            data = self._get_from_yfinance(symbol, days)
        if _has_usable_history(data):
            self.cache[cache_key] = data
            return data
        return None

    def _get_from_yfinance(self, symbol: str, days: int) -> Optional[dict]:
        """Fallback: fetch ETF history via yfinance when FMP is unavailable.

        Returns the same contract as the FMP path
        (``{"symbol": ..., "historical": [...]}`` with most-recent-first bars,
        each carrying ``date``/``open``/``high``/``low``/``close``/``adjClose``/
        ``volume``) or ``None`` on empty/error. Never caches here — caching is
        the caller's responsibility so a failed lookup leaves no poisoned entry.
        ``yfinance`` is imported lazily so the FMP success path never depends on
        it.
        """
        try:
            import yfinance as yf

            # Request ~1.5x calendar days to cover weekends/holidays.
            end = date.today()
            start = end - timedelta(days=int(days * 1.5))
            df = yf.download(
                symbol,
                start=start.isoformat(),
                end=end.isoformat(),
                auto_adjust=True,
                progress=False,
            )
            if df is None or df.empty:
                return None
            # yfinance returns MultiIndex columns for a single ticker.
            if hasattr(df.columns, "levels"):
                df.columns = df.columns.droplevel(1)
            historical = []
            for idx, row in df.iterrows():
                close = float(row["Close"])
                historical.append(
                    {
                        "date": idx.strftime("%Y-%m-%d"),
                        "open": float(row["Open"]),
                        "high": float(row["High"]),
                        "low": float(row["Low"]),
                        "close": close,
                        # auto_adjust=True -> Close is already adjusted.
                        "adjClose": close,
                        "volume": int(row["Volume"]),
                    }
                )
            if not historical:
                return None
            # yfinance returns ascending; FMP contract is most-recent-first.
            historical.reverse()
            return {"symbol": symbol, "historical": historical[:days]}
        except Exception as e:
            print(
                f"WARNING: yfinance fallback failed for {symbol}: {e}",
                file=sys.stderr,
            )
            return None

    def get_batch_historical(self, symbols: list[str], days: int = 600) -> dict[str, list[dict]]:
        """Fetch historical prices for multiple symbols"""
        results = {}
        for symbol in symbols:
            data = self.get_historical_prices(symbol, days=days)
            if data and "historical" in data:
                results[symbol] = data["historical"]
        return results

    def get_treasury_rates(self, days: int = 600) -> Optional[list[dict]]:
        """
        Fetch treasury rate data from FMP stable endpoint.

        Returns list of dicts with keys like 'date', 'year2', 'year10', etc.
        Most recent first.
        """
        cache_key = f"treasury_{days}"
        if cache_key in self.cache:
            return self.cache[cache_key]

        url = f"{self.STABLE_URL}/treasury-rates"
        params = {"limit": days}
        data = self._rate_limited_get(url, params)
        if data and isinstance(data, list):
            self.cache[cache_key] = data
            return data
        return None

    def get_api_stats(self) -> dict:
        return {
            "cache_entries": len(self.cache),
            "api_calls_made": self.api_calls_made,
            "rate_limit_reached": self.rate_limit_reached,
        }