quantwise 1.2.0 → 1.2.2

package/.claude/skills/vcp-screener/scripts/calculators/vcp_pattern_calculator.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""
+VCP Pattern Calculator - Core Volatility Contraction Pattern Detection
+
+Implements Mark Minervini's VCP detection algorithm:
+1. Find swing highs and lows within a 120-day lookback window
+2. Identify successive contractions (T1, T2, T3, T4)
+3. Validate that each contraction is tighter than the previous
+4. Score based on number of contractions, tightness, and depth ratios
+
+VCP Characteristics:
+- T1 (first correction): 8-35% depth for S&P 500 large-caps
+- Each successive contraction should be 25%+ tighter than the previous
+- Minimum 2 contractions required for valid VCP
+- Successive highs should be within 5% of each other
+- Pattern duration: 15-325 trading days
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+
+def calculate_vcp_pattern(
+    historical_prices: List[Dict],
+    lookback_days: int = 120,
+) -> Dict:
+    """
+    Detect Volatility Contraction Pattern in price data.
+
+    Args:
+        historical_prices: Daily OHLCV data (most recent first), need 30+ days
+        lookback_days: Number of days to look back for pattern (default 120)
+
+    Returns:
+        Dict with score (0-100), contractions list, pattern validity, pivot point
+    """
+    if not historical_prices or len(historical_prices) < 30:
+        return {
+            "score": 0,
+            "valid_vcp": False,
+            "contractions": [],
+            "num_contractions": 0,
+            "pivot_price": None,
+            "error": "Insufficient data (need 30+ days)",
+        }
+
+    # Work in chronological order (oldest first)
+    prices = list(reversed(historical_prices[:lookback_days]))
+    n = len(prices)
+
+    if n < 30:
+        return {
+            "score": 0,
+            "valid_vcp": False,
+            "contractions": [],
+            "num_contractions": 0,
+            "pivot_price": None,
+            "error": "Insufficient data in lookback window",
+        }
+
+    # Step A: Find swing points
+    highs = [d.get("high", d.get("close", 0)) for d in prices]
+    lows = [d.get("low", d.get("close", 0)) for d in prices]
+    closes = [d.get("close", 0) for d in prices]
+    dates = [d.get("date", f"day-{i}") for i, d in enumerate(prices)]
+
+    swing_highs = _find_swing_highs(highs, window=5)
+    swing_lows = _find_swing_lows(lows, window=5)
+
+    if len(swing_highs) < 1 or len(swing_lows) < 1:
+        return {
+            "score": 0,
+            "valid_vcp": False,
+            "contractions": [],
+            "num_contractions": 0,
+            "pivot_price": None,
+            "error": "Insufficient swing points detected",
+        }
+
+    # Step B: Identify contractions
+    contractions = _identify_contractions(swing_highs, swing_lows, highs, lows, dates)
+
+    if len(contractions) < 2:
+        return {
+            "score": 0,
+            "valid_vcp": False,
+            "contractions": contractions,
+            "num_contractions": len(contractions),
+            "pivot_price": _get_pivot_price(contractions, highs, swing_highs),
+            "error": "Fewer than 2 contractions found" if len(contractions) < 2 else None,
+        }
+
+    # Step C: Validate VCP
+    validation = _validate_vcp(contractions, n)
+
+    # Pivot price = high of the last contraction
+    pivot_price = _get_pivot_price(contractions, highs, swing_highs)
+
+    # Calculate pattern duration
+    if len(contractions) >= 2:
+        first_idx = contractions[0]["high_idx"]
+        last_low_idx = contractions[-1]["low_idx"]
+        pattern_duration = last_low_idx - first_idx
+    else:
+        pattern_duration = 0
+
+    # Score the pattern
+    score = _score_vcp(contractions, validation)
+
+    return {
+        "score": score,
+        "valid_vcp": validation["valid"],
+        "contractions": contractions,
+        "num_contractions": len(contractions),
+        "pivot_price": round(pivot_price, 2) if pivot_price else None,
+        "pattern_duration_days": pattern_duration,
+        "validation": validation,
+        "error": None,
+    }
+
+
+def _find_swing_highs(highs: List[float], window: int = 5) -> List[Tuple[int, float]]:
+    """Find swing high points. Returns list of (index, value)."""
+    swing_highs = []
+    for i in range(window, len(highs) - window):
+        is_high = True
+        for j in range(1, window + 1):
+            if highs[i] <= highs[i - j] or highs[i] <= highs[i + j]:
+                is_high = False
+                break
+        if is_high:
+            swing_highs.append((i, highs[i]))
+    return swing_highs
+
+
+def _find_swing_lows(lows: List[float], window: int = 5) -> List[Tuple[int, float]]:
+    """Find swing low points. Returns list of (index, value)."""
+    swing_lows = []
+    for i in range(window, len(lows) - window):
+        is_low = True
+        for j in range(1, window + 1):
+            if lows[i] >= lows[i - j] or lows[i] >= lows[i + j]:
+                is_low = False
+                break
+        if is_low:
+            swing_lows.append((i, lows[i]))
+    return swing_lows
+
+
+def _identify_contractions(
+    swing_highs: List[Tuple[int, float]],
+    swing_lows: List[Tuple[int, float]],
+    highs: List[float],
+    lows: List[float],
+    dates: List[str],
+) -> List[Dict]:
+    """
+    Identify successive contractions from swing points.
+    Each contraction is defined by a swing high followed by a swing low.
+    """
+    if not swing_highs:
+        return []
+
+    # Start from the highest swing high in the lookback
+    h1_idx, h1_val = max(swing_highs, key=lambda x: x[1])
+
+    contractions = []
+    current_high_idx = h1_idx
+    current_high_val = h1_val
+
+    # Find successive contraction pairs
+    for _ in range(4):  # Max 4 contractions
+        # Find next swing low after current high
+        next_low = None
+        for idx, val in swing_lows:
+            if idx > current_high_idx:
+                next_low = (idx, val)
+                break
+
+        if next_low is None:
+            break
+
+        low_idx, low_val = next_low
+        depth_pct = (current_high_val - low_val) / current_high_val * 100 if current_high_val > 0 else 0
+
+        contractions.append({
+            "label": f"T{len(contractions) + 1}",
+            "high_idx": current_high_idx,
+            "high_price": round(current_high_val, 2),
+            "high_date": dates[current_high_idx] if current_high_idx < len(dates) else "N/A",
+            "low_idx": low_idx,
+            "low_price": round(low_val, 2),
+            "low_date": dates[low_idx] if low_idx < len(dates) else "N/A",
+            "depth_pct": round(depth_pct, 2),
+        })
+
+        # Find next swing high after this low (for the next contraction)
+        next_high = None
+        for idx, val in swing_highs:
+            if idx > low_idx:
+                next_high = (idx, val)
+                break
+
+        if next_high is None:
+            break
+
+        current_high_idx, current_high_val = next_high
+
+    return contractions
+
+
+def _validate_vcp(contractions: List[Dict], total_days: int) -> Dict:
+    """Validate whether the contraction pattern qualifies as a VCP."""
+    issues = []
+    valid = True
+
+    if len(contractions) < 2:
+        return {"valid": False, "issues": ["Need at least 2 contractions"]}
+
+    # Check T1 depth (8-35% for large-caps)
+    t1_depth = contractions[0]["depth_pct"]
+    if t1_depth < 8:
+        issues.append(f"T1 depth too shallow ({t1_depth:.1f}%, need >= 8%)")
+        valid = False
+    elif t1_depth > 35:
+        issues.append(f"T1 depth too deep ({t1_depth:.1f}%, prefer <= 35%)")
+        # Don't invalidate, just flag
+
+    # Check contraction tightening (each T should be <= 75% of previous)
+    contraction_ratios = []
+    for i in range(1, len(contractions)):
+        prev_depth = contractions[i - 1]["depth_pct"]
+        curr_depth = contractions[i]["depth_pct"]
+        if prev_depth > 0:
+            ratio = curr_depth / prev_depth
+            contraction_ratios.append(ratio)
+            if ratio > 0.75:
+                issues.append(
+                    f"{contractions[i]['label']} ({curr_depth:.1f}%) does not contract "
+                    f"25%+ vs {contractions[i-1]['label']} ({prev_depth:.1f}%), "
+                    f"ratio={ratio:.2f} (need <= 0.75)"
+                )
+                valid = False
+
+    # Check successive highs within 5% of each other
+    for i in range(1, len(contractions)):
+        prev_high = contractions[i - 1]["high_price"]
+        curr_high = contractions[i]["high_price"] if i < len(contractions) else contractions[-1]["high_price"]
+        # The high of subsequent contraction should be near the first
+        if prev_high > 0:
+            pct_diff = abs(curr_high - contractions[0]["high_price"]) / contractions[0]["high_price"] * 100
+            if pct_diff > 5:
+                issues.append(
+                    f"{contractions[i]['label']} high ${curr_high:.2f} is "
+                    f"{pct_diff:.1f}% from H1 ${contractions[0]['high_price']:.2f}"
+                )
+
+    # Pattern duration check (15-325 trading days)
+    if len(contractions) >= 2:
+        duration = contractions[-1]["low_idx"] - contractions[0]["high_idx"]
+        if duration < 15:
+            issues.append(f"Pattern too short ({duration} days, need >= 15)")
+            valid = False
+        elif duration > 325:
+            issues.append(f"Pattern too long ({duration} days, prefer <= 325)")
+
+    return {
+        "valid": valid,
+        "issues": issues,
+        "contraction_ratios": [round(r, 3) for r in contraction_ratios],
+        "t1_depth": t1_depth,
+    }
+
+
+def _get_pivot_price(
+    contractions: List[Dict],
+    highs: List[float],
+    swing_highs: List[Tuple[int, float]],
+) -> Optional[float]:
+    """Get the pivot (breakout) price - high of the last contraction."""
+    if contractions:
+        return contractions[-1]["high_price"]
+    elif swing_highs:
+        return swing_highs[-1][1]
+    return None
+
+
+def _score_vcp(contractions: List[Dict], validation: Dict) -> int:
+    """Score the VCP pattern quality (0-100)."""
+    if not validation["valid"]:
+        # Even invalid patterns get partial credit for structure
+        return min(40, len(contractions) * 15)
+
+    num = len(contractions)
+
+    # Base score by contraction count
+    if num >= 4:
+        base = 90
+    elif num >= 3:
+        base = 80
+    elif num >= 2:
+        base = 60
+    else:
+        return 20
+
+    score = base
+
+    # Bonus: tight final contraction (< 5% depth)
+    final_depth = contractions[-1]["depth_pct"]
+    if final_depth < 5:
+        score += 10
+
+    # Bonus: good contraction ratio (avg < 0.4 of T1)
+    ratios = validation.get("contraction_ratios", [])
+    if ratios and sum(ratios) / len(ratios) < 0.4:
+        score += 10
+
+    # Penalty: deep T1 (> 30%)
+    t1_depth = validation.get("t1_depth", 0)
+    if t1_depth > 30:
+        score -= 10
+
+    return max(0, min(100, score))

