Backtest Integrity Guard

A small, dependency-free Python CLI for catching common integrity failures in quantitative backtests before performance metrics are trusted.

It focuses on causality, data integrity, explicit ambiguity handling, and reproducibility. It does not implement trading signals or ship market data.

Install

From PyPI

python -m pip install backtest-integrity-guard
btguard --help

From a GitHub release

The GitHub release includes a wheel, source archive, and SHA256SUMS for users who want to verify exact artifacts.

From source

git clone https://github.com/suguobin2021/backtest-integrity-guard.git
cd backtest-integrity-guard
python -m pip install -e .

Quick start

Audit ordinary OHLCV data:

btguard ohlcv examples/ohlcv.csv --hash-input

Audit vendor-specific column names:

btguard ohlcv examples/vendor.csv --map examples/schema.json

Check a 5-minute cadence while explicitly allowing a known session break:

btguard ohlcv examples/session_gap.csv \
  --interval-seconds 300 \
  --allow-gaps examples/allowed_gaps.json

Audit signal-to-execution timing:

btguard ledger examples/trades.csv --hash-input

Freeze and verify research inputs:

btguard freeze examples/ohlcv.csv examples/trades.csv -o manifest.json --root .
btguard verify manifest.json --root .

Commands exit non-zero when an integrity error is found, so they can be used in CI.

Output contract

Audit output is deterministic JSON with a stable report schema:

{
  "errors": 0,
  "findings": [],
  "input_sha256": "<64 hex chars>",
  "report_schema_version": "1.0",
  "status": "PASS",
  "tool_version": "0.2.2",
  "warnings": 0
}

Use --hash-input when a report should be bound to the exact audited file.

What it checks

• OHLC geometry and negative or invalid volume
• duplicate/conflicting and non-monotonic timestamps
• timezone-aware timestamps
• incomplete-bar markers
• configurable OHLCV schema aliases
• missing bars and irregular cadence
• explicitly allowlisted session gaps
• signal-close to execution ordering
• next-bar execution constraints
• same-bar stop/target ambiguity
• SHA256 frozen-input manifests
• deterministic machine-readable reports

Scope

Backtest Integrity Guard intentionally does not contain:

• trading signals or alpha logic
• brokerage execution code
• proprietary or licensed market data
• account credentials or API keys

The goal is to make research assumptions machine-checkable without depending on any particular strategy.

Contributing

See CONTRIBUTING.md. Bug reports should include the smallest synthetic example that reproduces the problem.

Useful project links:

• Issues
• Roadmap
• Changelog
• Releases

License

MIT.