optopsy

optopsy

AI enabled options backtesting library for Python

Stars: 1262

Visit
 screenshot

Optopsy is a fast, flexible backtesting library for options strategies in Python. It helps users generate comprehensive performance statistics from historical options data to answer questions like 'How do iron condors perform on SPX?' or 'What delta range produces the best results for covered calls?' The library features an AI Chat UI for natural language interaction, a trade simulator for full trade-by-trade simulation, 28 built-in strategies, live data providers, smart caching, entry signals with TA indicators, and returns DataFrames that integrate with existing workflows.

README:

uv Ruff ty CI PyPI version Downloads Python

Optopsy

A fast, flexible backtesting library for options strategies in Python.

Optopsy helps you answer questions like "How do iron condors perform on SPX?" or "What delta range produces the best results for covered calls?" by generating comprehensive performance statistics from historical options data.

Full Documentation | API Reference | Examples

Features

  • AI Chat UI - Run backtests, fetch data, and interpret results using natural language
  • Trade Simulator - Full trade-by-trade simulation with capital tracking, equity curves, and performance metrics
  • 28 Built-in Strategies - From simple calls/puts to iron condors, butterflies, calendars, and diagonals
  • Live Data Providers - Fetch options chains and stock prices directly from supported data sources (e.g. EODHD)
  • Smart Caching - Automatic local caching of fetched data with gap detection for efficient re-fetches
  • Entry Signals - Filter entries with TA indicators (RSI, MACD, Bollinger Bands, EMA, ATR) via pandas-ta
  • Pandas Native - Returns DataFrames that integrate with your existing workflow

AI Chat UI (Beta)

An AI-powered chat interface that lets you fetch data, run backtests, and interpret results using natural language.

AI Chat UI

Setup & Configuration

Install the beta pre-release with the ui extra:

pip install --pre optopsy[ui]

Configure your environment variables in a .env file at the project root (the app auto-loads it):

ANTHROPIC_API_KEY=sk-ant-...       # or OPENAI_API_KEY for OpenAI models
EODHD_API_KEY=your-key-here        # enables live data downloads (optional)
OPTOPSY_MODEL=anthropic/claude-haiku-4-5-20251001  # override the default model (optional)

At minimum you need an LLM API key (ANTHROPIC_API_KEY or OPENAI_API_KEY). Set EODHD_API_KEY to enable downloading historical options data directly from EODHD. The OPTOPSY_MODEL variable accepts any LiteLLM model string if you want to use a different model.

Downloading Data

The recommended workflow is to download data first via the CLI, then use the chat agent to analyze it:

# Download historical options data (requires EODHD_API_KEY)
optopsy-chat download SPY
optopsy-chat download SPY AAPL TSLA    # multiple symbols
optopsy-chat download SPY -v           # verbose/debug output

Note: If developing with uv, prefix commands with uv run (e.g., uv run optopsy-chat download SPY).

Data is stored locally as Parquet files at ~/.optopsy/cache/. Re-running the download command only fetches new data since your last download — it won't re-download what you already have. A Rich progress display shows download progress in the terminal.

Once downloaded, the chat agent can query this data instantly without needing to re-fetch. Stock price history (via yfinance) is also cached locally and fetched automatically when the agent needs it for charting or signal analysis — no manual download required.

Cache Management

optopsy-chat cache size              # show per-symbol disk usage
optopsy-chat cache clear             # clear all cached data
optopsy-chat cache clear SPY         # clear specific symbol

Launching the Chat

optopsy-chat                         # launch (opens browser)
optopsy-chat run --port 9000         # custom port
optopsy-chat run --headless          # don't open browser
optopsy-chat run --debug             # enable debug logging

