quantwise 1.2.0 → 1.2.2

package/.claude/skills/market-breadth-analyzer/scripts/calculators/trend_level_calculator.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Component 1: Current Breadth Level & Trend (Weight: 25%)
+
+The most direct indicator of market health.
+
+Input: Breadth_Index_8MA, Breadth_200MA_Trend (latest row)
+
+Scoring (100 = healthy):
+  8MA Level (70% of component):
+    >= 0.70 -> 95    >= 0.60 -> 80    >= 0.50 -> 65
+    >= 0.40 -> 50    >= 0.30 -> 35    >= 0.20 -> 20
+    <  0.20 -> 5
+
+  200MA Trend (30% of component):
+    Trend == 1  -> 80 (uptrend)
+    Trend == -1 -> 20 (downtrend)
+
+  Score = 0.70 * level_score + 0.30 * trend_score
+"""
+
+from typing import Dict, List
+
+
+def calculate_breadth_level_trend(rows: List[Dict]) -> Dict:
+    """
+    Calculate current breadth level and trend score.
+
+    Args:
+        rows: All detail rows sorted by date ascending.
+
+    Returns:
+        Dict with score, signal, and component details.
+    """
+    if not rows:
+        return {
+            "score": 50,
+            "signal": "NO DATA: No breadth data available",
+            "data_available": False,
+        }
+
+    latest = rows[-1]
+    ma8 = latest["Breadth_Index_8MA"]
+    trend = latest["Breadth_200MA_Trend"]
+
+    # 8MA level score
+    level_score = _score_8ma_level(ma8)
+
+    # Trend score
+    trend_score = 80 if trend == 1 else 20
+
+    # Combined
+    score = round(0.70 * level_score + 0.30 * trend_score)
+    score = max(0, min(100, score))
+
+    # Signal
+    signal = _generate_signal(ma8, trend, score)
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "current_8ma": ma8,
+        "current_200ma": latest["Breadth_Index_200MA"],
+        "trend": trend,
+        "level_score": level_score,
+        "trend_score": trend_score,
+        "date": latest["Date"],
+    }
+
+
+def _score_8ma_level(ma8: float) -> int:
+    """Score based on 8MA level."""
+    if ma8 >= 0.70:
+        return 95
+    elif ma8 >= 0.60:
+        return 80
+    elif ma8 >= 0.50:
+        return 65
+    elif ma8 >= 0.40:
+        return 50
+    elif ma8 >= 0.30:
+        return 35
+    elif ma8 >= 0.20:
+        return 20
+    else:
+        return 5
+
+
+def _generate_signal(ma8: float, trend: int, score: int) -> str:
+    """Generate human-readable signal."""
+    trend_str = "uptrend" if trend == 1 else "downtrend"
+
+    if score >= 80:
+        return f"STRONG: 8MA={ma8:.3f} in {trend_str} - broad participation"
+    elif score >= 60:
+        return f"HEALTHY: 8MA={ma8:.3f} in {trend_str} - above average"
+    elif score >= 40:
+        return f"NEUTRAL: 8MA={ma8:.3f} in {trend_str} - mixed signals"
+    elif score >= 20:
+        return f"WEAK: 8MA={ma8:.3f} in {trend_str} - deteriorating breadth"
+    else:
+        return f"CRITICAL: 8MA={ma8:.3f} in {trend_str} - severe weakness"

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

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+Market Breadth Analyzer - CSV Data Client
+
+Fetches and parses market breadth CSV data from TraderMonty's public GitHub Pages.
+No API key required.
+
+Data sources:
+  Detail:  https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv
+  Summary: https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv
+"""
+
+import csv
+import io
+import sys
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+DEFAULT_DETAIL_URL = (
+    "https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv"
+)
+DEFAULT_SUMMARY_URL = (
+    "https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv"
+)
+
+DETAIL_COLUMNS = {
+    "Date": str,
+    "S&P500_Price": float,
+    "Breadth_Index_Raw": float,
+    "Breadth_Index_200MA": float,
+    "Breadth_Index_8MA": float,
+    "Breadth_200MA_Trend": int,
+    "Bearish_Signal": bool,
+    "Is_Peak": bool,
+    "Is_Trough": bool,
+    "Is_Trough_8MA_Below_04": bool,
+}
+
+TIMEOUT = 30
+
+
+def fetch_detail_csv(url: str = DEFAULT_DETAIL_URL) -> List[Dict]:
+    """
+    Fetch and parse the detail CSV (market_breadth_data.csv).
+
+    Returns list of dicts sorted by date ascending (oldest first).
+    """
+    print(f"  Fetching detail CSV from {url}...", end=" ", flush=True)
+    try:
+        resp = requests.get(url, timeout=TIMEOUT)
+        resp.raise_for_status()
+    except requests.RequestException as e:
+        print("FAILED")
+        print(f"ERROR: Failed to fetch detail CSV: {e}", file=sys.stderr)
+        return []
+
+    reader = csv.DictReader(io.StringIO(resp.text))
+    rows = []
+
+    for line_num, raw_row in enumerate(reader, start=2):
+        try:
+            row = _parse_detail_row(raw_row)
+            rows.append(row)
+        except (ValueError, KeyError) as e:
+            print(f"\n  WARN: Skipping line {line_num}: {e}", file=sys.stderr)
+
+    # Validate columns
+    if rows:
+        missing = set(DETAIL_COLUMNS.keys()) - set(rows[0].keys())
+        if missing:
+            print(f"\n  WARN: Missing columns: {missing}", file=sys.stderr)
+
+    # Sort by date ascending
+    rows.sort(key=lambda r: r["Date"])
+
+    print(f"OK ({len(rows)} rows, {rows[0]['Date']} to {rows[-1]['Date']})")
+    return rows
+
+
+def fetch_summary_csv(url: str = DEFAULT_SUMMARY_URL) -> Dict[str, str]:
+    """
+    Fetch and parse the summary CSV (market_breadth_summary.csv).
+
+    Returns dict mapping Metric -> Value.
+    """
+    print(f"  Fetching summary CSV from {url}...", end=" ", flush=True)
+    try:
+        resp = requests.get(url, timeout=TIMEOUT)
+        resp.raise_for_status()
+    except requests.RequestException as e:
+        print("FAILED")
+        print(f"ERROR: Failed to fetch summary CSV: {e}", file=sys.stderr)
+        return {}
+
+    reader = csv.DictReader(io.StringIO(resp.text))
+    summary = {}
+    for raw_row in reader:
+        metric = raw_row.get("Metric", "").strip()
+        value = raw_row.get("Value", "").strip()
+        if metric:
+            summary[metric] = value
+
+    print(f"OK ({len(summary)} metrics)")
+    return summary
+
+
+def check_data_freshness(rows: List[Dict], max_stale_days: int = 5,
+                         detail_url: str = DEFAULT_DETAIL_URL) -> Dict:
+    """
+    Check whether the latest data is reasonably fresh.
+    Uses both CSV date and HTTP Last-Modified header for accuracy.
+
+    Args:
+        rows: Parsed detail rows (sorted by date ascending).
+        max_stale_days: Calendar days before data is considered stale.
+        detail_url: URL to check Last-Modified header against.
+
+    Returns:
+        Dict with is_fresh, latest_date, days_old, last_modified, warning.
+    """
+    if not rows:
+        return {
+            "is_fresh": False,
+            "latest_date": None,
+            "days_old": None,
+            "last_modified": None,
+            "warning": "No data available",
+        }
+
+    latest_date_str = rows[-1]["Date"]
+    try:
+        latest_date = datetime.strptime(latest_date_str, "%Y-%m-%d")
+    except ValueError:
+        return {
+            "is_fresh": False,
+            "latest_date": latest_date_str,
+            "days_old": None,
+            "last_modified": None,
+            "warning": f"Cannot parse latest date: {latest_date_str}",
+        }
+
+    days_old = (datetime.now() - latest_date).days
+    is_fresh = days_old <= max_stale_days
+
+    # Check HTTP Last-Modified header for additional freshness info
+    last_modified = _check_last_modified(detail_url)
+
+    warning = None
+    if not is_fresh:
+        warning = (
+            f"Data is {days_old} days old (latest: {latest_date_str}). "
+            f"Threshold: {max_stale_days} days. Results may not reflect current conditions."
+        )
+
+    return {
+        "is_fresh": is_fresh,
+        "latest_date": latest_date_str,
+        "days_old": days_old,
+        "last_modified": last_modified,
+        "warning": warning,
+    }
+
+
+def _check_last_modified(url: str) -> Optional[str]:
+    """Check HTTP Last-Modified header via HEAD request."""
+    try:
+        resp = requests.head(url, timeout=10, allow_redirects=True)
+        resp.raise_for_status()
+        lm = resp.headers.get("Last-Modified")
+        if lm:
+            from email.utils import parsedate_to_datetime
+            dt = parsedate_to_datetime(lm)
+            return dt.strftime("%Y-%m-%d %H:%M UTC")
+    except Exception:
+        pass
+    return None
+
+
+def get_latest_n_rows(rows: List[Dict], n: int) -> List[Dict]:
+    """Return the last n rows (most recent)."""
+    return rows[-n:] if len(rows) >= n else rows[:]
+
+
+def _parse_detail_row(raw: Dict) -> Dict:
+    """Convert a raw CSV row dict to properly typed values."""
+    row = {}
+    row["Date"] = raw["Date"].strip()
+    row["S&P500_Price"] = float(raw["S&P500_Price"])
+    row["Breadth_Index_Raw"] = float(raw["Breadth_Index_Raw"])
+    row["Breadth_Index_200MA"] = float(raw["Breadth_Index_200MA"])
+    row["Breadth_Index_8MA"] = float(raw["Breadth_Index_8MA"])
+    row["Breadth_200MA_Trend"] = int(raw["Breadth_200MA_Trend"])
+    row["Bearish_Signal"] = _parse_bool(raw["Bearish_Signal"])
+    row["Is_Peak"] = _parse_bool(raw["Is_Peak"])
+    row["Is_Trough"] = _parse_bool(raw["Is_Trough"])
+    row["Is_Trough_8MA_Below_04"] = _parse_bool(raw["Is_Trough_8MA_Below_04"])
+    return row
+
+
+def _parse_bool(val: str) -> bool:
+    """Parse boolean from CSV string."""
+    return val.strip().lower() in ("true", "1", "yes")
+
+
+# Testing
+if __name__ == "__main__":
+    print("Testing CSV Client...\n")
+
+    detail = fetch_detail_csv()
+    print(f"  Detail rows: {len(detail)}")
+    if detail:
+        print(f"  First row: {detail[0]}")
+        print(f"  Last row:  {detail[-1]}")
+
+    print()
+    summary = fetch_summary_csv()
+    print(f"  Summary metrics: {summary}")
+
+    print()
+    freshness = check_data_freshness(detail)
+    print(f"  Freshness: {freshness}")
+
+    print("\nAll tests completed.")

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

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""
+Market Breadth Analyzer - Main Orchestrator
+
+Quantifies market breadth health using TraderMonty's public CSV data.
+Generates a 0-100 composite score across 6 components.
+No API key required.
+
+Usage:
+    # Default (uses public CSV URLs):
+    python3 market_breadth_analyzer.py
+
+    # Custom URLs:
+    python3 market_breadth_analyzer.py \\
+        --detail-url "https://example.com/data.csv" \\
+        --summary-url "https://example.com/summary.csv"
+
+    # Custom output directory:
+    python3 market_breadth_analyzer.py --output-dir ./reports
+
+Output:
+    - JSON: market_breadth_YYYY-MM-DD_HHMMSS.json
+    - Markdown: market_breadth_YYYY-MM-DD_HHMMSS.md
+"""
+
+import argparse
+import os
+import sys
+from datetime import datetime
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(__file__))
+
+from csv_client import (
+    fetch_detail_csv,
+    fetch_summary_csv,
+    check_data_freshness,
+    DEFAULT_DETAIL_URL,
+    DEFAULT_SUMMARY_URL,
+)
+from calculators.trend_level_calculator import calculate_breadth_level_trend
+from calculators.ma_crossover_calculator import calculate_ma_crossover
+from calculators.cycle_calculator import calculate_cycle_position
+from calculators.bearish_signal_calculator import calculate_bearish_signal
+from calculators.historical_context_calculator import calculate_historical_percentile
+from calculators.divergence_calculator import calculate_divergence
+from scorer import calculate_composite_score
+from report_generator import generate_json_report, generate_markdown_report
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(
+        description="Market Breadth Analyzer - 6-Component Health Scoring"
+    )
+
+    parser.add_argument(
+        "--detail-url",
+        default=DEFAULT_DETAIL_URL,
+        help="URL for detail CSV (market_breadth_data.csv)",
+    )
+    parser.add_argument(
+        "--summary-url",
+        default=DEFAULT_SUMMARY_URL,
+        help="URL for summary CSV (market_breadth_summary.csv)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Output directory for reports (default: current directory)",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_arguments()
+
+    print("=" * 70)
+    print("Market Breadth Analyzer")
+    print("6-Component Health Scoring (No API Key Required)")
+    print("=" * 70)
+    print()
+
+    # ========================================================================
+    # Step 1: Fetch CSV Data
+    # ========================================================================
+    print("Step 1: Fetching CSV Data")
+    print("-" * 70)
+
+    detail_rows = fetch_detail_csv(args.detail_url)
+    if not detail_rows:
+        print("ERROR: Cannot proceed without detail CSV data", file=sys.stderr)
+        sys.exit(1)
+
+    summary = fetch_summary_csv(args.summary_url)
+
+    freshness = check_data_freshness(detail_rows)
+    if freshness.get("warning"):
+        print(f"  WARNING: {freshness['warning']}")
+    else:
+        print(
+            f"  Data freshness: OK "
+            f"(latest: {freshness['latest_date']}, {freshness['days_old']} days old)"
+        )
+
+    print()
+
+    # ========================================================================
+    # Step 2: Calculate Components
+    # ========================================================================
+    print("Step 2: Calculating Components")
+    print("-" * 70)
+
+    # Component 1: Current Breadth Level & Trend (25%)
+    print("  [1/6] Current Breadth Level & Trend...", end=" ", flush=True)
+    comp1 = calculate_breadth_level_trend(detail_rows)
+    print(f"Score: {comp1['score']} ({comp1['signal']})")
+
+    # Component 2: 8MA vs 200MA Crossover (20%)
+    print("  [2/6] 8MA vs 200MA Crossover...", end=" ", flush=True)
+    comp2 = calculate_ma_crossover(detail_rows)
+    print(f"Score: {comp2['score']} ({comp2['signal']})")
+
+    # Component 3: Peak/Trough Cycle Position (20%)
+    print("  [3/6] Peak/Trough Cycle Position...", end=" ", flush=True)
+    comp3 = calculate_cycle_position(detail_rows)
+    print(f"Score: {comp3['score']} ({comp3['signal']})")
+
+    # Component 4: Bearish Signal Status (15%)
+    print("  [4/6] Bearish Signal Status...", end=" ", flush=True)
+    comp4 = calculate_bearish_signal(detail_rows)
+    print(f"Score: {comp4['score']} ({comp4['signal']})")
+
+    # Component 5: Historical Percentile (10%)
+    print("  [5/6] Historical Percentile...", end=" ", flush=True)
+    comp5 = calculate_historical_percentile(detail_rows, summary)
+    print(f"Score: {comp5['score']} ({comp5['signal']})")
+
+    # Component 6: S&P 500 vs Breadth Divergence (10%)
+    print("  [6/6] S&P 500 vs Breadth Divergence...", end=" ", flush=True)
+    comp6 = calculate_divergence(detail_rows)
+    print(f"Score: {comp6['score']} ({comp6['signal']})")
+
+    print()
+
+    # ========================================================================
+    # Step 3: Composite Score
+    # ========================================================================
+    print("Step 3: Calculating Composite Score")
+    print("-" * 70)
+
+    component_scores = {
+        "breadth_level_trend": comp1["score"],
+        "ma_crossover": comp2["score"],
+        "cycle_position": comp3["score"],
+        "bearish_signal": comp4["score"],
+        "historical_percentile": comp5["score"],
+        "divergence": comp6["score"],
+    }
+
+    data_availability = {
+        "breadth_level_trend": comp1.get("data_available", True),
+        "ma_crossover": comp2.get("data_available", True),
+        "cycle_position": comp3.get("data_available", True),
+        "bearish_signal": comp4.get("data_available", True),
+        "historical_percentile": comp5.get("data_available", True),
+        "divergence": comp6.get("data_available", True),
+    }
+
+    composite = calculate_composite_score(component_scores, data_availability)
+
+    print(f"  Composite Score: {composite['composite_score']}/100")
+    print(f"  Health Zone: {composite['zone']}")
+    print(f"  Equity Exposure: {composite['exposure_guidance']}")
+    print(
+        f"  Strongest: {composite['strongest_health']['label']} "
+        f"({composite['strongest_health']['score']})"
+    )
+    print(
+        f"  Weakest: {composite['weakest_health']['label']} "
+        f"({composite['weakest_health']['score']})"
+    )
+    print()
+
+    # ========================================================================
+    # Step 4: Key Levels
+    # ========================================================================
+    key_levels = _compute_key_levels(detail_rows, summary)
+
+    # ========================================================================
+    # Step 5: Generate Reports
+    # ========================================================================
+    print("Step 4: Generating Reports")
+    print("-" * 70)
+
+    analysis = {
+        "metadata": {
+            "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "data_source": "TraderMonty Market Breadth CSV",
+            "detail_url": args.detail_url,
+            "summary_url": args.summary_url,
+            "total_rows": len(detail_rows),
+            "data_freshness": freshness,
+        },
+        "composite": composite,
+        "components": {
+            "breadth_level_trend": comp1,
+            "ma_crossover": comp2,
+            "cycle_position": comp3,
+            "bearish_signal": comp4,
+            "historical_percentile": comp5,
+            "divergence": comp6,
+        },
+        "key_levels": key_levels,
+    }
+
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H%M%S")
+    json_file = os.path.join(args.output_dir, f"market_breadth_{timestamp}.json")
+    md_file = os.path.join(args.output_dir, f"market_breadth_{timestamp}.md")
+
+    generate_json_report(analysis, json_file)
+    generate_markdown_report(analysis, md_file)
+
+    print()
+    print("=" * 70)
+    print("Market Breadth Analysis Complete")
+    print("=" * 70)
+    print(f"  Composite Score: {composite['composite_score']}/100")
+    print(f"  Health Zone: {composite['zone']}")
+    print(f"  Equity Exposure: {composite['exposure_guidance']}")
+    print(f"  JSON Report: {json_file}")
+    print(f"  Markdown Report: {md_file}")
+    print()
+
+
+def _compute_key_levels(rows, summary):
+    """Compute key breadth levels to watch."""
+    if not rows:
+        return {}
+
+    latest = rows[-1]
+    ma8 = latest["Breadth_Index_8MA"]
+    ma200 = latest["Breadth_Index_200MA"]
+
+    levels = {}
+
+    # 200MA crossover level
+    levels["200MA Level"] = {
+        "value": f"{ma200:.4f}",
+        "significance": (
+            "Key support/resistance for 8MA. "
+            "8MA crossing below is an early warning of deterioration, "
+            "not a standalone bearish signal."
+        ),
+    }
+
+    # 0.40 extreme weakness threshold
+    levels["Extreme Weakness (0.40)"] = {
+        "value": "0.4000",
+        "significance": (
+            "8MA below 0.40 marks extreme weakness. "
+            "Historically, troughs at this level precede significant rallies."
+        ),
+    }
+
+    # 0.60 healthy threshold
+    levels["Healthy Threshold (0.60)"] = {
+        "value": "0.6000",
+        "significance": (
+            "8MA above 0.60 indicates broad participation. "
+            "Below 0.60 = selective market, above = inclusive rally."
+        ),
+    }
+
+    # Average peak from summary
+    avg_peak_str = summary.get("Average Peaks (200MA)", "")
+    try:
+        avg_peak = float(avg_peak_str)
+        levels["Historical Avg Peak"] = {
+            "value": f"{avg_peak:.3f}",
+            "significance": (
+                "Average peak level. Approaching this level suggests "
+                "breadth may be near a cyclical high."
+            ),
+        }
+    except (ValueError, TypeError):
+        pass
+
+    # Average trough from summary
+    avg_trough_str = summary.get("Average Troughs (8MA < 0.4)", "")
+    try:
+        avg_trough = float(avg_trough_str)
+        levels["Historical Avg Trough"] = {
+            "value": f"{avg_trough:.3f}",
+            "significance": (
+                "Average extreme trough level. Reaching this level "
+                "is a potential contrarian buy signal."
+            ),
+        }
+    except (ValueError, TypeError):
+        pass
+
+    return levels
+
+
+if __name__ == "__main__":
+    main()