quantwise 1.2.0 → 1.2.2

package/.claude/skills/market-breadth-analyzer/scripts/report_generator.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""
+Market Breadth Analyzer - Report Generator
+
+Generates JSON and Markdown reports for market breadth health 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", {})
+    freshness = metadata.get("data_freshness", {})
+
+    score = composite.get("composite_score", 0)
+    zone = composite.get("zone", "Unknown")
+    exposure = composite.get("exposure_guidance", "N/A")
+
+    # Header
+    lines.append("# Market Breadth Analyzer Report")
+    lines.append("")
+    lines.append(f"**Generated:** {metadata.get('generated_at', 'N/A')}")
+    lines.append(f"**Data Source:** TraderMonty Market Breadth CSV (no API key required)")
+    latest = freshness.get("latest_date", "N/A")
+    days_old = freshness.get("days_old", "?")
+    last_modified = freshness.get("last_modified")
+    lm_str = f" | CSV last modified: {last_modified}" if last_modified else ""
+    lines.append(f"**Latest Data:** {latest} ({days_old} days old{lm_str})")
+    lines.append(
+        f"**Live Dashboard:** [Interactive Chart]"
+        f"(https://tradermonty.github.io/market-breadth-analysis/)"
+    )
+    lines.append("")
+
+    # Freshness warning
+    warning = freshness.get("warning")
+    if warning:
+        lines.append(f"> **WARNING:** {warning}")
+        lines.append("")
+
+    # Overall Assessment
+    lines.append("---")
+    lines.append("")
+    lines.append("## Overall Assessment")
+    lines.append("")
+    zone_emoji = _zone_emoji(composite.get("zone_color", ""))
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    lines.append(f"| **Composite Score** | **{score}/100** |")
+    lines.append(f"| **Health Zone** | {zone_emoji} {zone} |")
+    lines.append(f"| **Equity Exposure** | {exposure} |")
+    lines.append(
+        f"| **Strongest** | {composite.get('strongest_health', {}).get('label', 'N/A')} "
+        f"({composite.get('strongest_health', {}).get('score', 0)}/100) |"
+    )
+    lines.append(
+        f"| **Weakest** | {composite.get('weakest_health', {}).get('label', 'N/A')} "
+        f"({composite.get('weakest_health', {}).get('score', 0)}/100) |"
+    )
+    dq = composite.get("data_quality", {})
+    if dq:
+        lines.append(f"| **Data Quality** | {dq.get('label', 'N/A')} |")
+    lines.append("")
+
+    # Guidance
+    lines.append(f"> **Guidance:** {composite.get('guidance', '')}")
+    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 = [
+        "breadth_level_trend",
+        "ma_crossover",
+        "cycle_position",
+        "bearish_signal",
+        "historical_percentile",
+        "divergence",
+    ]
+
+    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("")
+
+    # C1: Breadth Level & Trend
+    c1 = components.get("breadth_level_trend", {})
+    lines.append("### 1. Current Breadth Level & Trend")
+    lines.append("")
+    if c1:
+        lines.append(f"- **8MA Level:** {c1.get('current_8ma', 0):.4f}")
+        lines.append(f"- **200MA Level:** {c1.get('current_200ma', 0):.4f}")
+        lines.append(
+            f"- **200MA Trend:** {'Uptrend' if c1.get('trend') == 1 else 'Downtrend'}"
+        )
+        lines.append(f"- **Level Score:** {c1.get('level_score', 'N/A')}")
+        lines.append(f"- **Trend Score:** {c1.get('trend_score', 'N/A')}")
+    lines.append("")
+
+    # C2: MA Crossover
+    c2 = components.get("ma_crossover", {})
+    lines.append("### 2. 8MA vs 200MA Crossover Dynamics")
+    lines.append("")
+    if c2:
+        lines.append(f"- **Gap (8MA - 200MA):** {c2.get('gap', 0):+.4f}")
+        lines.append(f"- **Gap Score:** {c2.get('gap_score', 'N/A')}")
+        lines.append(
+            f"- **8MA Direction (5d):** {c2.get('ma8_direction', 'N/A')}"
+        )
+        lines.append(
+            f"- **Direction Modifier:** {c2.get('direction_modifier', 0):+d}"
+        )
+    lines.append("")
+
+    # C3: Cycle Position
+    c3 = components.get("cycle_position", {})
+    lines.append("### 3. Peak/Trough Cycle Position")
+    lines.append("")
+    if c3:
+        lines.append(f"- **Latest Marker:** {c3.get('latest_marker_type', 'None')}")
+        lines.append(f"- **Days Since Marker:** {c3.get('days_since_marker', 'N/A')}")
+        lines.append(f"- **8MA Trend:** {c3.get('ma8_trend', 'N/A')}")
+        if c3.get("extreme_trough"):
+            lines.append("- **Extreme Trough (8MA < 0.4):** Yes (+10 bonus)")
+    lines.append("")
+
+    # C4: Bearish Signal
+    c4 = components.get("bearish_signal", {})
+    lines.append("### 4. Bearish Signal Status")
+    lines.append("")
+    if c4:
+        lines.append(
+            f"- **Bearish Signal Active:** {'YES' if c4.get('signal_active') else 'No'}"
+        )
+        lines.append(
+            f"- **200MA Trend:** {'Uptrend' if c4.get('trend') == 1 else 'Downtrend'}"
+        )
+        lines.append(f"- **Current 8MA:** {c4.get('current_8ma', 0):.4f}")
+        in_pink = c4.get("in_pink_zone", False)
+        pink_days = c4.get("pink_zone_days", 0)
+        if in_pink:
+            lines.append(
+                f"- **Pink Zone:** YES ({pink_days} consecutive days) "
+                f"- 200MA downtrend + 8MA below 200MA"
+            )
+        else:
+            lines.append("- **Pink Zone:** No (outside bearish region)")
+        lines.append(f"- **Base Score:** {c4.get('base_score', 'N/A')}")
+        lines.append(
+            f"- **Context Adjustment:** {c4.get('context_adjustment', 0):+d}"
+        )
+        pink_adj = c4.get("pink_zone_adjustment", 0)
+        if pink_adj != 0:
+            lines.append(f"- **Pink Zone Adjustment:** {pink_adj:+d}")
+    lines.append("")
+
+    # C5: Historical Percentile
+    c5 = components.get("historical_percentile", {})
+    lines.append("### 5. Historical Percentile")
+    lines.append("")
+    if c5:
+        lines.append(f"- **Current 8MA:** {c5.get('current_8ma', 0):.4f}")
+        lines.append(
+            f"- **Percentile Rank:** {c5.get('percentile_rank', 'N/A'):.1f}%"
+        )
+        lines.append(f"- **Avg Peak (200MA):** {c5.get('avg_peak', 'N/A')}")
+        lines.append(f"- **Avg Trough (8MA<0.4):** {c5.get('avg_trough', 'N/A')}")
+        adj = c5.get("adjustment", 0)
+        if adj != 0:
+            label = "Overheated (-10)" if adj < 0 else "Oversold (+10)"
+            lines.append(f"- **Adjustment:** {label}")
+    lines.append("")
+
+    # C6: Divergence
+    c6 = components.get("divergence", {})
+    lines.append("### 6. S&P 500 vs Breadth Divergence")
+    lines.append("")
+    if c6:
+        lines.append(
+            f"- **S&P 500 60d Change:** {c6.get('sp500_pct_change', 0):+.2f}%"
+        )
+        lines.append(
+            f"- **Breadth 8MA 60d Change:** {c6.get('breadth_change', 0):+.4f}"
+        )
+        lines.append(f"- **Divergence Type:** {c6.get('divergence_type', 'N/A')}")
+    lines.append("")
+
+    # Key Levels to Watch
+    lines.append("---")
+    lines.append("")
+    lines.append("## Key Levels to Watch")
+    lines.append("")
+    key_levels = analysis.get("key_levels", {})
+    if key_levels:
+        lines.append("| Level | Value | Significance |")
+        lines.append("|-------|-------|-------------|")
+        for level_name, level_info in key_levels.items():
+            lines.append(
+                f"| {level_name} | {level_info.get('value', 'N/A')} | "
+                f"{level_info.get('significance', '')} |"
+            )
+    else:
+        lines.append("*No key levels computed.*")
+    lines.append("")
+
+    # Recommended Actions
+    lines.append("---")
+    lines.append("")
+    lines.append("## Recommended Actions")
+    lines.append("")
+    lines.append(f"**Health Zone:** {zone}")
+    lines.append(f"**Equity Exposure:** {exposure}")
+    lines.append("")
+    for action in composite.get("actions", []):
+        lines.append(f"- {action}")
+    lines.append("")
+
+    # Methodology
+    lines.append("---")
+    lines.append("")
+    lines.append("## Methodology")
+    lines.append("")
+    lines.append(
+        "This analysis uses TraderMonty's market breadth dataset to quantify "
+        "market participation health across 6 dimensions:"
+    )
+    lines.append("")
+    lines.append(
+        "1. **Breadth Level & Trend (25%):** Current 8MA level and 200MA trend direction"
+    )
+    lines.append(
+        "2. **MA Crossover (20%):** Gap between 8MA and 200MA with momentum detection"
+    )
+    lines.append(
+        "3. **Cycle Position (20%):** Position relative to recent peaks/troughs"
+    )
+    lines.append(
+        "4. **Bearish Signal (15%):** Backtested bearish signal flag from dataset"
+    )
+    lines.append(
+        "5. **Historical Percentile (10%):** Current level vs full history distribution"
+    )
+    lines.append(
+        "6. **Divergence (10%):** S&P 500 price vs breadth directional agreement"
+    )
+    lines.append("")
+    lines.append(
+        "Composite score: 0-100 (100 = maximum health). "
+        "No API key required - uses freely available CSV data."
+    )
+    lines.append("")
+    lines.append(
+        "For detailed methodology, see `references/breadth_analysis_methodology.md`."
+    )
+    lines.append("")
+
+    # Disclaimer
+    lines.append("---")
+    lines.append("")
+    lines.append(
+        "**Disclaimer:** This analysis is for educational and informational purposes only. "
+        "Not investment advice. Past patterns may not predict future outcomes. "
+        "Conduct your own research and consult a financial advisor before making "
+        "investment decisions."
+    )
+    lines.append("")
+
+    with open(output_file, "w") as f:
+        f.write("\n".join(lines))
+
+    print(f"  Markdown report saved to: {output_file}")
+
+
+def _zone_emoji(color: str) -> str:
+    mapping = {
+        "green": "🟢",
+        "blue": "🔵",
+        "yellow": "🟡",
+        "orange": "🟠",
+        "red": "🔴",
+    }
+    return mapping.get(color, "⚪")
+
+
+def _score_bar(score: int) -> str:
+    """Text bar for score visualization (100 = full/healthy)."""
+    if score >= 80:
+        return "████"
+    elif score >= 60:
+        return "███░"
+    elif score >= 40:
+        return "██░░"
+    elif score >= 20:
+        return "█░░░"
+    else:
+        return "░░░░"

