Uptrend Analyzer

# Uptrend Analyzer - Calculator modules

#!/usr/bin/env python3
"""
Component 5: Historical Context - Weight: 10%

Evaluates the current uptrend ratio relative to its full historical
distribution (2023/08~present) using percentile rank.

Data Source: Timeseries "all" worksheet

Score = percentile rank of current ratio in historical distribution
Additional context: min, max, median, 30d avg, 90d avg
"""

from typing import Optional


def calculate_historical_context(all_timeseries: list[dict]) -> dict:
    """
    Calculate historical context score via percentile rank.

    Args:
        all_timeseries: Full "all" timeseries sorted by date ascending

    Returns:
        Dict with score (0-100), signal, and context fields
    """
    if not all_timeseries:
        return {
            "score": 50,
            "signal": "NO DATA: Historical timeseries unavailable (neutral default)",
            "data_available": False,
            "percentile": None,
            "current_ratio": None,
            "historical_min": None,
            "historical_max": None,
            "historical_median": None,
        }

    # Extract all valid ratios
    ratios = [r["ratio"] for r in all_timeseries if r.get("ratio") is not None]

    if len(ratios) < 2:
        return {
            "score": 50,
            "signal": "INSUFFICIENT DATA: Need at least 2 data points",
            "data_available": False,
            "percentile": None,
            "current_ratio": None,
            "data_points": len(ratios),
        }

    current_ratio = ratios[-1]

    # Calculate percentile rank
    below_count = sum(1 for r in ratios if r < current_ratio)
    equal_count = sum(1 for r in ratios if r == current_ratio)
    percentile = (below_count + equal_count * 0.5) / len(ratios) * 100
    percentile = round(percentile, 1)

    # Score = percentile rank (direct mapping)
    score = round(min(100, max(0, percentile)))

    # Historical statistics
    sorted_ratios = sorted(ratios)
    hist_min = sorted_ratios[0]
    hist_max = sorted_ratios[-1]
    n = len(sorted_ratios)
    if n % 2 == 0:
        hist_median = (sorted_ratios[n // 2 - 1] + sorted_ratios[n // 2]) / 2
    else:
        hist_median = sorted_ratios[n // 2]

    # Recent averages
    avg_30d = _avg_last_n(ratios, 30)
    avg_90d = _avg_last_n(ratios, 90)

    signal = _build_signal(score, percentile, current_ratio)

    # Assess confidence of historical analysis
    confidence = _assess_confidence(ratios)

    # Append confidence caveat to signal if low
    if confidence["confidence_level"] in ("Low", "Very Low"):
        signal += f" [confidence: {confidence['confidence_level']}]"

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "percentile": percentile,
        "current_ratio": current_ratio,
        "current_ratio_pct": round(current_ratio * 100, 1),
        "historical_min": round(hist_min, 4),
        "historical_min_pct": round(hist_min * 100, 1),
        "historical_max": round(hist_max, 4),
        "historical_max_pct": round(hist_max * 100, 1),
        "historical_median": round(hist_median, 4),
        "historical_median_pct": round(hist_median * 100, 1),
        "avg_30d": round(avg_30d, 4) if avg_30d is not None else None,
        "avg_30d_pct": round(avg_30d * 100, 1) if avg_30d is not None else None,
        "avg_90d": round(avg_90d, 4) if avg_90d is not None else None,
        "avg_90d_pct": round(avg_90d * 100, 1) if avg_90d is not None else None,
        "data_points": len(ratios),
        "date_range": f"{all_timeseries[0].get('date', '?')} to {all_timeseries[-1].get('date', '?')}",
        "confidence": confidence,
    }


def _assess_confidence(ratios: list[float]) -> dict:
    """Assess confidence level of percentile analysis.

    Evaluates:
    - Sample size: >=1000 full, 500-999 moderate, 200-499 limited, <200 minimal
    - Regime coverage: Has bear data (min<10%) AND bull data (max>40%)
    - Recency bias: Whether recent 90 days span less than 30% of full range

    Returns:
        Dict with confidence_level, confidence_score, regime details
    """
    n = len(ratios)

    # Sample size assessment
    if n >= 1000:
        size_score = 3
        size_label = "full"
    elif n >= 500:
        size_score = 2
        size_label = "moderate"
    elif n >= 200:
        size_score = 1
        size_label = "limited"
    else:
        size_score = 0
        size_label = "minimal"

    # Regime coverage
    hist_min = min(ratios) if ratios else 0
    hist_max = max(ratios) if ratios else 0
    has_bear = hist_min < 0.10  # Below 10%
    has_bull = hist_max > 0.40  # Above 40%

    if has_bear and has_bull:
        regime_coverage = "Both"
        regime_score = 2
    elif has_bear or has_bull:
        regime_coverage = "Partial"
        regime_score = 1
    else:
        regime_coverage = "Narrow"
        regime_score = 0

    # Recency bias
    full_range = hist_max - hist_min if hist_max != hist_min else 1.0
    recent_90 = ratios[-90:] if len(ratios) >= 90 else ratios
    recent_range = max(recent_90) - min(recent_90) if len(recent_90) >= 2 else 0
    recency_ratio = recent_range / full_range if full_range > 0 else 0

    if recency_ratio >= 0.30:
        recency_label = "balanced"
        recency_score = 1
    else:
        recency_label = "biased"
        recency_score = 0

    # Overall confidence
    total_score = size_score + regime_score + recency_score
    if total_score >= 5:
        confidence_level = "High"
    elif total_score >= 3:
        confidence_level = "Moderate"
    elif total_score >= 1:
        confidence_level = "Low"
    else:
        confidence_level = "Very Low"

    return {
        "confidence_level": confidence_level,
        "confidence_score": total_score,
        "sample_size": n,
        "sample_label": size_label,
        "has_bear_data": has_bear,
        "has_bull_data": has_bull,
        "regime_coverage": regime_coverage,
        "recency_label": recency_label,
    }


def _avg_last_n(values: list[float], n: int) -> Optional[float]:
    """Average of the last n values, or all if fewer than n."""
    if not values:
        return None
    subset = values[-n:]
    return sum(subset) / len(subset)


def _build_signal(score: int, percentile: float, current_ratio: float) -> str:
    """Build human-readable signal."""
    ratio_pct = round(current_ratio * 100, 1)

    if score >= 80:
        return f"ABOVE AVERAGE: {ratio_pct}% at {percentile}th percentile historically"
    elif score >= 60:
        return f"SLIGHTLY ABOVE: {ratio_pct}% at {percentile}th percentile historically"
    elif score >= 40:
        return f"NEAR MEDIAN: {ratio_pct}% at {percentile}th percentile historically"
    elif score >= 20:
        return f"BELOW AVERAGE: {ratio_pct}% at {percentile}th percentile historically"
    else:
        return f"HISTORICALLY LOW: {ratio_pct}% at {percentile}th percentile historically"

#!/usr/bin/env python3
"""
Component 1: Market Breadth (Overall) - Weight: 30%

Evaluates the overall market uptrend ratio level and trend direction.
Primary signal: ratio level mapped to scoring bands with trend adjustment.

Data Source: Timeseries "all" worksheet

Thresholds aligned with Monty's dashboard:
  - Overbought: 37% (upper threshold)
  - Oversold: 9.7% (lower threshold)

Scoring Bands (linear interpolation within each band):
  >= 50%    -> 90-100 (Strong Bull)
  37-50%    -> 70-89  (Bullish / above overbought threshold)
  25-37%    -> 40-69  (Neutral/Recovering)
  9.7-25%   -> 10-39  (Weak / between thresholds)
  < 9.7%    -> 0-9    (Crisis / below oversold threshold)

Trend adjustment: trend="up" & slope>0 -> +5, trend="down" & slope<0 -> -5
"""

from typing import Optional

# Monty's official dashboard thresholds
UPPER_THRESHOLD = 0.37  # Overbought
LOWER_THRESHOLD = 0.097  # Oversold


def calculate_market_breadth(latest_all: Optional[dict], all_timeseries: list[dict]) -> dict:
    """
    Calculate market breadth score from overall uptrend ratio.

    Args:
        latest_all: Most recent "all" timeseries row
        all_timeseries: Full "all" timeseries sorted by date ascending

    Returns:
        Dict with score (0-100), signal, and detail fields
    """
    if not latest_all or latest_all.get("ratio") is None:
        return {
            "score": 50,
            "signal": "NO DATA: Overall uptrend ratio unavailable (neutral default)",
            "data_available": False,
            "ratio": None,
            "ma_10": None,
            "trend": None,
            "slope": None,
            "distance_from_upper": None,
            "distance_from_lower": None,
        }

    ratio = latest_all["ratio"]
    ma_10 = latest_all.get("ma_10")
    trend = latest_all.get("trend", "")
    slope = latest_all.get("slope")

    # Map ratio to base score via linear interpolation
    base_score = _ratio_to_score(ratio)

    # Trend adjustment
    trend_adj = 0
    if trend.lower() == "up" and slope is not None and slope > 0:
        trend_adj = 5
    elif trend.lower() == "down" and slope is not None and slope < 0:
        trend_adj = -5

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

    # Signal label
    signal = _score_to_signal(score, ratio, trend)

    # Key distances from Monty's official thresholds
    distance_from_upper = round(ratio - UPPER_THRESHOLD, 4) if ratio is not None else None
    distance_from_lower = round(ratio - LOWER_THRESHOLD, 4) if ratio is not None else None

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "ratio": ratio,
        "ratio_pct": round(ratio * 100, 1) if ratio is not None else None,
        "ma_10": ma_10,
        "ma_10_pct": round(ma_10 * 100, 1) if ma_10 is not None else None,
        "trend": trend,
        "slope": slope,
        "trend_adjustment": trend_adj,
        "distance_from_upper": distance_from_upper,
        "distance_from_lower": distance_from_lower,
        "upper_threshold": UPPER_THRESHOLD,
        "lower_threshold": LOWER_THRESHOLD,
        "date": latest_all.get("date", "N/A"),
    }


def _ratio_to_score(ratio: float) -> float:
    """Map uptrend ratio (0-1 scale) to base score (0-100).

    Aligned with Monty's dashboard thresholds:
      Upper (Overbought) = 0.37, Lower (Oversold) = 0.097

    Scoring bands with linear interpolation:
      >= 0.50  -> 90-100 (Strong Bull)
      0.37-0.50 -> 70-89 (Bullish, above overbought)
      0.25-0.37 -> 40-69 (Neutral/Recovering)
      0.097-0.25 -> 10-39 (Weak, between thresholds)
      < 0.097  -> 0-9   (Crisis, below oversold)
    """
    if ratio >= 0.50:
        # 0.50 -> 90, 0.60+ -> 100
        return min(100, 90 + (ratio - 0.50) / 0.10 * 10)
    elif ratio >= UPPER_THRESHOLD:
        # 0.37 -> 70, 0.50 -> 89
        return 70 + (ratio - UPPER_THRESHOLD) / (0.50 - UPPER_THRESHOLD) * 19
    elif ratio >= 0.25:
        # 0.25 -> 40, 0.37 -> 69
        return 40 + (ratio - 0.25) / (UPPER_THRESHOLD - 0.25) * 29
    elif ratio >= LOWER_THRESHOLD:
        # 0.097 -> 10, 0.25 -> 39
        return 10 + (ratio - LOWER_THRESHOLD) / (0.25 - LOWER_THRESHOLD) * 29
    else:
        # 0 -> 0, 0.097 -> 9
        return max(0, ratio / LOWER_THRESHOLD * 9)


def _score_to_signal(score: int, ratio: float, trend: str) -> str:
    """Map score to human-readable signal."""
    ratio_pct = round(ratio * 100, 1)
    trend_label = f", trend {trend}" if trend else ""

    if score >= 90:
        return f"STRONG BULL: {ratio_pct}% uptrend ratio{trend_label}"
    elif score >= 70:
        return f"BULLISH: {ratio_pct}% uptrend ratio{trend_label}"
    elif score >= 45:
        return f"NEUTRAL: {ratio_pct}% uptrend ratio{trend_label}"
    elif score >= 30:
        return f"WEAK: {ratio_pct}% uptrend ratio{trend_label}"
    elif score >= 10:
        return f"VERY WEAK: {ratio_pct}% uptrend ratio{trend_label}"
    else:
        return f"CRISIS: {ratio_pct}% uptrend ratio{trend_label}"

#!/usr/bin/env python3
"""
Component 4: Momentum - Weight: 20%

Evaluates the rate of change (slope) and acceleration of the overall
uptrend ratio, plus sector-level slope breadth.

Data Source: Timeseries "all" + Sector Summary

Sub-scores:
  - Slope Score (50%): EMA(3)-smoothed current slope mapped to 0-100
  - Acceleration (30%): EMA(3)-smoothed slope series, 10v10 window (fallback 5v5)
  - Sector Slope Breadth (20%): Count of sectors with positive slope
"""

from typing import Optional


def calculate_momentum(all_timeseries: list[dict], sector_summary: list[dict]) -> dict:
    """
    Calculate momentum score from slope, acceleration, and sector breadth.

    Args:
        all_timeseries: Full "all" timeseries sorted by date ascending
        sector_summary: Latest sector summary rows

    Returns:
        Dict with score (0-100), signal, and detail fields
    """
    if not all_timeseries:
        return {
            "score": 50,
            "signal": "NO DATA: Timeseries unavailable (neutral default)",
            "data_available": False,
            "slope": None,
            "acceleration": None,
            "sector_slope_breadth": None,
        }

    latest = all_timeseries[-1]
    current_slope = latest.get("slope")

    # Extract slope series for smoothing
    slopes = [r.get("slope") for r in all_timeseries if r.get("slope") is not None]

    # Apply EMA(3) smoothing to slope series
    smoothed_slope = None
    if slopes:
        smoothed_slopes = _ema(slopes, span=3)
        smoothed_slope = smoothed_slopes[-1] if smoothed_slopes else current_slope
    else:
        smoothed_slopes = []

    # Sub-score 1: Slope Score (50%) - use smoothed slope
    effective_slope = smoothed_slope if smoothed_slope is not None else current_slope
    slope_score = _score_slope(effective_slope) if effective_slope is not None else 50

    # Sub-score 2: Acceleration (30%) - use smoothed slopes with 10v10 window
    accel_score, accel_value, accel_label = _score_acceleration_smoothed(smoothed_slopes)

    # Sub-score 3: Sector Slope Breadth (20%)
    breadth_score, positive_slope_count, total_sectors = _score_sector_slope_breadth(sector_summary)

    # Composite
    raw_score = slope_score * 0.50 + accel_score * 0.30 + breadth_score * 0.20
    score = round(min(100, max(0, raw_score)))

    signal = _build_signal(score, effective_slope, accel_label)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "slope": current_slope,
        "slope_smoothed": round(smoothed_slope, 6) if smoothed_slope is not None else None,
        "slope_smoothing": "EMA(3)",
        "slope_score": round(slope_score),
        "acceleration": accel_value,
        "acceleration_label": accel_label,
        "acceleration_score": round(accel_score),
        "acceleration_window": "10v10",
        "sector_positive_slope_count": positive_slope_count,
        "sector_total": total_sectors,
        "sector_slope_breadth_score": round(breadth_score),
        "date": latest.get("date", "N/A"),
    }


