Sixian-Li / plain-backtest

# PlainBacktest
**English** | 中文
**Say It Simply, Test It Properly.**
Describe your trading strategy in everyday language. PlainBacktest works with your coding agent to turn it into explicit rules, run the backtest, and reconcile orders and daily account balances against an independent ledger. Explicit execution timing, recorded data and code hashes, and reproducible reports make the calculation open to inspection.
Source code and bundled data: Sixian-Li/plainbacktest.
 [code] 
Your agent interprets the strategy and implements its rules; the Python framework handles reproducible calculation and validation. The repository includes three Skills, curated local data, research code, and 83 experiment definitions. Start with an offline example, then use your agent to continue the research.
## Run your first example
Clone the repository and run the following commands. The verified environment is macOS with Python 3.13. Installing dependencies requires an internet connection; running the example needs no market-data API, credentials, or live data.
 [code] 
Open the `outputs/example_…/report.html` path printed at the end. Each execution creates a new directory containing the input data, frozen rules, daily account state, orders, metrics, code and data hashes, and reconciliation results.
The default example uses QQQ from 2016-01-01 through 2026-08-04. It holds QQQ when SMA20 is above SMA100 and stays in cash otherwise. Signals are confirmed at the close and executed at the next session's open, with a cost of 5 bps per side. Initial capital is $100,000; fractional shares are allowed, with no leverage. The example uses the framework's PyBroker execution engine, independent ledger, and v5 report template.
Change the parameters or choose another approved symbol:
 [code] 
This exploratory example checks installation, execution, and reconciliation. It does not mark existing experiments as validated or replace parameter robustness and out-of-sample analysis. Moving averages use earlier history for warmup. Adjusted OHLC prices approximate total returns without modeling individual cash dividend payments.
## Research with natural language
Open this directory with an agent that supports project Skills. Have it read AGENTS.md, then describe a strategy. For example:
> Use quant-backtest to study QQQ with an SMA20/SMA100 rule. If the fast SMA is above the slow SMA at the close, hold a fully invested position from the next session's open; otherwise, exit to cash. Define the data range, costs, warmup, and benchmark before implementing the strategy, reconciling the ledgers, and explaining the results.
The project overview and quickstart are available in English and Chinese. Detailed research documents and report text are currently mainly in Chinese.
All three Skills are versioned with the repository, each with a `SKILL.md` entry point:
| Skill | Purpose |
| --- | --- |
| quant-backtest | Turn a strategy description into an experiment, execution, independent reconciliation,