quantwise 1.2.0 → 1.2.2

package/.claude/skills/vcp-screener/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: vcp-screener
+description: Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP). Identifies Stage 2 uptrend stocks forming tight bases with contracting volatility near breakout pivot points. Use when user requests VCP screening, Minervini-style setups, tight base patterns, volatility contraction breakout candidates, or Stage 2 momentum stock scanning.
+---
+
+# VCP Screener - Minervini Volatility Contraction Pattern
+
+Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP), identifying Stage 2 uptrend stocks with contracting volatility near breakout pivot points.
+
+## When to Use
+
+- User asks for VCP screening or Minervini-style setups
+- User wants to find tight base / volatility contraction patterns
+- User requests Stage 2 momentum stock scanning
+- User asks for breakout candidates with defined risk
+
+## Prerequisites
+
+- FMP API key (set `FMP_API_KEY` environment variable or pass `--api-key`)
+- Free tier (250 calls/day) is sufficient for default screening (top 100 candidates)
+- Paid tier recommended for full S&P 500 screening (`--full-sp500`)
+
+## Workflow
+
+### Step 1: Prepare and Execute Screening
+
+Run the VCP screener script:
+
+```bash
+# Default: S&P 500, top 100 candidates
+python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts
+
+# Custom universe
+python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts
+
+# Full S&P 500 (paid API tier)
+python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts
+```
+
+### Step 2: Review Results
+
+1. Read the generated JSON and Markdown reports
+2. Load `references/vcp_methodology.md` for pattern interpretation context
+3. Load `references/scoring_system.md` for score threshold guidance
+
+### Step 3: Present Analysis
+
+For each top candidate, present:
+- VCP composite score and rating
+- Contraction details (T1/T2/T3 depths and ratios)
+- Trade setup: pivot price, stop-loss, risk percentage
+- Volume dry-up ratio
+- Relative strength rank
+
+### Step 4: Provide Actionable Guidance
+
+Based on ratings:
+- **Textbook VCP (90+):** Buy at pivot with aggressive sizing
+- **Strong VCP (80-89):** Buy at pivot with standard sizing
+- **Good VCP (70-79):** Buy on volume confirmation above pivot
+- **Developing (60-69):** Add to watchlist, wait for tighter contraction
+- **Weak/No VCP (<60):** Monitor only or skip
+
+## 3-Phase Pipeline
+
+1. **Pre-Filter** - Quote-based screening (price, volume, 52w position) ~101 API calls
+2. **Trend Template** - 7-point Stage 2 filter with 260-day histories ~100 API calls
+3. **VCP Detection** - Pattern analysis, scoring, report generation (no additional API calls)
+
+## Output
+
+- `vcp_screener_YYYY-MM-DD_HHMMSS.json` - Structured results
+- `vcp_screener_YYYY-MM-DD_HHMMSS.md` - Human-readable report
+
+## Resources
+
+- `references/vcp_methodology.md` - VCP theory and Trend Template explanation
+- `references/scoring_system.md` - Scoring thresholds and component weights
+- `references/fmp_api_endpoints.md` - API endpoints and rate limits

package/.claude/skills/vcp-screener/references/fmp_api_endpoints.md