def _ema(values: list[float], span: int = 3) -> list[float]:
    """Calculate Exponential Moving Average.

    Args:
        values: List of float values
        span: EMA span (default 3)

    Returns:
        List of EMA values, same length as input. Empty list if input is empty.
    """
    if not values:
        return []
    if len(values) == 1:
        return [values[0]]

    alpha = 2.0 / (span + 1)
    result = [values[0]]
    for i in range(1, len(values)):
        ema_val = alpha * values[i] + (1 - alpha) * result[-1]
        result.append(ema_val)
    return result


def _classify_acceleration(acceleration: float) -> tuple:
    """Map acceleration value to (score, label)."""
    if acceleration > 0.005:
        return 90, "strong_accelerating"
    elif acceleration > 0.001:
        return 75, "accelerating"
    elif acceleration > -0.001:
        return 50, "steady"
    elif acceleration > -0.005:
        return 25, "decelerating"
    else:
        return 10, "strong_decelerating"


def _score_acceleration_smoothed(smoothed_slopes: list[float]) -> tuple:
    """Calculate acceleration from smoothed slopes using 10v10 window.

    Compares recent 10-point average vs prior 10-point average of smoothed slopes.

    Falls back to original 5v5 if fewer than 20 points available.

    Returns: (score, acceleration_value, label)
    """
    if len(smoothed_slopes) < 10:
        return _score_acceleration_from_values(smoothed_slopes, window=5)

    if len(smoothed_slopes) >= 20:
        recent_avg = sum(smoothed_slopes[-10:]) / 10
        prior_avg = sum(smoothed_slopes[-20:-10]) / 10
    else:
        # Fallback to 5v5 with smoothed data
        return _score_acceleration_from_values(smoothed_slopes, window=5)

    acceleration = recent_avg - prior_avg
    score, label = _classify_acceleration(acceleration)

    return score, round(acceleration, 6), label


