Market Breadth Analyzer

# Market Breadth Analyzer - Calculator modules

#!/usr/bin/env python3
"""
Component 4: Bearish Signal Status (Weight: 15%)

Evaluates the backtested bearish signal flag and its context.
Also detects the "Pink Zone" (Bearish Region) from the source repository:
  Pink Zone = Breadth_200MA_Trend == -1 AND 8MA < 200MA

Input: Bearish_Signal, Breadth_200MA_Trend, Breadth_Index_8MA,
       Breadth_Index_200MA (latest row)

Scoring (100 = healthy):
  Base:
    Signal=False & Trend=1  -> 85 (all clear)
    Signal=False & Trend=-1 -> 50 (no warning but downtrend)
    Signal=True  & Trend=1  -> 30 (warning in uptrend)
    Signal=True  & Trend=-1 -> 10 (fully bearish)

  Context Adjustment:
    Signal=True & 8MA > 0.50 -> +15 (weak signal amid strong breadth)
    Signal=True & 8MA < 0.25 -> -5  (severe signal amid extreme weakness)

  Pink Zone Adjustment:
    In Pink Zone & Signal=False -> -10 (structural weakness even without signal)
"""


def calculate_bearish_signal(rows: list[dict]) -> dict:
    """
    Calculate bearish signal status score.

    Args:
        rows: All detail rows sorted by date ascending.

    Returns:
        Dict with score, signal, and component details.
    """
    if not rows:
        return {
            "score": 50,
            "signal": "NO DATA: No data available for bearish signal analysis",
            "data_available": False,
        }

    latest = rows[-1]
    signal_active = latest["Bearish_Signal"]
    trend = latest["Breadth_200MA_Trend"]
    ma8 = latest["Breadth_Index_8MA"]
    ma200 = latest["Breadth_Index_200MA"]

    # Pink Zone detection (from source repo: chart's pink background)
    # Condition: 200MA trend declining AND 8MA below 200MA
    in_pink_zone = (trend == -1) and (ma8 < ma200)

    # Count consecutive pink zone days
    pink_zone_days = 0
    if in_pink_zone:
        for i in range(len(rows) - 1, -1, -1):
            r = rows[i]
            if r["Breadth_200MA_Trend"] == -1 and r["Breadth_Index_8MA"] < r["Breadth_Index_200MA"]:
                pink_zone_days += 1
            else:
                break

    # Base score
    base_score = _base_score(signal_active, trend)

    # Context adjustment
    context_adj = 0
    if signal_active:
        if ma8 > 0.50:
            context_adj = +15  # Weak signal amid strong breadth
        elif ma8 < 0.25:
            context_adj = -5  # Severe signal amid extreme weakness

    # Pink Zone adjustment: structural weakness even without bearish signal
    pink_zone_adj = 0
    if in_pink_zone and not signal_active:
        pink_zone_adj = -10

    score = round(base_score + context_adj + pink_zone_adj)
    score = max(0, min(100, score))

    signal_text = _generate_signal(signal_active, trend, ma8, in_pink_zone, score)

    return {
        "score": score,
        "signal": signal_text,
        "data_available": True,
        "signal_active": signal_active,
        "trend": trend,
        "current_8ma": ma8,
        "current_200ma": ma200,
        "in_pink_zone": in_pink_zone,
        "pink_zone_days": pink_zone_days,
        "base_score": base_score,
        "context_adjustment": context_adj,
        "pink_zone_adjustment": pink_zone_adj,
        "date": latest["Date"],
    }


def _base_score(signal_active: bool, trend: int) -> int:
    """Calculate base score from signal and trend combination."""
    if not signal_active and trend == 1:
        return 85  # All clear
    elif not signal_active and trend == -1:
        return 50  # No warning but downtrend
    elif signal_active and trend == 1:
        return 30  # Warning in uptrend
    else:  # signal_active and trend == -1
        return 10  # Fully bearish


def _generate_signal(
    signal_active: bool,
    trend: int,
    ma8: float,
    in_pink_zone: bool,
    score: int,
) -> str:
    """Generate human-readable signal."""
    trend_str = "uptrend" if trend == 1 else "downtrend"
    pink_str = " [PINK ZONE]" if in_pink_zone else ""

    if not signal_active:
        if trend == 1:
            return f"ALL CLEAR: No bearish signal, {trend_str}"
        elif in_pink_zone:
            return (
                f"CAUTION: No bearish signal but in Pink Zone (downtrend + 8MA < 200MA){pink_str}"
            )
        else:
            return f"CAUTION: No bearish signal but {trend_str}"
    else:
        if ma8 > 0.50:
            return (
                f"WARNING (muted): Bearish signal active in {trend_str}, "
                f"but 8MA={ma8:.3f} still relatively strong{pink_str}"
            )
        elif ma8 < 0.25:
            return (
                f"CRITICAL: Bearish signal active in {trend_str}, "
                f"8MA={ma8:.3f} extremely weak{pink_str}"
            )
        else:
            return f"BEARISH: Signal active in {trend_str}, 8MA={ma8:.3f}{pink_str}"

#!/usr/bin/env python3
"""
Component 3: Peak/Trough Cycle Position (Weight: 20%)

Determines where we are in the breadth cycle relative to recent peaks and troughs.

Input: Is_Peak, Is_Trough, Is_Trough_8MA_Below_04, Breadth_Index_8MA (last 120 days)

Scoring (100 = healthy):
  Latest marker = TROUGH:
    <= 20 days & 8MA rising       -> 85 (early recovery)
    <= 20 days & 8MA flat/falling -> 30 (failed reversal)
    21-60 days & 8MA rising       -> 75 (sustained recovery)
    > 60 days & 8MA rising        -> 65 (mature recovery)

  Latest marker = PEAK:
    <= 20 days & 8MA falling      -> 20 (post-peak decline)
    <= 20 days & 8MA flat/rising  -> 60 (high-level consolidation)
    21-60 days & 8MA falling      -> 15 (sustained decline)
    > 60 days & 8MA falling       -> 10 (prolonged decline)
    > 60 days & 8MA rising        -> 50 (possible bottom formation)

  Extreme Trough Bonus: Is_Trough_8MA_Below_04 == True -> +10
  No marker within 120 days -> 50 (neutral)
"""

from typing import Optional


def calculate_cycle_position(rows: list[dict]) -> dict:
    """
    Calculate peak/trough cycle position score.

    Args:
        rows: All detail rows sorted by date ascending.

    Returns:
        Dict with score, signal, and component details.
    """
    if not rows or len(rows) < 10:
        return {
            "score": 50,
            "signal": "NO DATA: Insufficient data for cycle analysis",
            "data_available": False,
        }

    # Look at last 120 trading days
    lookback = min(120, len(rows))
    recent = rows[-lookback:]
    latest = rows[-1]
    current_8ma = latest["Breadth_Index_8MA"]

    # Find latest peak or trough marker
    marker_type, marker_idx, days_since = _find_latest_marker(recent)

    # Determine 8MA trend (rising/falling) over last 5 days
    if len(rows) >= 6:
        ma8_trend = "rising" if current_8ma > rows[-6]["Breadth_Index_8MA"] else "falling"
    else:
        ma8_trend = "unknown"

    # Check for extreme trough
    extreme_trough = False
    if marker_type == "TROUGH":
        extreme_trough = recent[marker_idx]["Is_Trough_8MA_Below_04"]

    # Calculate score
    score = _calculate_score(marker_type, days_since, ma8_trend, extreme_trough)
    score = max(0, min(100, score))

    signal = _generate_signal(marker_type, days_since, ma8_trend, score)

    marker_found = marker_type is not None

    return {
        "score": score,
        "signal": signal,
        "data_available": marker_found,
        "latest_marker_type": marker_type,
        "days_since_marker": days_since,
        "ma8_trend": ma8_trend,
        "current_8ma": current_8ma,
        "extreme_trough": extreme_trough,
        "date": latest["Date"],
    }


