期权价差置信度引擎

说明文档

# Options Spread Conviction Engine

**Multi-regime options spread scoring using technical indicators and IV term structure analysis.**

## Install

```bash
brew install jq
npm install yahoo-finance2
sudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf
```

## Overview

This engine analyzes any ticker and scores **seven** options strategies across two categories:

### Vertical Spreads (Directional)
| Strategy | Type | Philosophy | Ideal Setup |
|----------|------|------------|-------------|
| **bull_put** | Credit | Mean Reversion | Bullish trend + oversold dip |
| **bear_call** | Credit | Mean Reversion | Bearish trend + overbought rip |
| **bull_call** | Debit | Breakout | Strong bullish momentum |
| **bear_put** | Debit | Breakout | Strong bearish momentum |

### Multi-Leg Strategies (Non-Directional / Theta)
| Strategy | Type | Philosophy | Ideal Setup |
|----------|------|------------|-------------|
| **iron_condor** | Credit | Premium Selling | IV Rank >70, RSI neutral, range-bound |
| **butterfly** | Debit | Pinning Play | BB squeeze, RSI center, low ADX |
| **calendar** | Debit | Theta Harvest | Inverted IV term structure (front > back) |

## Scoring Methodology

### Vertical Spreads

Weights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):

#### Credit Spreads (bull_put, bear_call)
| Indicator | Weight | Purpose |
|-----------|--------|---------|
| Ichimoku Cloud | 25 pts | Trend structure & equilibrium |
| RSI | 20 pts | Entry timing (mean-reversion) |
| MACD | 15 pts | Momentum confirmation |
| Bollinger Bands | 25 pts | Volatility regime |
| ADX | 15 pts | Trend strength validation |

#### Debit Spreads (bull_call, bear_put)
| Indicator | Weight | Purpose |
|-----------|--------|---------|
| Ichimoku Cloud | 20 pts | Trend confirmation |
| RSI | 10 pts | Directional momentum |
| MACD | 30 pts | Breakout acceleration |
| Bollinger Bands | 25 pts | Bandwidth expansion |
| ADX | 15 pts | Trend strength validation |

### Multi-Leg Strategies

#### Iron Condor (Credit / Range-Bound)
| Component | Weight | Rationale |
|-----------|--------|-----------|
| IV Rank (BBW %) | 25 pts | Rich premiums to sell |
| RSI Neutrality | 20 pts | No directional momentum |
| ADX Range-Bound | 20 pts | Weak trend = range structure |
| Price Position | 20 pts | Centered in range = safe margins |
| MACD Neutrality | 15 pts | No acceleration in any direction |

**Triggers:**
- IV Rank > 70: Premium-rich environment
- RSI 40-60: Neutral momentum
- ADX < 25: Weak/no trend
- Price near %B center: Max profit zone maximized

**Strike Selection:**
- SELL put at 1-sigma below price (short put)
- BUY put at 2-sigma below (long put — wing)
- SELL call at 1-sigma above price (short call)
- BUY call at 2-sigma above (long call — wing)

**Output:**
- All 4 strikes (put_long, put_short, call_short, call_long)
- Max profit zone (width between short strikes)
- Wing width

#### Butterfly (Debit / Volatility Compression)
| Component | Weight | Rationale |
|-----------|--------|-----------|
| BB Squeeze | 30 pts | Vol compression = narrow range |
| RSI Neutrality | 25 pts | Price at equilibrium |
| ADX Weakness | 20 pts | No directional trend at all |
| Price Centering | 15 pts | At center of range for max profit |
| MACD Flatness | 10 pts | No momentum |

**Triggers:**
- BBW percentile < 25: Squeeze active
- RSI 45-55: Dead-center (tighter than condor)
- ADX < 20: Very weak trend
- MACD histogram near zero
- Price at %B = 0.50

**Strike Selection:**
- BUY 1 call at strike below center (lower wing)
- SELL 2 calls at center strike (body)
- BUY 1 call at strike above center (upper wing)

**Output:**
- 3 strikes (lower_long, middle_short, upper_long)
- Max profit price (= middle strike)
- Profit zone (approximate breakevens)

