quantwise 1.2.0 → 1.2.2

package/.claude/skills/canslim-screener/scripts/calculators/leadership_calculator.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""
+L Component - Leadership / Relative Strength Calculator
+
+Calculates CANSLIM 'L' component score based on relative price performance vs market.
+
+O'Neil's Rule: "The top-performing stocks, prior to major advances, have Relative Strength
+Ratings averaging 87 at pivot points. You want to see 80+ RS Rank - meaning the stock is
+outperforming 80% of all other stocks over the past 52 weeks."
+
+Key Principles:
+- RS Rank 90+: Market leader, top 10% performer
+- RS Rank 80-89: Strong performer, top 20%
+- RS Rank 70-79: Above average, top 30%
+- RS Rank 60-69: Average performer
+- RS Rank <60: Laggard, underperforming majority
+
+Implementation Note:
+Since IBD's official RS Rank is proprietary, we estimate RS using:
+1. 52-week price performance vs S&P 500
+2. Sector-relative performance (optional enhancement)
+
+Scoring:
+- 100 points: Relative outperformance > +30% vs S&P 500 (market leader)
+- 90 points: Relative outperformance +20% to +30%
+- 80 points: Relative outperformance +10% to +20% (strong)
+- 60 points: Relative outperformance 0% to +10% (above average)
+- 40 points: Relative performance -10% to 0% (lagging)
+- 20 points: Relative performance -20% to -10% (weak)
+- 0 points: Relative underperformance > -20% (avoid)
+"""
+
+from typing import Dict, List, Optional
+
+
+def calculate_leadership(
+    historical_prices: List[Dict],
+    sp500_historical: Optional[List[Dict]] = None,
+    sp500_performance: Optional[float] = None
+) -> Dict:
+    """
+    Calculate Leadership/Relative Strength score (L component)
+
+    Args:
+        historical_prices: List of daily price data for the stock (oldest to newest)
+                          Each entry: {"date": str, "close": float, "volume": int}
+        sp500_historical: Optional list of S&P 500 daily prices (for RS calculation)
+        sp500_performance: Optional pre-calculated S&P 500 52-week performance (%)
+
+    Returns:
+        Dict with:
+            - score: 0-100 points
+            - stock_52w_performance: Stock's 52-week return (%)
+            - sp500_52w_performance: S&P 500's 52-week return (%)
+            - relative_performance: Stock return - S&P 500 return (%)
+            - rs_rank_estimate: Estimated RS Rank (0-99)
+            - interpretation: Human-readable interpretation
+            - quality_warning: Warning if data quality issues
+            - error: Error message if calculation failed
+
+    Example:
+        >>> prices = client.get_historical_prices("NVDA", days=365)
+        >>> sp500 = client.get_historical_prices("SPY", days=365)
+        >>> result = calculate_leadership(prices, sp500)
+        >>> print(f"L Score: {result['score']}, RS Estimate: {result['rs_rank_estimate']}")
+    """
+    # Validate input
+    if not historical_prices or len(historical_prices) < 50:
+        return {
+            "score": 0,
+            "error": "Insufficient historical price data (need 50+ days)",
+            "stock_52w_performance": None,
+            "sp500_52w_performance": None,
+            "relative_performance": None,
+            "rs_rank_estimate": None,
+            "interpretation": "Data unavailable"
+        }
+
+    # Calculate stock's 52-week (or available period) performance
+    # Prices should be sorted oldest to newest
+    try:
+        # Get start and end prices (handle both orderings)
+        if historical_prices[0].get("date", "") < historical_prices[-1].get("date", ""):
+            # Oldest first (ascending)
+            start_price = historical_prices[0].get("close", 0)
+            end_price = historical_prices[-1].get("close", 0)
+        else:
+            # Newest first (descending)
+            start_price = historical_prices[-1].get("close", 0)
+            end_price = historical_prices[0].get("close", 0)
+
+        if start_price <= 0:
+            return {
+                "score": 0,
+                "error": "Invalid start price (zero or negative)",
+                "stock_52w_performance": None,
+                "sp500_52w_performance": None,
+                "relative_performance": None,
+                "rs_rank_estimate": None,
+                "interpretation": "Data quality issue"
+            }
+
+        stock_performance = ((end_price - start_price) / start_price) * 100
+        days_analyzed = len(historical_prices)
+
+    except (KeyError, TypeError, ZeroDivisionError) as e:
+        return {
+            "score": 0,
+            "error": f"Price calculation error: {str(e)}",
+            "stock_52w_performance": None,
+            "sp500_52w_performance": None,
+            "relative_performance": None,
+            "rs_rank_estimate": None,
+            "interpretation": "Calculation error"
+        }
+
+    # Calculate S&P 500 performance for comparison
+    sp500_perf = None
+    quality_warning = None
+
+    if sp500_performance is not None:
+        # Use pre-calculated S&P 500 performance
+        sp500_perf = sp500_performance
+    elif sp500_historical and len(sp500_historical) >= 50:
+        # Calculate from provided S&P 500 data
+        try:
+            if sp500_historical[0].get("date", "") < sp500_historical[-1].get("date", ""):
+                sp500_start = sp500_historical[0].get("close", 0)
+                sp500_end = sp500_historical[-1].get("close", 0)
+            else:
+                sp500_start = sp500_historical[-1].get("close", 0)
+                sp500_end = sp500_historical[0].get("close", 0)
+
+            if sp500_start > 0:
+                sp500_perf = ((sp500_end - sp500_start) / sp500_start) * 100
+        except (KeyError, TypeError, ZeroDivisionError):
+            quality_warning = "S&P 500 performance calculation failed"
+    else:
+        quality_warning = "S&P 500 data unavailable - using absolute performance only"
+
+    # Calculate relative performance
+    if sp500_perf is not None:
+        relative_performance = stock_performance - sp500_perf
+    else:
+        # Fallback: use absolute performance with penalty
+        relative_performance = stock_performance
+        if quality_warning is None:
+            quality_warning = "Using absolute performance (S&P 500 comparison unavailable)"
+
+    # Score based on relative performance
+    score, rs_rank_estimate = score_leadership(relative_performance, sp500_perf is not None)
+
+    # Generate interpretation
+    interpretation = interpret_leadership(
+        score, stock_performance, sp500_perf, relative_performance, days_analyzed
+    )
+
+    return {
+        "score": score,
+        "stock_52w_performance": round(stock_performance, 2),
+        "sp500_52w_performance": round(sp500_perf, 2) if sp500_perf is not None else None,
+        "relative_performance": round(relative_performance, 2),
+        "rs_rank_estimate": rs_rank_estimate,
+        "days_analyzed": days_analyzed,
+        "interpretation": interpretation,
+        "quality_warning": quality_warning,
+        "error": None
+    }
+
+
+def score_leadership(relative_performance: float, has_benchmark: bool) -> tuple:
+    """
+    Score leadership based on relative performance
+
+    Args:
+        relative_performance: Stock performance minus S&P 500 performance (%)
+        has_benchmark: True if S&P 500 comparison was available
+
+    Returns:
+        tuple: (score, rs_rank_estimate)
+    """
+    # Scoring thresholds for relative performance
+    if relative_performance >= 50:
+        score = 100
+        rs_rank_estimate = 99  # Top 1%
+    elif relative_performance >= 30:
+        score = 95
+        rs_rank_estimate = 95  # Top 5%
+    elif relative_performance >= 20:
+        score = 90
+        rs_rank_estimate = 90  # Top 10%
+    elif relative_performance >= 10:
+        score = 80
+        rs_rank_estimate = 80  # Top 20%
+    elif relative_performance >= 5:
+        score = 70
+        rs_rank_estimate = 70  # Top 30%
+    elif relative_performance >= 0:
+        score = 60
+        rs_rank_estimate = 60  # Top 40%
+    elif relative_performance >= -5:
+        score = 50
+        rs_rank_estimate = 50  # Average
+    elif relative_performance >= -10:
+        score = 40
+        rs_rank_estimate = 40  # Below average
+    elif relative_performance >= -20:
+        score = 20
+        rs_rank_estimate = 25  # Weak
+    else:
+        score = 0
+        rs_rank_estimate = 10  # Laggard
+
+    # Apply penalty if no benchmark comparison available
+    if not has_benchmark:
+        score = int(score * 0.8)  # 20% penalty for absolute-only comparison
+        rs_rank_estimate = int(rs_rank_estimate * 0.9)
+
+    return score, rs_rank_estimate
+
+
+def interpret_leadership(
+    score: int,
+    stock_performance: float,
+    sp500_performance: Optional[float],
+    relative_performance: float,
+    days_analyzed: int
+) -> str:
+    """
+    Generate human-readable interpretation
+
+    Args:
+        score: Leadership score (0-100)
+        stock_performance: Stock's period return (%)
+        sp500_performance: S&P 500's period return (%)
+        relative_performance: Stock - S&P 500 (%)
+        days_analyzed: Number of days analyzed
+
+    Returns:
+        str: Interpretation string
+    """
+    # Period description
+    if days_analyzed >= 250:
+        period = "52-week"
+    elif days_analyzed >= 180:
+        period = "9-month"
+    elif days_analyzed >= 90:
+        period = "quarterly"
+    else:
+        period = f"{days_analyzed}-day"
+
+    # Performance description
+    if stock_performance > 0:
+        stock_msg = f"+{stock_performance:.1f}%"
+    else:
+        stock_msg = f"{stock_performance:.1f}%"
+
+    # Relative performance description
+    if sp500_performance is not None:
+        if relative_performance > 0:
+            rel_msg = f"+{relative_performance:.1f}% vs S&P 500"
+        else:
+            rel_msg = f"{relative_performance:.1f}% vs S&P 500"
+    else:
+        rel_msg = "(absolute performance)"
+
+    # Rating based on score
+    if score >= 90:
+        rating = "Market Leader"
+        action = "Strong momentum, prime CANSLIM candidate"
+    elif score >= 80:
+        rating = "Strong Performer"
+        action = "Outperforming market significantly"
+    elif score >= 60:
+        rating = "Above Average"
+        action = "Slight outperformance"
+    elif score >= 40:
+        rating = "Average"
+        action = "Matching or slightly lagging market"
+    elif score >= 20:
+        rating = "Laggard"
+        action = "Underperforming market - caution"
+    else:
+        rating = "Weak"
+        action = "Significant underperformance - avoid"
+
+    return f"{rating} - {period} return {stock_msg} ({rel_msg}). {action}"
+
+
+def calculate_sector_relative_strength(
+    stock_performance: float,
+    sector_stocks_performance: List[float]
+) -> Dict:
+    """
+    Calculate relative strength within sector (optional enhancement)
+
+    Args:
+        stock_performance: Target stock's period return (%)
+        sector_stocks_performance: List of sector peers' period returns (%)
+
+    Returns:
+        Dict with:
+            - sector_rank: Stock's rank within sector (1 = best)
+            - sector_percentile: Percentile within sector (0-100)
+            - is_sector_leader: True if top 20% in sector
+    """
+    if not sector_stocks_performance:
+        return {
+            "sector_rank": None,
+            "sector_percentile": None,
+            "is_sector_leader": False,
+            "error": "No sector data available"
+        }
+
+    # Add stock to list and sort (descending)
+    all_stocks = sector_stocks_performance + [stock_performance]
+    all_stocks_sorted = sorted(all_stocks, reverse=True)
+
+    # Find rank
+    rank = all_stocks_sorted.index(stock_performance) + 1
+    total = len(all_stocks)
+    percentile = ((total - rank) / total) * 100
+
+    return {
+        "sector_rank": rank,
+        "sector_total": total,
+        "sector_percentile": round(percentile, 1),
+        "is_sector_leader": percentile >= 80
+    }
+
+
+# Example usage
+if __name__ == "__main__":
+    print("Testing Leadership Calculator (L Component)...")
+    print()
+
+    # Test 1: Strong outperformer
+    sample_prices = [
+        {"date": "2024-01-01", "close": 100.0},
+        {"date": "2024-06-01", "close": 120.0},
+        {"date": "2025-01-01", "close": 180.0}  # +80% YoY
+    ]
+    sample_sp500 = [
+        {"date": "2024-01-01", "close": 4500.0},
+        {"date": "2024-06-01", "close": 4700.0},
+        {"date": "2025-01-01", "close": 5400.0}  # +20% YoY
+    ]
+
+    result = calculate_leadership(sample_prices, sample_sp500)
+    print("Test 1: Strong Outperformer (+80% stock vs +20% S&P)")
+    print(f"  Stock Performance: {result['stock_52w_performance']}%")
+    print(f"  S&P 500 Performance: {result['sp500_52w_performance']}%")
+    print(f"  Relative Performance: {result['relative_performance']}%")
+    print(f"  L Score: {result['score']}/100")
+    print(f"  RS Rank Estimate: {result['rs_rank_estimate']}")
+    print(f"  Interpretation: {result['interpretation']}")
+    print()
+
+    # Test 2: Underperformer
+    sample_prices_weak = [
+        {"date": "2024-01-01", "close": 100.0},
+        {"date": "2025-01-01", "close": 90.0}  # -10% YoY
+    ]
+
+    result2 = calculate_leadership(sample_prices_weak, sample_sp500)
+    print("Test 2: Underperformer (-10% stock vs +20% S&P)")
+    print(f"  Stock Performance: {result2['stock_52w_performance']}%")
+    print(f"  Relative Performance: {result2['relative_performance']}%")
+    print(f"  L Score: {result2['score']}/100")
+    print(f"  Interpretation: {result2['interpretation']}")
+    print()
+
+    # Test 3: Without S&P 500 data (fallback)
+    result3 = calculate_leadership(sample_prices)
+    print("Test 3: Without S&P 500 Data (Fallback)")
+    print(f"  L Score: {result3['score']}/100 (20% penalty applied)")
+    print(f"  Warning: {result3['quality_warning']}")
+    print()
+
+    print("✓ All tests completed")

package/.claude/skills/canslim-screener/scripts/calculators/market_calculator.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+M Component - Market Direction Calculator
+
+Calculates CANSLIM 'M' component score based on overall market trend.
+
+O'Neil's Rule: "You can be right about a stock but wrong about the market,
+and still lose money. Three out of four stocks follow the market's trend."
+
+Scoring:
+- 100: Strong uptrend (S&P 500 >2% above 50-EMA) + VIX <15
+- 80: Uptrend (S&P 500 above 50-EMA) + VIX <20
+- 60: Early uptrend (S&P 500 just above 50-EMA)
+- 40: Choppy/neutral (S&P 500 near 50-EMA ±2%)
+- 20: Downtrend forming (S&P 500 below 50-EMA)
+- 0: Bear market (S&P 500 well below 50-EMA OR VIX >30) - DO NOT BUY
+"""
+
+from typing import Dict, List, Optional
+
+
+def calculate_market_direction(sp500_quote: Dict,
+                               sp500_prices: Optional[List[Dict]] = None,
+                               vix_quote: Optional[Dict] = None) -> Dict:
+    """
+    Calculate M component score based on S&P 500 trend and VIX
+
+    Args:
+        sp500_quote: S&P 500 quote data (symbol ^GSPC)
+        sp500_prices: Optional historical prices for EMA calculation
+        vix_quote: Optional VIX quote (symbol ^VIX)
+
+    Returns:
+        Dict with:
+            - score: 0-100 points
+            - trend: "strong_uptrend", "uptrend", "choppy", "downtrend", "bear_market"
+            - sp500_price: Current S&P 500 level
+            - sp500_ema_50: 50-day EMA (if calculated)
+            - distance_from_ema_pct: Distance from 50-EMA (%)
+            - vix_level: Current VIX level
+            - interpretation: Human-readable interpretation
+            - warning: Warning message if bear market (M=0)
+    """
+    # Validate input
+    if not sp500_quote:
+        return {
+            "score": 50,  # Default to neutral if data unavailable
+            "error": "S&P 500 quote data missing",
+            "trend": "unknown",
+            "interpretation": "Market data unavailable"
+        }
+
+    sp500_price = sp500_quote.get("price")
+    if not sp500_price:
+        return {
+            "score": 50,
+            "error": "S&P 500 price missing",
+            "trend": "unknown",
+            "interpretation": "Market data unavailable"
+        }
+
+    # Calculate or estimate 50-day EMA
+    sp500_ema_50 = None
+    if sp500_prices and len(sp500_prices) >= 50:
+        # Calculate from historical data
+        close_prices = [day.get("close") for day in sp500_prices if day.get("close")]
+        if len(close_prices) >= 50:
+            sp500_ema_50 = calculate_ema(close_prices, period=50)
+    else:
+        # Estimate: Assume EMA is ~2% below current price in uptrend, ~2% above in downtrend
+        # This is a simplified fallback when historical data unavailable
+        sp500_ema_50 = sp500_price * 0.98  # Conservative estimate
+
+    # Calculate distance from EMA
+    distance_from_ema_pct = ((sp500_price / sp500_ema_50) - 1) * 100 if sp500_ema_50 else 0
+
+    # Get VIX level
+    vix_level = None
+    if vix_quote:
+        vix_level = vix_quote.get("price")
+
+    # Determine trend
+    if distance_from_ema_pct >= 2.0:
+        trend = "strong_uptrend"
+    elif distance_from_ema_pct >= 0:
+        trend = "uptrend"
+    elif distance_from_ema_pct >= -2.0:
+        trend = "choppy"
+    elif distance_from_ema_pct >= -5.0:
+        trend = "downtrend"
+    else:
+        trend = "bear_market"
+
+    # Calculate score
+    score = score_market_direction(trend, vix_level)
+
+    # Generate interpretation
+    interpretation = interpret_market_score(score, trend, distance_from_ema_pct, vix_level)
+
+    # Warning for bear market
+    warning = None
+    if score == 0:
+        warning = ("⚠️ BEAR MARKET - Do not buy stocks regardless of C, A, N scores. "
+                  "Raise 80-100% cash and wait for market recovery.")
+
+    return {
+        "score": score,
+        "trend": trend,
+        "sp500_price": sp500_price,
+        "sp500_ema_50": sp500_ema_50,
+        "distance_from_ema_pct": round(distance_from_ema_pct, 2),
+        "vix_level": vix_level,
+        "interpretation": interpretation,
+        "warning": warning,
+        "error": None
+    }
+
+
+def calculate_ema(prices: List[float], period: int = 50) -> float:
+    """
+    Calculate Exponential Moving Average
+
+    Args:
+        prices: List of prices (most recent first)
+        period: EMA period (default 50)
+
+    Returns:
+        EMA value
+
+    Formula: EMA = Price * k + EMA_prev * (1-k), where k = 2/(period+1)
+    """
+    if len(prices) < period:
+        return sum(prices) / len(prices)  # Fallback to simple average
+
+    # Reverse to oldest-first for calculation
+    prices_reversed = prices[::-1]
+
+    # Initialize with SMA
+    sma = sum(prices_reversed[:period]) / period
+    ema = sma
+
+    # Calculate EMA
+    k = 2 / (period + 1)
+    for price in prices_reversed[period:]:
+        ema = price * k + ema * (1 - k)
+
+    return ema
+
+
+def score_market_direction(trend: str, vix_level: Optional[float]) -> int:
+    """
+    Score M component based on trend and VIX
+
+    Args:
+        trend: Market trend classification
+        vix_level: Current VIX level
+
+    Returns:
+        Score (0-100)
+    """
+    # Base score from trend
+    if trend == "strong_uptrend":
+        base_score = 90
+    elif trend == "uptrend":
+        base_score = 70
+    elif trend == "choppy":
+        base_score = 40
+    elif trend == "downtrend":
+        base_score = 20
+    else:  # bear_market
+        base_score = 0
+
+    # VIX adjustments
+    if vix_level:
+        if vix_level < 15:
+            base_score += 10  # Low fear, bullish
+        elif vix_level > 30:
+            base_score = 0    # Panic mode - override trend
+
+    return min(max(base_score, 0), 100)
+
+
+def interpret_market_score(score: int,
+                           trend: str,
+                           distance: float,
+                           vix: Optional[float]) -> str:
+    """
+    Generate human-readable market interpretation
+
+    Args:
+        score: M component score
+        trend: Trend classification
+        distance: Distance from 50-EMA (%)
+        vix: VIX level
+
+    Returns:
+        Interpretation string
+    """
+    vix_text = f", VIX {vix:.1f}" if vix else ""
+
+    if score >= 90:
+        return f"Strong bull market - Aggressive buying recommended (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+    elif score >= 70:
+        return f"Bull market - Standard position sizing (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+    elif score >= 50:
+        return f"Early uptrend - Small initial positions (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+    elif score >= 30:
+        return f"Choppy/neutral - Reduce exposure, be selective (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+    elif score >= 10:
+        return f"Downtrend forming - Defensive posture (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+    else:
+        return f"Bear market - Raise 80-100% cash, DO NOT BUY (S&P 500 {distance:+.1f}% from 50-EMA{vix_text})"
+
+
+# Example usage
+if __name__ == "__main__":
+    print("Testing Market Calculator (M Component)...\n")
+
+    # Test 1: Strong uptrend (score 100)
+    test_sp500_1 = {"symbol": "^GSPC", "price": 4900}
+    test_vix_1 = {"symbol": "^VIX", "price": 12.5}
+    result1 = calculate_market_direction(test_sp500_1, vix_quote=test_vix_1)
+    print(f"Test 1: Strong Uptrend - Score: {result1['score']}")
+    print(f"  {result1['interpretation']}\n")
+
+    # Test 2: Choppy market (score 40)
+    test_sp500_2 = {"symbol": "^GSPC", "price": 4700}
+    # EMA estimated at 4750 (price 1% below)
+    test_vix_2 = {"symbol": "^VIX", "price": 18.0}
+    result2 = calculate_market_direction(test_sp500_2, vix_quote=test_vix_2)
+    print(f"Test 2: Choppy Market - Score: {result2['score']}")
+    print(f"  {result2['interpretation']}\n")
+
+    # Test 3: Bear market (score 0)
+    test_sp500_3 = {"symbol": "^GSPC", "price": 4200}
+    # EMA estimated at 4600 (price 8.7% below)
+    test_vix_3 = {"symbol": "^VIX", "price": 32.0}
+    result3 = calculate_market_direction(test_sp500_3, vix_quote=test_vix_3)
+    print(f"Test 3: Bear Market - Score: {result3['score']}")
+    print(f"  {result3['interpretation']}")
+    if result3['warning']:
+        print(f"  {result3['warning']}\n")
+
+    print("✓ All tests completed")