def _find_latest_marker(recent: list[dict]) -> tuple[Optional[str], int, Optional[int]]:
    """
    Find the most recent peak or trough marker.

    Returns (marker_type, index_in_recent, days_since).
    """
    for i in range(len(recent) - 1, -1, -1):
        row = recent[i]
        if row["Is_Peak"]:
            days_since = len(recent) - 1 - i
            return "PEAK", i, days_since
        if row["Is_Trough"] or row["Is_Trough_8MA_Below_04"]:
            days_since = len(recent) - 1 - i
            return "TROUGH", i, days_since

    return None, -1, None


def _calculate_score(
    marker_type: Optional[str],
    days_since: Optional[int],
    ma8_trend: str,
    extreme_trough: bool,
) -> int:
    """Calculate cycle position score based on marker and context."""
    if marker_type is None or days_since is None:
        return 50  # Neutral when no marker found

    rising = ma8_trend == "rising"

    if marker_type == "TROUGH":
        if days_since <= 20:
            base = 85 if rising else 30
        elif days_since <= 60:
            base = 75 if rising else 35
        else:
            base = 65 if rising else 40

        # Extreme trough bonus (contrarian buy signal)
        if extreme_trough:
            base += 10

    elif marker_type == "PEAK":
        if days_since <= 20:
            base = 60 if rising else 20
        elif days_since <= 60:
            base = 45 if rising else 15
        else:
            base = 50 if rising else 10

    else:
        base = 50

    return base


def _generate_signal(
    marker_type: Optional[str],
    days_since: Optional[int],
    ma8_trend: str,
    score: int,
) -> str:
    """Generate human-readable signal."""
    if marker_type is None:
        return "NEUTRAL: No cycle marker in last 120 days"

    if marker_type == "TROUGH":
        if days_since <= 20:
            phase = "early recovery" if ma8_trend == "rising" else "failed reversal attempt"
        elif days_since <= 60:
            phase = "sustained recovery" if ma8_trend == "rising" else "stalled recovery"
        else:
            phase = "mature recovery" if ma8_trend == "rising" else "weakening recovery"
        return f"TROUGH ({days_since}d ago): {phase}, 8MA {ma8_trend}"

    else:  # PEAK
        if days_since <= 20:
            phase = "consolidation near highs" if ma8_trend == "rising" else "post-peak decline"
        elif days_since <= 60:
            phase = "gradual decline" if ma8_trend != "rising" else "recovery attempt"
        else:
            phase = "possible bottom formation" if ma8_trend == "rising" else "prolonged decline"
        return f"PEAK ({days_since}d ago): {phase}, 8MA {ma8_trend}"

#!/usr/bin/env python3
"""
Component 6: S&P 500 vs Breadth Divergence (Weight: 10%)

Detects divergence between price action and breadth participation.

Uses dual windows:
  - 60-day window (weight 0.6): Medium-term structural divergence
  - 20-day window (weight 0.4): Short-term early warning

Composite score = 60d_score * 0.6 + 20d_score * 0.4

Early Warning: 20d bearish (<=25) while 60d healthy (>=50) flags
an emerging short-term divergence before it becomes structural.

Input: S&P500_Price, Breadth_Index_8MA (last 60+ days)

Scoring per window (100 = healthy):
  Both rising                        -> 70 (healthy rally)
  Both falling                       -> 30 (consistent decline)
  SP up(>3%) & Breadth down(<-0.05)  -> 10 (dangerous divergence)
  SP up(>1%) & Breadth down(<-0.03)  -> 25
  SP down(<-3%) & Breadth up(>+0.05) -> 80 (bullish divergence)
  SP down(<-1%) & Breadth up(>+0.03) -> 65
  Otherwise                          -> 50
"""


def calculate_divergence(rows: list[dict]) -> dict:
    """
    Calculate S&P 500 vs breadth divergence score using dual windows.

    Args:
        rows: All detail rows sorted by date ascending.

    Returns:
        Dict with score, signal, windows, and component details.
    """
    if not rows or len(rows) < 20:
        return {
            "score": 50,
            "signal": "NO DATA: Insufficient data for divergence analysis",
            "data_available": False,
        }

    latest = rows[-1]

    # Compute both windows
    w60 = _compute_window(rows, 60)
    w20 = _compute_window(rows, 20)

    # Composite score
    score = round(w60["score"] * 0.6 + w20["score"] * 0.4, 1)
    score = max(0, min(100, score))

    # Early Warning: short-term bearish divergence while long-term healthy
    early_warning = w20["score"] <= 25 and w60["score"] >= 50

    # Signal uses the composite
    signal = _generate_signal(w60["sp_pct"], w60["breadth_chg"], w60["div_type"], score)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        # Top-level backward compatibility (from 60d window)
        "sp500_pct_change": round(w60["sp_pct"], 2),
        "breadth_change": round(w60["breadth_chg"], 4),
        "sp500_latest": latest["S&P500_Price"],
        "sp500_past": w60["sp_past"],
        "ma8_latest": latest["Breadth_Index_8MA"],
        "ma8_past": w60["ma8_past"],
        "lookback_days": w60["lookback_days"],
        "divergence_type": w60["div_type"],
        "date": latest["Date"],
        # New window details
        "window_60d": {
            "score": w60["score"],
            "divergence_type": w60["div_type"],
            "sp500_pct_change": round(w60["sp_pct"], 2),
            "breadth_change": round(w60["breadth_chg"], 4),
            "lookback_days": w60["lookback_days"],
        },
        "window_20d": {
            "score": w20["score"],
            "divergence_type": w20["div_type"],
            "sp500_pct_change": round(w20["sp_pct"], 2),
            "breadth_change": round(w20["breadth_chg"], 4),
            "lookback_days": w20["lookback_days"],
        },
        "early_warning": early_warning,
    }


def _compute_window(rows: list[dict], lookback: int) -> dict:
    """Compute divergence metrics for a single lookback window."""
    actual_lookback = min(lookback, len(rows))
    latest = rows[-1]
    past = rows[-actual_lookback]

    sp_latest = latest["S&P500_Price"]
    sp_past = past["S&P500_Price"]
    ma8_latest = latest["Breadth_Index_8MA"]
    ma8_past = past["Breadth_Index_8MA"]

    if sp_past <= 0:
        return {
            "score": 50,
            "sp_pct": 0.0,
            "breadth_chg": 0.0,
            "div_type": "Invalid data",
            "sp_past": sp_past,
            "ma8_past": ma8_past,
            "lookback_days": actual_lookback,
        }

    sp_pct = (sp_latest - sp_past) / sp_past * 100
    breadth_chg = ma8_latest - ma8_past

    score, div_type = _score_divergence(sp_pct, breadth_chg)
    score = max(0, min(100, score))

    return {
        "score": score,
        "sp_pct": sp_pct,
        "breadth_chg": breadth_chg,
        "div_type": div_type,
        "sp_past": sp_past,
        "ma8_past": ma8_past,
        "lookback_days": actual_lookback,
    }


def _score_divergence(sp_pct: float, breadth_chg: float) -> tuple[int, str]:
    """Score based on price/breadth divergence. Returns (score, type_label)."""
    sp_up = sp_pct > 0
    breadth_up = breadth_chg > 0

    # Dangerous divergence: SP up, breadth down
    if sp_pct > 3.0 and breadth_chg < -0.05:
        return 10, "Dangerous bearish divergence"
    if sp_pct > 1.0 and breadth_chg < -0.03:
        return 25, "Moderate bearish divergence"

    # Bullish divergence: SP down, breadth up
    if sp_pct < -3.0 and breadth_chg > 0.05:
        return 80, "Strong bullish divergence"
    if sp_pct < -1.0 and breadth_chg > 0.03:
        return 65, "Moderate bullish divergence"

    # Near-flat movements (noise level)
    if abs(sp_pct) < 0.5 and abs(breadth_chg) < 0.01:
        return 50, "Near-flat (insufficient movement)"

    # Aligned movements
    if sp_up and breadth_up:
        return 70, "Healthy alignment (both rising)"
    if not sp_up and not breadth_up:
        return 30, "Consistent decline (both falling)"

    return 50, "Mixed signals"