@@ -0,0 +1,45 @@
+# FMP API Endpoints Used by VCP Screener
+
+## Endpoints
+
+### 1. S&P 500 Constituents
+- **URL:** `GET /api/v3/sp500_constituent`
+- **Calls:** 1 (cached)
+- **Returns:** `[{symbol, name, sector, subSector}, ...]`
+- **Used in:** Phase 1 - Universe definition
+
+### 2. Batch Quote
+- **URL:** `GET /api/v3/quote/{symbols}` (comma-separated, max 5)
+- **Calls:** ~101 (503 stocks / 5 per batch)
+- **Returns:** `[{symbol, price, yearHigh, yearLow, avgVolume, marketCap, ...}]`
+- **Used in:** Phase 1 - Pre-filter
+
+### 3. Historical Prices
+- **URL:** `GET /api/v3/historical-price-full/{symbol}?timeseries=260`
+- **Calls:** 1 (SPY) + up to 100 (candidates)
+- **Returns:** `{symbol, historical: [{date, open, high, low, close, adjClose, volume}, ...]}`
+- **Used in:** Phase 2 - Trend Template, Phase 3 - VCP detection
+
+## API Budget Summary
+
+| Phase | Operation | API Calls |
+|-------|-----------|-----------|
+| 1 | S&P 500 constituents | 1 |
+| 1 | Batch quotes (503 / 5) | ~101 |
+| 2 | SPY 260-day history | 1 |
+| 2 | Candidate histories (max 100) | 100 |
+| **Total (default)** | | **~203** |
+| **Total (--full-sp500)** | | **~350** |
+
+## Rate Limits
+
+- **Free tier:** 250 API calls/day - Default screening fits within this limit
+- **Starter tier ($29.99/mo):** 750 calls/day
+- **Rate limiting:** 0.3s delay between requests, automatic retry on 429
+- **Caching:** In-memory session cache prevents duplicate requests
+
+## Notes
+
+- All historical data uses `timeseries=260` parameter (260 trading days = ~1 year)
+- Phase 3 (VCP detection, scoring, reporting) requires NO additional API calls
+- The `--full-sp500` flag fetches histories for all pre-filter passers (~250 stocks)

package/.claude/skills/vcp-screener/references/scoring_system.md

