Equity Options Volatility & Risk Engine

Quantitative Python engine for pricing, implied volatility analysis, volatility surface construction, risk measurement, mispricing detection, and simple backtesting for equity options.

What it includes

• Data ingestion with two providers:
  • synthetic for deterministic local development
  • yahoo via yfinance when optional market-data dependencies are installed
  • alpha_vantage for historical options chains on specific dates when an API key is available
  • csv for local historical vendor exports or manually supplied datasets
• Pricing models:
  • Black-Scholes
  • Binomial tree
  • Heston stochastic volatility model
• Implied volatility solver using Newton-Raphson with bisection fallback
• Volatility surface builder from contract-level IV observations
• Greeks and portfolio-level risk aggregation
• Heston calibration against observed option prices
• Mispricing detection engine with ranked trade signals
• Backtesting module for convergence-style signal evaluation
• CLI entrypoint for running the full workflow end-to-end

Project structure

src/equity_options_engine/
  cli.py
  pipeline.py
  models.py
  implied_vol.py
  surface.py
  calibration.py
  signals.py
  portfolio.py
  backtest.py
  data/providers.py
  pricing/
    black_scholes.py
    binomial.py
    heston.py

Quickstart

Create a virtual environment and install the package:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

To enable Yahoo Finance ingestion as well:

pip install -e ".[market-data]"

Run the full engine with synthetic market data:

eovre --symbol SPY --source synthetic

Print JSON output:

eovre --symbol AAPL --source synthetic --json

Try Yahoo Finance data when dependencies are available:

eovre --symbol SPY --source yahoo

Run a historical stress-period pricing study with local CSV data:

eovre study --source csv --csv-path data/your_historical_options.csv --covid-2020 --symbols SPY AAPL MSFT QQQ IWM

CSV columns expected by the engine are shown in historical_options_template.csv. Minimum useful fields per row are:

• quote_date
• underlying
• underlying_price
• expiration
• option_type
• strike
• bid
• ask
• last

If available, also include:

• implied_volatility
• volume
• open_interest
• risk_free_rate
• dividend_yield

The predefined --covid-2020 study uses these exact stress-session dates:

2020-02-24, 2020-02-27, 2020-03-09, 2020-03-12, 2020-03-16, 2020-03-18, 2020-03-20, 2020-03-23, 2020-03-24, 2020-03-26, 2020-04-01, 2020-04-06

Workflow

The full pipeline in pipeline.py performs the following steps:

1. Load an options chain and underlying spot snapshot.
2. Solve implied volatility for each option contract.
3. Build an interpolated implied volatility surface.
4. Calibrate Heston parameters to market option prices.
5. Reprice the chain with the calibrated model.
6. Flag mispricings above a threshold.
7. Aggregate portfolio Greeks for the top signals.
8. Run a simple convergence-style backtest.

The historical study mode additionally:

1. Pulls full historical chains for each requested symbol/date.
2. Filters invalid contracts and counts total coverage.
3. Prices each contract with Black-Scholes, binomial, and Heston-style models.
4. Compares model prices with observed market prices.
5. Reports MAE, RMSE, MAPE, and the share of contracts priced within 5% and 10%.

Testing

Run the smoke tests with:

python3 -m pytest

Notes

• The synthetic provider makes the project runnable without API keys or internet access.
• Alpha Vantage's historical options endpoint is a premium API, so the most practical route is often importing a reputable vendor CSV instead.
• The file at data/historical_options_template.csv is only a schema template, not real market data.
• The Heston implementation is designed for research and prototyping rather than low-latency production trading.
• The backtest is intentionally simple and should be extended with transaction costs, liquidity filters, holding rules, and risk limits before real use.