options-spread-conviction-engine

# 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 St...

# Options Spread Conviction Engine

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skill-green.svg)](https://clawhub.com)

**Multi-regime options spread analysis engine with Kelly Criterion Position Sizing, Multi-Leg Strategies, and Quantitative Scanning.**

A comprehensive scoring system for options traders that analyzes market conditions and provides actionable conviction scores (0-100) for seven strategies including vertical spreads, iron condors, butterflies, and calendar spreads. Features mathematically-rigorous Kelly criterion position sizing integrated directly into the conviction engine.

## 🎯 What It Does

Analyzes any stock ticker and scores **seven** options strategies across directional and non-directional setups:

| 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 |
| **iron_condor** | Credit | Premium Selling | IV Rank >70, range-bound |
| **butterfly** | Debit | Pinning Play | Vol compression, low trend |
| **calendar** | Debit | Theta Harvest | Inverted IV term structure |

### Key Features

- **Kelly Criterion Position Sizing**: Mathematically optimal position sizing based on edge, win probability, and account constraints. Half-Kelly default for options volatility, with 25% bankroll cap and full edge case handling.
- **Multi-Leg Strategy Support**: Iron condors, butterflies, and calendar spreads with IV term structure analysis.
- **Quantitative Scanners**: Monte Carlo POP simulation and expected value optimization.
- **Volume Multiplier**: Rewards breako...