@@ -0,0 +1,154 @@
+# VCP Screener Scoring System
+
+## 5-Component Composite Score
+
+| Component | Weight | Source |
+|-----------|--------|--------|
+| Trend Template (Stage 2) | 25% | 7-point Minervini criteria |
+| Contraction Quality | 25% | VCP pattern detection |
+| Volume Pattern | 20% | Volume dry-up analysis |
+| Pivot Proximity | 15% | Distance from breakout level |
+| Relative Strength | 15% | Minervini-weighted RS vs S&P 500 |
+
+## Component Scoring Details
+
+### 1. Trend Template (0-100)
+
+Each of the 7 criteria contributes 14.3 points:
+
+| Criteria Passed | Score | Status |
+|-----------------|-------|--------|
+| 7/7 | 100 | Perfect Stage 2 |
+| 6/7 | 85.8 | Pass (minimum threshold) |
+| 5/7 | 71.5 | Borderline |
+| <= 4/7 | <= 57 | Fail |
+
+**Pass threshold:** Score >= 85 (6+ criteria) to proceed to VCP analysis.
+
+### 2. Contraction Quality (0-100)
+
+| # Contractions | Base Score |
+|----------------|-----------|
+| 4 | 90 |
+| 3 | 80 |
+| 2 | 60 |
+| 1 or invalid | 0-40 |
+
+**Modifiers:**
+- Tight final contraction (< 5% depth): +10
+- Good average contraction ratio (< 0.4 of T1): +10
+- Deep T1 (> 30%): -10
+
+### 3. Volume Pattern (0-100)
+
+Based on dry-up ratio (recent 10-bar avg / 50-day avg):
+
+| Dry-Up Ratio | Base Score |
+|-------------|-----------|
+| < 0.30 | 90 |
+| 0.30-0.50 | 75 |
+| 0.50-0.70 | 60 |
+| 0.70-1.00 | 40 |
+| > 1.00 | 20 |
+
+**Modifiers:**
+- Breakout on 1.5x+ volume: +10
+- Net accumulation > 3 days (in 20d): +10
+- Net distribution > 3 days (in 20d): -10
+
+### 4. Pivot Proximity (0-100) — Distance-Priority Scoring
+
+Scoring is distance-first. Volume confirmation adds a bonus only within 0-5% above pivot (Minervini: never chase >5% above pivot).
+
+| Distance from Pivot | Base Score | Volume Bonus | Final Score | Trade Status |
+|--------------------|-----------|-------------|------------|--------------|
+| 0-3% above | 90 | +10 | 100 | BREAKOUT CONFIRMED |
+| 3-5% above | 65 | +10 | 75 | EXTENDED - Moderate chase risk (vol confirmed) |
+| 5-10% above | 50 | — (none) | 50 | EXTENDED - High chase risk |
+| 10-20% above | 35 | — (none) | 35 | EXTENDED - Very high chase risk |
+| >20% above | 20 | — (none) | 20 | OVEREXTENDED - Do not chase |
+| 0 to -2% below | 90 | — | 90 | AT PIVOT (within 2%) |
+| -2% to -5% | 75 | — | 75 | NEAR PIVOT |
+| -5% to -8% | 60 | — | 60 | APPROACHING |
+| -8% to -10% | 45 | — | 45 | DEVELOPING |
+| -10% to -15% | 30 | — | 30 | EARLY |
+| < -15% | 10 | — | 10 | FAR FROM PIVOT |
+
+**Volume bonus rules:**
+- 0-3% above pivot + volume: +10 points, status = "BREAKOUT CONFIRMED"
+- 3-5% above pivot + volume: +10 points, "(vol confirmed)" appended to status
+- >5% above pivot: no volume bonus (Minervini: do not chase extended breakouts)
+- Below pivot: volume bonus not applicable
+
+**Chase risk rule (Minervini):** Do not buy stocks >5% above their pivot point. Distance determines the base score; volume confirmation is a bonus, not an override.
+
+### 5. Relative Strength (0-100)
+
+Minervini weighting (emphasizes recent performance):
+- 40%: Last 3 months (63 trading days)
+- 20%: Last 6 months (126 trading days)
+- 20%: Last 9 months (189 trading days)
+- 20%: Last 12 months (252 trading days)
+
+| Weighted RS vs S&P 500 | Score | RS Rank Estimate |
+|-------------------------|-------|------------------|
+| >= +50% | 100 | ~99 (top 1%) |
+| >= +30% | 95 | ~95 (top 5%) |
+| >= +20% | 90 | ~90 (top 10%) |
+| >= +10% | 80 | ~80 (top 20%) |
+| >= +5% | 70 | ~70 (top 30%) |
+| >= 0% | 60 | ~60 (top 40%) |
+| >= -5% | 50 | ~50 (average) |
+| >= -10% | 40 | ~40 |
+| >= -20% | 20 | ~25 |
+| < -20% | 0 | ~10 |
+
+## Rating Bands
+
+| Composite Score | Rating | Position Sizing | Action |
+|-----------------|--------|-----------------|--------|
+| 90-100 | Textbook VCP | 1.5-2x normal | Buy at pivot, aggressive |
+| 80-89 | Strong VCP | 1x normal | Buy at pivot, standard |
+| 70-79 | Good VCP | 0.75x normal | Buy on volume confirmation |
+| 60-69 | Developing VCP | Wait | Watchlist only |
+| 50-59 | Weak VCP | Skip | Monitor only |
+| < 50 | No VCP | Skip | Not actionable |
+
+### valid_vcp Gate Rule
+
+When the VCP pattern calculator returns `valid_vcp=false` (e.g., contraction ratios exceed 0.75, expanding contractions), the rating is capped regardless of composite score:
+
+- If `valid_vcp=false` AND composite >= 70: rating is overridden to **"Developing VCP"** with guidance "Watchlist only - VCP pattern not validated, do not buy"
+- If `valid_vcp=false` AND composite < 70: no override needed (already below actionable threshold)
+
+This prevents stocks with expanding or non-contracting patterns from receiving actionable buy ratings.
+
+## Entry Ready Conditions
+
+A stock is classified as `entry_ready=True` when all of the following conditions are met:
+
+| Condition | Default Threshold | CLI Override |
+|-----------|-------------------|--------------|
+| `valid_vcp` | `True` | `--no-require-valid-vcp` |
+| `distance_from_pivot_pct` | -8.0% to +3.0% | `--max-above-pivot` |
+| `dry_up_ratio` | <= 1.0 | — |
+| `risk_pct` | <= 15.0% | `--max-risk` |
+
+**Report sections:**
+- **Section A: Pre-Breakout Watchlist** — `entry_ready=True` stocks, sorted by composite score
+- **Section B: Extended / Quality VCP** — `entry_ready=False` stocks, sorted by composite score
+
+**CLI mode:**
+- `--mode all` (default): Shows both sections
+- `--mode prebreakout`: Shows only entry_ready=True stocks
+
+## Pre-Filter Criteria (Phase 1)
+
+Quick filter using quote data only (no historical needed):
+
+| Criterion | Threshold | Purpose |
+|-----------|-----------|---------|
+| Price | > $10 | Exclude penny stocks |
+| % above 52w low | > 20% | Roughly in uptrend |
+| % below 52w high | < 30% | Not in deep correction |
+| Average volume | > 200,000 | Sufficient liquidity |