def _generate_signal(sp_pct: float, breadth_chg: float, div_type: str, score: int) -> str:
    """Generate human-readable signal."""
    return f"{div_type}: S&P {sp_pct:+.1f}%, Breadth 8MA {breadth_chg:+.3f} over 60d"

#!/usr/bin/env python3
"""
Component 5: Historical Percentile (Weight: 10%)

Determines where the current breadth level sits in the full historical distribution.

Input: Breadth_Index_8MA (all rows), Summary CSV (average peak/trough values)

Scoring (100 = healthy):
  Percentile rank of current 8MA among all historical 8MA values:
    >= 80th -> 90    >= 60th -> 70    >= 40th -> 50
    >= 20th -> 30    <  20th -> 10

  Adjustment:
    Current >= avg_peak * 0.95 -> -10 (overheated caution)
    Current <= avg_trough * 1.05 -> +10 (oversold zone)
"""

from typing import Optional


def calculate_historical_percentile(
    rows: list[dict],
    summary: dict[str, str],
) -> dict:
    """
    Calculate historical percentile score.

    Args:
        rows: All detail rows sorted by date ascending.
        summary: Summary CSV as dict {Metric: Value}.

    Returns:
        Dict with score, signal, and component details.
    """
    if not rows:
        return {
            "score": 50,
            "signal": "NO DATA: No data available for historical analysis",
            "data_available": False,
        }

    # Extract all 8MA values
    all_8ma = [r["Breadth_Index_8MA"] for r in rows]
    current_8ma = all_8ma[-1]

    # Calculate percentile rank
    below_count = sum(1 for v in all_8ma if v < current_8ma)
    percentile = (below_count / len(all_8ma)) * 100

    # Base score from percentile
    base_score = _score_percentile(percentile)

    # Parse summary values
    avg_peak = _safe_float(summary.get("Average Peaks (200MA)", ""))
    avg_trough = _safe_float(summary.get("Average Troughs (8MA < 0.4)", ""))

    # Adjustment for extremes
    adjustment = 0
    if avg_peak is not None and current_8ma >= avg_peak * 0.95:
        adjustment = -10  # Overheated
    elif avg_trough is not None and current_8ma <= avg_trough * 1.05:
        adjustment = +10  # Oversold

    score = round(base_score + adjustment)
    score = max(0, min(100, score))

    signal = _generate_signal(percentile, adjustment, score)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "current_8ma": current_8ma,
        "percentile_rank": percentile,
        "base_score": base_score,
        "adjustment": adjustment,
        "avg_peak": avg_peak,
        "avg_trough": avg_trough,
        "total_observations": len(all_8ma),
        "date": rows[-1]["Date"],
    }


def _score_percentile(percentile: float) -> int:
    """Score from percentile rank."""
    if percentile >= 80:
        return 90
    elif percentile >= 60:
        return 70
    elif percentile >= 40:
        return 50
    elif percentile >= 20:
        return 30
    else:
        return 10


def _safe_float(val: str) -> Optional[float]:
    """Safely parse float from string."""
    try:
        return float(val)
    except (ValueError, TypeError):
        return None


def _generate_signal(percentile: float, adjustment: int, score: int) -> str:
    """Generate human-readable signal."""
    adj_str = ""
    if adjustment < 0:
        adj_str = " (near historical peak - overheated)"
    elif adjustment > 0:
        adj_str = " (near historical trough - oversold)"

    if score >= 70:
        return f"HIGH: {percentile:.0f}th percentile - above average breadth{adj_str}"
    elif score >= 40:
        return f"AVERAGE: {percentile:.0f}th percentile - normal range{adj_str}"
    else:
        return f"LOW: {percentile:.0f}th percentile - below average breadth{adj_str}"

#!/usr/bin/env python3
"""
Component 2: 8MA vs 200MA Crossover Dynamics (Weight: 20%)

Detects momentum and direction changes via the gap between fast and slow MAs.

Input: Breadth_Index_8MA, Breadth_Index_200MA (latest + 5-day lookback)

Scoring (100 = healthy):
  Gap = 8MA - 200MA
    >= +0.15 -> 95    >= +0.10 -> 80    >= +0.05 -> 65
    >=  0.00 -> 50    >= -0.05 -> 35    >= -0.10 -> 20
    <  -0.10 -> 5

  Direction Modifier (5-day 8MA trend):
    Gap < 0 and 8MA rising  -> +10 (recovery signal)
    Gap > 0 and 8MA falling -> -10 (deterioration signal)
"""


def calculate_ma_crossover(rows: list[dict]) -> dict:
    """
    Calculate 8MA vs 200MA crossover dynamics score.

    Args:
        rows: All detail rows sorted by date ascending.

    Returns:
        Dict with score, signal, and component details.
    """
    if not rows or len(rows) < 6:
        return {
            "score": 50,
            "signal": "NO DATA: Insufficient data for crossover analysis",
            "data_available": False,
        }

    latest = rows[-1]
    ma8 = latest["Breadth_Index_8MA"]
    ma200 = latest["Breadth_Index_200MA"]
    gap = ma8 - ma200

    # Gap score
    gap_score = _score_gap(gap)

    # 8MA direction over last 5 days
    ma8_5d_ago = rows[-6]["Breadth_Index_8MA"]
    ma8_rising = ma8 > ma8_5d_ago
    ma8_direction = "rising" if ma8_rising else "falling"

    # Direction modifier
    direction_modifier = 0
    if gap < 0 and ma8_rising:
        direction_modifier = +10  # Recovery signal
    elif gap > 0 and not ma8_rising:
        direction_modifier = -10  # Deterioration signal

    score = round(gap_score + direction_modifier)
    score = max(0, min(100, score))

    signal = _generate_signal(gap, ma8_direction, direction_modifier, score)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "gap": gap,
        "gap_score": gap_score,
        "current_8ma": ma8,
        "current_200ma": ma200,
        "ma8_5d_ago": ma8_5d_ago,
        "ma8_direction": ma8_direction,
        "direction_modifier": direction_modifier,
        "date": latest["Date"],
    }


def _score_gap(gap: float) -> int:
    """Score based on 8MA - 200MA gap."""
    if gap >= 0.15:
        return 95
    elif gap >= 0.10:
        return 80
    elif gap >= 0.05:
        return 65
    elif gap >= 0.00:
        return 50
    elif gap >= -0.05:
        return 35
    elif gap >= -0.10:
        return 20
    else:
        return 5


def _generate_signal(gap: float, direction: str, modifier: int, score: int) -> str:
    """Generate human-readable signal."""
    mod_str = ""
    if modifier > 0:
        mod_str = " (recovery signal)"
    elif modifier < 0:
        mod_str = " (deterioration signal)"

    if score >= 80:
        return f"BULLISH: 8MA well above 200MA (gap={gap:+.3f}, 8MA {direction}){mod_str}"
    elif score >= 60:
        return f"POSITIVE: 8MA above 200MA (gap={gap:+.3f}, 8MA {direction}){mod_str}"
    elif score >= 40:
        return f"NEUTRAL: Near crossover (gap={gap:+.3f}, 8MA {direction}){mod_str}"
    elif score >= 20:
        return f"NEGATIVE: 8MA below 200MA (gap={gap:+.3f}, 8MA {direction}){mod_str}"
    else:
        return f"BEARISH: 8MA far below 200MA (gap={gap:+.3f}, 8MA {direction}){mod_str}"