def _score_acceleration_from_values(slopes: list[float], window: int = 5) -> tuple:
    """Fallback acceleration using smaller window."""
    if len(slopes) < window * 2:
        return 50, None, "insufficient_data"

    recent_avg = sum(slopes[-window:]) / window
    prior_avg = sum(slopes[-window * 2 : -window]) / window
    acceleration = recent_avg - prior_avg
    score, label = _classify_acceleration(acceleration)

    return score, round(acceleration, 6), label


def _score_slope(slope: float) -> float:
    """Map current slope to 0-100 score.

    Typical slope range: -0.02 to +0.02
    Extreme range: -0.03 to +0.03

      >= +0.02 -> 95-100 (strong bullish momentum)
      +0.01~+0.02 -> 75-94
      0~+0.01 -> 55-74 (mild positive)
      -0.01~0 -> 35-54 (mild negative)
      -0.02~-0.01 -> 10-34
      < -0.02 -> 0-9 (strong bearish momentum)
    """
    if slope >= 0.02:
        return min(100, 95 + (slope - 0.02) / 0.01 * 5)
    elif slope >= 0.01:
        return 75 + (slope - 0.01) / 0.01 * 19
    elif slope >= 0:
        return 55 + slope / 0.01 * 19
    elif slope >= -0.01:
        return 35 + (slope + 0.01) / 0.01 * 19
    elif slope >= -0.02:
        return 10 + (slope + 0.02) / 0.01 * 24
    else:
        return max(0, 9 + (slope + 0.02) / 0.01 * 9)


def _score_sector_slope_breadth(sector_summary: list[dict]) -> tuple:
    """Score based on count of sectors with positive slope.

    Returns: (score, positive_count, total_count)
    """
    if not sector_summary:
        return 50, 0, 0

    total = len(sector_summary)
    positive = sum(1 for s in sector_summary if s.get("Slope") is not None and s["Slope"] > 0)

    if total == 0:
        return 50, 0, 0

    # Linear mapping: 0 sectors -> 0, all sectors -> 100
    score = (positive / total) * 100

    return score, positive, total


def _build_signal(score: int, slope: Optional[float], accel_label: str) -> str:
    """Build human-readable signal."""
    slope_str = f"slope={slope:.4f}" if slope is not None else "slope=N/A"
    accel_str = accel_label.replace("_", " ")

    if score >= 80:
        return f"STRONG MOMENTUM: {slope_str}, {accel_str}"
    elif score >= 60:
        return f"POSITIVE MOMENTUM: {slope_str}, {accel_str}"
    elif score >= 40:
        return f"NEUTRAL MOMENTUM: {slope_str}, {accel_str}"
    elif score >= 20:
        return f"WEAK MOMENTUM: {slope_str}, {accel_str}"
    else:
        return f"NEGATIVE MOMENTUM: {slope_str}, {accel_str}"

#!/usr/bin/env python3
"""
Component 2: Sector Participation - Weight: 25%

Evaluates how many sectors are participating in the uptrend and the
uniformity of participation (spread between strongest and weakest).

Data Source: Sector Summary CSV

Sub-scores:
  - Uptrend Count (60%): How many of 11 sectors are in uptrend
  - Spread (40%): Max-min ratio spread (uniform = healthy, selective = weak)
"""

import sys
from typing import Optional

from data_fetcher import build_summary_from_timeseries

# Monty's official dashboard thresholds
OVERBOUGHT_THRESHOLD = 0.37  # Upper threshold
OVERSOLD_THRESHOLD = 0.097  # Lower threshold


def calculate_sector_participation(
    sector_summary: list[dict], sector_timeseries: dict[str, list[dict]]
) -> dict:
    """
    Calculate sector participation score.

    Args:
        sector_summary: List of sector summary rows
        sector_timeseries: Dict mapping sector -> timeseries rows; used as
                          fallback if sector_summary is unavailable

    Returns:
        Dict with score (0-100), signal, and detail fields
    """
    if not sector_summary:
        if sector_timeseries:
            sector_summary = build_summary_from_timeseries(sector_timeseries)
            print("  (fallback: built sector summary from timeseries data)", file=sys.stderr)
        else:
            return {
                "score": 50,
                "signal": "NO DATA: Sector summary unavailable (neutral default)",
                "data_available": False,
                "uptrend_count": None,
                "total_sectors": None,
                "spread": None,
                "sector_details": [],
            }

    total_sectors = len(sector_summary)
    if total_sectors == 0:
        return {
            "score": 50,
            "signal": "NO DATA: No sectors in summary",
            "data_available": False,
            "uptrend_count": 0,
            "total_sectors": 0,
            "spread": None,
            "sector_details": [],
        }

    # Count sectors in uptrend
    uptrend_count = sum(1 for s in sector_summary if s.get("Trend", "").lower() == "up")

    # Get ratios for spread calculation
    ratios = [s["Ratio"] for s in sector_summary if s.get("Ratio") is not None]

    if ratios:
        max_ratio = max(ratios)
        min_ratio = min(ratios)
        spread = max_ratio - min_ratio
    else:
        max_ratio = None
        min_ratio = None
        spread = None

    # Sub-score 1: Uptrend Count (60%)
    count_score = _score_uptrend_count(uptrend_count, total_sectors)

    # Sub-score 2: Spread (40%)
    spread_score = _score_spread(spread) if spread is not None else 50

    # Composite
    raw_score = count_score * 0.60 + spread_score * 0.40
    score = round(min(100, max(0, raw_score)))

    # Identify overbought/oversold sectors
    overbought = [
        s
        for s in sector_summary
        if s.get("Ratio") is not None and s["Ratio"] >= OVERBOUGHT_THRESHOLD
    ]
    oversold = [
        s for s in sector_summary if s.get("Ratio") is not None and s["Ratio"] < OVERSOLD_THRESHOLD
    ]

    signal = _build_signal(score, uptrend_count, total_sectors, spread)

    # Build sector details sorted by ratio descending
    sector_details = []
    for s in sorted(sector_summary, key=lambda x: x.get("Ratio") or 0, reverse=True):
        sector_details.append(
            {
                "sector": s.get("Sector", "Unknown"),
                "ratio": s.get("Ratio"),
                "ratio_pct": round(s["Ratio"] * 100, 1) if s.get("Ratio") is not None else None,
                "ma_10": s.get("10MA"),
                "trend": s.get("Trend", ""),
                "slope": s.get("Slope"),
                "status": s.get("Status", ""),
                "count": s.get("Count"),
                "total": s.get("Total"),
            }
        )

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "uptrend_count": uptrend_count,
        "total_sectors": total_sectors,
        "count_score": round(count_score),
        "spread": round(spread, 4) if spread is not None else None,
        "spread_pct": round(spread * 100, 1) if spread is not None else None,
        "spread_score": round(spread_score),
        "max_ratio": max_ratio,
        "min_ratio": min_ratio,
        "overbought_count": len(overbought),
        "overbought_sectors": [s.get("Sector", "") for s in overbought],
        "oversold_count": len(oversold),
        "oversold_sectors": [s.get("Sector", "") for s in oversold],
        "sector_details": sector_details,
    }