What the Agent Can Do

  • Run any of the 28 strategies — ask in plain English (e.g. "Run iron condors on SPY with 30-45 DTE") and the agent picks the right function and parameters
  • Fetch live options data — pull options chains from EODHD and cache them locally for fast repeat access
  • Fetch stock price history — automatically download OHLCV data via yfinance for charting and signal analysis
  • Load & preview CSV data — drag-and-drop a CSV into the chat or point to a file on disk; inspect shape, columns, date ranges, and sample rows
  • Scan & compare strategies — run up to 50 strategy/parameter combinations in one call and get a ranked leaderboard
  • Suggest parameters — analyze your dataset's DTE and OTM% distributions and recommend sensible starting ranges
  • Build entry/exit signals — compose technical analysis signals (RSI, MACD, Bollinger Bands, EMA crossovers, SMA, ATR, day-of-week) with AND/OR logic
  • Simulate trades — run chronological simulations with starting capital, position limits, and a full equity curve with metrics (win rate, profit factor, max drawdown, etc.)
  • Create interactive charts — generate Plotly charts (line, bar, scatter, histogram, heatmap, candlestick with indicator overlays) from results, simulations, or raw data
  • Multi-dataset sessions — load multiple symbols, run the same strategy across each, and compare side-by-side
  • Session memory — the agent tracks all strategy runs and results so it can reference prior analysis without re-running

Data Providers

EODHD is the built-in data provider for downloading historical options and stock data. The provider system is pluggable — you can build custom providers by subclassing DataProvider in optopsy/ui/providers/ to integrate your own data sources.

See the Chat UI documentation for more details.

Installation

# Core library only (latest stable release)
pip install optopsy

# With AI Chat UI (beta — requires pre-release)
pip install --pre optopsy[ui]

Requirements: Python 3.12-3.13, Pandas 2.0+, NumPy 1.26+

Core Library Quick Start

import optopsy as op

# Load your options data
data = op.csv_data(
    "options_data.csv",
    underlying_symbol=0,
    underlying_price=1,
    option_type=2,
    expiration=3,
    quote_date=4,
    strike=5,
    bid=6,
    ask=7,
)

# Backtest long calls and get performance statistics
results = op.long_calls(data)
print(results)

Output:

   dte_range    otm_pct_range  count   mean    std    min    25%    50%    75%    max
0    (0, 7]   (-0.05, -0.0]    505   0.64   1.03  -1.00   0.14   0.37   0.87   7.62
1    (0, 7]    (-0.0, 0.05]    269   2.34   8.65  -1.00  -1.00  -0.89   1.16  68.00
2   (7, 14]   (-0.05, -0.0]    404   1.02   0.68  -0.46   0.58   0.86   1.32   4.40
...

Results are grouped by DTE (days to expiration) and OTM% (out-of-the-money percentage), showing descriptive statistics for percentage returns.

Simulator

Run a full trade-by-trade simulation with capital tracking, position limits, and performance metrics:

result = op.simulate(
    data,
    op.long_calls,
    capital=100_000,
    quantity=1,
    max_positions=1,
    selector="nearest",       # "nearest", "highest_premium", "lowest_premium", or custom callable
    max_entry_dte=45,
    exit_dte=14,
)

print(result.summary)         # win rate, profit factor, max drawdown, etc.
print(result.trade_log)       # per-trade P&L, entry/exit dates, equity
print(result.equity_curve)    # portfolio value over time

The simulator works with all 28 strategies. It selects one trade per entry date, enforces concurrent position limits, and computes a full equity curve with metrics like win rate, profit factor, max drawdown, and average days in trade.

Supported Strategies

Category Strategies
Single Leg long_calls, short_calls, long_puts, short_puts
Straddles/Strangles long_straddles, short_straddles, long_strangles, short_strangles
Vertical Spreads long_call_spread, short_call_spread, long_put_spread, short_put_spread
Butterflies long_call_butterfly, short_call_butterfly, long_put_butterfly, short_put_butterfly
Iron Condors iron_condor, reverse_iron_condor
Iron Butterflies iron_butterfly, reverse_iron_butterfly
Covered covered_call, protective_put
Calendar Spreads long_call_calendar, short_call_calendar, long_put_calendar, short_put_calendar
Diagonal Spreads long_call_diagonal, short_call_diagonal, long_put_diagonal, short_put_diagonal

Documentation

Star History

Star History Chart

Disclaimer

Optopsy is intended for research and educational purposes only. Backtest results are based on historical data and simplified assumptions — they do not account for all real-world factors such as liquidity constraints, execution slippage, assignment risk, or changing market conditions. Past performance is not indicative of future results. Always perform your own due diligence before making any trading decisions.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for optopsy

Similar Open Source Tools

For similar tasks

For similar jobs