options portfolio backtester

Abstract

Backtester for evaluating options and equity portfolio strategies over historical data. Includes tools for strategy sweeps, tail-risk hedge analysis, and signal-based timing research.

The Problem

Evaluating options‑and‑equity portfolio strategies over historical data demands a reproducible pipeline that handles realistic execution, Greeks‑aware risk, and tail‑risk hedging. The repo supplies those capabilities, but its module graph contains circular imports, oversized files, and deep nesting that make changes risky and hard to reason about.

What This Does

The package is a full‑stack backtester built around a Rust compute core (rust/ob_core) and Python orchestration (options_portfolio_backtester).

Data ingestion – options_portfolio_backtester/data/providers.py supplies HistoricalOptionsData and TiingoData; raw parquet/CSV is fetched with scripts/fetch_data.py.
Strategy construction – options_portfolio_backtester/strategy/strategy.py and strategy_leg.py let legs be added, filtered, and cleared; the canonical Spitznagel tail‑hedge leg is built with deep_otm_put.
Engine execution – options_portfolio_backtester/engine/engine.py (BacktestEngine) coordinates rebalancing, cost models (execution/cost_model.py), and risk checks (portfolio/risk.py).
Analysis & reporting – analytics/tearsheet.py and analytics/charts.py produce HTML reports, equity curves, and options‑specific panels from engine.balance and engine.trade_log.

A single run call (entry point options_portfolio_backtester/engine/engine.py:345) drives the backtest from data load through trade execution to results, reaching 28 internal functions.

How It Is Wired

Entry points – setup (test‑only, reaches 47 functions, called from nothing else), main in research/spitznagel_spy/experiments/cross_underlying.py:159 (reaches 148 functions, invoked once), and run in engine.py:345 (reaches 28 functions, called once).
Call graph – 3 239 resolved edges; the most‑connected symbols are _ctx (116 callers), from_balance (105), and BacktestEngine (70).
Hubs & cycles – options_portfolio_backtester/core/types is imported by 59 modules (instability 0); options_portfolio_backtester/engine/engine.py and options_portfolio_backtester/__init__.py form a circular‑import cycle.
Blast‑radius files – engine/engine.py (864 loc, 3 classes, 32 functions) and engine/pipeline.py (106 functions) are change‑propagation points; a modification ripples widely.
Outside‑process effects – execution paths can write CSV (to_csv), run external commands, make a single outbound network call (traced from main → to_csv), and perform a cryptographic operation.

How To Use It

Setup

# With Nix
nix develop

# Without Nix (Python ≥ 3.12)
python -m venv .venv && source .venv/bin/activate
make install-dev   # installs from pyproject.toml

Get data

python scripts/fetch_data.py all --symbols SPY
# pulls SPY options & underlying parquet into data/processed/

Run a first backtest (example from the README)

from options_portfolio_backtester import (
    BacktestEngine, Stock,
    HistoricalOptionsData, TiingoData,
    deep_otm_put,
)

options_data = HistoricalOptionsData("data/processed/options.parquet")
stocks_data  = TiingoData("data/processed/stocks.csv")

strategy = deep_otm_put(options_data.schema, "SPY")

engine = BacktestEngine({"stocks": 1.0, "options": 0.0, "cash": 0.0},
                        initial_capital=1_000_000)
engine.use_external_budget(annual_pct=0.005)
engine.stocks = [Stock("SPY", 1.0)]
engine.stocks_data = stocks_data
engine.options_data = options_data
engine.options_strategy = strategy
engine.run(rebalance_freq=1, rebalance_unit="BMS")

results = engine.get_results()
print(results.summary())
# {'annual_return': 13.5, 'max_drawdown': -46.4, 'sharpe': 0.72, 'trades': 327, ...}

Generate a tearsheet

from options_portfolio_backtester.analytics.tearsheet import build_tearsheet

report = build_tearsheet(
    engine.balance,
    budget_annual_pct=0.033,
    trade_log=engine.trade_log,
)
report.to_file("tearsheet.html")

Real‑World Use

A portfolio manager seeking a tail‑hedge can instantiate the Spitznagel leg (deep_otm_put) and allocate a small options budget (e.g., engine.use_allocation(stocks=0.99, options=0.01, cash=0.0)). The backtest then simulates monthly rebalancing, tracks premium spend against the budget, and produces a crash‑window P&L attribution—all within the same framework used for equity‑only sweeps.