package/.claude/skills/market-breadth-analyzer/scripts/scorer.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+Market Breadth Analyzer - Composite Scoring Engine
+
+Combines 6 component scores into a weighted composite (0-100).
+Score direction: 100 = Healthy, 0 = Critical (breadth is a health indicator).
+
+Component Weights:
+1. Current Breadth Level & Trend:  25%
+2. 8MA vs 200MA Crossover:        20%
+3. Peak/Trough Cycle Position:    20%
+4. Bearish Signal Status:         15%
+5. Historical Percentile:         10%
+6. S&P 500 vs Breadth Divergence: 10%
+Total: 100%
+
+Health Zone Mapping (100 = Healthy):
+  80-100: Strong    - Full equity exposure
+  60-79:  Healthy   - Normal operations
+  40-59:  Neutral   - Selective positioning
+  20-39:  Weakening - Profit-taking, raise cash
+  0-19:   Critical  - Capital preservation
+"""
+
+from typing import Dict, List, Optional
+
+
+COMPONENT_WEIGHTS = {
+    "breadth_level_trend": 0.25,
+    "ma_crossover": 0.20,
+    "cycle_position": 0.20,
+    "bearish_signal": 0.15,
+    "historical_percentile": 0.10,
+    "divergence": 0.10,
+}
+
+COMPONENT_LABELS = {
+    "breadth_level_trend": "Current Breadth Level & Trend",
+    "ma_crossover": "8MA vs 200MA Crossover",
+    "cycle_position": "Peak/Trough Cycle Position",
+    "bearish_signal": "Bearish Signal Status",
+    "historical_percentile": "Historical Percentile",
+    "divergence": "S&P 500 vs Breadth Divergence",
+}
+
+
+def calculate_composite_score(
+    component_scores: Dict[str, float],
+    data_availability: Optional[Dict[str, bool]] = None,
+) -> Dict:
+    """
+    Calculate weighted composite market breadth health score.
+
+    Args:
+        component_scores: Dict with keys matching COMPONENT_WEIGHTS, each 0-100.
+        data_availability: Optional dict mapping component key -> bool.
+
+    Returns:
+        Dict with composite_score, zone, exposure_guidance, guidance,
+        strongest/weakest components, component breakdown, and data_quality.
+    """
+    if data_availability is None:
+        data_availability = {}
+
+    # Weighted composite
+    composite = 0.0
+    for key, weight in COMPONENT_WEIGHTS.items():
+        score = component_scores.get(key, 50)
+        composite += score * weight
+
+    composite = round(composite, 1)
+
+    # Identify strongest and weakest health signals
+    valid_scores = {
+        k: v for k, v in component_scores.items() if k in COMPONENT_WEIGHTS
+    }
+
+    if valid_scores:
+        strongest_health = max(valid_scores, key=valid_scores.get)
+        weakest_health = min(valid_scores, key=valid_scores.get)
+    else:
+        strongest_health = "N/A"
+        weakest_health = "N/A"
+
+    # Zone interpretation
+    zone_info = _interpret_zone(composite)
+
+    # 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 - 2:
+        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"],
+        "strongest_health": {
+            "component": strongest_health,
+            "label": COMPONENT_LABELS.get(strongest_health, strongest_health),
+            "score": valid_scores.get(strongest_health, 0),
+        },
+        "weakest_health": {
+            "component": weakest_health,
+            "label": COMPONENT_LABELS.get(weakest_health, weakest_health),
+            "score": valid_scores.get(weakest_health, 0),
+        },
+        "data_quality": data_quality,
+        "component_scores": {
+            k: {
+                "score": component_scores.get(k, 50),
+                "weight": w,
+                "weighted_contribution": round(component_scores.get(k, 50) * w, 1),
+                "label": COMPONENT_LABELS[k],
+            }
+            for k, w in COMPONENT_WEIGHTS.items()
+        },
+    }
+
+
+def _interpret_zone(composite: float) -> Dict:
+    """Map composite score to health zone (100 = healthy)."""
+    if composite >= 80:
+        return {
+            "zone": "Strong",
+            "color": "green",
+            "exposure_guidance": "90-100%",
+            "guidance": (
+                "Broad market participation. Maintain full equity exposure."
+            ),
+            "actions": [
+                "Full position sizing allowed",
+                "New entries on pullbacks encouraged",
+                "Wide stop-losses acceptable",
+                "Growth and momentum strategies favored",
+            ],
+        }
+    elif composite >= 60:
+        return {
+            "zone": "Healthy",
+            "color": "blue",
+            "exposure_guidance": "75-90%",
+            "guidance": (
+                "Above-average breadth. Normal operations with standard risk management."
+            ),
+            "actions": [
+                "Normal position sizing",
+                "Standard stop-loss levels",
+                "New position entries allowed",
+                "Monitor for deterioration in leading indicators",
+            ],
+        }
+    elif composite >= 40:
+        return {
+            "zone": "Neutral",
+            "color": "yellow",
+            "exposure_guidance": "60-75%",
+            "guidance": (
+                "Mixed signals. Be selective with new positions and tighten risk controls."
+            ),
+            "actions": [
+                "Reduce new position sizes by 25-50%",
+                "Tighten stop-losses",
+                "Focus on stocks with strong relative strength",
+                "Avoid lagging sectors and speculative names",
+            ],
+        }
+    elif composite >= 20:
+        return {
+            "zone": "Weakening",
+            "color": "orange",
+            "exposure_guidance": "40-60%",
+            "guidance": (
+                "Breadth deteriorating. Begin profit-taking and raise cash allocation."
+            ),
+            "actions": [
+                "Take profits on weakest 25-40% of positions",
+                "No new momentum entries",
+                "Raise cash allocation significantly",
+                "Consider defensive sector rotation (XLU, XLP, XLV)",
+                "Watch for cycle trough signal for re-entry",
+            ],
+        }
+    else:
+        return {
+            "zone": "Critical",
+            "color": "red",
+            "exposure_guidance": "25-40%",
+            "guidance": (
+                "Severe breadth weakness. Capital preservation is the priority. "
+                "Watch for trough formation as re-entry signal."
+            ),
+            "actions": [
+                "Maximum cash allocation (60-75%)",
+                "Only hold strongest relative strength leaders",
+                "Consider hedges (put options, inverse ETFs)",
+                "Monitor for extreme trough (8MA < 0.4) as contrarian buy signal",
+                "Prepare watchlist for recovery: quality stocks near support",
+            ],
+        }
+
+
+# Testing
+if __name__ == "__main__":
+    print("Testing Market Breadth Scorer...\n")
+
+    # Test 1: Strong market
+    strong = {
+        "breadth_level_trend": 85,
+        "ma_crossover": 80,
+        "cycle_position": 75,
+        "bearish_signal": 85,
+        "historical_percentile": 70,
+        "divergence": 70,
+    }
+    r1 = calculate_composite_score(strong)
+    print(f"Test 1 - Strong: {r1['composite_score']}/100 -> {r1['zone']}")
+
+    # Test 2: Neutral
+    neutral = {
+        "breadth_level_trend": 50,
+        "ma_crossover": 50,
+        "cycle_position": 50,
+        "bearish_signal": 50,
+        "historical_percentile": 50,
+        "divergence": 50,
+    }
+    r2 = calculate_composite_score(neutral)
+    print(f"Test 2 - Neutral: {r2['composite_score']}/100 -> {r2['zone']}")
+
+    # Test 3: Critical
+    crisis = {
+        "breadth_level_trend": 10,
+        "ma_crossover": 5,
+        "cycle_position": 15,
+        "bearish_signal": 10,
+        "historical_percentile": 10,
+        "divergence": 30,
+    }
+    r3 = calculate_composite_score(crisis)
+    print(f"Test 3 - Critical: {r3['composite_score']}/100 -> {r3['zone']}")
+
+    print("\nAll tests completed.")