quantwise 1.2.0 → 1.2.2

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+N Component - Newness / New Highs Calculator
+
+Calculates CANSLIM 'N' component score based on price position relative to
+52-week high and momentum indicators.
+
+O'Neil's Rule: "Stocks making new price highs have no overhead supply.
+New products, services, or management catalyze major moves."
+
+Scoring:
+- 100: Within 5% of 52-week high + breakout + new product catalyst
+- 80: Within 10% of 52-week high + breakout
+- 60: Within 15% of 52-week high OR breakout
+- 40: Within 25% of 52-week high
+- 20: >25% from 52-week high (lacks momentum)
+"""
+
+from typing import Dict, List, Optional
+
+
+def calculate_newness(quote: Dict, historical_prices: Optional[Dict] = None) -> Dict:
+    """
+    Calculate N component score based on price position and momentum
+
+    Args:
+        quote: Stock quote data from FMP API (contains yearHigh, price, volume)
+        historical_prices: Optional historical price data for detailed analysis
+
+    Returns:
+        Dict with:
+            - score: 0-100 points
+            - distance_from_high_pct: Distance from 52-week high (%)
+            - current_price: Current stock price
+            - week_52_high: 52-week high price
+            - week_52_low: 52-week low price
+            - breakout_detected: Boolean
+            - interpretation: Human-readable interpretation
+    """
+    # Validate input
+    if not quote:
+        return {
+            "score": 0,
+            "error": "Quote data missing",
+            "distance_from_high_pct": None,
+            "interpretation": "Data unavailable"
+        }
+
+    # Extract price data
+    current_price = quote.get("price")
+    week_52_high = quote.get("yearHigh")
+    week_52_low = quote.get("yearLow")
+    current_volume = quote.get("volume")
+    avg_volume = quote.get("avgVolume")
+
+    if not current_price or not week_52_high:
+        return {
+            "score": 0,
+            "error": "Price or 52-week high data missing",
+            "distance_from_high_pct": None,
+            "interpretation": "Data unavailable"
+        }
+
+    # Calculate distance from 52-week high
+    distance_from_high_pct = ((current_price / week_52_high) - 1) * 100
+
+    # Detect breakout (new high on elevated volume)
+    breakout_detected = False
+    if current_volume and avg_volume:
+        # Within 0.5% of high AND volume 40%+ above average
+        if current_price >= week_52_high * 0.995 and current_volume > avg_volume * 1.4:
+            breakout_detected = True
+
+    # Calculate score
+    score = score_newness(distance_from_high_pct, breakout_detected)
+
+    # Generate interpretation
+    interpretation = interpret_newness_score(score, distance_from_high_pct, breakout_detected)
+
+    return {
+        "score": score,
+        "distance_from_high_pct": round(distance_from_high_pct, 1),
+        "current_price": current_price,
+        "week_52_high": week_52_high,
+        "week_52_low": week_52_low,
+        "breakout_detected": breakout_detected,
+        "current_volume": current_volume,
+        "avg_volume": avg_volume,
+        "volume_ratio": round(current_volume / avg_volume, 2) if avg_volume else None,
+        "interpretation": interpretation,
+        "error": None
+    }
+
+
+def score_newness(distance_from_high_pct: float, breakout_detected: bool) -> int:
+    """
+    Score N component based on price position and breakout
+
+    Args:
+        distance_from_high_pct: Distance from 52-week high (negative = below high)
+        breakout_detected: Boolean indicating volume-confirmed breakout
+
+    Returns:
+        Score (0-100)
+
+    Scoring Logic:
+    - Within 5% of high + breakout: 100
+    - Within 10% of high + breakout: 80
+    - Within 15% of high OR breakout: 60
+    - Within 25% of high: 40
+    - >25% from high: 20
+    """
+    if distance_from_high_pct >= -5 and breakout_detected:
+        return 100  # Perfect setup - at new highs with volume
+    elif distance_from_high_pct >= -10 and breakout_detected:
+        return 80   # Strong momentum
+    elif distance_from_high_pct >= -15 or breakout_detected:
+        return 60   # Acceptable
+    elif distance_from_high_pct >= -25:
+        return 40   # Weak momentum
+    else:
+        return 20   # Too far from highs, lacks sponsorship
+
+
+def interpret_newness_score(score: int, distance: float, breakout: bool) -> str:
+    """
+    Generate human-readable interpretation
+
+    Args:
+        score: Component score
+        distance: Distance from 52-week high (%)
+        breakout: Breakout detected flag
+
+    Returns:
+        Interpretation string
+    """
+    breakout_text = " with volume breakout" if breakout else ""
+
+    if score >= 90:
+        return f"Exceptional - At new highs{breakout_text} ({distance:+.1f}% from high)"
+    elif score >= 70:
+        return f"Strong - Near 52-week high{breakout_text} ({distance:+.1f}% from high)"
+    elif score >= 50:
+        return f"Acceptable - Within 15% of high ({distance:+.1f}% from high)"
+    elif score >= 30:
+        return f"Weak - Lacks momentum ({distance:+.1f}% from high)"
+    else:
+        return f"Poor - Too far from highs, overhead resistance ({distance:+.1f}% from high)"
+
+
+# Example usage
+if __name__ == "__main__":
+    print("Testing New Highs Calculator (N Component)...\n")
+
+    # Test 1: At new high with breakout (score 100)
+    test_quote_1 = {
+        "symbol": "NVDA",
+        "price": 495.50,
+        "yearHigh": 496.00,
+        "yearLow": 280.00,
+        "volume": 60000000,
+        "avgVolume": 40000000
+    }
+    result1 = calculate_newness(test_quote_1)
+    print(f"Test 1: New High + Breakout - Score: {result1['score']}")
+    print(f"  {result1['interpretation']}\n")
+
+    # Test 2: Within 10% of high, no breakout (score 60)
+    test_quote_2 = {
+        "symbol": "META",
+        "price": 450.00,
+        "yearHigh": 490.00,
+        "yearLow": 320.00,
+        "volume": 15000000,
+        "avgVolume": 16000000
+    }
+    result2 = calculate_newness(test_quote_2)
+    print(f"Test 2: Near High, No Breakout - Score: {result2['score']}")
+    print(f"  {result2['interpretation']}\n")
+
+    # Test 3: Far from high (score 20)
+    test_quote_3 = {
+        "symbol": "XYZ",
+        "price": 50.00,
+        "yearHigh": 80.00,
+        "yearLow": 45.00,
+        "volume": 1000000,
+        "avgVolume": 1200000
+    }
+    result3 = calculate_newness(test_quote_3)
+    print(f"Test 3: Far from High - Score: {result3['score']}")
+    print(f"  {result3['interpretation']}\n")
+
+    print("✓ All tests completed")

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

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+S Component - Supply and Demand Calculator
+
+Calculates CANSLIM 'S' component score based on volume accumulation/distribution patterns.
+
+O'Neil's Rule: "Volume is the gas in the tank of a stock. Without gas, the car doesn't
+go anywhere. Look for stocks where volume expands on up days and contracts on down days."
+
+Key Principle:
+- UP-DAY VOLUME > DOWN-DAY VOLUME = Accumulation (institutions buying)
+- DOWN-DAY VOLUME > UP-DAY VOLUME = Distribution (institutions selling)
+
+Scoring:
+- 100 points: Up/down ratio ≥ 2.0 (Strong Accumulation)
+- 80 points: Ratio 1.5-2.0 (Accumulation)
+- 60 points: Ratio 1.0-1.5 (Neutral/Weak Accumulation)
+- 40 points: Ratio 0.7-1.0 (Neutral/Weak Distribution)
+- 20 points: Ratio 0.5-0.7 (Distribution)
+- 0 points: Ratio < 0.5 (Strong Distribution)
+"""
+
+from typing import Dict, List
+
+
+def calculate_supply_demand(historical_prices: Dict) -> Dict:
+    """
+    Calculate supply/demand dynamics based on volume patterns
+
+    Args:
+        historical_prices: Historical price data from FMP API
+                          Dict with keys: 'historical' (list of daily price/volume data)
+                          Each entry should have: date, close, volume
+
+    Returns:
+        Dict with:
+            - score: 0-100 points
+            - up_down_ratio: Average up-day volume / average down-day volume
+            - accumulation_detected: True if ratio ≥ 1.5
+            - avg_up_volume: Average volume on up days
+            - avg_down_volume: Average volume on down days
+            - up_days_count: Number of up days in analysis period
+            - down_days_count: Number of down days
+            - 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=90)
+        >>> result = calculate_supply_demand(prices)
+        >>> print(f"S Score: {result['score']}, Ratio: {result['up_down_ratio']:.2f}")
+    """
+    # Validate input
+    if not historical_prices or "historical" not in historical_prices:
+        return {
+            "score": 0,
+            "error": "No historical price data provided",
+            "up_down_ratio": None,
+            "accumulation_detected": False,
+            "avg_up_volume": None,
+            "avg_down_volume": None,
+            "up_days_count": 0,
+            "down_days_count": 0,
+            "interpretation": "Data unavailable"
+        }
+
+    prices = historical_prices["historical"]
+
+    if not prices or len(prices) < 60:
+        return {
+            "score": 0,
+            "error": f"Insufficient data (need 60+ days, got {len(prices)})",
+            "up_down_ratio": None,
+            "accumulation_detected": False,
+            "avg_up_volume": None,
+            "avg_down_volume": None,
+            "up_days_count": 0,
+            "down_days_count": 0,
+            "interpretation": "Data unavailable",
+            "quality_warning": "Less than 60 days of historical data available"
+        }
+
+    # Analyze last 60 days (prices are typically newest first, so take first 60)
+    analysis_period = prices[:60]
+
+    # Classify days as up or down
+    up_days = []
+    down_days = []
+    previous_close = None
+
+    for day in reversed(analysis_period):  # Process chronologically
+        current_close = day.get("close")
+        current_volume = day.get("volume")
+
+        if current_close is None or current_volume is None:
+            continue  # Skip incomplete data
+
+        if previous_close is not None:
+            if current_close > previous_close:
+                up_days.append(current_volume)
+            elif current_close < previous_close:
+                down_days.append(current_volume)
+            # Unchanged days are ignored
+
+        previous_close = current_close
+
+    # Validate we have enough classified days
+    if len(up_days) < 10 or len(down_days) < 10:
+        return {
+            "score": 0,
+            "error": "Insufficient up/down days for analysis",
+            "up_down_ratio": None,
+            "accumulation_detected": False,
+            "avg_up_volume": None,
+            "avg_down_volume": None,
+            "up_days_count": len(up_days),
+            "down_days_count": len(down_days),
+            "interpretation": "Data quality issues",
+            "quality_warning": f"Too few classified days (up: {len(up_days)}, down: {len(down_days)})"
+        }
+
+    # Calculate average volumes
+    avg_up_volume = sum(up_days) / len(up_days)
+    avg_down_volume = sum(down_days) / len(down_days)
+
+    # Calculate accumulation/distribution ratio
+    if avg_down_volume == 0:
+        # Edge case: no volume on down days (extremely bullish, but rare)
+        ratio = 5.0  # Cap at 5.0 to avoid infinity
+    else:
+        ratio = avg_up_volume / avg_down_volume
+
+    # Determine accumulation status
+    accumulation_detected = ratio >= 1.5
+
+    # Score based on ratio
+    score = score_supply_demand(ratio)
+
+    # Generate interpretation
+    interpretation = interpret_supply_demand(ratio, accumulation_detected)
+
+    return {
+        "score": score,
+        "up_down_ratio": ratio,
+        "accumulation_detected": accumulation_detected,
+        "avg_up_volume": int(avg_up_volume),
+        "avg_down_volume": int(avg_down_volume),
+        "up_days_count": len(up_days),
+        "down_days_count": len(down_days),
+        "interpretation": interpretation
+    }
+
+
+def score_supply_demand(ratio: float) -> int:
+    """
+    Score accumulation/distribution ratio
+
+    Args:
+        ratio: Up-day volume / down-day volume
+
+    Returns:
+        int: Score from 0-100
+    """
+    if ratio >= 2.0:
+        return 100  # Strong Accumulation
+    elif ratio >= 1.5:
+        return 80   # Accumulation
+    elif ratio >= 1.0:
+        return 60   # Neutral/Weak Accumulation
+    elif ratio >= 0.7:
+        return 40   # Neutral/Weak Distribution
+    elif ratio >= 0.5:
+        return 20   # Distribution
+    else:
+        return 0    # Strong Distribution
+
+
+def interpret_supply_demand(ratio: float, accumulation: bool) -> str:
+    """
+    Generate human-readable interpretation of supply/demand dynamics
+
+    Args:
+        ratio: Up-day volume / down-day volume
+        accumulation: True if accumulation detected
+
+    Returns:
+        str: Interpretation string
+    """
+    if ratio >= 2.0:
+        return f"Strong Accumulation (ratio: {ratio:.2f}x) - Institutions aggressively buying. Volume precedes price."
+    elif ratio >= 1.5:
+        return f"Accumulation (ratio: {ratio:.2f}x) - Bullish volume pattern. Institutional interest building."
+    elif ratio >= 1.0:
+        return f"Neutral/Weak Accumulation (ratio: {ratio:.2f}x) - Slightly positive volume trend."
+    elif ratio >= 0.7:
+        return f"Neutral/Weak Distribution (ratio: {ratio:.2f}x) - Slightly negative volume trend. Monitor closely."
+    elif ratio >= 0.5:
+        return f"Distribution (ratio: {ratio:.2f}x) - Bearish volume pattern. Institutions may be selling."
+    else:
+        return f"Strong Distribution (ratio: {ratio:.2f}x) - Heavy selling pressure. Volume leads price lower."
+
+
+# Example usage
+if __name__ == "__main__":
+    # Test with sample data
+    sample_data = {
+        "historical": [
+            {"date": "2024-12-10", "close": 150.0, "volume": 80000000},  # up day
+            {"date": "2024-12-09", "close": 148.0, "volume": 50000000},  # down day
+            {"date": "2024-12-06", "close": 149.0, "volume": 75000000},  # up day
+            {"date": "2024-12-05", "close": 147.0, "volume": 45000000},  # down day
+        ] * 15  # Repeat to get 60 days
+    }
+
+    result = calculate_supply_demand(sample_data)
+
+    print("S Component Test Results:")
+    print(f"  Score: {result['score']}/100")
+    print(f"  Up/Down Ratio: {result['up_down_ratio']:.2f}")
+    print(f"  Accumulation: {result['accumulation_detected']}")
+    print(f"  Interpretation: {result['interpretation']}")