def _score_uptrend_count(uptrend_count: int, total_sectors: int) -> float:
    """Score based on number of sectors in uptrend.

    10-11 sectors -> 100
    8-9  sectors -> 80
    6-7  sectors -> 60
    4-5  sectors -> 40
    2-3  sectors -> 20
    0-1  sectors -> 0
    """
    if total_sectors == 0:
        return 50

    if uptrend_count >= 10:
        return 100
    elif uptrend_count >= 8:
        return 80
    elif uptrend_count >= 6:
        return 60
    elif uptrend_count >= 4:
        return 40
    elif uptrend_count >= 2:
        return 20
    else:
        return 0


def _score_spread(spread: float) -> float:
    """Score based on max-min ratio spread (0-1 scale).

    < 0.15 -> 100 (uniform participation)
    0.15-0.25 -> 80 (healthy spread)
    0.25-0.35 -> 60 (moderate dispersion)
    0.35-0.45 -> 30 (wide divergence)
    > 0.45 -> 0 (extremely selective)
    """
    if spread < 0.15:
        return 100
    elif spread < 0.25:
        return 100 - (spread - 0.15) / 0.10 * 20
    elif spread < 0.35:
        return 80 - (spread - 0.25) / 0.10 * 20
    elif spread < 0.45:
        return 60 - (spread - 0.35) / 0.10 * 30
    else:
        return max(0, 30 - (spread - 0.45) / 0.10 * 30)


def _build_signal(
    score: int, uptrend_count: int, total_sectors: int, spread: Optional[float]
) -> str:
    """Build human-readable signal."""
    spread_pct = f", spread {round(spread * 100, 1)}%" if spread is not None else ""

    if score >= 80:
        return (
            f"BROAD PARTICIPATION: {uptrend_count}/{total_sectors} sectors uptrending{spread_pct}"
        )
    elif score >= 60:
        return f"HEALTHY: {uptrend_count}/{total_sectors} sectors uptrending{spread_pct}"
    elif score >= 40:
        return f"MODERATE: {uptrend_count}/{total_sectors} sectors uptrending{spread_pct}"
    elif score >= 20:
        return f"NARROW: {uptrend_count}/{total_sectors} sectors uptrending{spread_pct}"
    else:
        return f"VERY NARROW: {uptrend_count}/{total_sectors} sectors uptrending{spread_pct}"

#!/usr/bin/env python3
"""
Component 3: Sector Rotation - Weight: 15%

Evaluates whether cyclical (risk-on) or defensive (risk-off) sectors are
leading, plus commodity sector dynamics for late-cycle detection.

Data Source: Sector Summary CSV

Sector Groups:
  Cyclical:  Technology, Consumer Cyclical, Communication Services, Financial, Industrials
  Defensive: Utilities, Consumer Defensive, Healthcare, Real Estate
  Commodity:  Energy, Basic Materials

Primary score: cyclical_avg - defensive_avg difference
  > +0.15  -> 90-100 (strong risk-on)
  +0.05~+0.15 -> 70-89 (healthy cyclical lead)
  -0.05~+0.05 -> 45-69 (balanced)
  -0.15~-0.05 -> 20-44 (defensive tilt)
  < -0.15  -> 0-19  (strong risk-off)

Commodity adjustment: if commodity_avg > both groups -> late cycle flag, penalty
"""

import math
import sys

from data_fetcher import build_summary_from_timeseries

# Sector classification
CYCLICAL_SECTORS = [
    "Technology",
    "Consumer Cyclical",
    "Communication Services",
    "Financial",
    "Industrials",
]
DEFENSIVE_SECTORS = [
    "Utilities",
    "Consumer Defensive",
    "Healthcare",
    "Real Estate",
]
COMMODITY_SECTORS = [
    "Energy",
    "Basic Materials",
]


def calculate_sector_rotation(
    sector_summary: list[dict], sector_timeseries: dict[str, list[dict]]
) -> dict:
    """
    Calculate sector rotation score.

    Args:
        sector_summary: List of sector summary rows
        sector_timeseries: Dict mapping sector -> timeseries rows (reserved)

    Returns:
        Dict with score (0-100), signal, and detail fields
    """
    if not sector_summary:
        if sector_timeseries:
            sector_summary = build_summary_from_timeseries(sector_timeseries)
            print("  (fallback: built sector summary from timeseries data)", file=sys.stderr)
        else:
            return {
                "score": 50,
                "signal": "NO DATA: Sector summary unavailable (neutral default)",
                "data_available": False,
                "cyclical_avg": None,
                "defensive_avg": None,
                "commodity_avg": None,
                "difference": None,
            }

    # Build lookup by sector name
    sector_map = {s["Sector"]: s for s in sector_summary if s.get("Sector")}

    # Calculate group averages
    cyclical_ratios = _get_group_ratios(sector_map, CYCLICAL_SECTORS)
    defensive_ratios = _get_group_ratios(sector_map, DEFENSIVE_SECTORS)
    commodity_ratios = _get_group_ratios(sector_map, COMMODITY_SECTORS)

    cyclical_avg = _avg(cyclical_ratios) if cyclical_ratios else None
    defensive_avg = _avg(defensive_ratios) if defensive_ratios else None
    commodity_avg = _avg(commodity_ratios) if commodity_ratios else None

    if cyclical_avg is None or defensive_avg is None:
        return {
            "score": 50,
            "signal": "INCOMPLETE DATA: Cannot calculate rotation (neutral default)",
            "data_available": False,
            "cyclical_avg": cyclical_avg,
            "defensive_avg": defensive_avg,
            "commodity_avg": commodity_avg,
            "difference": None,
        }

    difference = cyclical_avg - defensive_avg

    # Map difference to base score
    base_score = _difference_to_score(difference)

    # Commodity adjustment: late-cycle penalty
    late_cycle_flag = False
    commodity_penalty = 0
    if commodity_avg is not None:
        if commodity_avg > cyclical_avg and commodity_avg > defensive_avg:
            late_cycle_flag = True
            # Stronger penalty if commodity leads by a lot
            excess = commodity_avg - max(cyclical_avg, defensive_avg)
            if excess > 0.10:
                commodity_penalty = -10
            else:
                commodity_penalty = -5

    # Group divergence detection
    divergence_result = _calculate_group_divergence(sector_map)
    divergence_penalty = divergence_result.get("divergence_penalty", 0)

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

    signal = _build_signal(score, difference, late_cycle_flag)

    # Build group details
    cyclical_details = _build_group_details(sector_map, CYCLICAL_SECTORS)
    defensive_details = _build_group_details(sector_map, DEFENSIVE_SECTORS)
    commodity_details = _build_group_details(sector_map, COMMODITY_SECTORS)

    return {
        "score": score,
        "signal": signal,
        "data_available": True,
        "cyclical_avg": round(cyclical_avg, 4),
        "cyclical_avg_pct": round(cyclical_avg * 100, 1),
        "defensive_avg": round(defensive_avg, 4),
        "defensive_avg_pct": round(defensive_avg * 100, 1),
        "commodity_avg": round(commodity_avg, 4) if commodity_avg is not None else None,
        "commodity_avg_pct": round(commodity_avg * 100, 1) if commodity_avg is not None else None,
        "difference": round(difference, 4),
        "difference_pct": round(difference * 100, 1),
        "late_cycle_flag": late_cycle_flag,
        "commodity_penalty": commodity_penalty,
        "divergence_flag": divergence_result.get("divergence_flag", False),
        "divergence_penalty": divergence_penalty,
        "cyclical_divergence": divergence_result.get("cyclical_divergence"),
        "defensive_divergence": divergence_result.get("defensive_divergence"),
        "cyclical_details": cyclical_details,
        "defensive_details": defensive_details,
        "commodity_details": commodity_details,
    }


