Options Spread Conviction Engine

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

Install

CODEBLOCK0

Overview

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

Vertical Spreads (Directional)

Strategy	Type	Philosophy	Ideal Setup
bullput	Credit	Mean Reversion	Bullish trend + oversold dip
bearcall

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 (bullput, bearcall)

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 (bullcall, bearput)

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 (putlong, putshort, callshort, calllong)
• 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 (lowerlong, middleshort, 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

CODEBLOCK1

Multi-Leg Strategies

CODEBLOCK2

Multiple Tickers

CODEBLOCK3

JSON Output (for automation)

CODEBLOCK4

Full Options

CODEBLOCK5

Example Outputs

Iron Condor

CODEBLOCK6

Butterfly

CODEBLOCK7

Calendar Spread

CODEBLOCK8

IV Rank Approximation

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

CODEBLOCK9

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)
• HIGHVOL: VIX 60-80th — elevated IV benefits credit spreads
• NORMAL: VIX 40-60th — balanced environment, all strategies viable
• LOWVOL: VIX 20-40th — cheap options favor debit spreads
• EUPHORIA: VIX < 20th — momentum continues, mean reversion brewing

CODEBLOCK10

Integration:
CODEBLOCK11

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

CODEBLOCK12

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

3. Enhanced Kelly Sizer (enhanced_kelly.py)

Drawdown-constrained, correlation-aware position sizing:

• - Full Kelly criterion calculation
• Drawdown constraint: fdd = fkelly × (1 - targetdd / maxdd)
• Conviction-based Kelly scaling:

- 90-100: Half Kelly
- 80-89: Quarter Kelly
- 60-79: Eighth Kelly
- <60: No position

• - Correlation penalty for portfolio context

CODEBLOCK14

Integration:
CODEBLOCK15

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

CODEBLOCK16

Output Metrics:

• - Win rate per tier
• Expectancy per tier: (winrate × avgwin) - (lossrate × avgloss)
• Sharpe ratio per tier
• P-values for tier differences
• Separation score (0-1, higher = better discrimination)

Integration:
CODEBLOCK17

5. Quantitative Integration (quantitative_integration.py)

Unified interface combining all quantitative modules:

CODEBLOCK18

Integration:
CODEBLOCK19

Academic Foundation

• - Ichimoku Cloud — Trend structure (Hosoda, 1968)
• RSI — Momentum oscillator (Wilder, 1978)
• MACD — Trend momentum (Appel, 1979)
• Bollinger Bands — Volatility envelopes (Bollinger, 2001)
• IV Rank / Term Structure — Options market microstructure (Sinclair, 2013)

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

Architecture

CODEBLOCK20

Module Separation

• - spreadconvictionengine.py: Vertical spreads, shared infrastructure (data fetching, indicator computation)
• multilegstrategies.py: Iron condors, butterflies, calendars (imports from main engine)
• quantitativeintegration.py: Unified interface for regime/vol/Kelly/backtest modules
• regimedetector.py: Market regime classification using VIX percentiles
• volforecaster.py: GARCH-based realized volatility forecasting
• enhancedkelly.py: Drawdown-constrained, correlation-aware position sizing
• backtest_validator.py: Walk-forward validation of conviction scores

This separation keeps concerns clean while avoiding duplication.

Limitations & Assumptions

IV Data

• - Yahoo Finance Limitations: Options chains may be unavailable after market hours or for low-volume tickers
• Fallback: Historical volatility (HV) proxy is less accurate than live IV but provides signal
• IV Rank: Approximated from BBW; actual IV Rank requires options chain data

Strike Selection

• - Approximation: Strikes derived from Bollinger Band levels (1-sigma / 2-sigma)
• Rounding: Rounded to standard option strike intervals based on stock price
• No Live Pricing: Does not fetch live option premiums; strike selection is structural, not value-optimized

Data Quality

• - Minimum 180 trading days required for full Ichimoku cloud population
• Multi-leg strategies require options chains (calendar spreads especially)
• After-hours analysis may have reduced data quality

Market Assumptions

• - Assumes normal options market conditions (not extreme volatility events)
• Strike intervals assume US equity options conventions
• Not tested on futures, commodities, or non-US markets

Requirements

• - Python 3.10+ (Python 3.14+ supported via pure-python mode)
• Isolated virtual environment (auto-created on first run)
• Internet connection (fetches data from Yahoo Finance)

Installation

CODEBLOCK21

The skill automatically creates a virtual environment and installs:

• - pandas >= 2.0
• pandas_ta >= 0.4.0 (pure Python mode on 3.14+)
• yfinance >= 1.0
• scipy, tqdm

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)

Automates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).

Features

• - Scans S&P 500, Nasdaq 100, or custom ticker lists.
• Filters for EXECUTE tier (conviction ≥80).
• Runs position sizing to ensure trades fit account guardrails.

Usage

CODEBLOCK22

2. Quantitative Scanner (quant_scanner.py)

A mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.

Features

• - IV Surface Analysis: Analyzes skew and term structure.
• Monte Carlo POP: 10,000-run simulations for true Probability of Profit.
• EV Optimization: Finds trades with the highest risk-adjusted mathematical expectancy.
• Account-Aware: Enforces small-account constraints ($100 max risk).

Usage

CODEBLOCK23

Calculator & Position Sizer

The integrated toolchain includes:

calculator.py

Black-Scholes options pricing with support for:

• - Single options: calls, puts
• Vertical spreads: bull call, bear put
• Multi-leg: iron condors, butterflies
• Greeks calculation (delta, gamma, theta, vega, rho)
• Monte Carlo POP simulation

position_sizer.py

Kelly criterion position sizing adapted for small accounts:

• - Full Kelly and fractional Kelly (default 0.25)
• Account guardrails ($390 default, $100 max risk)
• Trade screening and ranking
• Strike adjustment suggestions

CODEBLOCK24

Files

• - scripts/conviction-engine — Main CLI wrapper for conviction engine
• INLINECODE6 — Core engine (vertical spreads)
• INLINECODE7 — Multi-leg extensions (v2.0.0)
• INLINECODE8 — Automated market scanner for EXECUTE plays
• INLINECODE9 — Black-Scholes pricing, Greeks, Monte Carlo POP
• INLINECODE10 — Kelly criterion position sizing
• INLINECODE11 — Environment setup
• INLINECODE12 — S&P 500 constituents
• INLINECODE13 — Nasdaq 100 constituents
• INLINECODE14 — Documentation and examples

Version History

• - v2.3.0 (2026-02-13): Quantitative rigor upgrade

- Regime Detector: VIX-based market regime classification - Volatility Forecaster: GARCH-based RV forecasting with VRP analysis - Enhanced Kelly Sizer: Drawdown-constrained, correlation-aware position sizing - Backtest Validator: Walk-forward validation with tier separation testing - Quantitative Integration: Unified interface for all quantitative modules - Comprehensive unit test suite for all new modules

• - v2.2.0 (2026-02-13): Kelly Criterion position sizing with full/half Kelly, edge calculation, and account-aware contract sizing
• v2.1.0 (2026-02-12): Added market scanner, integrated calculator and position sizer
• v2.0.0 (2026-02-12): Added multi-leg strategies (iron condor, butterfly, calendar)
• v1.2.1 (2026-02-09): Volume multiplier, dynamic strike suggestions
• v1.1.0 (2026-02-08): Cross-signal weighting, multi-strategy support
• v1.0.0 (2026-02-07): Initial bull put spread engine

License

MIT — Part of the Financial Toolkit for OpenClaw