#!/usr/bin/env python3
"""
Component 1: Current Breadth Level & Trend (Weight: 25%)

The most direct indicator of market health.

Input: Breadth_Index_8MA, Breadth_200MA_Trend (latest row + 5-day lookback)

Scoring (100 = healthy):
  8MA Level (70% of component):
    >= 0.70 -> 95    >= 0.60 -> 80    >= 0.50 -> 65
    >= 0.40 -> 50    >= 0.30 -> 35    >= 0.20 -> 20
    <  0.20 -> 5

  200MA Trend (30% of component):
    Trend == 1  -> 80 (uptrend)
    Trend == -1 -> 20 (downtrend)

  8MA Direction Modifier (5-day direction):
    Falling & level > 0.60 -> -10 (deceleration from high level)
    Falling & level < 0.40 -> +5  (limited downside near bottom)
    Rising  & level < 0.60 -> +5  (early recovery bonus)
    Otherwise              ->  0

  Score = clamp(0.70 * level_score + 0.30 * trend_score + modifier, 0, 100)
"""


def calculate_breadth_level_trend(rows: list[dict]) -> dict:
    """
    Calculate current breadth level and trend score.

    Args:
        rows: All detail rows sorted by date ascending.

    Returns:
        Dict with score, signal, and component details.
    """
    if not rows:
        return {
            "score": 50,
            "signal": "NO DATA: No breadth data available",
            "data_available": False,
        }

    latest = rows[-1]
    ma8 = latest["Breadth_Index_8MA"]
    trend = latest["Breadth_200MA_Trend"]

    # 8MA level score
    level_score = _score_8ma_level(ma8)

    # Trend score
    trend_score = 80 if trend == 1 else 20

    # 8MA direction modifier
    ma8_direction, direction_modifier = _direction_modifier(rows, ma8)

    # Combined
    base = round(0.70 * level_score + 0.30 * trend_score)
    score = max(0, min(100, base + direction_modifier))

    # Signal
    signal = _generate_signal(ma8, trend, score)

    result = {
        "score": score,
        "signal": signal,
        "data_available": True,
        "current_8ma": ma8,
        "current_200ma": latest["Breadth_Index_200MA"],
        "trend": trend,
        "level_score": level_score,
        "trend_score": trend_score,
        "date": latest["Date"],
    }

    if ma8_direction is not None:
        result["ma8_direction"] = ma8_direction
        result["direction_modifier"] = direction_modifier

    return result


def _direction_modifier(rows: list[dict], current_8ma: float):
    """Calculate 8MA direction modifier based on 5-day movement.

    Returns (direction_str_or_None, modifier_int).
    """
    if len(rows) < 6:
        return None, 0

    ma8_5d_ago = rows[-6]["Breadth_Index_8MA"]

    if current_8ma > ma8_5d_ago:
        direction = "rising"
    elif current_8ma < ma8_5d_ago:
        direction = "falling"
    else:
        return "flat", 0

    if direction == "falling" and current_8ma > 0.60:
        return direction, -10
    if direction == "falling" and current_8ma < 0.40:
        return direction, 5
    if direction == "rising" and current_8ma < 0.60:
        return direction, 5

    return direction, 0


def _score_8ma_level(ma8: float) -> int:
    """Score based on 8MA level."""
    if ma8 >= 0.70:
        return 95
    elif ma8 >= 0.60:
        return 80
    elif ma8 >= 0.50:
        return 65
    elif ma8 >= 0.40:
        return 50
    elif ma8 >= 0.30:
        return 35
    elif ma8 >= 0.20:
        return 20
    else:
        return 5


def _generate_signal(ma8: float, trend: int, score: int) -> str:
    """Generate human-readable signal."""
    trend_str = "uptrend" if trend == 1 else "downtrend"

    if score >= 80:
        return f"STRONG: 8MA={ma8:.3f} in {trend_str} - broad participation"
    elif score >= 60:
        return f"HEALTHY: 8MA={ma8:.3f} in {trend_str} - above average"
    elif score >= 40:
        return f"NEUTRAL: 8MA={ma8:.3f} in {trend_str} - mixed signals"
    elif score >= 20:
        return f"WEAK: 8MA={ma8:.3f} in {trend_str} - deteriorating breadth"
    else:
        return f"CRITICAL: 8MA={ma8:.3f} in {trend_str} - severe weakness"

#!/usr/bin/env python3
"""
Market Breadth Analyzer - CSV Data Client

Fetches and parses market breadth CSV data from TraderMonty's public GitHub Pages.
No API key required.

Data sources:
  Detail:  https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv
  Summary: https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv
"""

import csv
import io
import sys
from datetime import datetime
from typing import Optional

import requests

DEFAULT_DETAIL_URL = "https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv"
DEFAULT_SUMMARY_URL = (
    "https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv"
)

DETAIL_COLUMNS = {
    "Date": str,
    "S&P500_Price": float,
    "Breadth_Index_Raw": float,
    "Breadth_Index_200MA": float,
    "Breadth_Index_8MA": float,
    "Breadth_200MA_Trend": int,
    "Bearish_Signal": bool,
    "Is_Peak": bool,
    "Is_Trough": bool,
    "Is_Trough_8MA_Below_04": bool,
}

TIMEOUT = 30


def fetch_detail_csv(url: str = DEFAULT_DETAIL_URL) -> list[dict]:
    """
    Fetch and parse the detail CSV (market_breadth_data.csv).

    Returns list of dicts sorted by date ascending (oldest first).
    """
    print(f"  Fetching detail CSV from {url}...", end=" ", flush=True)
    try:
        resp = requests.get(url, timeout=TIMEOUT)
        resp.raise_for_status()
    except requests.RequestException as e:
        print("FAILED")
        print(f"ERROR: Failed to fetch detail CSV: {e}", file=sys.stderr)
        return []

    reader = csv.DictReader(io.StringIO(resp.text))
    rows = []

    for line_num, raw_row in enumerate(reader, start=2):
        try:
            row = _parse_detail_row(raw_row)
            rows.append(row)
        except (ValueError, KeyError) as e:
            print(f"\n  WARN: Skipping line {line_num}: {e}", file=sys.stderr)

    # Validate columns
    if rows:
        missing = set(DETAIL_COLUMNS.keys()) - set(rows[0].keys())
        if missing:
            print(f"\n  WARN: Missing columns: {missing}", file=sys.stderr)

    # Sort by date ascending
    rows.sort(key=lambda r: r["Date"])

    print(f"OK ({len(rows)} rows, {rows[0]['Date']} to {rows[-1]['Date']})")
    return rows


def fetch_summary_csv(url: str = DEFAULT_SUMMARY_URL) -> dict[str, str]:
    """
    Fetch and parse the summary CSV (market_breadth_summary.csv).

    Returns dict mapping Metric -> Value.
    """
    print(f"  Fetching summary CSV from {url}...", end=" ", flush=True)
    try:
        resp = requests.get(url, timeout=TIMEOUT)
        resp.raise_for_status()
    except requests.RequestException as e:
        print("FAILED")
        print(f"ERROR: Failed to fetch summary CSV: {e}", file=sys.stderr)
        return {}

    reader = csv.DictReader(io.StringIO(resp.text))
    summary = {}
    for raw_row in reader:
        metric = raw_row.get("Metric", "").strip()
        value = raw_row.get("Value", "").strip()
        if metric:
            summary[metric] = value

    print(f"OK ({len(summary)} metrics)")
    return summary