Code Health & Issues

Measured analysis (static, 171 files): 66 issues across 7 categories

High/cognitive_load – deep nesting in engine/engine.py, strategy/strategy.py, portfolio/risk.py (max indent 8).
High/soundness – import‑cycle member in engine/engine.py & __init__.py.
High/clarity – hub module core/types (59 importers) and duplicated 6‑line blocks (173 repeats across 53 files).
Medium/resilience – broad except in engine/engine.py, analytics/results.py, analytics/tearsheet.py.
Medium/resource_safety – file opened without context manager in tests/engine/test_rust_parity.py.

Code‑health audit (8 findings, 0 critical):

HIGH – Pin GitHub Actions to commit SHA (.github/workflows, dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2).
HIGH – Commit lockfile beside pyproject.toml.
HIGH – Remove continue-on-error from correctness‑gating steps (.github/workflows/ci.yml:40).
MEDIUM – Declare least‑privilege permissions: contents: read for GITHUB_TOKEN.
MEDIUM – Enable Dependabot or Renovate (cover Python, Rust, GitHub‑Actions).
MEDIUM – Gate PRs on dependency vulnerability scan (add dependency-review-action).
MEDIUM – Set persist-credentials: false on checkout.
LOW – Add timeout-minutes to workflow jobs.

The Bottom Line

This repo delivers a capable, reproducible options‑backtesting platform with a Rust core and rich analytics, but its module interdependencies, oversized files, and circular imports raise maintenance risk. Teams that need fast strategy sweeps and tail‑risk hedging will find value here, provided they invest in cleaning the identified cycles and pinning CI dependencies.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

206 files

Python144
Rust27
Markdown13
TOML5
YAML1

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests<br/>89 modules"] g1["options_portfolio_back<br/>44 modules"] g2["research<br/>8 modules"] g3["scripts<br/>3 modules"] g0 -->|267| g1 g2 -->|18| g1

Module dependencies

The 10 most depended-upon modules of 144, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_tfolio_backtester_core_types["types"] n1_io_backtester_data_providers["providers"] n2_ktester_execution_cost_model["cost_model"] n3_tester_strategy_strategy_leg["strategy_leg"] n4_lio_backtester_engine_engine["engine"] n5_backtester_strategy_strategy["strategy"] n6_er_execution_signal_selector["signal_selector"] n7_ktester_execution_fill_model["fill_model"] n8_folio_backtester_data_schema["schema"] n9_ortfolio_backtester___init__["__init__"] n9_ortfolio_backtester___init__ --> n0_tfolio_backtester_core_types n9_ortfolio_backtester___init__ --> n8_folio_backtester_data_schema n9_ortfolio_backtester___init__ --> n1_io_backtester_data_providers n9_ortfolio_backtester___init__ --> n5_backtester_strategy_strategy n9_ortfolio_backtester___init__ --> n3_tester_strategy_strategy_leg n9_ortfolio_backtester___init__ --> n2_ktester_execution_cost_model n9_ortfolio_backtester___init__ --> n7_ktester_execution_fill_model n9_ortfolio_backtester___init__ --> n6_er_execution_signal_selector n9_ortfolio_backtester___init__ --> n4_lio_backtester_engine_engine n1_io_backtester_data_providers --> n8_folio_backtester_data_schema n4_lio_backtester_engine_engine --> n0_tfolio_backtester_core_types n4_lio_backtester_engine_engine --> n2_ktester_execution_cost_model n4_lio_backtester_engine_engine --> n7_ktester_execution_fill_model n4_lio_backtester_engine_engine --> n6_er_execution_signal_selector n4_lio_backtester_engine_engine --> n9_ortfolio_backtester___init__ n4_lio_backtester_engine_engine --> n1_io_backtester_data_providers n4_lio_backtester_engine_engine --> n8_folio_backtester_data_schema n4_lio_backtester_engine_engine --> n5_backtester_strategy_strategy classDef cyc stroke:#ef4444,stroke-width:2px; class n4_lio_backtester_engine_engine,n9_ortfolio_backtester___init__ cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/ci.yml

line 40 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.