quantwise 1.2.0 → 1.2.2

package/.claude/skills/market-top-detector/scripts/calculators/sentiment_calculator.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Component 6: Sentiment & Speculation (Weight: 10%)
+
+Data sources:
+- VIX: FMP API quote
+- Put/Call ratio: CLI argument (from WebSearch)
+- VIX term structure: CLI argument (from WebSearch)
+
+Scoring (additive, max 100):
+  Put/Call < 0.60 -> +40pt (extreme call buying = complacency)
+  Put/Call < 0.70 -> +30pt
+  Put/Call < 0.80 -> +15pt
+  Put/Call >= 0.80 -> +0pt (healthy caution)
+
+  VIX < 12       -> +30pt (extreme low fear)
+  VIX < 14       -> +20pt
+  VIX < 16       -> +10pt
+  VIX 16-20      -> +0pt (normal)
+  VIX > 25       -> -10pt (fear already present, top less likely)
+
+  VIX term structure:
+    Steep contango (normal) -> +30pt (complacency)
+    Normal contango        -> +15pt
+    Flat                   -> +0pt
+    Backwardation          -> -10pt (hedging demand = fear)
+"""
+
+from typing import Dict, Optional
+
+
+# VIX term structure states
+STEEP_CONTANGO = "steep_contango"
+NORMAL_CONTANGO = "contango"
+FLAT = "flat"
+BACKWARDATION = "backwardation"
+
+
+def calculate_sentiment(vix_level: Optional[float] = None,
+                        put_call_ratio: Optional[float] = None,
+                        vix_term_structure: Optional[str] = None,
+                        margin_debt_yoy_pct: Optional[float] = None) -> Dict:
+    """
+    Calculate sentiment and speculation score.
+
+    Args:
+        vix_level: Current VIX value (from FMP API)
+        put_call_ratio: CBOE equity put/call ratio (from WebSearch/CLI)
+        vix_term_structure: One of 'steep_contango', 'contango', 'flat', 'backwardation'
+        margin_debt_yoy_pct: Year-over-year margin debt change % (optional extra context)
+
+    Returns:
+        Dict with score (0-100), signal, component details
+    """
+    # All inputs missing -> neutral default
+    if vix_level is None and put_call_ratio is None and vix_term_structure is None:
+        return {
+            "score": 50,
+            "signal": "NO DATA: All sentiment inputs missing (neutral default)",
+            "data_available": False,
+            "total_points": 0,
+            "details": {},
+        }
+
+    total_points = 0
+    details = {}
+
+    # 1. Put/Call Ratio scoring
+    pc_points = 0
+    if put_call_ratio is not None:
+        if put_call_ratio < 0.60:
+            pc_points = 40
+        elif put_call_ratio < 0.70:
+            pc_points = 30
+        elif put_call_ratio < 0.80:
+            pc_points = 15
+        else:
+            pc_points = 0
+        details["put_call_ratio"] = {
+            "value": put_call_ratio,
+            "points": pc_points,
+            "interpretation": _interpret_put_call(put_call_ratio),
+        }
+    else:
+        details["put_call_ratio"] = {"value": None, "points": 0, "interpretation": "No data"}
+
+    total_points += pc_points
+
+    # 2. VIX Level scoring
+    vix_points = 0
+    if vix_level is not None:
+        if vix_level < 12:
+            vix_points = 30
+        elif vix_level < 14:
+            vix_points = 20
+        elif vix_level < 16:
+            vix_points = 10
+        elif vix_level <= 25:
+            vix_points = 0
+        else:
+            vix_points = -10  # High fear = top less likely
+        details["vix_level"] = {
+            "value": round(vix_level, 2),
+            "points": vix_points,
+            "interpretation": _interpret_vix(vix_level),
+        }
+    else:
+        details["vix_level"] = {"value": None, "points": 0, "interpretation": "No data"}
+
+    total_points += vix_points
+
+    # 3. VIX Term Structure scoring
+    vts_points = 0
+    if vix_term_structure:
+        if vix_term_structure == STEEP_CONTANGO:
+            vts_points = 30
+        elif vix_term_structure == NORMAL_CONTANGO:
+            vts_points = 15
+        elif vix_term_structure == FLAT:
+            vts_points = 0
+        elif vix_term_structure == BACKWARDATION:
+            vts_points = -10
+        details["vix_term_structure"] = {
+            "value": vix_term_structure,
+            "points": vts_points,
+            "interpretation": _interpret_vix_term(vix_term_structure),
+        }
+    else:
+        details["vix_term_structure"] = {"value": None, "points": 0, "interpretation": "No data"}
+
+    total_points += vts_points
+
+    # Clamp to 0-100
+    score = max(0, min(100, total_points))
+
+    # Margin debt as additional context (not scored but reported)
+    if margin_debt_yoy_pct is not None:
+        details["margin_debt"] = {
+            "yoy_pct": margin_debt_yoy_pct,
+            "interpretation": _interpret_margin_debt(margin_debt_yoy_pct),
+            "note": "Not included in score - additional context only",
+        }
+
+    # Signal
+    if score >= 70:
+        signal = "CRITICAL: Extreme complacency / speculation"
+    elif score >= 50:
+        signal = "WARNING: Elevated complacency"
+    elif score >= 30:
+        signal = "CAUTION: Some speculative excess"
+    elif score >= 10:
+        signal = "MIXED: Moderate sentiment"
+    else:
+        signal = "HEALTHY: No excessive speculation"
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "total_points": total_points,
+        "details": details,
+    }
+
+
+def _interpret_put_call(ratio: float) -> str:
+    if ratio < 0.60:
+        return "Extreme call buying - maximum complacency"
+    elif ratio < 0.70:
+        return "Elevated call buying - notable optimism"
+    elif ratio < 0.80:
+        return "Slightly optimistic"
+    elif ratio < 0.90:
+        return "Normal range"
+    else:
+        return "Elevated put buying - caution/fear present"
+
+
+def _interpret_vix(level: float) -> str:
+    if level < 12:
+        return "Extreme low fear - complacency zone"
+    elif level < 14:
+        return "Low fear"
+    elif level < 16:
+        return "Mildly low volatility"
+    elif level <= 20:
+        return "Normal range"
+    elif level <= 25:
+        return "Elevated fear"
+    else:
+        return "High fear - panic present"
+
+
+def _interpret_vix_term(structure: str) -> str:
+    mapping = {
+        STEEP_CONTANGO: "Market expects calm - complacency in term structure",
+        NORMAL_CONTANGO: "Normal term structure",
+        FLAT: "Uncertainty - no clear expectation",
+        BACKWARDATION: "Hedging demand elevated - fear in term structure",
+    }
+    return mapping.get(structure, "Unknown")
+
+
+def _interpret_margin_debt(yoy_pct: float) -> str:
+    if yoy_pct >= 30:
+        return f"DANGER: Margin debt surging +{yoy_pct:.0f}% YoY"
+    elif yoy_pct >= 20:
+        return f"WARNING: Rapid leverage increase +{yoy_pct:.0f}% YoY"
+    elif yoy_pct >= 10:
+        return f"Elevated: +{yoy_pct:.0f}% YoY"
+    elif yoy_pct >= 0:
+        return f"Normal: +{yoy_pct:.0f}% YoY"
+    else:
+        return f"Deleveraging: {yoy_pct:.0f}% YoY"

package/.claude/skills/market-top-detector/scripts/fmp_client.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+FMP API Client for Market Top Detector
+
+Provides rate-limited access to Financial Modeling Prep API endpoints
+for market top detection analysis.
+
+Features:
+- Rate limiting (0.3s between requests)
+- Automatic retry on 429 errors
+- Session caching for duplicate requests
+- Batch quote support for ETF baskets
+"""
+
+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_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 = {}
+        # FMP supports comma-separated symbols in quote endpoint
+        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 = 50) -> 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_ema(self, prices: List[float], period: int) -> float:
+        """Calculate Exponential Moving Average from a list of prices (most recent first)"""
+        if len(prices) < period:
+            return sum(prices) / len(prices)
+
+        prices_reversed = prices[::-1]
+        sma = sum(prices_reversed[:period]) / period
+        ema = sma
+        k = 2 / (period + 1)
+        for price in prices_reversed[period:]:
+            ema = price * k + ema * (1 - k)
+        return ema
+
+    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,
+        }