Research backtesting engine for testing simple trading hypotheses with transaction costs, risk metrics, walk-forward evaluation, and QA checks that guard against look-ahead bias. This is a research and engineering project, not a live trading system.
This project focuses on the engineering discipline behind financial research: deterministic data loading, strategy interfaces, transaction-cost accounting, reproducible experiments, and honest risk reporting before any result is presented as evidence.
- CSV market-data loader with deterministic validation
- Mean-reversion and momentum strategy implementations
- Transaction-cost and slippage model
- Portfolio equity curve generation
- Sharpe ratio, volatility, max drawdown, hit rate, and turnover metrics
- Walk-forward train/test evaluation framing
- Monte Carlo-style return sensitivity report
- Deterministic limit-order-book demo with price-time matching
- CLI subcommands for run, evaluate, validate, and report generation
- Markdown research reports and evaluation workflow guide
- Unit tests for execution accounting and no-lookahead behavior
- Real FRED S&P 500 data pipeline with saved report evidence
- GitHub Actions CI workflow
| Layer | Tools |
|---|---|
| Core engine | Python, dataclasses, typed strategy interfaces |
| Data | CSV loader, deterministic validation reports, FRED SP500 pipeline |
| Research | strategy registry, walk-forward train/test split, Monte Carlo-style sensitivity |
| Market structure | limit order book, price-time priority, partial-fill accounting |
| Risk | Sharpe ratio, volatility, drawdown, hit rate, turnover, cost accounting |
| Quality | unittest, no-lookahead tests, product demo, evaluation demo, GitHub Actions |
flowchart LR
A["Fetch FRED SP500 CSV"] --> B["Validate ordered price bars"]
B --> C["Generate mean-reversion signals"]
C --> D["Apply transaction costs"]
D --> E["Build equity curve"]
E --> F["Compute risk metrics"]
F --> G["Run walk-forward evaluation"]
G --> H["Write reports/evaluation_demo.json"]
H --> I["CI verifies tests and demo"]
flowchart TB
Data["Historical CSV data"] --> Loader["Market data loader"]
Loader --> Strategy["Strategy interface"]
Strategy --> Engine["Backtest engine"]
Costs["Transaction cost model"] --> Engine
Engine --> Metrics["Risk metrics"]
Engine --> WalkForward["Walk-forward evaluator"]
WalkForward --> Report["JSON evidence report"]
Tests["Unit tests"] --> Engine
Tests --> WalkForward
Run these commands to validate the input data, execute two simple strategy paths, generate reports, process real FRED market data, and exercise the order-book demo. Outputs are historical research evidence, not live trading performance.
python -m src.backtester.cli validate --prices examples/research_prices.csv --report reports/data_validation.json
python -m src.backtester.cli run --prices examples/research_prices.csv --strategy mean-reversion --window 5 --z-entry 1.0 --report reports/product_backtest.json --markdown-report reports/research_report.md
python -m src.backtester.cli run --prices examples/research_prices.csv --strategy momentum --fast-window 4 --slow-window 12 --report reports/second_strategy_report.json
python scripts/real_market_pipeline.py --series-id SP500 --start-date 2023-01-01 --end-date 2024-12-31
python scripts/order_book_demo.py
python scripts/product_demo.pyEvidence map:
| Area | Feature | Evidence |
|---|---|---|
| Data quality | Ordered CSV validation with issue reporting | reports/data_validation.json |
| Strategy engine | Mean-reversion and momentum strategy paths | reports/product_backtest.json, reports/second_strategy_report.json |
| Research reporting | JSON and Markdown report generation | reports/research_report.md |
| Risk metrics | Sharpe, volatility, max drawdown, hit rate, turnover | reports/real_market_pipeline.json |
| Cost modeling | Transaction-cost accounting in equity curve | reports/product_backtest.json |
| Evaluation discipline | Walk-forward train/test split | reports/evaluation_demo.json |
| Robustness check | Monte Carlo-style return sensitivity | reports/real_market_pipeline.json |
| Market structure | Limit-order matching with price-time priority | reports/order_book_demo.json |
Implementation notes:
- Built a typed Python backtesting engine with strategy interfaces, portfolio accounting, transaction costs, and deterministic report output.
- Added no-lookahead tests and validation gates so research outputs are checked before metrics are discussed.
- Processed 502 real FRED S&P 500 daily observations with 109 trade events and 250 return-sensitivity simulations.
- Reported risk metrics with explicit caveats; the outputs are not investment advice or live performance records.
Run the keyless real-data pipeline:
python scripts/real_market_pipeline.py --series-id SP500 --start-date 2023-01-01 --end-date 2024-12-31 --window 20 --z-entry 1.5Latest measured report: reports/real_market_pipeline.json.
| Measurement | Value |
|---|---|
| Source | FRED SP500 daily observations |
| Bars processed | 502 |
| Compute time | 0.2375 seconds |
| Throughput | 2113.59 bars/second |
| Trade events | 109 |
| Total transaction cost | 106.053154 |
| Walk-forward test total return | 0.00363281 |
| Walk-forward test max drawdown | -0.00308047 |
These are engineering measurements from a local research run. Live-trading, alpha, production PnL, and investment-performance statements require separate infrastructure, risk controls, and verified trading records.
Run the CLI on sample data:
python -m src.backtester.cli --prices examples/sample_prices.csv --window 5 --z-entry 1.0
python -m src.backtester.cli --prices examples/sample_prices.csv --window 5 --z-entry 1.0 --report reports/sample_report.json
python -m src.backtester.cli validate --prices examples/research_prices.csv --report reports/data_validation.json
python -m src.backtester.cli run --prices examples/research_prices.csv --strategy mean-reversion --window 5 --z-entry 1.0 --report reports/product_backtest.json --markdown-report reports/research_report.md
python -m src.backtester.cli run --prices examples/research_prices.csv --strategy momentum --fast-window 4 --slow-window 12 --report reports/second_strategy_report.jsonRun demos and tests:
python scripts/evaluation_demo.py
python scripts/product_demo.py
python scripts/real_market_pipeline.py --series-id SP500 --start-date 2023-01-01 --end-date 2024-12-31
python scripts/order_book_demo.py
python -m unittest discover -s testsdocs/qa_ci.md: test strategy, CI checks, and quality gatesdocs/real_data_pipeline.md: source, measurement method, and claim boundarydocs/engineering_quality.md: completed engineering practices and evidence rulesdocs/research_evaluation_guide.md: evaluation workflow and claim boundarydocs/order_book.md: limit-order-book demo and claim boundary
This is historical research tooling with transaction-cost modeling, simple strategy interfaces, FRED S&P 500 ingestion, walk-forward evaluation, deterministic limit-order-book matching, and tests for accounting, price-time priority, and no-lookahead behavior. Live trading, profit, Sharpe superiority, and production trading ownership require separate infrastructure, risk controls, and verified trading records.