def _get_group_ratios(sector_map: dict[str, dict], sector_names: list[str]) -> list[float]:
    """Extract ratios for a group of sectors."""
    ratios = []
    for name in sector_names:
        sector = sector_map.get(name)
        if sector and sector.get("Ratio") is not None:
            ratios.append(sector["Ratio"])
    return ratios


def _avg(values: list[float]) -> float:
    """Simple average."""
    return sum(values) / len(values)


def _difference_to_score(diff: float) -> float:
    """Map cyclical-defensive difference to score.

    > +0.15  -> 90-100 (strong risk-on)
    +0.05~+0.15 -> 70-89 (healthy cyclical lead)
    -0.05~+0.05 -> 45-69 (balanced)
    -0.15~-0.05 -> 20-44 (defensive tilt)
    < -0.15  -> 0-19  (strong risk-off)
    """
    if diff > 0.15:
        return min(100, 90 + (diff - 0.15) / 0.10 * 10)
    elif diff > 0.05:
        return 70 + (diff - 0.05) / 0.10 * 19
    elif diff > -0.05:
        return 45 + (diff + 0.05) / 0.10 * 24
    elif diff > -0.15:
        return 20 + (diff + 0.15) / 0.10 * 24
    else:
        return max(0, 19 + (diff + 0.15) / 0.10 * 19)


def _build_signal(score: int, difference: float, late_cycle: bool) -> str:
    """Build human-readable signal."""
    diff_pct = round(difference * 100, 1)
    late_str = " [LATE CYCLE WARNING]" if late_cycle else ""

    if score >= 90:
        return f"STRONG RISK-ON: Cyclical leads by {diff_pct}pp{late_str}"
    elif score >= 70:
        return f"RISK-ON: Cyclical leads by {diff_pct}pp{late_str}"
    elif score >= 45:
        return f"BALANCED: Cyclical-Defensive gap {diff_pct}pp{late_str}"
    elif score >= 20:
        return f"DEFENSIVE TILT: Defensive leads by {abs(diff_pct)}pp{late_str}"
    else:
        return f"STRONG RISK-OFF: Defensive leads by {abs(diff_pct)}pp{late_str}"


def _calculate_group_divergence(sector_map: dict[str, dict]) -> dict:
    """Detect intra-group divergence in Cyclical and Defensive groups.

    Divergence flag triggers when any of:
    - Group internal std_dev > 8pp (0.08)
    - Group internal max-min > 20pp (0.20)
    - A sector's trend opposes the majority trend within its group

    Returns:
        Dict with divergence_flag, divergence_penalty, cyclical_divergence,
        defensive_divergence
    """
    cyclical_div = _analyze_group(sector_map, CYCLICAL_SECTORS)
    defensive_div = _analyze_group(sector_map, DEFENSIVE_SECTORS)

    flag = cyclical_div["flagged"] or defensive_div["flagged"]
    penalty = -5 if flag else 0

    return {
        "divergence_flag": flag,
        "divergence_penalty": penalty,
        "cyclical_divergence": cyclical_div,
        "defensive_divergence": defensive_div,
    }


def _analyze_group(sector_map: dict[str, dict], sector_names: list[str]) -> dict:
    """Analyze divergence within a sector group."""
    ratios = []
    trends = []
    names_with_data = []

    for name in sector_names:
        sector = sector_map.get(name)
        if sector and sector.get("Ratio") is not None:
            ratios.append(sector["Ratio"])
            trends.append(sector.get("Trend", "").lower())
            names_with_data.append(name)

    if len(ratios) < 2:
        return {
            "flagged": False,
            "std_dev": None,
            "spread": None,
            "outliers": [],
            "trend_dissenters": [],
        }

    mean = sum(ratios) / len(ratios)
    variance = sum((r - mean) ** 2 for r in ratios) / len(ratios)
    std_dev = math.sqrt(variance)
    spread = max(ratios) - min(ratios)

    # Outlier detection: sectors more than 1.5 * std_dev from mean
    outliers = []
    for _i, (name, ratio) in enumerate(zip(names_with_data, ratios)):
        if abs(ratio - mean) > 1.5 * std_dev and std_dev > 0:
            outliers.append({"sector": name, "ratio": ratio, "deviation": round(ratio - mean, 4)})

    # Trend dissenter detection: sectors opposing the majority
    trend_dissenters = []
    if trends:
        up_count = sum(1 for t in trends if t == "up")
        down_count = sum(1 for t in trends if t == "down")
        majority = "up" if up_count >= down_count else "down"

        for name, trend in zip(names_with_data, trends):
            if trend and trend != majority:
                trend_dissenters.append({"sector": name, "trend": trend, "majority": majority})

    # Divergence flag conditions
    flagged = std_dev > 0.08 or spread > 0.20 or len(trend_dissenters) > 0

    return {
        "flagged": flagged,
        "std_dev": round(std_dev, 4),
        "spread": round(spread, 4),
        "outliers": outliers,
        "trend_dissenters": trend_dissenters,
    }


def _build_group_details(sector_map: dict[str, dict], sector_names: list[str]) -> list[dict]:
    """Build detail rows for a sector group."""
    details = []
    for name in sector_names:
        sector = sector_map.get(name)
        if sector:
            details.append(
                {
                    "sector": name,
                    "ratio": sector.get("Ratio"),
                    "ratio_pct": round(sector["Ratio"] * 100, 1)
                    if sector.get("Ratio") is not None
                    else None,
                    "trend": sector.get("Trend", ""),
                    "slope": sector.get("Slope"),
                }
            )
        else:
            details.append(
                {
                    "sector": name,
                    "ratio": None,
                    "ratio_pct": None,
                    "trend": "N/A",
                    "slope": None,
                }
            )
    return details

#!/usr/bin/env python3
"""
Uptrend Analyzer - CSV Data Fetcher

Downloads and parses Monty's Uptrend Ratio Dashboard CSV data from GitHub.
No API key required - uses publicly available CSV files.

Data Sources:
- Timeseries: uptrend_ratio_timeseries.csv (all + 11 sectors, 2023/08~present)
- Sector Summary: sector_summary.csv (latest snapshot)
"""

import csv
import io
import sys
from typing import Optional

import requests

TIMESERIES_URL = (
    "https://raw.githubusercontent.com/tradermonty/uptrend-dashboard/"
    "main/data/uptrend_ratio_timeseries.csv"
)
SECTOR_SUMMARY_URL = (
    "https://raw.githubusercontent.com/tradermonty/uptrend-dashboard/main/data/sector_summary.csv"
)


WORKSHEET_TO_DISPLAY = {
    "sec_basicmaterials": "Basic Materials",
    "sec_communicationservices": "Communication Services",
    "sec_consumercyclical": "Consumer Cyclical",
    "sec_consumerdefensive": "Consumer Defensive",
    "sec_energy": "Energy",
    "sec_financial": "Financial",
    "sec_healthcare": "Healthcare",
    "sec_industrials": "Industrials",
    "sec_realestate": "Real Estate",
    "sec_technology": "Technology",
    "sec_utilities": "Utilities",
}