package/.claude/skills/vcp-screener/references/vcp_methodology.md

@@ -0,0 +1,124 @@
+# VCP Methodology - Minervini's Volatility Contraction Pattern
+
+## Overview
+
+The Volatility Contraction Pattern (VCP) was developed by Mark Minervini, two-time U.S. Investing Championship winner. It identifies stocks in Stage 2 uptrends that are forming progressively tighter consolidation patterns before a potential breakout.
+
+## Stage Analysis Foundation
+
+### The 4 Stages (Stan Weinstein / Minervini)
+
+1. **Stage 1 - Accumulation/Basing:** Stock trades sideways after a decline. Smart money accumulates.
+2. **Stage 2 - Advancing/Uptrend:** Stock is in a confirmed uptrend. This is where VCPs form. **The only stage to buy.**
+3. **Stage 3 - Distribution/Topping:** Stock stalls after an advance. Smart money distributes.
+4. **Stage 4 - Declining/Downtrend:** Stock is in a confirmed downtrend. Avoid or short.
+
+### Minervini's 7-Point Trend Template (Stage 2 Confirmation)
+
+A stock MUST pass all (or nearly all) of these criteria to be in a confirmed Stage 2:
+
+| # | Criterion | Purpose |
+|---|-----------|---------|
+| 1 | Price > 150-day SMA AND Price > 200-day SMA | Above major trend lines |
+| 2 | 150-day SMA > 200-day SMA | Shorter MA above longer (bullish alignment) |
+| 3 | 200-day SMA trending up for 22+ trading days | Long-term trend is up |
+| 4 | Price > 50-day SMA | Above intermediate trend line |
+| 5 | Price at least 25% above 52-week low | Sufficient distance from lows |
+| 6 | Price within 25% of 52-week high | Not in a deep correction |
+| 7 | Relative Strength rating > 70 | Outperforming most stocks |
+
+**Pass threshold:** 6 of 7 criteria (score >= 85) to proceed to VCP detection.
+
+## VCP Pattern Mechanics
+
+### What is a VCP?
+
+A VCP occurs when a stock in a Stage 2 uptrend pulls back and then rallies, but each successive pullback is **shallower** (less volatile) than the previous one. This "volatility contraction" signals that:
+
+1. Selling pressure is being absorbed
+2. Remaining sellers are being exhausted
+3. Supply is drying up
+4. A breakout becomes more probable
+
+### Contraction Structure
+
+```
+        H1 (Highest swing high)
+       / \
+      /   \  T1 (First contraction: deepest)
+     /     \
+    /       L1
+   /       / \
+  /       /   \ T2 (Second contraction: tighter)
+         H2    \
+          \    L2
+           \  / \
+            \/   \ T3 (Third contraction: tightest)
+            H3    L3
+             \   /
+              \ /  ← PIVOT POINT (buy here on volume)
+               P
+```
+
+### Contraction Rules
+
+- **T1 (first correction):** 8-35% depth for S&P 500 large-caps (up to 50% for small-caps)
+- **T2:** Must be at least 25% tighter than T1 (ratio <= 0.75)
+- **T3:** Must be at least 25% tighter than T2 (if present)
+- **T4:** Extremely tight, often < 5% (rare, very bullish)
+- **Minimum:** 2 contractions required
+- **Ideal:** 3-4 contractions with progressive tightening
+- **Duration:** 15-325 trading days for the complete pattern
+
+### Pivot Point
+
+The **pivot** is the high of the last contraction. This is the buy point:
+
+- Buy when price moves above the pivot on volume 1.5x+ above the 50-day average
+- Place stop-loss 1-2% below the last contraction low
+- Risk per trade should be 5-8% from entry to stop
+
+### Volume Signature
+
+Ideal volume behavior during a VCP:
+
+1. **During corrections:** Volume should decrease (sellers exhausting)
+2. **Near the pivot:** Volume should "dry up" (extremely low, calm before the storm)
+3. **On breakout:** Volume should surge to 1.5-2x the 50-day average
+
+**Dry-up ratio** = Average volume (last 10 bars near pivot) / 50-day average volume
+- < 0.30: Exceptional (textbook)
+- 0.30-0.50: Strong
+- 0.50-0.70: Adequate
+- \> 0.70: Weak (caution)
+
+## Historical VCP Examples
+
+### Classic 3-Contraction VCP
+- T1: 20% pullback over 6 weeks
+- T2: 12% pullback over 3 weeks (40% tighter)
+- T3: 5% pullback over 2 weeks (58% tighter)
+- Breakout on 2x volume → 50%+ advance
+
+### Tight 2-Contraction VCP (Large-Cap)
+- T1: 12% pullback over 4 weeks
+- T2: 5% pullback over 2 weeks (58% tighter)
+- Breakout on 1.8x volume → 25-30% advance
+
+## Common Pitfalls
+
+1. **Buying before the pivot:** Wait for the breakout, not the setup
+2. **Ignoring volume:** A breakout without volume often fails
+3. **Wide stops:** Keep stops tight (below last contraction low)
+4. **Wrong stage:** VCPs only work in Stage 2; verify with Trend Template first
+5. **Deep T1:** If T1 > 35% for large-caps, the pattern is less reliable
+6. **Expanding contractions:** If T2 > T1, it's NOT a VCP
+
+## Position Sizing by VCP Quality
+
+| Rating | Position Size | Risk Budget |
+|--------|---------------|-------------|
+| Textbook (90+) | 1.5-2x normal | Full |
+| Strong (80-89) | 1x normal | Full |
+| Good (70-79) | 0.75x normal | Standard |
+| Developing (60-69) | Wait/Watch | Reduced |

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