package/.claude/skills/vcp-screener/scripts/calculators/volume_pattern_calculator.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Volume Pattern Calculator - Volume Dry-Up Analysis
+
+Analyzes volume behavior near the pivot point of a VCP pattern.
+Key principle: Volume should contract (dry up) as the pattern tightens,
+then expand on breakout.
+
+Key Metric: Volume dry-up ratio = avg volume (last 10 bars near pivot) / 50-day avg volume
+
+Scoring:
+- Dry-up ratio < 0.30:  90 (exceptional volume contraction)
+- 0.30-0.50:            75 (strong dry-up)
+- 0.50-0.70:            60 (moderate dry-up)
+- 0.70-1.00:            40 (weak dry-up)
+- > 1.00:               20 (no dry-up, not ideal)
+
+Modifiers:
+- Breakout on 1.5x+ volume: +10
+- Net accumulation > 3 days: +10
+- Net distribution > 3 days: -10
+"""
+
+from typing import Dict, List, Optional
+
+
+def calculate_volume_pattern(
+    historical_prices: List[Dict],
+    pivot_price: Optional[float] = None,
+) -> Dict:
+    """
+    Analyze volume behavior near the VCP pivot point.
+
+    Args:
+        historical_prices: Daily OHLCV data (most recent first), need 50+ days
+        pivot_price: The pivot (breakout) price level. If None, uses recent high.
+
+    Returns:
+        Dict with score (0-100), dry_up_ratio, volume details
+    """
+    if not historical_prices or len(historical_prices) < 20:
+        return {
+            "score": 0,
+            "dry_up_ratio": None,
+            "error": "Insufficient data (need 20+ days)",
+        }
+
+    volumes = [d.get("volume", 0) for d in historical_prices]
+    closes = [d.get("close", d.get("adjClose", 0)) for d in historical_prices]
+
+    # 50-day average volume (or available)
+    vol_period = min(50, len(volumes))
+    avg_volume_50d = sum(volumes[:vol_period]) / vol_period if vol_period > 0 else 0
+
+    if avg_volume_50d <= 0:
+        return {
+            "score": 0,
+            "dry_up_ratio": None,
+            "error": "No volume data available",
+        }
+
+    # Recent volume (last 10 bars, representing area near pivot)
+    recent_period = min(10, len(volumes))
+    avg_volume_recent = sum(volumes[:recent_period]) / recent_period if recent_period > 0 else 0
+
+    # Volume dry-up ratio
+    dry_up_ratio = avg_volume_recent / avg_volume_50d if avg_volume_50d > 0 else 1.0
+
+    # Base score from dry-up ratio
+    if dry_up_ratio < 0.30:
+        base_score = 90
+    elif dry_up_ratio < 0.50:
+        base_score = 75
+    elif dry_up_ratio < 0.70:
+        base_score = 60
+    elif dry_up_ratio <= 1.00:
+        base_score = 40
+    else:
+        base_score = 20
+
+    score = base_score
+
+    # Modifier: Check for breakout volume (most recent day)
+    breakout_volume = False
+    if len(volumes) >= 2 and volumes[0] > avg_volume_50d * 1.5:
+        current_price = closes[0] if closes else 0
+        if pivot_price and current_price > pivot_price:
+            breakout_volume = True
+            score += 10
+
+    # Modifier: Net accumulation/distribution in last 20 days
+    # Count up-volume vs down-volume days
+    up_vol_days = 0
+    down_vol_days = 0
+    analysis_period = min(20, len(closes) - 1)
+
+    for i in range(analysis_period):
+        if i + 1 < len(closes) and closes[i] > closes[i + 1]:
+            up_vol_days += 1
+        elif i + 1 < len(closes) and closes[i] < closes[i + 1]:
+            down_vol_days += 1
+
+    net_accumulation = up_vol_days - down_vol_days
+    if net_accumulation > 3:
+        score += 10
+    elif net_accumulation < -3:
+        score -= 10
+
+    score = max(0, min(100, score))
+
+    return {
+        "score": score,
+        "dry_up_ratio": round(dry_up_ratio, 3),
+        "avg_volume_50d": int(avg_volume_50d),
+        "avg_volume_recent_10d": int(avg_volume_recent),
+        "breakout_volume_detected": breakout_volume,
+        "up_volume_days_20d": up_vol_days,
+        "down_volume_days_20d": down_vol_days,
+        "net_accumulation": net_accumulation,
+        "error": None,
+    }

package/.claude/skills/vcp-screener/scripts/fmp_client.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+FMP API Client for VCP Screener
+
+Provides rate-limited access to Financial Modeling Prep API endpoints
+for VCP (Volatility Contraction Pattern) screening.
+
+Features:
+- Rate limiting (0.3s between requests)
+- Automatic retry on 429 errors
+- Session caching for duplicate requests
+- Batch quote support
+- S&P 500 constituents fetching
+"""
+
+import os
+import sys
+import time
+from typing import Dict, List, Optional
+
+try:
+    import requests
+except ImportError:
+    print("ERROR: requests library not found. Install with: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+
+class FMPClient:
+    """Client for Financial Modeling Prep API with rate limiting and caching"""
+
+    BASE_URL = "https://financialmodelingprep.com/api/v3"
+    RATE_LIMIT_DELAY = 0.3  # 300ms between requests
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.getenv("FMP_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "FMP API key required. Set FMP_API_KEY environment variable "
+                "or pass api_key parameter."
+            )
+        self.session = requests.Session()
+        self.cache = {}
+        self.last_call_time = 0
+        self.rate_limit_reached = False
+        self.retry_count = 0
+        self.max_retries = 1
+        self.api_calls_made = 0
+
+    def _rate_limited_get(self, url: str, params: Optional[Dict] = None) -> Optional[Dict]:
+        if self.rate_limit_reached:
+            return None
+
+        if params is None:
+            params = {}
+        params['apikey'] = self.api_key
+
+        elapsed = time.time() - self.last_call_time
+        if elapsed < self.RATE_LIMIT_DELAY:
+            time.sleep(self.RATE_LIMIT_DELAY - elapsed)
+
+        try:
+            response = self.session.get(url, params=params, timeout=30)
+            self.last_call_time = time.time()
+            self.api_calls_made += 1
+
+            if response.status_code == 200:
+                self.retry_count = 0
+                return response.json()
+            elif response.status_code == 429:
+                self.retry_count += 1
+                if self.retry_count <= self.max_retries:
+                    print("WARNING: Rate limit exceeded. Waiting 60 seconds...", file=sys.stderr)
+                    time.sleep(60)
+                    return self._rate_limited_get(url, params)
+                else:
+                    print("ERROR: Daily API rate limit reached.", file=sys.stderr)
+                    self.rate_limit_reached = True
+                    return None
+            else:
+                print(f"ERROR: API request failed: {response.status_code} - {response.text[:200]}",
+                      file=sys.stderr)
+                return None
+        except requests.exceptions.RequestException as e:
+            print(f"ERROR: Request exception: {e}", file=sys.stderr)
+            return None
+
+    def get_sp500_constituents(self) -> Optional[List[Dict]]:
+        """Fetch S&P 500 constituent list.
+
+        Returns:
+            List of dicts with keys: symbol, name, sector, subSector
+            or None on failure.
+        """
+        cache_key = "sp500_constituents"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        url = f"{self.BASE_URL}/sp500_constituent"
+        data = self._rate_limited_get(url)
+        if data:
+            self.cache[cache_key] = data
+        return data
+
+    def get_quote(self, symbols: str) -> Optional[List[Dict]]:
+        """Fetch real-time quote data for one or more symbols (comma-separated)"""
+        cache_key = f"quote_{symbols}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        url = f"{self.BASE_URL}/quote/{symbols}"
+        data = self._rate_limited_get(url)
+        if data:
+            self.cache[cache_key] = data
+        return data
+
+    def get_historical_prices(self, symbol: str, days: int = 365) -> Optional[Dict]:
+        """Fetch historical daily OHLCV data"""
+        cache_key = f"prices_{symbol}_{days}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        url = f"{self.BASE_URL}/historical-price-full/{symbol}"
+        params = {"timeseries": days}
+        data = self._rate_limited_get(url, params)
+        if data:
+            self.cache[cache_key] = data
+        return data
+
+    def get_batch_quotes(self, symbols: List[str]) -> Dict[str, Dict]:
+        """Fetch quotes for a list of symbols, batching up to 5 per request"""
+        results = {}
+        batch_size = 5
+        for i in range(0, len(symbols), batch_size):
+            batch = symbols[i:i+batch_size]
+            batch_str = ",".join(batch)
+            quotes = self.get_quote(batch_str)
+            if quotes:
+                for q in quotes:
+                    results[q['symbol']] = q
+        return results
+
+    def get_batch_historical(self, symbols: List[str], days: int = 260) -> Dict[str, List[Dict]]:
+        """Fetch historical prices for multiple symbols"""
+        results = {}
+        for symbol in symbols:
+            data = self.get_historical_prices(symbol, days=days)
+            if data and 'historical' in data:
+                results[symbol] = data['historical']
+        return results
+
+    def calculate_sma(self, prices: List[float], period: int) -> float:
+        """Calculate Simple Moving Average from a list of prices (most recent first)"""
+        if len(prices) < period:
+            return sum(prices) / len(prices)
+        return sum(prices[:period]) / period
+
+    def get_api_stats(self) -> Dict:
+        return {
+            "cache_entries": len(self.cache),
+            "api_calls_made": self.api_calls_made,
+            "rate_limit_reached": self.rate_limit_reached,
+        }