#### Calendar Spread (Debit / Theta Harvesting)
| Component | Weight | Rationale |
|-----------|--------|-----------|
| IV Term Structure | 30 pts | Front IV > Back IV = theta edge |
| Price Stability | 20 pts | Price stays near strike |
| RSI Neutrality | 20 pts | Not trending away from strike |
| ADX Moderate | 15 pts | Some structure, not trending hard |
| MACD Neutrality | 15 pts | No directional acceleration |

**Triggers:**
- Front-month IV > Back-month IV by > 5%: Inverted term structure
- Low recent volatility: Price stability
- RSI neutral: No directional momentum
- ADX 18-25: Moderate trend structure (not chaos)

**Data Sources:**
- Primary: Live options chain IV from Yahoo Finance
- Fallback: Historical volatility proxy (HV 10-day vs 30-day)

**Strike Selection:**
- ATM strike (rounded to standard interval)
- Front expiry: nearest available
- Back expiry: 25+ days after front

**Output:**
- Single strike (both legs)
- Front and back expiry dates
- IV differential (%)
- Theta advantage description

## Conviction Tiers

| Score | Tier | Action |
|-------|------|--------|
| 80-100 | EXECUTE | High conviction — Enter the spread |
| 60-79 | PREPARE | Favorable — Size the trade |
| 40-59 | WATCH | Interesting — Add to watchlist |
| 0-39 | WAIT | Poor conditions — Avoid / No setup |

## Usage

### Vertical Spreads

```bash
# Basic analysis (auto-detects best strategy)
conviction-engine AAPL

# Specific strategy
conviction-engine SPY --strategy bear_call
conviction-engine QQQ --strategy bull_call --period 2y
```

### Multi-Leg Strategies

```bash
# Iron Condor — high IV, range-bound
conviction-engine SPY --strategy iron_condor

# Butterfly — volatility compression, pinning play
conviction-engine AAPL --strategy butterfly

# Calendar — inverted IV term structure, theta harvest
conviction-engine TSLA --strategy calendar
```

### Multiple Tickers

```bash
conviction-engine AAPL MSFT GOOGL --strategy bull_put
conviction-engine SPY QQQ IWM --strategy iron_condor
```

### JSON Output (for automation)

```bash
conviction-engine TSLA --strategy butterfly --json
conviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'
```

### Full Options

```bash
conviction-engine <ticker> [ticker...]
  --strategy {bull_put,bear_call,bull_call,bear_put,iron_condor,butterfly,calendar}
  --period {1y,2y,3y,5y}
  --interval {1h,1d,1wk}
  --json
```

## Example Outputs

### Iron Condor

```
================================================================================
SPY — Iron Condor (Credit)
================================================================================
Price: $681.27 | Score: 31.8/100 → WAIT

[IV Rank +2.5/25]
  IV Rank (BBW proxy): 5% (VERY_LOW)
  BBW: 3.17 (1Y range: 2.37 - 18.13)
  Premiums are THIN — poor risk/reward for credit

Strikes:
  BUY  680.0P | SELL 685.0P
  SELL 695.0C | BUY  700.0C
  Max Profit Zone: $685.0 - $695.0
  Wing Width: $5.00
```

### Butterfly

```
================================================================================
SPY — Long Butterfly (Debit)
================================================================================
Price: $681.27 | Score: 64.5/100 → PREPARE

[BB Squeeze +27.0/30]
  Bandwidth: 3.1701 (percentile: 21%)
  SQUEEZE ACTIVE — 19 consecutive bars

Strikes:
  BUY 1x 685.0C | SELL 2x 690.0C | BUY 1x 695.0C
  Max Profit Price: $690.0
  Profit Zone: ~$685.0 - $695.0
```

### Calendar Spread

```
================================================================================
SPY — Calendar Spread (Debit)
================================================================================
Price: $681.27 | Score: 67.2/100 → PREPARE

[IV Term Structure +30.0/30]
  Front IV: 27.5% | Back IV: 19.4%
  Differential: +41.7%
  INVERTED TERM STRUCTURE — calendar opportunity confirmed

Strikes:
  Strike: $680.0
  SELL 2026-02-13 | BUY 2026-03-13
  Theta Advantage: Front IV > Back IV by 41.7%
```

## IV Rank Approximation

IV Rank is approximated using **Bollinger Bandwidth (BBW) percentile** over 252 trading days:

```
IV Rank ≈ (Current BBW - 52wk Low BBW) / (52wk High BBW - 52wk Low BBW) × 100
```

