quantwise 1.2.0 → 1.2.2

package/.claude/skills/uptrend-analyzer/references/uptrend_methodology.md

@@ -0,0 +1,215 @@
+# Uptrend Analyzer Methodology
+
+## Data Source: Monty's Uptrend Ratio Dashboard
+
+Monty's Uptrend Ratio Dashboard tracks approximately 2,800 US stocks across 11 GICS sectors. For each stock, it determines whether the stock is in an "uptrend" based on the criteria below. The dashboard publishes daily CSV data on GitHub.
+
+**GitHub Repository:** `tradermonty/uptrend-dashboard`
+**Live Dashboard:** https://uptrend-dashboard.streamlit.app/
+
+### Uptrend Definition (Finviz Elite Screener)
+
+A stock is classified as "uptrend" when it meets **all** of the following conditions:
+
+| Condition | Description |
+|-----------|-------------|
+| Price > $10 | Penny stocks excluded |
+| Avg Volume > 100K | Sufficient liquidity |
+| Market Cap > $50M | Micro-cap and above |
+| Price > SMA20 | Short-term uptrend |
+| Price > SMA200 | Long-term uptrend |
+| SMA50 > SMA200 | Golden cross (bullish structure) |
+| 52W High/Low > 30% above Low | Recovering from bottom |
+| 4-Week Performance: Up | Recent momentum positive |
+
+The **uptrend ratio** = (stocks meeting all conditions) / (stocks meeting base filters: price, volume, market cap).
+
+### CSV Files
+
+| File | Description | Update Frequency |
+|------|-------------|------------------|
+| `uptrend_ratio_timeseries.csv` | Daily ratios for "all" + 11 sectors | Daily |
+| `sector_summary.csv` | Latest snapshot of all sectors | Daily |
+
+**Data availability:**
+- "all" (full market): Since 2023-08-11
+- Sector-level data: Since 2024-07-21
+
+### Timeseries Columns
+
+| Column | Type | Description |
+|--------|------|-------------|
+| worksheet | string | "all" or sector slug (e.g., "sec_technology") |
+| date | string | YYYY-MM-DD format |
+| count | int | Number of stocks in uptrend |
+| total | int | Total stocks tracked |
+| ratio | float | count/total (0-1 scale, raw decimal) |
+| ma_10 | float | 10-day simple moving average of ratio |
+| slope | float | 1-day difference of ma_10 (`ma_10.diff()`) |
+| trend | string | "up" (slope > 0) or "down" (slope <= 0) |
+
+### Sector Summary Columns
+
+| Column | Type | Description |
+|--------|------|-------------|
+| Sector | string | Display name (e.g., "Technology") |
+| Ratio | float | Current uptrend ratio (0-1) |
+| 10MA | float | 10-day MA of ratio |
+| Trend | string | "Up" or "Down" |
+| Slope | float | 1-day difference of MA |
+| Status | string | "Overbought", "Oversold", or "Normal" |
+
+### Indicator Calculations (from source code)
+
+All indicators are computed on-the-fly from raw count/total data:
+
+```
+ratio    = count / total
+ma_10    = ratio.rolling(10).mean()       # 10-day simple MA
+slope    = ma_10.diff()                   # 1-day change of MA
+trend    = "up" if slope > 0 else "down"
+```
+
+**Peak/Trough Detection:** The dashboard uses `scipy.signal.find_peaks` with parameters `distance=20, prominence=0.015` to identify local tops and bottoms in the 10MA series.
+
+---
+
+## Official Dashboard Thresholds
+
+These thresholds are defined in `src/constants.py` of the source repository:
+
+| Threshold | Value | Meaning |
+|-----------|-------|---------|
+| **Upper (Overbought)** | **37%** | Ratio above this = overbought conditions |
+| **Lower (Oversold)** | **9.7%** | Ratio below this = oversold / crisis |
+| MA Period | 10 | Simple moving average window |
+
+### Status Determination
+
+```
+ratio > 0.37  -> "Overbought"
+ratio < 0.097 -> "Oversold"
+otherwise     -> "Normal"
+```
+
+### Practical Interpretation
+
+| Ratio | Interpretation | Market Environment |
+|-------|---------------|-------------------|
+| 50%+ | Strong breadth | Broad bull market, most stocks participating |
+| 37-50% | Overbought / Healthy | Above upper threshold, strong but extended |
+| 25-37% | Normal / Recovering | Between thresholds, typical trading range |
+| 9.7-25% | Weak | Below normal, breadth deteriorating |
+| < 9.7% | Oversold / Crisis | Below lower threshold, extreme selling |
+
+---
+
+## 5-Component Scoring System
+
+### Component 1: Market Breadth (Overall) - Weight: 30%
+
+**Rationale:** The overall uptrend ratio is the single most important measure of market health. A high ratio means broad participation; a low ratio means a narrow, fragile market.
+
+**Scoring Bands (aligned with dashboard thresholds):**
+
+| Ratio | Score Range | Signal |
+|-------|-------------|--------|
+| >= 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:** +5 when trend="up" and slope>0, -5 when trend="down" and slope<0.
+
+### Component 2: Sector Participation - Weight: 25%
+
+**Rationale:** A healthy market has most sectors participating. When only 2-3 sectors lead, the market is fragile and vulnerable to sector rotation shocks.
+
+**Sub-scores:**
+- **Uptrend Count (60%):** Number of sectors in uptrend mapped to 0-100
+- **Spread (40%):** Max-min ratio spread. Narrow spread = uniform participation (good). Wide spread = selective market (risky).
+
+**Overbought/Oversold classification uses dashboard thresholds:** >37% = Overbought, <9.7% = Oversold.
+
+### Component 3: Sector Rotation - Weight: 15%
+
+**Rationale:** In a healthy bull market, cyclical sectors (Technology, Consumer Cyclical) lead defensive sectors (Utilities, Consumer Defensive). When defensives lead, it signals risk-off behavior.
+
+**Sector Classification:**
+
+| Group | Sectors |
+|-------|---------|
+| Cyclical | Technology, Consumer Cyclical, Communication Services, Financial, Industrials |
+| Defensive | Utilities, Consumer Defensive, Healthcare, Real Estate |
+| Commodity | Energy, Basic Materials |
+
+**Scoring:** Based on cyclical_avg - defensive_avg difference.
+- Cyclical lead > +15pp = Strong risk-on (90-100)
+- Balanced within +/-5pp = Neutral (45-69)
+- Defensive lead > +15pp = Strong risk-off (0-19)
+
+**Commodity Adjustment:** When commodity sectors outperform both cyclical and defensive groups, it may signal late-cycle dynamics. A penalty of -5 to -10 is applied.
+
+### Component 4: Momentum - Weight: 20%
+
+**Rationale:** The direction and rate of change in breadth matters as much as the level. Improving breadth (positive slope, accelerating) suggests the environment is getting better; deteriorating breadth suggests caution.
+
+**Sub-scores:**
+- **Slope Score (50%):** Current slope mapped to 0-100 (typical range: -0.02 to +0.02)
+- **Acceleration (30%):** Recent 5-point slope average vs prior 5-point average
+- **Sector Slope Breadth (20%):** Count of sectors with positive slope
+
+### Component 5: Historical Context - Weight: 10%
+
+**Rationale:** Knowing where the current ratio falls in historical distribution provides perspective. A ratio that seems "low" might be historically average, or vice versa.
+
+**Scoring:** Percentile rank of current ratio in the full historical distribution (Aug 2023 to present).
+
+**Note:** The "all" dataset starts from 2023-08-11 (~650+ data points), while sector data starts from 2024-07-21 (~370+ data points each).
+
+---
+
+## Scoring Zones and Exposure Guidance
+
+| Score | Zone | Exposure | Description |
+|-------|------|----------|-------------|
+| 80-100 | Strong Bull | Full (100%) | Broad participation, strong momentum. Ideal for aggressive positioning. |
+| 60-79 | Bull | Normal (80-100%) | Healthy breadth. Standard position management. |
+| 40-59 | Neutral | Reduced (60-80%) | Mixed signals. Participate selectively. |
+| 20-39 | Cautious | Defensive (30-60%) | Weak breadth. Prioritize capital preservation. |
+| 0-19 | Bear | Preservation (0-30%) | Severe deterioration. Maximum defense. |
+
+---
+
+## Weight Rationale
+
+| Component | Weight | Rationale |
+|-----------|--------|-----------|
+| Market Breadth | 30% | Most direct measure of market health |
+| Sector Participation | 25% | Breadth of sector-level participation is critical for sustainability |
+| Momentum | 20% | Direction matters as much as level |
+| Sector Rotation | 15% | Rotation signals provide important risk-on/off context |
+| Historical Context | 10% | Provides perspective but less actionable than real-time signals |
+
+---
+
+## Limitations
+
+1. **Data History:** "all" data starts from Aug 2023; sector data from Jul 2024. Long-term percentile analysis is limited.
+2. **Single Source:** Relies entirely on Monty's dashboard (Finviz Elite data); no cross-validation with other breadth measures.
+3. **No Volume Data:** Uptrend ratio is price-based only; no volume confirmation.
+4. **Lagging Indicator:** 10-day moving average and slope introduce inherent lag.
+5. **US Only:** Covers US stocks only; no international market breadth.
+6. **Sector Classification:** Uses fixed GICS sectors which may not capture all rotation dynamics.
+7. **Finviz Dependency:** Upstream data depends on Finviz Elite availability and screener accuracy.
+
+---
+
+## Complementary Analysis
+
+This skill works best when combined with:
+- **Market Top Detector:** For distribution day and leadership deterioration signals
+- **Technical Analyst:** For index-level chart confirmation
+- **Sector Analyst:** For detailed sector rotation analysis
+- **Market News Analyst:** For fundamental catalyst context