# Monty's official dashboard thresholds (same as in sector_participation_calculator)
OVERBOUGHT_THRESHOLD = 0.37
OVERSOLD_THRESHOLD = 0.097


def build_summary_from_timeseries(sector_timeseries: dict[str, dict]) -> list[dict]:
    """Build sector_summary-compatible list from timeseries latest rows.

    Used as fallback when sector_summary.csv is unavailable.

    Args:
        sector_timeseries: Dict mapping worksheet name -> latest timeseries row
            e.g. {"sec_technology": {"ratio": 0.288, "ma_10": 0.266, ...}}

    Returns:
        List of dicts matching sector_summary format:
            [{"Sector": "Technology", "Ratio": 0.288, "10MA": 0.266, ...}]
    """
    rows = []
    for ws_name, row in sector_timeseries.items():
        display_name = WORKSHEET_TO_DISPLAY.get(ws_name, ws_name)
        ratio = row.get("ratio")
        status = (
            "Overbought"
            if ratio is not None and ratio > OVERBOUGHT_THRESHOLD
            else "Oversold"
            if ratio is not None and ratio < OVERSOLD_THRESHOLD
            else "Normal"
        )
        rows.append(
            {
                "Sector": display_name,
                "Ratio": ratio,
                "10MA": row.get("ma_10"),
                "Trend": (row.get("trend") or "").capitalize(),
                "Slope": row.get("slope"),
                "Status": status,
                "Count": row.get("count"),
                "Total": row.get("total"),
            }
        )
    return rows


class UptrendDataFetcher:
    """Client for Monty's Uptrend Ratio Dashboard CSV data"""

    def __init__(self):
        self.session = requests.Session()
        self._timeseries_cache: Optional[list[dict]] = None
        self._sector_summary_cache: Optional[list[dict]] = None

    def fetch_timeseries(self) -> list[dict]:
        """Download and parse the timeseries CSV.

        Returns:
            List of dicts with keys: worksheet, date, count, total, ratio,
            ma_10, slope, trend. Numeric fields cast to float/int.
        """
        if self._timeseries_cache is not None:
            return self._timeseries_cache

        try:
            response = self.session.get(TIMESERIES_URL, timeout=30)
            response.raise_for_status()
        except requests.exceptions.RequestException as e:
            print(f"WARNING: Failed to fetch timeseries CSV: {e}", file=sys.stderr)
            return []

        rows = []
        reader = csv.DictReader(io.StringIO(response.text))
        for row in reader:
            parsed = _parse_timeseries_row(row)
            if parsed:
                rows.append(parsed)

        self._timeseries_cache = rows
        return rows

    def fetch_sector_summary(self) -> list[dict]:
        """Download and parse the sector summary CSV.

        Returns:
            List of dicts with keys: Sector, Ratio, 10MA, Trend, Slope, Status.
            Numeric fields cast to float.
        """
        if self._sector_summary_cache is not None:
            return self._sector_summary_cache

        try:
            response = self.session.get(SECTOR_SUMMARY_URL, timeout=30)
            response.raise_for_status()
        except requests.exceptions.RequestException as e:
            print(f"WARNING: Failed to fetch sector summary CSV: {e}", file=sys.stderr)
            return []

        rows = []
        reader = csv.DictReader(io.StringIO(response.text))
        for row in reader:
            parsed = _parse_sector_summary_row(row)
            if parsed:
                rows.append(parsed)

        self._sector_summary_cache = rows
        return rows

    def get_all_timeseries(self) -> list[dict]:
        """Get timeseries filtered to worksheet=='all', sorted by date ascending."""
        data = self.fetch_timeseries()
        filtered = [r for r in data if r["worksheet"] == "all"]
        filtered.sort(key=lambda r: r["date"])
        return filtered

    def get_sector_timeseries(self, sector: str) -> list[dict]:
        """Get timeseries for a specific sector worksheet, sorted by date ascending."""
        data = self.fetch_timeseries()
        filtered = [r for r in data if r["worksheet"] == sector]
        filtered.sort(key=lambda r: r["date"])
        return filtered

    def get_latest_all(self) -> Optional[dict]:
        """Get the most recent 'all' row."""
        ts = self.get_all_timeseries()
        return ts[-1] if ts else None

    def get_all_sector_latest(self) -> dict[str, dict]:
        """Get latest row for each sector (excluding 'all').

        Returns:
            Dict mapping sector name -> latest timeseries row
        """
        data = self.fetch_timeseries()
        sectors: dict[str, dict] = {}
        for row in data:
            ws = row["worksheet"]
            if ws == "all":
                continue
            if ws not in sectors or row["date"] > sectors[ws]["date"]:
                sectors[ws] = row
        return sectors


def _parse_timeseries_row(row: dict) -> Optional[dict]:
    """Parse a timeseries CSV row, casting numeric fields."""
    try:
        return {
            "worksheet": row.get("worksheet", "").strip(),
            "date": row.get("date", "").strip(),
            "count": _safe_int(row.get("count")),
            "total": _safe_int(row.get("total")),
            "ratio": _safe_float(row.get("ratio")),
            "ma_10": _safe_float(row.get("ma_10")),
            "slope": _safe_float(row.get("slope")),
            "trend": row.get("trend", "").strip(),
        }
    except (ValueError, TypeError):
        return None


def _parse_sector_summary_row(row: dict) -> Optional[dict]:
    """Parse a sector summary CSV row, casting numeric fields."""
    try:
        return {
            "Sector": row.get("Sector", "").strip(),
            "Ratio": _safe_float(row.get("Ratio")),
            "10MA": _safe_float(row.get("10MA")),
            "Trend": row.get("Trend", "").strip(),
            "Slope": _safe_float(row.get("Slope")),
            "Status": row.get("Status", "").strip(),
        }
    except (ValueError, TypeError):
        return None


def _safe_float(value) -> Optional[float]:
    """Convert to float, return None if empty or invalid."""
    if value is None or str(value).strip() == "":
        return None
    try:
        return float(value)
    except (ValueError, TypeError):
        return None


def _safe_int(value) -> Optional[int]:
    """Convert to int, return None if empty or invalid."""
    if value is None or str(value).strip() == "":
        return None
    try:
        return int(float(value))
    except (ValueError, TypeError):
        return None

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