This correlation is well-documented: realized volatility (BBW) and implied volatility rank move with ~0.7-0.8 correlation (Sinclair, "Volatility Trading", 2013).

## IV Term Structure

For calendar spreads, the engine attempts to fetch live ATM implied volatility from Yahoo Finance options chains. If unavailable, it falls back to historical volatility term structure (HV 10-day vs HV 30-day) as a proxy.

## Quantitative Modules (v2.3.0)

The engine now includes four quantitative modules for rigorous strategy validation and optimization:

### 1. Regime Detector (`regime_detector.py`)

Market regime classification using VIX percentiles:
- **CRISIS**: VIX > 80th percentile — favors premium selling (iron condors)
- **HIGH_VOL**: VIX 60-80th — elevated IV benefits credit spreads
- **NORMAL**: VIX 40-60th — balanced environment, all strategies viable
- **LOW_VOL**: VIX 20-40th — cheap options favor debit spreads
- **EUPHORIA**: VIX < 20th — momentum continues, mean reversion brewing

```bash
# Detect current regime
python3 scripts/regime_detector.py

# Get regime-adjusted weights for specific strategy
python3 scripts/regime_detector.py --strategy iron_condor --json
```

**Integration:**
```python
from regime_detector import RegimeDetector

detector = RegimeDetector()
regime, confidence = detector.detect_regime()
weights = detector.get_regime_weights(regime)
adjusted_score, reasoning = detector.regime_aware_score(75, regime, 'bull_put')
```

### 2. Volatility Forecaster (`vol_forecaster.py`)

GARCH-based realized volatility forecasting with VRP analysis:
- Fits GARCH(1,1) to historical returns
- Forecasts realized volatility over configurable horizon
- Calculates volatility risk premium (IV - RV forecast)
- Provides conviction adjustments based on VRP

```bash
# Analyze AAPL volatility
python3 scripts/vol_forecaster.py AAPL

# Compare IV = 25% vs forecast RV
python3 scripts/vol_forecaster.py SPY --iv 0.25 --horizon 5
```

**Interpretation:**
- VRP > 5%: Favorable for selling premium (credit spreads)
- VRP < -5%: Favorable for buying premium (debit spreads)
- VRP near 0: No volatility edge, focus on directional setup

**Integration:**
```python
from vol_forecaster import VolatilityForecaster

forecaster = VolatilityForecaster("AAPL")
params = forecaster.fit_garch()  # Returns omega, alpha, beta
forecast = forecaster.forecast_vol(horizon=5)
vrp, strength, rec = forecaster.vol_risk_premium(iv=0.25, rv_forecast=forecast.annualized_vol)
adjusted_score, reasoning = forecaster.add_to_conviction(70, vrp_signal, 'bull_put')
```

### 3. Enhanced Kelly Sizer (`enhanced_kelly.py`)

Drawdown-constrained, correlation-aware position sizing:
- Full Kelly criterion calculation
- Drawdown constraint: f_dd = f_kelly × (1 - target_dd / max_dd)
- Conviction-based Kelly scaling:
  - 90-100: Half Kelly
  - 80-89: Quarter Kelly
  - 60-79: Eighth Kelly
  - <60: No position
- Correlation penalty for portfolio context

```bash
# Calculate position with $390 account
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85

# Include correlation with existing position
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85 --correlation 0.3
```

**Integration:**
```python
from enhanced_kelly import EnhancedKellySizer

sizer = EnhancedKellySizer(account_value=390, max_drawdown=0.20)
result = sizer.calculate_position(
    spread_cost=80,
    max_loss=80,
    win_amount=40,
    conviction=85,
    pop=0.65,
    existing_correlation=0.0
)
# Returns: contracts, total_risk, kelly_fraction, recommendation
```

### 4. Backtest Validator (`backtest_validator.py`)

Walk-forward validation of conviction scores:
- Simulates historical trades across ticker universe
- Validates tier separation (EXECUTE vs WAIT performance)
- Statistical tests (t-tests, ANOVA)
- Tier separation scoring (0-1)
- Weight calibration suggestions

```bash
# Backtest bull_put on AAPL, MSFT, SPY (2022-2024)
python3 scripts/backtest_validator.py --tickers AAPL MSFT SPY --start 2022-01-01 --end 2024-01-01 --strategy bull_put

# JSON outp...