def check_data_freshness(
    rows: list[dict], max_stale_days: int = 5, detail_url: str = DEFAULT_DETAIL_URL
) -> dict:
    """
    Check whether the latest data is reasonably fresh.
    Uses both CSV date and HTTP Last-Modified header for accuracy.

    Args:
        rows: Parsed detail rows (sorted by date ascending).
        max_stale_days: Calendar days before data is considered stale.
        detail_url: URL to check Last-Modified header against.

    Returns:
        Dict with is_fresh, latest_date, days_old, last_modified, warning.
    """
    if not rows:
        return {
            "is_fresh": False,
            "latest_date": None,
            "days_old": None,
            "last_modified": None,
            "warning": "No data available",
        }

    latest_date_str = rows[-1]["Date"]
    try:
        latest_date = datetime.strptime(latest_date_str, "%Y-%m-%d")
    except ValueError:
        return {
            "is_fresh": False,
            "latest_date": latest_date_str,
            "days_old": None,
            "last_modified": None,
            "warning": f"Cannot parse latest date: {latest_date_str}",
        }

    days_old = (datetime.now() - latest_date).days
    is_fresh = days_old <= max_stale_days

    # Check HTTP Last-Modified header for additional freshness info
    last_modified = _check_last_modified(detail_url)

    warning = None
    if not is_fresh:
        warning = (
            f"Data is {days_old} days old (latest: {latest_date_str}). "
            f"Threshold: {max_stale_days} days. Results may not reflect current conditions."
        )

    return {
        "is_fresh": is_fresh,
        "latest_date": latest_date_str,
        "days_old": days_old,
        "last_modified": last_modified,
        "warning": warning,
    }


def _check_last_modified(url: str) -> Optional[str]:
    """Check HTTP Last-Modified header via HEAD request."""
    try:
        resp = requests.head(url, timeout=10, allow_redirects=True)
        resp.raise_for_status()
        lm = resp.headers.get("Last-Modified")
        if lm:
            from email.utils import parsedate_to_datetime

            dt = parsedate_to_datetime(lm)
            return dt.strftime("%Y-%m-%d %H:%M UTC")
    except Exception:
        pass
    return None


def get_latest_n_rows(rows: list[dict], n: int) -> list[dict]:
    """Return the last n rows (most recent)."""
    return rows[-n:] if len(rows) >= n else rows[:]


def _parse_detail_row(raw: dict) -> dict:
    """Convert a raw CSV row dict to properly typed values."""
    row = {}
    row["Date"] = raw["Date"].strip()
    row["S&P500_Price"] = float(raw["S&P500_Price"])
    row["Breadth_Index_Raw"] = float(raw["Breadth_Index_Raw"])
    row["Breadth_Index_200MA"] = float(raw["Breadth_Index_200MA"])
    row["Breadth_Index_8MA"] = float(raw["Breadth_Index_8MA"])
    row["Breadth_200MA_Trend"] = int(raw["Breadth_200MA_Trend"])
    row["Bearish_Signal"] = _parse_bool(raw["Bearish_Signal"])
    row["Is_Peak"] = _parse_bool(raw["Is_Peak"])
    row["Is_Trough"] = _parse_bool(raw["Is_Trough"])
    row["Is_Trough_8MA_Below_04"] = _parse_bool(raw["Is_Trough_8MA_Below_04"])
    return row


def _parse_bool(val: str) -> bool:
    """Parse boolean from CSV string."""
    return val.strip().lower() in ("true", "1", "yes")


# Testing
if __name__ == "__main__":
    print("Testing CSV Client...\n")

    detail = fetch_detail_csv()
    print(f"  Detail rows: {len(detail)}")
    if detail:
        print(f"  First row: {detail[0]}")
        print(f"  Last row:  {detail[-1]}")

    print()
    summary = fetch_summary_csv()
    print(f"  Summary metrics: {summary}")

    print()
    freshness = check_data_freshness(detail)
    print(f"  Freshness: {freshness}")

    print("\nAll tests completed.")

#!/usr/bin/env python3
"""
Market Breadth Analyzer - Score History Tracker

Persists composite scores keyed by data date (the latest date in the CSV),
enabling trend analysis across consecutive runs.

History file format: JSON array of entries, each with:
  - data_date: str (YYYY-MM-DD) — the date of the analyzed data
  - composite_score: float (0-100)
  - component_scores: dict (component key -> score)
  - recorded_at: str (ISO timestamp of when the entry was recorded)

Max 20 entries retained; oldest pruned first.
Same data_date re-run overwrites the existing entry.
"""

import json
import os
from datetime import datetime
from typing import Any


def load_history(path: str) -> list[dict]:
    """Load history from JSON file. Returns [] on missing/corrupt file."""
    if not os.path.exists(path):
        return []
    try:
        with open(path) as f:
            content = f.read().strip()
            if not content:
                return []
            data = json.loads(content)
            if isinstance(data, list):
                return data
            return []
    except (json.JSONDecodeError, OSError):
        return []


def append_history(
    path: str,
    composite_score: float,
    component_scores: dict[str, Any],
    data_date: str,
) -> list[dict]:
    """Append or overwrite an entry for *data_date*, then save.

    Returns the updated history list.
    """
    history = load_history(path)

    entry = {
        "data_date": data_date,
        "composite_score": composite_score,
        "component_scores": component_scores,
        "recorded_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
    }

    # Overwrite if same data_date exists
    history = [h for h in history if h.get("data_date") != data_date]
    history.append(entry)

    # Sort by data_date ascending
    history.sort(key=lambda h: h.get("data_date", ""))

    # Prune to max 20 entries
    if len(history) > 20:
        history = history[-20:]

    with open(path, "w") as f:
        json.dump(history, f, indent=2, default=str)

    return history


def get_trend_summary(history: list[dict], n: int = 5) -> dict:
    """Compute trend direction from the last *n* entries.

    Returns:
        Dict with delta, direction ("improving"/"deteriorating"/"stable"),
        and the entries used.
    """
    if not history:
        return {"delta": 0, "direction": "stable", "entries": []}

    recent = history[-n:]

    if len(recent) < 2:
        return {
            "delta": 0,
            "direction": "stable",
            "entries": recent,
        }

    first_score = recent[0]["composite_score"]
    last_score = recent[-1]["composite_score"]
    delta = round(last_score - first_score, 1)

    if delta > 2:
        direction = "improving"
    elif delta < -2:
        direction = "deteriorating"
    else:
        direction = "stable"

    return {
        "delta": delta,
        "direction": direction,
        "entries": recent,
    }

#!/usr/bin/env python3
"""
Market Breadth Analyzer - Main Orchestrator

Quantifies market breadth health using TraderMonty's public CSV data.
Generates a 0-100 composite score across 6 components.
No API key required.

Usage:
    # Default (uses public CSV URLs):
    python3 market_breadth_analyzer.py

    # Custom URLs:
    python3 market_breadth_analyzer.py \\
        --detail-url "https://example.com/data.csv" \\
        --summary-url "https://example.com/summary.csv"

    # Custom output directory:
    python3 market_breadth_analyzer.py --output-dir ./reports

Output:
    - JSON: market_breadth_YYYY-MM-DD_HHMMSS.json
    - Markdown: market_breadth_YYYY-MM-DD_HHMMSS.md
"""

import argparse
import os
import sys
from datetime import datetime

# Add parent directory to path for imports
sys.path.insert(0, os.path.dirname(__file__))

from calculators.bearish_signal_calculator import calculate_bearish_signal
from calculators.cycle_calculator import calculate_cycle_position
from calculators.divergence_calculator import calculate_divergence
from calculators.historical_context_calculator import calculate_historical_percentile
from calculators.ma_crossover_calculator import calculate_ma_crossover
from calculators.trend_level_calculator import calculate_breadth_level_trend
from csv_client import (
    DEFAULT_DETAIL_URL,
    DEFAULT_SUMMARY_URL,
    check_data_freshness,
    fetch_detail_csv,
    fetch_summary_csv,
)
from history_tracker import append_history, get_trend_summary
from report_generator import generate_json_report, generate_markdown_report
from scorer import calculate_composite_score