package/.claude/skills/uptrend-analyzer/scripts/calculators/__init__.py

@@ -0,0 +1 @@
+# Uptrend Analyzer - Calculator modules

package/.claude/skills/uptrend-analyzer/scripts/calculators/historical_context_calculator.py

@@ -0,0 +1,122 @@
+#!/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 Dict, List, 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)
+
+    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', '?')}",
+    }
+
+
+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"

package/.claude/skills/uptrend-analyzer/scripts/calculators/market_breadth_calculator.py

@@ -0,0 +1,145 @@
+#!/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 Dict, List, 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}"

package/.claude/skills/uptrend-analyzer/scripts/calculators/momentum_calculator.py

@@ -0,0 +1,183 @@
+#!/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%): Current slope mapped to 0-100 (typical range: -0.02~+0.02)
+  - Acceleration (30%): Recent 5-point slope avg vs prior 5-point
+  - Sector Slope Breadth (20%): Count of sectors with positive slope
+"""
+
+from typing import Dict, List, 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")
+
+    # Sub-score 1: Slope Score (50%)
+    slope_score = _score_slope(current_slope) if current_slope is not None else 50
+
+    # Sub-score 2: Acceleration (30%)
+    accel_score, accel_value, accel_label = _score_acceleration(all_timeseries)
+
+    # 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, current_slope, accel_label)
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "slope": current_slope,
+        "slope_score": round(slope_score),
+        "acceleration": accel_value,
+        "acceleration_label": accel_label,
+        "acceleration_score": round(accel_score),
+        "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 _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_acceleration(timeseries: List[Dict]) -> tuple:
+    """Calculate acceleration: recent vs prior slope average.
+
+    Returns: (score, acceleration_value, label)
+    """
+    if len(timeseries) < 10:
+        return 50, None, "insufficient_data"
+
+    # Get slopes for recent 10 data points
+    recent_slopes = []
+    for row in timeseries[-10:]:
+        s = row.get("slope")
+        if s is not None:
+            recent_slopes.append(s)
+
+    if len(recent_slopes) < 10:
+        return 50, None, "insufficient_data"
+
+    recent_5_avg = sum(recent_slopes[-5:]) / 5
+    prior_5_avg = sum(recent_slopes[:5]) / 5
+
+    acceleration = recent_5_avg - prior_5_avg
+
+    if acceleration > 0.005:
+        label = "strong_accelerating"
+        score = 90
+    elif acceleration > 0.001:
+        label = "accelerating"
+        score = 75
+    elif acceleration > -0.001:
+        label = "steady"
+        score = 50
+    elif acceleration > -0.005:
+        label = "decelerating"
+        score = 25
+    else:
+        label = "strong_decelerating"
+        score = 10
+
+    return score, round(acceleration, 6), label
+
+
+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}"