quantwise 1.2.0 → 1.2.2

package/.claude/skills/uptrend-analyzer/scripts/report_generator.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+Uptrend Analyzer - Report Generator
+
+Generates JSON and Markdown reports for uptrend breadth analysis.
+"""
+
+import json
+from typing import Dict
+
+
+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", {})
+
+    score = composite.get("composite_score", 0)
+    zone = composite.get("zone", "Unknown")
+    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(f"**Data Source:** Monty's Uptrend Ratio Dashboard (GitHub CSV)")
+    lines.append(f"**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"| **Exposure Guidance** | {exposure} |")
+    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')} |")
+    lines.append("")
+
+    # Guidance
+    lines.append(f"> **Guidance:** {composite.get('guidance', '')}")
+    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)})")
+
+        # 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"- **Current Slope:** {_format_slope(momentum.get('slope'))} "
+                     f"(score: {momentum.get('slope_score', 0)}/100)")
+        lines.append(f"- **Acceleration:** {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
+    historical = components.get("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')})")
+    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 | 10MA | Trend | Slope | Status |")
+        lines.append("|------|--------|-------|------|-------|-------|--------|")
+        for i, s in enumerate(sector_details, 1):
+            lines.append(f"| {i} | {s.get('sector', '')} | "
+                         f"{s.get('ratio_pct', 'N/A')}% | "
+                         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("")
+
+    # Recommended Actions
+    lines.append("---")
+    lines.append("")
+    lines.append("## Recommended Actions")
+    lines.append("")
+    lines.append(f"**Zone:** {zone}")
+    lines.append(f"**Exposure Guidance:** {exposure}")
+    lines.append("")
+    for action in composite.get("actions", []):
+        lines.append(f"- {action}")
+    lines.append("")
+
+    # Active Warnings (overlay adjustments)
+    active_warnings = composite.get("active_warnings", [])
+    if active_warnings:
+        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("")
+
+    # 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("")
+
+    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": "🟢",
+        "light_green": "🟢",
+        "yellow": "🟡",
+        "orange": "🟠",
+        "red": "🔴",
+    }
+    return mapping.get(color, "⚪")
+
+
+def _score_bar(score: int) -> str:
+    """Simple text bar for score visualization"""
+    if score >= 80:
+        return "████"
+    elif score >= 60:
+        return "███░"
+    elif score >= 40:
+        return "██░░"
+    elif score >= 20:
+        return "█░░░"
+    else:
+        return "░░░░"
+
+
+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"

package/.claude/skills/uptrend-analyzer/scripts/scorer.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""
+Uptrend Analyzer - Composite Scoring Engine
+
+Combines 5 component scores into a weighted composite (0-100).
+Higher score = healthier market (opposite of Market Top Detector).
+
+Component Weights:
+1. Market Breadth (Overall):   30%
+2. Sector Participation:       25%
+3. Sector Rotation:            15%
+4. Momentum:                   20%
+5. Historical Context:         10%
+Total: 100%
+
+Scoring Zones (higher = better):
+  80-100: Strong Bull   - Full Exposure (100%)
+  60-79:  Bull          - Normal Exposure (80-100%)
+  40-59:  Neutral       - Reduced Exposure (60-80%)
+  20-39:  Cautious      - Defensive (30-60%)
+  0-19:   Bear          - Capital Preservation (0-30%)
+"""
+
+from typing import Dict, List, Optional
+
+
+COMPONENT_WEIGHTS = {
+    "market_breadth": 0.30,
+    "sector_participation": 0.25,
+    "sector_rotation": 0.15,
+    "momentum": 0.20,
+    "historical_context": 0.10,
+}
+
+COMPONENT_LABELS = {
+    "market_breadth": "Market Breadth (Overall)",
+    "sector_participation": "Sector Participation",
+    "sector_rotation": "Sector Rotation",
+    "momentum": "Momentum",
+    "historical_context": "Historical Context",
+}
+
+
+def calculate_composite_score(component_scores: Dict[str, float],
+                              data_availability: Optional[Dict[str, bool]] = None,
+                              warning_flags: Optional[Dict[str, bool]] = None) -> Dict:
+    """
+    Calculate weighted composite market health score.
+
+    Args:
+        component_scores: Dict with keys matching COMPONENT_WEIGHTS,
+                         each value 0-100
+        data_availability: Optional dict mapping component key -> bool indicating
+                          if data was actually available (vs neutral default)
+        warning_flags: Optional dict of component warning flags, e.g.
+                      {"late_cycle": True, "high_spread": True}
+
+    Returns:
+        Dict with composite_score, zone, exposure_guidance, guidance,
+        strongest/weakest components, component breakdown, data_quality,
+        and active_warnings
+    """
+    if data_availability is None:
+        data_availability = {}
+    if warning_flags is None:
+        warning_flags = {}
+
+    # Calculate weighted composite
+    composite = 0.0
+    for key, weight in COMPONENT_WEIGHTS.items():
+        score = component_scores.get(key, 0)
+        composite += score * weight
+
+    composite = round(composite, 1)
+
+    # Identify strongest and weakest components
+    valid_scores = {k: v for k, v in component_scores.items()
+                    if k in COMPONENT_WEIGHTS}
+
+    if valid_scores:
+        strongest = max(valid_scores, key=valid_scores.get)
+        weakest = min(valid_scores, key=valid_scores.get)
+    else:
+        strongest = "N/A"
+        weakest = "N/A"
+
+    # Get zone interpretation
+    zone_info = _interpret_zone(composite)
+
+    # Overlay warning-specific adjustments
+    active_warnings = _apply_warning_overlays(zone_info, warning_flags)
+
+    # Calculate data quality
+    available_count = sum(
+        1 for k in COMPONENT_WEIGHTS
+        if data_availability.get(k, True)
+    )
+    total_components = len(COMPONENT_WEIGHTS)
+    missing_components = [
+        COMPONENT_LABELS[k] for k in COMPONENT_WEIGHTS
+        if not data_availability.get(k, True)
+    ]
+
+    if available_count == total_components:
+        quality_label = f"Complete ({available_count}/{total_components} components)"
+    elif available_count >= total_components - 1:
+        quality_label = (f"Partial ({available_count}/{total_components} components)"
+                        " - interpret with caution")
+    else:
+        quality_label = (f"Limited ({available_count}/{total_components} components)"
+                        " - low confidence")
+
+    data_quality = {
+        "available_count": available_count,
+        "total_components": total_components,
+        "label": quality_label,
+        "missing_components": missing_components,
+    }
+
+    return {
+        "composite_score": composite,
+        "zone": zone_info["zone"],
+        "zone_color": zone_info["color"],
+        "exposure_guidance": zone_info["exposure_guidance"],
+        "guidance": zone_info["guidance"],
+        "actions": zone_info["actions"],
+        "active_warnings": active_warnings,
+        "strongest_component": {
+            "component": strongest,
+            "label": COMPONENT_LABELS.get(strongest, strongest),
+            "score": valid_scores.get(strongest, 0),
+        },
+        "weakest_component": {
+            "component": weakest,
+            "label": COMPONENT_LABELS.get(weakest, weakest),
+            "score": valid_scores.get(weakest, 0),
+        },
+        "data_quality": data_quality,
+        "component_scores": {
+            k: {
+                "score": component_scores.get(k, 0),
+                "weight": w,
+                "weighted_contribution": round(component_scores.get(k, 0) * w, 1),
+                "label": COMPONENT_LABELS[k],
+            }
+            for k, w in COMPONENT_WEIGHTS.items()
+        },
+    }
+
+
+def _apply_warning_overlays(zone_info: Dict,
+                            warning_flags: Dict[str, bool]) -> List[Dict]:
+    """Apply warning-driven adjustments to zone guidance and actions.
+
+    When component-level warnings (e.g. late_cycle, high_spread) are active,
+    tighten the exposure guidance and prepend cautionary actions even if the
+    composite score places the market in a bullish zone.
+
+    Returns:
+        List of active warning dicts with label, description, and extra actions
+    """
+    active = []
+
+    if warning_flags.get("late_cycle"):
+        active.append({
+            "flag": "late_cycle",
+            "label": "LATE CYCLE WARNING",
+            "description": ("Commodity sectors leading both cyclical and defensive groups. "
+                            "Historically associated with late-cycle inflation or sector rotation "
+                            "preceding broader market weakness."),
+            "actions": [
+                "Favor lower end of exposure range (e.g. 80% if guidance is 80-100%)",
+                "New entries limited to A-grade setups only",
+                "Tighten stops on commodity/cyclical positions",
+                "Monitor for commodity rollover as potential broad market lead indicator",
+            ],
+        })
+
+    if warning_flags.get("high_spread"):
+        active.append({
+            "flag": "high_spread",
+            "label": "HIGH SELECTIVITY WARNING",
+            "description": ("Wide spread between strongest and weakest sectors indicates "
+                            "highly selective market. Breadth may be masking narrowing leadership."),
+            "actions": [
+                "Concentrate on sectors with ratio above 10MA",
+                "Avoid lagging sectors even if trend is nominally 'up'",
+                "Reduce position count to highest-conviction ideas",
+            ],
+        })
+
+    # If any warning is active, tighten exposure guidance for bullish zones
+    if active and zone_info["zone"] in ("Strong Bull", "Bull"):
+        original = zone_info["exposure_guidance"]
+        if zone_info["zone"] == "Strong Bull":
+            zone_info["exposure_guidance"] = "Full Exposure with Caution (90-100%)"
+        elif zone_info["zone"] == "Bull":
+            zone_info["exposure_guidance"] = "Normal Exposure, Lower End (80-90%)"
+        zone_info["guidance"] += (
+            f" However, active warnings suggest operating at the conservative "
+            f"end of the range."
+        )
+
+    return active
+
+
+def _interpret_zone(composite: float) -> Dict:
+    """Map composite score to health zone (higher = healthier)"""
+    if composite >= 80:
+        return {
+            "zone": "Strong Bull",
+            "color": "green",
+            "exposure_guidance": "Full Exposure (100%)",
+            "guidance": "Broad market participation with strong momentum. Ideal environment for new positions.",
+            "actions": [
+                "Full equity exposure allowed",
+                "Aggressive position sizing for breakout entries",
+                "Add to winning positions on pullbacks",
+                "Minimal hedging needed",
+            ],
+        }
+    elif composite >= 60:
+        return {
+            "zone": "Bull",
+            "color": "light_green",
+            "exposure_guidance": "Normal Exposure (80-100%)",
+            "guidance": "Healthy market breadth supporting equity allocation. Standard position management.",
+            "actions": [
+                "Normal position sizing",
+                "New entries on quality setups",
+                "Standard stop-loss levels",
+                "Monitor sector rotation for early warnings",
+            ],
+        }
+    elif composite >= 40:
+        return {
+            "zone": "Neutral",
+            "color": "yellow",
+            "exposure_guidance": "Reduced Exposure (60-80%)",
+            "guidance": "Mixed signals. Participate selectively with tighter risk controls.",
+            "actions": [
+                "Reduce position sizes by 20-30%",
+                "Focus on strongest sectors only",
+                "Tighten stop-losses",
+                "Avoid low-quality setups",
+                "Increase cash allocation gradually",
+            ],
+        }
+    elif composite >= 20:
+        return {
+            "zone": "Cautious",
+            "color": "orange",
+            "exposure_guidance": "Defensive (30-60%)",
+            "guidance": "Weak breadth environment. Prioritize capital preservation over gains.",
+            "actions": [
+                "Significant cash allocation (40-70%)",
+                "Only hold strongest leaders in uptrending sectors",
+                "Tight stops on all positions",
+                "Consider defensive sector allocation",
+                "No new aggressive entries",
+            ],
+        }
+    else:
+        return {
+            "zone": "Bear",
+            "color": "red",
+            "exposure_guidance": "Capital Preservation (0-30%)",
+            "guidance": "Severe breadth deterioration. Maximum defensive posture.",
+            "actions": [
+                "Maximum cash (70-100%)",
+                "Exit most equity positions",
+                "Only ultra-high-conviction holdings",
+                "Consider hedges (inverse ETFs, puts)",
+                "Wait for breadth recovery before re-entry",
+            ],
+        }