def parse_arguments():
    parser = argparse.ArgumentParser(
        description="Market Breadth Analyzer - 6-Component Health Scoring"
    )

    parser.add_argument(
        "--detail-url",
        default=DEFAULT_DETAIL_URL,
        help="URL for detail CSV (market_breadth_data.csv)",
    )
    parser.add_argument(
        "--summary-url",
        default=DEFAULT_SUMMARY_URL,
        help="URL for summary CSV (market_breadth_summary.csv)",
    )
    parser.add_argument(
        "--output-dir",
        default=".",
        help="Output directory for reports (default: current directory)",
    )

    return parser.parse_args()


def main():
    args = parse_arguments()

    print("=" * 70)
    print("Market Breadth Analyzer")
    print("6-Component Health Scoring (No API Key Required)")
    print("=" * 70)
    print()

    # ========================================================================
    # Step 1: Fetch CSV Data
    # ========================================================================
    print("Step 1: Fetching CSV Data")
    print("-" * 70)

    detail_rows = fetch_detail_csv(args.detail_url)
    if not detail_rows:
        print("ERROR: Cannot proceed without detail CSV data", file=sys.stderr)
        sys.exit(1)

    summary = fetch_summary_csv(args.summary_url)

    freshness = check_data_freshness(detail_rows)
    if freshness.get("warning"):
        print(f"  WARNING: {freshness['warning']}")
    else:
        print(
            f"  Data freshness: OK "
            f"(latest: {freshness['latest_date']}, {freshness['days_old']} days old)"
        )

    print()

    # ========================================================================
    # Step 2: Calculate Components
    # ========================================================================
    print("Step 2: Calculating Components")
    print("-" * 70)

    # Component 1: Current Breadth Level & Trend (25%)
    print("  [1/6] Current Breadth Level & Trend...", end=" ", flush=True)
    comp1 = calculate_breadth_level_trend(detail_rows)
    print(f"Score: {comp1['score']} ({comp1['signal']})")

    # Component 2: 8MA vs 200MA Crossover (20%)
    print("  [2/6] 8MA vs 200MA Crossover...", end=" ", flush=True)
    comp2 = calculate_ma_crossover(detail_rows)
    print(f"Score: {comp2['score']} ({comp2['signal']})")

    # Component 3: Peak/Trough Cycle Position (20%)
    print("  [3/6] Peak/Trough Cycle Position...", end=" ", flush=True)
    comp3 = calculate_cycle_position(detail_rows)
    print(f"Score: {comp3['score']} ({comp3['signal']})")

    # Component 4: Bearish Signal Status (15%)
    print("  [4/6] Bearish Signal Status...", end=" ", flush=True)
    comp4 = calculate_bearish_signal(detail_rows)
    print(f"Score: {comp4['score']} ({comp4['signal']})")

    # Component 5: Historical Percentile (10%)
    print("  [5/6] Historical Percentile...", end=" ", flush=True)
    comp5 = calculate_historical_percentile(detail_rows, summary)
    print(f"Score: {comp5['score']} ({comp5['signal']})")

    # Component 6: S&P 500 vs Breadth Divergence (10%)
    print("  [6/6] S&P 500 vs Breadth Divergence...", end=" ", flush=True)
    comp6 = calculate_divergence(detail_rows)
    print(f"Score: {comp6['score']} ({comp6['signal']})")

    print()

    # ========================================================================
    # Step 3: Composite Score
    # ========================================================================
    print("Step 3: Calculating Composite Score")
    print("-" * 70)

    component_scores = {
        "breadth_level_trend": comp1["score"],
        "ma_crossover": comp2["score"],
        "cycle_position": comp3["score"],
        "bearish_signal": comp4["score"],
        "historical_percentile": comp5["score"],
        "divergence": comp6["score"],
    }

    data_availability = {
        "breadth_level_trend": comp1.get("data_available", True),
        "ma_crossover": comp2.get("data_available", True),
        "cycle_position": comp3.get("data_available", True),
        "bearish_signal": comp4.get("data_available", True),
        "historical_percentile": comp5.get("data_available", True),
        "divergence": comp6.get("data_available", True),
    }

    composite = calculate_composite_score(component_scores, data_availability)

    print(f"  Composite Score: {composite['composite_score']}/100")
    print(f"  Health Zone: {composite['zone']}")
    print(f"  Equity Exposure: {composite['exposure_guidance']}")
    print(
        f"  Strongest: {composite['strongest_health']['label']} "
        f"({composite['strongest_health']['score']})"
    )
    print(
        f"  Weakest: {composite['weakest_health']['label']} "
        f"({composite['weakest_health']['score']})"
    )
    print()

    # ========================================================================
    # Step 3.5: Score History & Trend
    # ========================================================================
    data_date = detail_rows[-1]["Date"]
    history_file = os.path.join(args.output_dir, "market_breadth_history.json")
    updated_history = append_history(
        history_file,
        composite["composite_score"],
        component_scores,
        data_date,
    )
    trend_summary = get_trend_summary(updated_history)
    if trend_summary["direction"] != "stable" and len(trend_summary["entries"]) >= 2:
        print(
            f"  Score Trend: {trend_summary['direction']} "
            f"(delta {trend_summary['delta']:+.1f} over "
            f"{len(trend_summary['entries'])} observations)"
        )
    print()

    # ========================================================================
    # Step 4: Key Levels
    # ========================================================================
    key_levels = _compute_key_levels(detail_rows, summary)

    # ========================================================================
    # Step 5: Generate Reports
    # ========================================================================
    print("Step 4: Generating Reports")
    print("-" * 70)

    analysis = {
        "metadata": {
            "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
            "data_source": "TraderMonty Market Breadth CSV",
            "detail_url": args.detail_url,
            "summary_url": args.summary_url,
            "total_rows": len(detail_rows),
            "data_freshness": freshness,
        },
        "composite": composite,
        "components": {
            "breadth_level_trend": comp1,
            "ma_crossover": comp2,
            "cycle_position": comp3,
            "bearish_signal": comp4,
            "historical_percentile": comp5,
            "divergence": comp6,
        },
        "trend_summary": trend_summary,
        "key_levels": key_levels,
    }

    timestamp = datetime.now().strftime("%Y-%m-%d_%H%M%S")
    json_file = os.path.join(args.output_dir, f"market_breadth_{timestamp}.json")
    md_file = os.path.join(args.output_dir, f"market_breadth_{timestamp}.md")

    generate_json_report(analysis, json_file)
    generate_markdown_report(analysis, md_file)

    print()
    print("=" * 70)
    print("Market Breadth Analysis Complete")
    print("=" * 70)
    print(f"  Composite Score: {composite['composite_score']}/100")
    print(f"  Health Zone: {composite['zone']}")
    print(f"  Equity Exposure: {composite['exposure_guidance']}")
    print(f"  JSON Report: {json_file}")
    print(f"  Markdown Report: {md_file}")
    print()


def _compute_key_levels(rows, summary):
    """Compute key breadth levels to watch."""
    if not rows:
        return {}

    latest = rows[-1]
    latest["Breadth_Index_8MA"]
    ma200 = latest["Breadth_Index_200MA"]

    levels = {}

    # 200MA crossover level
    levels["200MA Level"] = {
        "value": f"{ma200:.4f}",
        "significance": (
            "Key support/resistance for 8MA. "
            "8MA crossing below is an early warning of deterioration, "
            "not a standalone bearish signal."
        ),
    }

    # 0.40 extreme weakness threshold
    levels["Extreme Weakness (0.40)"] = {
        "value": "0.4000",
        "significance": (
            "8MA below 0.40 marks extreme weakness. "
            "Historically, troughs at this level precede significant rallies."
        ),
    }

    # 0.60 healthy threshold
    levels["Healthy Threshold (0.60)"] = {
        "value": "0.6000",
        "significance": (
            "8MA above 0.60 indicates broad participation. "
            "Below 0.60 = selective market, above = inclusive rally."
        ),
    }

    # Average peak from summary
    avg_peak_str = summary.get("Average Peaks (200MA)", "")
    try:
        avg_peak = float(avg_peak_str)
        levels["Historical Avg Peak"] = {
            "value": f"{avg_peak:.3f}",
            "significance": (
                "Average peak level. Approaching this level suggests "
                "breadth may be near a cyclical high."
            ),
        }
    except (ValueError, TypeError):
        pass

    # Average trough from summary
    avg_trough_str = summary.get("Average Troughs (8MA < 0.4)", "")
    try:
        avg_trough = float(avg_trough_str)
        levels["Historical Avg Trough"] = {
            "value": f"{avg_trough:.3f}",
            "significance": (
                "Average extreme trough level. Reaching this level "
                "is a potential contrarian buy signal."
            ),
        }
    except (ValueError, TypeError):
        pass

    return levels


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Market Breadth Analyzer - Report Generator