@@ -0,0 +1 @@
+# VCP Screener Calculators

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Pivot Proximity Calculator - Breakout Distance & Risk Analysis
+
+Calculates how close the current price is to the VCP pivot (breakout) point
+and computes the risk profile for a potential trade.
+
+Distance-priority scoring (Minervini: do not chase >5% above pivot):
+- 0-3% above pivot:  90 (+ volume bonus 10 = 100 BREAKOUT CONFIRMED)
+- 3-5% above:        65 (+ volume bonus 10 = 75)
+- 5-10% above:       50 (no volume bonus)
+- 10-20% above:      35 (no volume bonus)
+- >20% above:        20 (no volume bonus)
+- 0 to -2% below:    90 (AT PIVOT)
+- -2% to -5%:        75 (NEAR PIVOT)
+- -5% to -8%:        60 (APPROACHING)
+- -8% to -10%:       45 (DEVELOPING)
+- -10% to -15%:      30 (EARLY)
+- < -15%:            10 (FAR FROM PIVOT)
+
+Also calculates:
+- Stop-loss price (below last contraction low)
+- Risk % per share (entry to stop distance)
+"""
+
+from typing import Dict, List, Optional
+
+
+def calculate_pivot_proximity(
+    current_price: float,
+    pivot_price: Optional[float],
+    last_contraction_low: Optional[float] = None,
+    breakout_volume: bool = False,
+) -> Dict:
+    """
+    Calculate proximity to pivot point and risk metrics.
+
+    Args:
+        current_price: Current stock price
+        pivot_price: The pivot (breakout) price from VCP pattern
+        last_contraction_low: Low of the last contraction (for stop-loss)
+        breakout_volume: Whether current volume is 1.5x+ above average
+
+    Returns:
+        Dict with score (0-100), distance_pct, stop_loss, risk_pct
+    """
+    if not pivot_price or pivot_price <= 0:
+        return {
+            "score": 0,
+            "distance_from_pivot_pct": None,
+            "stop_loss_price": None,
+            "risk_pct": None,
+            "trade_status": "NO PIVOT",
+            "error": "No valid pivot price",
+        }
+
+    if current_price <= 0:
+        return {
+            "score": 0,
+            "distance_from_pivot_pct": None,
+            "stop_loss_price": None,
+            "risk_pct": None,
+            "trade_status": "INVALID PRICE",
+            "error": "Invalid current price",
+        }
+
+    # Distance from pivot (negative = below pivot)
+    distance_pct = (current_price - pivot_price) / pivot_price * 100
+
+    # Determine trade status and score (distance-priority)
+    if distance_pct > 20:
+        score = 20
+        trade_status = "OVEREXTENDED - Do not chase"
+    elif distance_pct > 10:
+        score = 35
+        trade_status = "EXTENDED - Very high chase risk"
+    elif distance_pct > 5:
+        score = 50
+        trade_status = "EXTENDED - High chase risk"
+    elif distance_pct > 3:
+        score = 65
+        trade_status = "EXTENDED - Moderate chase risk"
+    elif distance_pct > 0:
+        score = 90
+        trade_status = "ABOVE PIVOT (within 3%)"
+    elif distance_pct >= -2:
+        score = 90
+        trade_status = "AT PIVOT (within 2%)"
+    elif distance_pct >= -5:
+        score = 75
+        trade_status = "NEAR PIVOT (2-5% below)"
+    elif distance_pct >= -8:
+        score = 60
+        trade_status = "APPROACHING (5-8% below)"
+    elif distance_pct >= -10:
+        score = 45
+        trade_status = "DEVELOPING (8-10% below)"
+    elif distance_pct >= -15:
+        score = 30
+        trade_status = "EARLY (10-15% below)"
+    else:
+        score = 10
+        trade_status = "FAR FROM PIVOT (>15% below)"
+
+    # Volume confirmation bonus (only for 0-5% above pivot)
+    if breakout_volume and distance_pct > 0:
+        if distance_pct <= 3:
+            score += 10
+            trade_status = "BREAKOUT CONFIRMED"
+        elif distance_pct <= 5:
+            score += 10
+            trade_status += " (vol confirmed)"
+
+    # Calculate stop-loss and risk
+    stop_loss_price = None
+    risk_pct = None
+
+    if last_contraction_low and last_contraction_low > 0:
+        # Stop-loss is 1-2% below the last contraction low
+        stop_loss_price = round(last_contraction_low * 0.99, 2)
+
+        # Risk per share from current price to stop
+        if current_price > stop_loss_price:
+            risk_pct = round((current_price - stop_loss_price) / current_price * 100, 2)
+        else:
+            # Price already below stop level
+            risk_pct = 0
+            trade_status = "BELOW STOP LEVEL"
+            score = max(0, score - 20)
+
+    return {
+        "score": score,
+        "distance_from_pivot_pct": round(distance_pct, 2),
+        "pivot_price": round(pivot_price, 2),
+        "stop_loss_price": stop_loss_price,
+        "risk_pct": risk_pct,
+        "trade_status": trade_status,
+        "error": None,
+    }