package/.claude/skills/canslim-screener/scripts/finviz_stock_client.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+Finviz Stock Data Client
+
+Fetches individual stock data from Finviz including institutional ownership.
+Uses simple web scraping with BeautifulSoup (no API key required).
+
+Install: pip install beautifulsoup4 requests lxml
+
+Usage:
+    from finviz_stock_client import FinvizStockClient
+
+    client = FinvizStockClient()
+    data = client.get_institutional_ownership("AAPL")
+    print(f"Inst Own: {data['inst_own_pct']}%")
+"""
+
+import sys
+import time
+import re
+from typing import Dict, Optional
+
+try:
+    import requests
+    from bs4 import BeautifulSoup
+except ImportError:
+    print("ERROR: required libraries not found. Install with: pip install beautifulsoup4 requests lxml", file=sys.stderr)
+    sys.exit(1)
+
+
+class FinvizStockClient:
+    """Client for fetching stock data from Finviz"""
+
+    BASE_URL = "https://finviz.com/quote.ashx"
+
+    def __init__(self, rate_limit_seconds: float = 2.0):
+        """
+        Initialize Finviz client
+
+        Args:
+            rate_limit_seconds: Delay between requests to avoid rate limiting (default: 2.0s)
+        """
+        self.rate_limit_seconds = rate_limit_seconds
+        self.last_request_time = 0.0
+        self.cache = {}
+        self.session = requests.Session()
+        # Use a realistic user agent to avoid blocking
+        self.session.headers.update({
+            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'
+        })
+
+    def _rate_limited_fetch(self, symbol: str) -> Optional[Dict]:
+        """
+        Fetch stock data with rate limiting
+
+        Args:
+            symbol: Stock ticker symbol
+
+        Returns:
+            Dict with stock data, or None if fetch failed
+        """
+        # Respect rate limit
+        elapsed = time.time() - self.last_request_time
+        if elapsed < self.rate_limit_seconds:
+            time.sleep(self.rate_limit_seconds - elapsed)
+
+        try:
+            url = f"{self.BASE_URL}?t={symbol}"
+            response = self.session.get(url, timeout=15)
+            self.last_request_time = time.time()
+
+            if response.status_code == 200:
+                return self._parse_finviz_page(response.text)
+            else:
+                print(f"WARNING: Finviz request failed with status {response.status_code} for {symbol}", file=sys.stderr)
+                return None
+
+        except Exception as e:
+            print(f"WARNING: Failed to fetch Finviz data for {symbol}: {e}", file=sys.stderr)
+            self.last_request_time = time.time()
+            return None
+
+    def _parse_finviz_page(self, html: str) -> Dict:
+        """
+        Parse Finviz stock page HTML
+
+        Args:
+            html: HTML content
+
+        Returns:
+            Dict with extracted data fields
+        """
+        soup = BeautifulSoup(html, 'lxml')
+
+        # Finviz uses a table structure with label-value pairs
+        data = {}
+
+        # Find all table rows containing data
+        tables = soup.find_all('table', {'class': 'snapshot-table2'})
+
+        for table in tables:
+            rows = table.find_all('tr')
+            for row in rows:
+                cells = row.find_all('td')
+                # Each row has pairs of (label, value, label, value, ...)
+                for i in range(0, len(cells), 2):
+                    if i + 1 < len(cells):
+                        label = cells[i].get_text(strip=True)
+                        value = cells[i + 1].get_text(strip=True)
+                        data[label] = value
+
+        return data
+
+    def get_institutional_ownership(self, symbol: str) -> Dict:
+        """
+        Get institutional ownership data from Finviz
+
+        Args:
+            symbol: Stock ticker symbol
+
+        Returns:
+            Dict with:
+                - inst_own_pct: Institutional ownership percentage (float, or None)
+                - inst_trans_pct: Institutional transactions percentage (float, or None)
+                - error: Error message if data unavailable
+
+        Example:
+            >>> client = FinvizStockClient()
+            >>> data = client.get_institutional_ownership("AAPL")
+            >>> print(f"Inst Own: {data['inst_own_pct']}%")
+            Inst Own: 60.5%
+        """
+        # Check cache first
+        cache_key = f"finviz_inst_{symbol}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        # Fetch from Finviz
+        stock_data = self._rate_limited_fetch(symbol)
+
+        if not stock_data:
+            result = {
+                "inst_own_pct": None,
+                "inst_trans_pct": None,
+                "error": f"Failed to fetch data from Finviz for {symbol}"
+            }
+            self.cache[cache_key] = result
+            return result
+
+        # Extract institutional data
+        # Finviz returns strings like "60.50%" or "-" if unavailable
+        inst_own_str = stock_data.get("Inst Own", "-")
+        inst_trans_str = stock_data.get("Inst Trans", "-")
+
+        # Parse percentage strings
+        inst_own_pct = self._parse_percentage(inst_own_str)
+        inst_trans_pct = self._parse_percentage(inst_trans_str)
+
+        result = {
+            "inst_own_pct": inst_own_pct,
+            "inst_trans_pct": inst_trans_pct,
+            "error": None
+        }
+
+        # Cache result
+        self.cache[cache_key] = result
+        return result
+
+    @staticmethod
+    def _parse_percentage(pct_str: str) -> Optional[float]:
+        """
+        Parse percentage string from Finviz
+
+        Args:
+            pct_str: Percentage string like "60.50%" or "-"
+
+        Returns:
+            Float percentage value (60.50), or None if unavailable
+        """
+        if not pct_str or pct_str == "-":
+            return None
+
+        try:
+            # Remove '%' and convert to float
+            return float(pct_str.rstrip('%'))
+        except (ValueError, AttributeError):
+            return None
+
+    def get_stock_data(self, symbol: str) -> Optional[Dict]:
+        """
+        Get full stock data dict from Finviz
+
+        Args:
+            symbol: Stock ticker symbol
+
+        Returns:
+            Dict with all Finviz data fields, or None if unavailable
+        """
+        cache_key = f"finviz_full_{symbol}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        stock_data = self._rate_limited_fetch(symbol)
+        if stock_data:
+            self.cache[cache_key] = stock_data
+
+        return stock_data
+
+
+# Example usage
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Test Finviz institutional ownership fetcher")
+    parser.add_argument("symbol", help="Stock ticker symbol")
+    args = parser.parse_args()
+
+    client = FinvizStockClient()
+    data = client.get_institutional_ownership(args.symbol)
+
+    print("\nFinviz Institutional Ownership Data:")
+    print(f"  Symbol: {args.symbol}")
+    print(f"  Inst Own: {data['inst_own_pct']}%" if data['inst_own_pct'] is not None else "  Inst Own: N/A")
+    print(f"  Inst Trans: {data['inst_trans_pct']}%" if data['inst_trans_pct'] is not None else "  Inst Trans: N/A")
+
+    if data.get('error'):
+        print(f"  Error: {data['error']}")