Options Spread Conviction Engine

Multi-regime options spread analysis engine with quantitative rigor. Features regime detection (VIX-based), GARCH volatility forecasting, drawdown-constrained Kelly position sizing, and walk-forward backtesting. Scores vertical spreads (bull put, bear call, bull call, bear put) and multi-leg strategies (iron condors, butterflies, calendar spreads) using Ichimoku, RSI, MACD, Bollinger Bands, and IV term structure analysis.

# 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 volat