run-options-forecast

Forecasts a stock's close at option expiration using the Breeden-Litzenberger risk-neutral density extracted from the LSE options flow smile, then recommends options plays keyed off the confidence-interval bands.

Usage

python3 scripts/forecast_cli.py --ticker <TICKER> --expiry <YYYY-MM-DD>

Inputs:

If --expiry is omitted, the nearest expiry in the flow data is used.

Minimal example:

cd <skill-root>
python3 scripts/forecast_cli.py --ticker MU --expiry 2026-07-31

The CLI prints an input banner at the top of every run confirming what was parsed:

────────────────────────────────────────────────────────────────────────
  Usage:  forecast_cli.py --ticker <TICKER> --expiry <YYYY-MM-DD>
          e.g.  --ticker MU --expiry 2026-07-31
────────────────────────────────────────────────────────────────────────
  Input received:
    ticker:           MU
    expiry requested: 2026-07-31
    expiry resolved:  2026-07-31  (4d)
    ...

Self-contained. All scripts live in scripts/. Config and docs live at the skill root. Copy the directory to any machine and it works.

Driver: scripts/forecast_cli.py.

Layout:

run-options-forecast/
├── SKILL.md              ← this file
├── README.md             ← user-facing quickstart
├── requirements.txt      ← Python deps
├── .env.example          ← API key template (copy to .env)
└── scripts/
    ├── forecast_cli.py   ← primary CLI driver
    ├── expiration_model.py
    ├── lse_options.py
    ├── recommend_plays.py
    ├── visualize.py
    ├── run_analysis.py   ← dashboard CLI
    ├── ws_stream.py
    ├── run_streaming.py
    └── backtest.py

Prerequisites

Python 3.10+. From the skill root:

pip install -r requirements.txt
cp .env.example .env
# Edit .env and replace lse_live_REPLACE_ME with your real LSE API key

Run (agent path) — primary entry point

Run from the skill root (so .env is found and outputs land predictably):

cd <skill-root>
python3 scripts/forecast_cli.py --ticker MU --expiry 2026-07-31

Common invocations:

# Nearest expiry automatically
python3 scripts/forecast_cli.py --ticker MU

# Surface 5 plays instead of default 4
python3 scripts/forecast_cli.py --ticker MU --expiry 2026-09-18 --top-n 5

# Machine-readable output (for downstream tooling)
python3 scripts/forecast_cli.py --ticker MU --expiry 2026-09-18 --json --out /tmp/mu_forecast.json

# Override risk-free rate and dividend yield
python3 scripts/forecast_cli.py --ticker AAPL --expiry 2026-08-15 --rate 0.053 --dividend-yield 0.005

Required flag: --ticker SYMBOL Optional flags: --expiry YYYY-MM-DD (default: nearest), --top-n N (default 4), --json, --out PATH, --rate R, --dividend-yield Q, --realized-variance V

Exit codes: 0 = OK, 2 = missing deps or API key, 3 = LSE API error, 4 = no flow data, 5 = spot extraction failed, 6 = forecast failed.

What the report contains

The text output has three sections:

1. Header — spot, forward, ATM IV, 1σ expected move, DTE, 25Δ risk reversal
2. Risk-neutral close forecast — median, mean, Q(close > spot) + direction, then 50/80/95% CI bands with absolute ranges AND ±% distances from spot
3. Recommended options plays — top N strategies ranked by (PoP × R/R), each with:
   • Strategy name + bias (BULLISH / BEARISH / NEUTRAL / VOLATILE)
   • Net debit or credit, total per-contract dollar amount
   • Probability of Profit (risk-neutral) and reward-to-risk ratio
   • Each leg: BUY/SELL, qty, strike, type (CALL/PUT), approx BS price
   • Breakeven(s), max profit, max loss
   • Rationale tied to the forecast (CI band used, IV level, etc.)

Strategy universe: Bull Call Spread, Bull Put Spread, Bear Put Spread, Bear Call Spread, Iron Condor, Long Call Butterfly, Long Straddle. Strikes are anchored to CI quantiles (e.g. iron condor shorts at 80% CI bounds, wings at 95% CI bounds).

Run (human path) — full dashboard

cd <skill-root>
python3 scripts/run_analysis.py MU
open MU_dashboard.html

The dashboard (MU_dashboard.html) lands at the skill root. It includes the risk-neutral density plot with 50/80/95% CI bands, the CI ladder panel, GEX walls, premium walls, IV smile, and the signal breakdown.

Other entry points

# Live WebSocket stream (replays 24h, then live if market open)
python3 scripts/run_streaming.py MU --replay 4

# Backtest an expiry (requires realized close callback — see scripts/backtest.py)
python3 scripts/backtest.py --score-log

Gotchas

• Risk-neutral ≠ real-world. All PoP numbers come from the BL density, which is tilted by the variance risk premium. Real-world PoP is typically HIGHER for short-vol credit plays (condors, credit spreads) and LOWER for long-vol plays (straddle). Treat as a ranking tool, not a calibrated probability.
• LSE chain has no open interest field, only volume_today. GEX is therefore a volume-based proxy, not true OI-based dealer positioning.
• Historical flow for PCR z-scoring is sparse — some days return 0 rows. The engine skips empty days and z-scores against whatever history survives.
• Approximate option prices use ATM IV at grid strikes (not the full smile per-leg). Verify against live quotes before execution.
• 0-DTE expiries still work — T is floored to 1/365 to avoid div-by-zero. The CIs become narrow; this is correct behavior.
• Dividend-paying stocks: pass --dividend-yield. MU's annual yield is ~0.3-0.5%. The forward F = S · e^((r−q)T) adjusts accordingly.
• No-arb check: every report shows arb_status (OK or FAIL). If it fails (μ/F outside [0.97, 1.03]), the smile fit produced arbitrage — distrust the tails.
• SSL on macOS: LSEClient uses certifi to avoid the "unable to get local issuer certificate" error. If you skip pip install certifi you will hit SSL errors.
• Run from skill root, not scripts/: python-dotenv's load_dotenv() looks for .env in the cwd. If you cd scripts/ first, .env won't be found at the skill root and the API key will be missing.

Troubleshooting

Programmatic use

The driver is a thin wrapper. For custom workflows, add scripts/ to your path and import:

import sys
sys.path.insert(0, "scripts")

from lse_options import LSEClient, _latest_spot
from expiration_model import forecast_expiration
from recommend_plays import recommend_plays

client = LSEClient()
flow = client.options_flow("MU", limit=5000)
spot = _latest_spot(flow)
fc = forecast_expiration(flow, spot, target_expiry="2026-07-31")
plays = recommend_plays(fc, top_n=3)

print(f"Median close: ${fc.median:,.2f}")
print(f"Q(close > spot) = {fc.prob_above_spot:.1%}")
print(f"CI bands: 50% {fc.ci_50}, 80% {fc.ci_80}, 95% {fc.ci_95}")

The ExpirationForecast dataclass carries the full density (density_strikes, density_values) for custom integration.

Files in this skill