Research Docs

Read this page with Backtesting Framework, Options Backtesting API, Backtesting Execution Realism, Backtesting Test Plan, and Backtest Artifacts and Launch Contracts.

cutebacktests is the public backtesting library from CuteMarkets. It packages the reusable intraday/options runtime and the opening-range profile layer that power our public research, without exposing the internal orchestration and deployment code from the private research repo.

Repository

• GitHub: cutemarkets/cutebacktests
• License: MIT

Scope

Included in the public package:

• Intraday/options backtest runtime
• Opening-range profile registry and profile helpers
• CuteMarkets and Alpaca provider adapters used by the runtime
• Walk-forward robustness helpers

For the implementation principles behind the runtime, read the Backtesting Framework knowledge base. It explains the data model, replay loop, contract selector, execution realism layer, robustness workflow, and regression test plan that a realistic options framework should preserve.

Not included:

• Live or paper trading bots
• Azure launch scripts and server tooling
• Phase routing and dashboard code
• Congressional-disclosure and Dan Meuser research pipelines

Install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Environment

The public package uses package-local paths and reads market-data credentials from your environment:

export CUTEBACKTESTS_DATA_DIR=data
export CUTEBACKTESTS_DB_PATH=data/cutebacktests.duckdb
export POLYGON_API_KEY=...
export ALPACA_API_KEY=...
export ALPACA_SECRET_KEY=...

CLI

Show the public CLI:

python -m cutebacktests.cli --help

Run the intraday/options backtester:

python -m cutebacktests.cli run-intraday-options-backtest \
  --ticker SPY \
  --start 2025-01-01 \
  --end 2025-12-31

Run a named opening-range profile:

python -m cutebacktests.cli run-opening-range-profile-backtest \
  --profile-name c4_long_only_rr15 \
  --ticker SPY \
  --start 2025-01-01 \
  --end 2025-12-31

Renamed API Surface

The public extraction removes legacy reddit_* naming and exposes behavior-based modules instead.

Python Example

from datetime import datetime

from cutebacktests.backtest import IntradayOptionsBacktestConfig, IntradayOptionsBacktester
from cutebacktests.profiles import get_opening_range_profile

profile = get_opening_range_profile("c4_long_only_rr15")
config = IntradayOptionsBacktestConfig(
    ticker="SPY",
    start=datetime(2025, 1, 1),
    end=datetime(2025, 3, 31),
    **profile.to_intraday_strategy_kwargs(),
)

backtester = IntradayOptionsBacktester(...)
result = backtester.run(config)

Providers

cutebacktests is designed around:

• CuteMarkets for options and market-history retrieval
• Alpaca for shared market-data surfaces used by the runtime

The library is a research/backtesting package, not a live-trading product.

How it should be used

Use cutebacktests when you want a reproducible research harness rather than a one-off notebook. The package is designed to make strategy configuration, provider access, contract selection, execution assumptions, and result artifacts explicit. That structure is useful when a backtest needs to be reviewed later or compared against a paper-trading candidate.

The public package intentionally excludes deployment code and private research orchestration. That boundary keeps the library focused on repeatable local research: define a profile, run a backtest over a known date range, inspect the artifacts, and decide whether the setup deserves further validation. Live trading, production scheduling, and account operations should remain outside this package.

Reproducibility checklist

• Pin the package version or commit hash used for a research run.
• Store the strategy profile name and full resolved configuration.
• Record the market-data provider, date range, ticker, and option-selection rules.
• Preserve output artifacts instead of relying only on a final return metric.
• Re-run the same profile after dependency or data-provider changes.

The goal is more than a performance number. The run needs enough evidence that another developer can understand how the result was created and why the next experiment is different.

CuteBacktests implementation notes

CuteBacktests examples are most useful when they expose the evidence behind a number. Store the input ticker list, signal code version, contract-selection policy, quote-quality filters, fill model, portfolio settings, and report hash beside each run. If a user changes DTE, spread cap, quote age, or stop logic, create a new run record instead of overwriting the old one.

Use Backtesting Framework for structure and Backtesting Robustness for promotion discipline. A CuteBacktests result can be persuasive only when another developer can replay the contract universe, quote window, aggregate bars, and rejected candidates. The artifact matters because it turns a performance chart into a claim that can be challenged.

Additional implementation review

Review the research package run as a sequence of named data objects, not as a single helper call. The implementation should preserve profile name, resolved configuration, contract-selection policy, quote-quality filter, fill model, artifact hash, and provider version. Those fields make support tickets, CI fixtures, and replay notebooks easier to compare because every step can point to the exact request and response that created the displayed value.

The main failure mode is that a result can look reproducible while hiding a changed DTE rule, spread cap, cache file, or dependency version. Before promoting the workflow, run one concrete example through discovery, retrieval, display, logging, and error handling. Keep the resulting artifact beside the code path so future changes can prove they still use the same terminology and the same market-data assumptions.

That review should include the saved command and environment.