Generates JSON and Markdown reports for uptrend breadth analysis.
"""

import json
import sys


def generate_json_report(analysis: dict, output_file: str):
    """Save full analysis as JSON"""
    try:
        with open(output_file, "w") as f:
            json.dump(analysis, f, indent=2, default=str)
    except OSError as e:
        print(f"ERROR: Failed to write JSON report to {output_file}: {e}", file=sys.stderr)
        raise
    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", {})

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

    # Header
    lines.append("# Uptrend Analyzer Report")
    lines.append("")
    lines.append(f"**Generated:** {metadata.get('generated_at', 'N/A')}")
    lines.append("**Data Source:** Monty's Uptrend Ratio Dashboard (GitHub CSV)")
    lines.append("**API Key Required:** No")
    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"| **Zone** | {zone_emoji} {zone} |")
    lines.append(f"| **Zone Detail** | {zone_detail} |")

    # Zone proximity
    prox = composite.get("zone_proximity", {})
    if prox.get("at_boundary"):
        lines.append(f"| **Zone Proximity** | **{prox.get('label', '')}** |")

    lines.append(f"| **Exposure Guidance** | {exposure} |")

    # Warning penalty
    warning_penalty = composite.get("warning_penalty", 0)
    if warning_penalty != 0:
        raw_score = composite.get("composite_score_raw", score)
        lines.append(f"| **Warning Penalty** | {warning_penalty} (raw: {raw_score}/100) |")

    # Active warnings summary
    active_warnings = composite.get("active_warnings", [])
    if active_warnings:
        warning_labels = [w.get("label", "") for w in active_warnings]
        lines.append(
            f"| **Active Warnings** | {len(active_warnings)}: {', '.join(warning_labels)} |"
        )

    lines.append(
        f"| **Strongest Component** | {composite.get('strongest_component', {}).get('label', 'N/A')} "
        f"({composite.get('strongest_component', {}).get('score', 0)}/100) |"
    )
    lines.append(
        f"| **Weakest Component** | {composite.get('weakest_component', {}).get('label', 'N/A')} "
        f"({composite.get('weakest_component', {}).get('score', 0)}/100) |"
    )
    dq = composite.get("data_quality", {})
    if dq:
        lines.append(f"| **Data Quality** | {dq.get('label', 'N/A')} |")

    # Historical confidence
    historical = components.get("historical_context", {})
    confidence = historical.get("confidence", {})
    if confidence:
        lines.append(
            f"| **Confidence** | {confidence.get('confidence_level', 'N/A')} "
            f"({confidence.get('sample_label', '')}, {confidence.get('regime_coverage', '')} regime coverage) |"
        )

    lines.append("")

    # Guidance blockquote
    lines.append(f"> **Guidance:** {composite.get('guidance', '')}")

    # Bull + warning tension visualization
    if active_warnings and zone in ("Strong Bull", "Bull"):
        lines.append(">")
        lines.append(
            f"> Note: Score is in the {zone} zone, but {len(active_warnings)} warning(s) are active."
        )
        lines.append("> Exposure guidance has been tightened. See Active Warnings below.")

    lines.append("")

    # Active Warnings - promoted to independent H2 section, right after Overall Assessment
    if active_warnings:
        lines.append("---")
        lines.append("")
        lines.append("## Active Warnings")
        lines.append("")
        for warning in active_warnings:
            lines.append(f"### {warning.get('label', 'WARNING')}")
            lines.append(f"> {warning.get('description', '')}")
            lines.append("")
            for action in warning.get("actions", []):
                lines.append(f"- {action}")
            lines.append("")

    # Current Market Snapshot
    breadth = components.get("market_breadth", {})
    if breadth.get("data_available"):
        lines.append("---")
        lines.append("")
        lines.append("## Current Market Snapshot")
        lines.append("")
        lines.append("| Metric | Value |")
        lines.append("|--------|-------|")
        lines.append(f"| Uptrend Ratio | {breadth.get('ratio_pct', 'N/A')}% |")
        lines.append(f"| 10-Day MA | {breadth.get('ma_10_pct', 'N/A')}% |")
        lines.append(f"| Trend | {breadth.get('trend', 'N/A')} |")
        lines.append(f"| Slope | {_format_slope(breadth.get('slope'))} |")
        lines.append(
            f"| Distance from 37% (Overbought) | {_format_distance(breadth.get('distance_from_upper'))} |"
        )
        lines.append(
            f"| Distance from 9.7% (Oversold) | {_format_distance(breadth.get('distance_from_lower'))} |"
        )
        lines.append(f"| Date | {breadth.get('date', 'N/A')} |")
        lines.append("")

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

    component_order = [
        "market_breadth",
        "sector_participation",
        "sector_rotation",
        "momentum",
        "historical_context",
    ]

    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 = comp.get("score", 0)
        weight_pct = f"{comp.get('weight', 0) * 100:.0f}%"
        contribution = comp.get("weighted_contribution", 0)
        bar = _score_bar(score_val)

        lines.append(
            f"| {i} | **{comp.get('label', key)}** | {weight_pct} | "
            f"{bar} {score_val} | {contribution:.1f} | {signal} |"
        )

    lines.append("")

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

    # 1. Market Breadth
    lines.append("### 1. Market Breadth (Overall)")
    lines.append("")
    if breadth.get("data_available"):
        lines.append(f"- **Uptrend Ratio:** {breadth.get('ratio_pct', 'N/A')}%")
        lines.append(f"- **10-Day MA:** {breadth.get('ma_10_pct', 'N/A')}%")
        lines.append(f"- **Trend:** {breadth.get('trend', 'N/A')}")
        lines.append(f"- **Slope:** {_format_slope(breadth.get('slope'))}")
        lines.append(f"- **Trend Adjustment:** {breadth.get('trend_adjustment', 0):+d}")
    else:
        lines.append("- Data unavailable")
    lines.append("")

    # 2. Sector Participation
    participation = components.get("sector_participation", {})
    lines.append("### 2. Sector Participation")
    lines.append("")
    if participation.get("data_available"):
        lines.append(
            f"- **Uptrending Sectors:** {participation.get('uptrend_count', 0)}"
            f"/{participation.get('total_sectors', 0)}"
        )
        lines.append(f"- **Count Score:** {participation.get('count_score', 0)}/100")
        lines.append(
            f"- **Spread:** {participation.get('spread_pct', 'N/A')}% "
            f"(score: {participation.get('spread_score', 0)}/100)"
        )
        lines.append(
            f"- **Overbought ({'>'}37%):** {participation.get('overbought_count', 0)} "
            f"sectors ({', '.join(participation.get('overbought_sectors', []))})"
        )
        lines.append(
            f"- **Oversold ({'<'}9.7%):** {participation.get('oversold_count', 0)} "
            f"sectors ({', '.join(participation.get('oversold_sectors', []))})"
        )
    else:
        lines.append("- Data unavailable")
    lines.append("")

    # 3. Sector Rotation
    rotation = components.get("sector_rotation", {})
    lines.append("### 3. Sector Rotation")
    lines.append("")
    if rotation.get("data_available"):
        lines.append(f"- **Cyclical Avg:** {rotation.get('cyclical_avg_pct', 'N/A')}%")
        lines.append(f"- **Defensive Avg:** {rotation.get('defensive_avg_pct', 'N/A')}%")
        lines.append(f"- **Commodity Avg:** {rotation.get('commodity_avg_pct', 'N/A')}%")
        lines.append(f"- **Cyclical-Defensive Gap:** {rotation.get('difference_pct', 'N/A')}pp")
        if rotation.get("late_cycle_flag"):
            lines.append(
                f"- **Late Cycle Warning:** YES (commodity penalty: {rotation.get('commodity_penalty', 0)})"
            )
        if rotation.get("divergence_flag"):
            lines.append(
                f"- **Divergence Warning:** YES (penalty: {rotation.get('divergence_penalty', 0)})"
            )
            for group_label, group_key in [
                ("Cyclical", "cyclical_divergence"),
                ("Defensive", "defensive_divergence"),
            ]:
                div = rotation.get(group_key, {})
                if div and div.get("flagged"):
                    lines.append(
                        f"  - **{group_label} Divergence:** "
                        f"std={div.get('std_dev', 'N/A')}, spread={div.get('spread', 'N/A')}"
                    )
                    for outlier in div.get("outliers", []):
                        lines.append(
                            f"    - Outlier: {outlier['sector']} "
                            f"(deviation: {outlier['deviation']:+.4f})"
                        )
                    for dissenter in div.get("trend_dissenters", []):
                        lines.append(
                            f"    - Trend dissenter: {dissenter['sector']} "
                            f"({dissenter['trend']} vs majority {dissenter['majority']})"
                        )

        # Group detail tables
        for group_name, group_key in [
            ("Cyclical", "cyclical_details"),
            ("Defensive", "defensive_details"),
            ("Commodity", "commodity_details"),
        ]:
            details = rotation.get(group_key, [])
            if details:
                lines.append(f"\n**{group_name} Sectors:**")
                lines.append("")
                lines.append("| Sector | Ratio | Trend | Slope |")
                lines.append("|--------|-------|-------|-------|")
                for d in details:
                    lines.append(
                        f"| {d.get('sector', '')} | "
                        f"{d.get('ratio_pct', 'N/A')}% | "
                        f"{d.get('trend', 'N/A')} | "
                        f"{_format_slope(d.get('slope'))} |"
                    )
                lines.append("")
    else:
        lines.append("- Data unavailable")
    lines.append("")

    # 4. Momentum
    momentum = components.get("momentum", {})
    lines.append("### 4. Momentum")
    lines.append("")
    if momentum.get("data_available"):
        lines.append(f"- **Raw Slope:** {_format_slope(momentum.get('slope'))} ")
        lines.append(
            f"- **Smoothed Slope ({momentum.get('slope_smoothing', 'EMA(3)')}):** "
            f"{_format_slope(momentum.get('slope_smoothed'))} "
            f"(score: {momentum.get('slope_score', 0)}/100)"
        )
        lines.append(
            f"- **Acceleration ({momentum.get('acceleration_window', '10v10')}):** "
            f"{momentum.get('acceleration', 'N/A')} "
            f"({momentum.get('acceleration_label', 'N/A')}, "
            f"score: {momentum.get('acceleration_score', 0)}/100)"
        )
        lines.append(
            f"- **Sector Slope Breadth:** "
            f"{momentum.get('sector_positive_slope_count', 0)}"
            f"/{momentum.get('sector_total', 0)} positive "
            f"(score: {momentum.get('sector_slope_breadth_score', 0)}/100)"
        )
    else:
        lines.append("- Data unavailable")
    lines.append("")

    # 5. Historical Context
    lines.append("### 5. Historical Context")
    lines.append("")
    if historical.get("data_available"):
        lines.append(f"- **Current Ratio:** {historical.get('current_ratio_pct', 'N/A')}%")
        lines.append(f"- **Percentile Rank:** {historical.get('percentile', 'N/A')}th")
        lines.append(
            f"- **Historical Range:** "
            f"{historical.get('historical_min_pct', 'N/A')}% - "
            f"{historical.get('historical_max_pct', 'N/A')}%"
        )
        lines.append(f"- **Historical Median:** {historical.get('historical_median_pct', 'N/A')}%")
        lines.append(f"- **30-Day Avg:** {historical.get('avg_30d_pct', 'N/A')}%")
        lines.append(f"- **90-Day Avg:** {historical.get('avg_90d_pct', 'N/A')}%")
        lines.append(
            f"- **Data Points:** {historical.get('data_points', 0)} "
            f"({historical.get('date_range', 'N/A')})"
        )
        if confidence:
            lines.append(
                f"- **Confidence:** {confidence.get('confidence_level', 'N/A')} "
                f"(sample: {confidence.get('sample_label', '')}, "
                f"regime: {confidence.get('regime_coverage', '')}, "
                f"recency: {confidence.get('recency_label', '')})"
            )
    else:
        lines.append("- Data unavailable")
    lines.append("")

    # Sector Heatmap Table
    sector_details = components.get("sector_participation", {}).get("sector_details", [])
    if sector_details:
        lines.append("---")
        lines.append("")
        lines.append("## Sector Heatmap")
        lines.append("")
        lines.append("| Rank | Sector | Ratio | Count/Total | 10MA | Trend | Slope | Status |")
        lines.append("|------|--------|-------|-------------|------|-------|-------|--------|")
        for i, s in enumerate(sector_details, 1):
            count_val = s.get("count")
            total_val = s.get("total")
            if count_val is not None and total_val is not None:
                count_total_str = f"{count_val}/{total_val}"
            else:
                count_total_str = "N/A"
            lines.append(
                f"| {i} | {s.get('sector', '')} | "
                f"{s.get('ratio_pct', 'N/A')}% | "
                f"{count_total_str} | "
                f"{round(s['ma_10'] * 100, 1) if s.get('ma_10') is not None else 'N/A'}% | "
                f"{s.get('trend', '')} | "
                f"{_format_slope(s.get('slope'))} | "
                f"{s.get('status', '')} |"
            )
        lines.append("")

        # Divergent Status-Trend note
        divergent = [
            s
            for s in sector_details
            if (s.get("status") == "Overbought" and s.get("trend", "").lower() == "down")
            or (s.get("status") == "Oversold" and s.get("trend", "").lower() == "up")
        ]
        if divergent:
            lines.append("> **Note on Status vs Trend:**")
            lines.append(
                "> Status (Overbought/Normal/Oversold) reflects the ratio *level* relative to thresholds."
            )
            lines.append("> Trend (Up/Down) reflects the *direction* of the 10-day MA slope.")
            lines.append("> These can diverge:")
            lines.append(
                "> - **Overbought + Down** = high level but momentum rolling over (warning)"
            )
            lines.append(
                "> - **Oversold + Up** = low level but momentum improving (potential recovery)"
            )
            for s in divergent:
                lines.append(
                    f"> - **{s['sector']}**: {s['status']} ({s['ratio_pct']}%) / Trend {s['trend']}"
                )
            lines.append("")

    # Recommended Actions
    lines.append("---")
    lines.append("")
    lines.append("## Recommended Actions")
    lines.append("")
    lines.append(f"**Zone:** {zone} ({zone_detail})")
    lines.append(f"**Exposure Guidance:** {exposure}")
    lines.append("")
    for action in composite.get("actions", []):
        lines.append(f"- {action}")
    lines.append("")

    # Methodology
    lines.append("---")
    lines.append("")
    lines.append("## Methodology")
    lines.append("")
    lines.append(
        "This analysis uses Monty's Uptrend Ratio Dashboard data to assess market breadth health."
    )
    lines.append(
        "The dashboard tracks ~2,800 US stocks across 11 sectors, measuring the percentage in uptrends."
    )
    lines.append("")
    lines.append("**5-Component Scoring System (0-100, higher = healthier):**")
    lines.append("")
    lines.append("1. **Market Breadth (30%):** Overall uptrend ratio level and trend direction")
    lines.append(
        "2. **Sector Participation (25%):** Number of uptrending sectors and spread uniformity"
    )
    lines.append("3. **Sector Rotation (15%):** Cyclical vs Defensive vs Commodity balance")
    lines.append("4. **Momentum (20%):** Slope direction, acceleration, and sector slope breadth")
    lines.append("5. **Historical Context (10%):** Percentile rank in historical distribution")
    lines.append("")
    lines.append("**Key Thresholds (Monty's Dashboard):** Overbought = 37%, Oversold = 9.7%")
    lines.append("")
    lines.append("For detailed methodology, see `references/uptrend_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("")

    try:
        with open(output_file, "w") as f:
            f.write("\n".join(lines))
    except OSError as e:
        print(f"ERROR: Failed to write Markdown report to {output_file}: {e}", file=sys.stderr)
        raise

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


def _zone_emoji(color: str) -> str:
    mapping = {
        "green": "\U0001f7e2",
        "light_green": "\U0001f7e2",
        "yellow": "\U0001f7e1",
        "orange": "\U0001f7e0",
        "red": "\U0001f534",
    }
    return mapping.get(color, "\u26aa")


def _score_bar(score: int) -> str:
    """Simple text bar for score visualization"""
    if score >= 80:
        return "\u2588\u2588\u2588\u2588"
    elif score >= 60:
        return "\u2588\u2588\u2588\u2591"
    elif score >= 40:
        return "\u2588\u2588\u2591\u2591"
    elif score >= 20:
        return "\u2588\u2591\u2591\u2591"
    else:
        return "\u2591\u2591\u2591\u2591"


def _format_slope(value) -> str:
    """Format slope value with 4 decimal places."""
    if value is None:
        return "N/A"
    return f"{value:+.4f}"


def _format_distance(value) -> str:
    """Format distance value as percentage points."""
    if value is None:
        return "N/A"
    pct = round(value * 100, 1)
    return f"{pct:+.1f}pp"