# cutebacktests

`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](https://github.com/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](/docs/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

```bash
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:

```bash
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:

```bash
python -m cutebacktests.cli --help
```

Run the intraday/options backtester:

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

Run a named opening-range profile:

```bash
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.

| Old private name | Public name |
|---|---|
| `capcopy.backtest.reddit_intraday` | `cutebacktests.backtest.intraday_options` |
| `capcopy.strategy.reddit_intraday` | `cutebacktests.strategies.intraday` |
| `RedditIntradayBacktestConfig` | `IntradayOptionsBacktestConfig` |
| `RedditIntradayOptionBacktester` | `IntradayOptionsBacktester` |
| `RedditIntradaySignalConfig` | `IntradayStrategyConfig` |
| `to_reddit_intraday_kwargs()` | `to_intraday_strategy_kwargs()` |

## Python Example

```python
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.