Options Spread Conviction Engine

Options Spread Conviction Engine

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

Install

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)

Multi-Leg Strategies (Non-Directional / Theta)

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:

Strike Selection:

Output:

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

Strike Selection:

Output:

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

Data Sources:

Strike Selection:

Output:

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

# 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

# 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

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

JSON Output (for automation)

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

Full Options

conviction-engine  [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:

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

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:

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

Integration:

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:

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

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:

# 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 output for analysis
python3 scripts/backtest_validator.py --tickers SPY --json

Output Metrics:

Integration:

from backtest_validator import BacktestValidator
validator = BacktestValidator(engine, "2022-01-01", "2024-01-01")
results_df = validator.run_walk_forward(["AAPL", "MSFT"], hold_days=5)
report = validator.validate_tiers(results_df)
print(f"Separation score: {report.tier_separation_score:.2f}")
print(f"EXECUTE vs WAIT p-value: {report.p_values['execute_vs_wait']:.4f}")

5. Quantitative Integration (quantitative_integration.py)

Unified interface combining all quantitative modules:

# Full quantitative analysis with regime and VRP
python3 scripts/quantitative_integration.py AAPL --regime-aware --vol-aware
With Kelly sizing
python3 scripts/quantitative_integration.py SPY --regime-aware --pop 0.65 --max-loss 80 --win-amount 40
Run backtest validation
python3 scripts/quantitative_integration.py --backtest SPY QQQ --start 2022-01-01 --end 2024-01-01

Integration:

from quantitative_integration import QuantConvictionEngine
engine = QuantConvictionEngine(account_value=390, max_drawdown=0.20)
Analyze with regime and VRP adjustments
result = engine.analyze("AAPL", "bull_put", regime_aware=True, vol_aware=True)
print(f"Final score: {result.final_score}")
print(f"Regime: {result.regime}")
print(f"VRP: {result.vrp_signal.vrp if result.vrp_signal else 'N/A'}")
Calculate position size
sizing = engine.calculate_position(result, pop=0.65, max_loss=80, win_amount=40)
print(f"Contracts: {sizing['contracts']}")
Run backtest validation
report = engine.run_backtest(["SPY", "QQQ"], "2022-01-01", "2024-01-01")
print(f"Recommendation: {report.recommendation}")

Academic Foundation

Combining orthogonal signals reduces false-positive rate compared to single-indicator strategies (Pring, 2002; Murphy, 1999).

Architecture

conviction-engine/
├── scripts/
│   ├── conviction-engine              # CLI wrapper (bash)
│   ├── spread_conviction_engine.py    # Core engine (vertical spreads)
│   ├── multi_leg_strategies.py        # Multi-leg extensions
│   ├── quantitative_integration.py    # Unified quantitative interface
│   ├── regime_detector.py             # VIX-based regime classification
│   ├── vol_forecaster.py              # GARCH volatility forecasting
│   ├── enhanced_kelly.py              # Drawdown-constrained Kelly sizing
│   ├── backtest_validator.py          # Walk-forward validation
│   ├── quant_scanner.py               # Quantitative options scanner
│   ├── market_scanner.py              # Technical market scanner
│   ├── calculator.py                  # Black-Scholes & POP calculator
│   ├── position_sizer.py              # Kelly position sizing
│   ├── chain_analyzer.py              # IV surface analyzer
│   ├── options_math.py                # Core mathematical models
│   └── setup-venv.sh                  # Environment setup
├── tests/                             # Unit tests
│   ├── test_regime_detector.py
│   ├── test_vol_forecaster.py
│   ├── test_enhanced_kelly.py
│   ├── test_backtest_validator.py
│   └── run_tests.py
└── SKILL.md                           # This documentation

Module Separation

This separation keeps concerns clean while avoiding duplication.

Limitations & Assumptions

IV Data

Strike Selection

Data Quality

Market Assumptions

Requirements

Installation

clawhub install options-spread-conviction-engine

The skill automatically creates a virtual environment and installs:

Note: On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly.

Market Scanners

The engine includes two distinct scanning tools for different trading philosophies:

1. Technical Scanner (market_scanner.py)

#### Features

#### Usage

# Scan S&P 500 for high-conviction technical setups
python3 scripts/market_scanner.py --universe sp500

2. Quantitative Scanner (quant_scanner.py)

#### Features

#### Usage

# Maximize POP (Probability of Profit) for SPY
python3 scripts/quant_scanner.py SPY --mode pop
High-expectancy (EV) plays with specific DTE
python3 scripts/quant_scanner.py AAPL TSLA --mode ev --min-dte 30

Calculator & Position Sizer

The integrated toolchain includes:

calculator.py

position_sizer.py

from position_sizer import calculate_position
result = calculate_position(
    account_value=390,
    max_loss_per_spread=80,
    win_amount=40,
    pop=0.65,
)
Returns: contracts, total_risk, recommendation, reason

Files

Version History

License

MIT — Part of the Financial Toolkit for OpenClaw

Vertical Spreads

# 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

# 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

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

JSON Output (for automation)

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

Full Options

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