Generates JSON and Markdown reports for market breadth health analysis.
"""

import json


def generate_json_report(analysis: dict, output_file: str):
    """Save full analysis as JSON."""
    with open(output_file, "w") as f:
        json.dump(analysis, f, indent=2, default=str)
    print(f"  JSON report saved to: {output_file}")


def generate_markdown_report(analysis: dict, output_file: str):
    """Generate comprehensive Markdown report."""
    lines = []
    composite = analysis.get("composite", {})
    components = analysis.get("components", {})
    metadata = analysis.get("metadata", {})
    freshness = metadata.get("data_freshness", {})

    score = composite.get("composite_score", 0)
    zone = composite.get("zone", "Unknown")
    exposure = composite.get("exposure_guidance", "N/A")

    # Header
    lines.append("# Market Breadth Analyzer Report")
    lines.append("")
    lines.append(f"**Generated:** {metadata.get('generated_at', 'N/A')}")
    lines.append("**Data Source:** TraderMonty Market Breadth CSV (no API key required)")
    latest = freshness.get("latest_date", "N/A")
    days_old = freshness.get("days_old", "?")
    last_modified = freshness.get("last_modified")
    lm_str = f" | CSV last modified: {last_modified}" if last_modified else ""
    lines.append(f"**Latest Data:** {latest} ({days_old} days old{lm_str})")
    lines.append(
        "**Live Dashboard:** [Interactive Chart]"
        "(https://tradermonty.github.io/market-breadth-analysis/)"
    )
    lines.append("")

    # Freshness warning
    warning = freshness.get("warning")
    if warning:
        lines.append(f"> **WARNING:** {warning}")
        lines.append("")

    # Overall Assessment
    lines.append("---")
    lines.append("")
    lines.append("## Overall Assessment")
    lines.append("")
    zone_emoji = _zone_emoji(composite.get("zone_color", ""))
    lines.append("| Metric | Value |")
    lines.append("|--------|-------|")
    lines.append(f"| **Composite Score** | **{score}/100** |")
    lines.append(f"| **Health Zone** | {zone_emoji} {zone} |")
    lines.append(f"| **Equity Exposure** | {exposure} |")
    lines.append(
        f"| **Strongest** | {composite.get('strongest_health', {}).get('label', 'N/A')} "
        f"({composite.get('strongest_health', {}).get('score', 0)}/100) |"
    )
    lines.append(
        f"| **Weakest** | {composite.get('weakest_health', {}).get('label', 'N/A')} "
        f"({composite.get('weakest_health', {}).get('score', 0)}/100) |"
    )
    dq = composite.get("data_quality", {})
    if dq:
        lines.append(f"| **Data Quality** | {dq.get('label', 'N/A')} |")
    lines.append("")

    # Guidance
    lines.append(f"> **Guidance:** {composite.get('guidance', '')}")
    c1_mod = components.get("breadth_level_trend", {}).get("direction_modifier", 0)
    c2_mod = components.get("ma_crossover", {}).get("direction_modifier", 0)
    if c1_mod < 0 or c2_mod < 0:
        lines.append(
            f"> **Caution:** 8MA is falling "
            f"(C1 modifier: {c1_mod:+d}, C2 modifier: {c2_mod:+d}). "
            f"Monitor for further deterioration."
        )
    lines.append("")

    # Component Scores Table
    lines.append("---")
    lines.append("")
    lines.append("## Component Scores")
    lines.append("")
    lines.append("| # | Component | Weight | Eff. Weight | Score | Contribution | Signal |")
    lines.append("|---|-----------|--------|-------------|-------|--------------|--------|")

    component_order = [
        "breadth_level_trend",
        "ma_crossover",
        "cycle_position",
        "bearish_signal",
        "historical_percentile",
        "divergence",
    ]

    excluded_components = composite.get("excluded_components", [])

    for i, key in enumerate(component_order, 1):
        comp = composite.get("component_scores", {}).get(key, {})
        detail = components.get(key, {})
        signal = detail.get("signal", "N/A")
        score_val = int(round(comp.get("score", 0)))
        weight_pct = f"{comp.get('weight', 0) * 100:.0f}%"
        eff_weight = comp.get("effective_weight", comp.get("weight", 0))
        eff_weight_pct = f"{eff_weight * 100:.0f}%"
        contribution = comp.get("weighted_contribution", 0)
        is_excluded = not comp.get("data_available", True)
        bar = _score_bar(score_val)

        label = comp.get("label", key)
        if is_excluded:
            label += " (excluded)"

        lines.append(
            f"| {i} | **{label}** | {weight_pct} | {eff_weight_pct} | "
            f"{bar} {score_val} | {contribution:.1f} | {signal} |"
        )

    lines.append("")

    if excluded_components:
        lines.append(
            f"> **Note:** {len(excluded_components)} component(s) excluded due to "
            f"insufficient data: {', '.join(excluded_components)}. "
            f"Weights have been redistributed among available components."
        )
        lines.append("")

    # Component Details
    lines.append("---")
    lines.append("")
    lines.append("## Component Details")
    lines.append("")

    # C1: Breadth Level & Trend
    c1 = components.get("breadth_level_trend", {})
    lines.append("### 1. Current Breadth Level & Trend")
    lines.append("")
    if c1:
        lines.append(f"- **8MA Level:** {c1.get('current_8ma', 0):.4f}")
        lines.append(f"- **200MA Level:** {c1.get('current_200ma', 0):.4f}")
        lines.append(f"- **200MA Trend:** {'Uptrend' if c1.get('trend') == 1 else 'Downtrend'}")
        lines.append(f"- **Level Score:** {c1.get('level_score', 'N/A')}")
        lines.append(f"- **Trend Score:** {c1.get('trend_score', 'N/A')}")
        if c1.get("ma8_direction"):
            lines.append(f"- **8MA Direction (5d):** {c1['ma8_direction']}")
            modifier = c1.get("direction_modifier", 0)
            if modifier != 0:
                lines.append(f"- **Direction Modifier:** {modifier:+d}")
    lines.append("")

    # C2: MA Crossover
    c2 = components.get("ma_crossover", {})
    lines.append("### 2. 8MA vs 200MA Crossover Dynamics")
    lines.append("")
    if c2:
        lines.append(f"- **Gap (8MA - 200MA):** {c2.get('gap', 0):+.4f}")
        lines.append(f"- **Gap Score:** {c2.get('gap_score', 'N/A')}")
        lines.append(f"- **8MA Direction (5d):** {c2.get('ma8_direction', 'N/A')}")
        lines.append(f"- **Direction Modifier:** {c2.get('direction_modifier', 0):+d}")
    lines.append("")

    # C3: Cycle Position
    c3 = components.get("cycle_position", {})
    lines.append("### 3. Peak/Trough Cycle Position")
    lines.append("")
    if c3:
        lines.append(f"- **Latest Marker:** {c3.get('latest_marker_type', 'None')}")
        lines.append(f"- **Days Since Marker:** {c3.get('days_since_marker', 'N/A')}")
        lines.append(f"- **8MA Trend:** {c3.get('ma8_trend', 'N/A')}")
        if c3.get("extreme_trough"):
            lines.append("- **Extreme Trough (8MA < 0.4):** Yes (+10 bonus)")
    lines.append("")

    # C4: Bearish Signal
    c4 = components.get("bearish_signal", {})
    lines.append("### 4. Bearish Signal Status")
    lines.append("")
    if c4:
        lines.append(f"- **Bearish Signal Active:** {'YES' if c4.get('signal_active') else 'No'}")
        lines.append(f"- **200MA Trend:** {'Uptrend' if c4.get('trend') == 1 else 'Downtrend'}")
        lines.append(f"- **Current 8MA:** {c4.get('current_8ma', 0):.4f}")
        in_pink = c4.get("in_pink_zone", False)
        pink_days = c4.get("pink_zone_days", 0)
        if in_pink:
            lines.append(
                f"- **Pink Zone:** YES ({pink_days} consecutive days) "
                f"- 200MA downtrend + 8MA below 200MA"
            )
        else:
            lines.append("- **Pink Zone:** No (outside bearish region)")
        lines.append(f"- **Base Score:** {c4.get('base_score', 'N/A')}")
        lines.append(f"- **Context Adjustment:** {c4.get('context_adjustment', 0):+d}")
        pink_adj = c4.get("pink_zone_adjustment", 0)
        if pink_adj != 0:
            lines.append(f"- **Pink Zone Adjustment:** {pink_adj:+d}")
    lines.append("")

    # C5: Historical Percentile
    c5 = components.get("historical_percentile", {})
    lines.append("### 5. Historical Percentile")
    lines.append("")
    if c5:
        lines.append(f"- **Current 8MA:** {c5.get('current_8ma', 0):.4f}")
        lines.append(f"- **Percentile Rank:** {c5.get('percentile_rank', 'N/A'):.1f}%")
        lines.append(f"- **Avg Peak (200MA):** {c5.get('avg_peak', 'N/A')}")
        lines.append(f"- **Avg Trough (8MA<0.4):** {c5.get('avg_trough', 'N/A')}")
        adj = c5.get("adjustment", 0)
        if adj != 0:
            label = "Overheated (-10)" if adj < 0 else "Oversold (+10)"
            lines.append(f"- **Adjustment:** {label}")
    lines.append("")

    # C6: Divergence
    c6 = components.get("divergence", {})
    lines.append("### 6. S&P 500 vs Breadth Divergence")
    lines.append("")
    if c6:
        lines.append(f"- **S&P 500 60d Change:** {c6.get('sp500_pct_change', 0):+.2f}%")
        lines.append(f"- **Breadth 8MA 60d Change:** {c6.get('breadth_change', 0):+.4f}")
        lines.append(f"- **Divergence Type:** {c6.get('divergence_type', 'N/A')}")

        # Dual-window details (new)
        w60 = c6.get("window_60d")
        w20 = c6.get("window_20d")
        if w60 and w20:
            lines.append("")
            lines.append(
                f"- **60-Day Window:** Score {w60['score']}, "
                f"{w60['divergence_type']} "
                f"(lookback: {w60.get('lookback_days', 60)}d)"
            )
            lines.append(
                f"- **20-Day Window:** Score {w20['score']}, "
                f"{w20['divergence_type']} "
                f"(lookback: {w20.get('lookback_days', 20)}d)"
            )

        if c6.get("early_warning"):
            lines.append("")
            lines.append(
                "> **Early Warning:** Short-term (20d) bearish divergence "
                "detected while long-term (60d) trend remains healthy. "
                "Monitor for potential deterioration."
            )
    lines.append("")

    # Score Trend (show N/A for single entry, full table for 2+)
    trend_summary = analysis.get("trend_summary")
    if trend_summary and len(trend_summary.get("entries", [])) >= 1:
        entries = trend_summary["entries"]
        lines.append("---")
        lines.append("")
        lines.append("## Score Trend")
        lines.append("")
        if len(entries) == 1:
            lines.append("**Direction:** N/A (single observation — trend requires 2+ data points)")
        else:
            direction = trend_summary["direction"].capitalize()
            delta = trend_summary["delta"]
            lines.append(
                f"**Direction:** {direction} ({delta:+.1f} over {len(entries)} observations)"
            )
            lines.append("")
            lines.append("| Date | Score |")
            lines.append("|------|-------|")
            for entry in entries:
                lines.append(f"| {entry['data_date']} | {entry['composite_score']:.1f} |")
        lines.append("")

    # Key Levels to Watch
    lines.append("---")
    lines.append("")
    lines.append("## Key Levels to Watch")
    lines.append("")
    key_levels = analysis.get("key_levels", {})
    if key_levels:
        lines.append("| Level | Value | Significance |")
        lines.append("|-------|-------|-------------|")
        for level_name, level_info in key_levels.items():
            lines.append(
                f"| {level_name} | {level_info.get('value', 'N/A')} | "
                f"{level_info.get('significance', '')} |"
            )
    else:
        lines.append("*No key levels computed.*")
    lines.append("")

    # Recommended Actions
    lines.append("---")
    lines.append("")
    lines.append("## Recommended Actions")
    lines.append("")
    lines.append(f"**Health Zone:** {zone}")
    lines.append(f"**Equity Exposure:** {exposure}")
    lines.append("")
    for action in composite.get("actions", []):
        lines.append(f"- {action}")
    # Inject cautionary actions when 8MA is falling
    c1_mod_act = components.get("breadth_level_trend", {}).get("direction_modifier", 0)
    c2_mod_act = components.get("ma_crossover", {}).get("direction_modifier", 0)
    if c1_mod_act < 0 or c2_mod_act < 0:
        lines.append("- Reduce new position sizes until 8MA stabilizes")
        lines.append("- Tighten stop-loss levels on existing positions")
    lines.append("")

    # Methodology
    lines.append("---")
    lines.append("")
    lines.append("## Methodology")
    lines.append("")
    lines.append(
        "This analysis uses TraderMonty's market breadth dataset to quantify "
        "market participation health across 6 dimensions:"
    )
    lines.append("")
    lines.append("1. **Breadth Level & Trend (25%):** Current 8MA level and 200MA trend direction")
    lines.append("2. **MA Crossover (20%):** Gap between 8MA and 200MA with momentum detection")
    lines.append("3. **Cycle Position (20%):** Position relative to recent peaks/troughs")
    lines.append("4. **Bearish Signal (15%):** Backtested bearish signal flag from dataset")
    lines.append("5. **Historical Percentile (10%):** Current level vs full history distribution")
    lines.append("6. **Divergence (10%):** S&P 500 price vs breadth directional agreement")
    lines.append("")
    lines.append(
        "Composite score: 0-100 (100 = maximum health). "
        "No API key required - uses freely available CSV data."
    )
    lines.append("")
    lines.append("For detailed methodology, see `references/breadth_analysis_methodology.md`.")
    lines.append("")

    # Disclaimer
    lines.append("---")
    lines.append("")
    lines.append(
        "**Disclaimer:** This analysis is for educational and informational purposes only. "
        "Not investment advice. Past patterns may not predict future outcomes. "
        "Conduct your own research and consult a financial advisor before making "
        "investment decisions."
    )
    lines.append("")

    with open(output_file, "w") as f:
        f.write("\n".join(lines))

    print(f"  Markdown report saved to: {output_file}")


def _zone_emoji(color: str) -> str:
    mapping = {
        "green": "🟢",
        "blue": "🔵",
        "yellow": "🟡",
        "orange": "🟠",
        "red": "🔴",
    }
    return mapping.get(color, "⚪")


def _score_bar(score: int) -> str:
    """Text bar for score visualization (100 = full/healthy)."""
    if score >= 80:
        return "████"
    elif score >= 60:
        return "███░"
    elif score >= 40:
        return "██░░"
    elif score >= 20:
        return "█░░░"
    else:
        return "░░░░"