topstep-backtest 0.2.0__tar.gz → 0.2.2__tar.gz

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/AGENTS.md

@@ -729,7 +729,7 @@ order placement — the SDK is async and the `await`s ARE the live contract. Tra
 | `self.buy(size=2, sl=…, tp=…)` | `await self.buy(2, stop_loss_ticks=40, take_profit_ticks=80)` |
 | `stats = bt.run()` → 30-key Series | `report = bt.run()` → `Report` + `.stats`/`.result`/`.trades` |
 | `optimize()` | `metrics.optimize(...)` — but read §5.9 first; it keeps every trial on purpose |
-| `plot()` | `report.show()` — interactive HTML tearsheet (or `report.to_html(path)` to name the file) |
+| `plot()` | `report.show()` — interactive HTML tearsheet (`report.to_html(path)` to name the file; `bt.run_with_tearsheet(dir)` to get one from every run) |
 
 ## 8. Knobs — the calibration seam
 
@@ -816,8 +816,9 @@ breakdowns, higher fill tiers, an XFA rule set, and any holiday calendar.
 **Do** write code against these — they used to be on the list above and now ship: Monte-Carlo
 (§5.7), `optimize()` and the overfitting guards (§5.9), the sequential-Combine sweep (§5.8),
 the continuous-contract stitcher (§5.10), and the HTML tearsheet (`report.show()` /
-`report.to_html(path)`; `print(report)` remains the text render). Their signatures are in the
-generated table in §3.
+`report.to_html(path)` / `Backtest.run_with_tearsheet(dir)`, which writes a timestamped file
+per run; `print(report)` remains the text render). Their signatures are in the generated
+table in §3.
 
 Parity status, precisely: **structural** conformance is proven — a pyright-strict protocol
 conformance test plus a signature diff of `SimOrderApi.place` against the SDK's

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/CHANGELOG.md

@@ -6,6 +6,30 @@ below 1.0, minor releases may contain breaking changes.
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-08-16
+
+### Fixed
+
+- **The README claimed shipped subsystems do not exist.** Its status section told readers
+  there is "no walk-forward, no PBO/DSR overfitting guard, and no EV-per-attempt model" —
+  all three have shipped since 0.2.0 (`metrics/walkforward.py`, `metrics/overfitting.py`,
+  `metrics/economics.py`), and `docs/ROADMAP.md` and the site documented them correctly the
+  whole time. This is the rot the 0.2.0 doc pass fixed everywhere except the one file a new
+  reader opens first, and it was the package's PyPI project description. The bullet now keeps
+  the limitation that is still true — every analytic resamples the tape you supplied, so none
+  of them invents a regime your data never contained — without the false premise. The "Next:"
+  pointer drops the analytics that shipped and names what the roadmap actually lists as
+  remaining.
+- **The HTML tearsheet was missing from the README and from the site's "Reading the report"
+  page** — the headline feature of 0.2.0, absent from both places a reader looks for it. Both
+  now cover it, including `Backtest.run_with_tearsheet(dir)`, which was documented only in the
+  changelog and `examples/run_tearsheet.py`. `AGENTS.md` §7 and §11 pick it up too, and the
+  examples list in the README no longer omits `run_tearsheet.py`.
+- Version strings that describe the CURRENT state (README status, `docs/DESIGN.md`'s "proven
+  today", the captured provenance lines in the tutorial and `website/results.md`) said 0.1.0.
+  The 0.1.0 references that are historical — when the exchange calendar was removed, and why —
+  are left alone deliberately.
+
 ## [0.2.0] — 2026-08-16
 
 ### Added

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topstep-backtest
-Version: 0.2.0
+Version: 0.2.2
 Summary: Event-driven backtesting framework for Topstep Trading Combine strategies, with backtest/live parity against topstep-sdk.
 Author-email: Tarric Sookdeo <tarricsookdeo@outlook.com>
 License-Expression: MIT
@@ -160,6 +160,21 @@ silently is how a report lies:
   how to read every figure above. The same drawdown at 5% and at 95% exposure are not the same
   risk. Alongside `equity_peak` (what a trailing floor anchors to) and the run's window.
 
+The same report renders as an **interactive HTML tearsheet** — one self-contained file with
+no server and no network, so it opens offline and archives next to the run:
+
+```python
+report.to_html("tearsheet.html")  # name the file
+report.show()  # or write a temp file and open a browser
+```
+
+It draws the candlestick tape with every fill marked, the equity curve against the trailing
+MLL floor, daily P&L and the R-multiple distribution, plus every statistic the text render
+prints, basis labels included — the two renders share their formatting helpers, so they
+cannot disagree. For a sheet from *every* run without naming a file each time,
+`Backtest(...).run_with_tearsheet("runs")` writes `tearsheet-<UTC stamp>.html` and returns
+both the report and the path.
+
 Then stop trusting one sample:
 
 ```python
@@ -194,7 +209,7 @@ uv run python examples/run_montecarlo.py   # the same edge at two sizes, failing
 
 ## Status and limitations
 
-**Pre-alpha (0.1.0).** The engine core is well covered — exact-Decimal money on the tick
+**Pre-alpha (0.2.0).** The engine core is well covered — exact-Decimal money on the tick
 grid, FIFO lot accounting, a structurally enforced no-look-ahead firewall, byte-identical
 reruns — but read these before trusting a number:
 
@@ -205,10 +220,11 @@ reruns — but read these before trusting a number:
   landing within a tick or a fee of a limit. This applies with *more* force to the
   Monte-Carlo pass probability: a figure printed to one decimal from unverified constants is
   precise, not accurate.
-- **Analytics are single-run plus resampling.** There is no walk-forward, no PBO/DSR
-  overfitting guard, and no EV-per-attempt model. The Monte-Carlo resamples a strategy's own
-  observed days, so it cannot invent a market regime your tape never contained and will
-  understate tail risk on a short or single-regime sample.
+- **Analytics can only resample the tape you gave them.** Walk-forward, PBO, deflated Sharpe
+  and the EV-per-attempt model all ship (`metrics/walkforward.py`, `metrics/overfitting.py`,
+  `metrics/economics.py`), but none of them escapes your sample: the Monte-Carlo resamples a
+  strategy's own observed days, so it cannot invent a market regime your tape never contained
+  and will understate tail risk on a short or single-regime sample.
 - **No exchange holiday calendar ships with this package.** Bars on market holidays and
   past early-close halts are not detected, flagged or filtered anywhere — filter them
   upstream. (A built-in calendar was removed in 0.1.0: it disagreed with CME on several
@@ -252,8 +268,13 @@ built wheel into a clean venv and smoke-tests it. **`ruff format --check` is par
 
 There is a full documentation site — a browsable version of everything below, plus a
 quickstart, a page on reading the report, and an API reference generated from the live
-docstrings. The source repository is private, so it is **not hosted publicly**; build and
-read it locally from a checkout:
+docstrings:
+
+**<https://tarricsookdeo.github.io/topstep-backtest/>**
+
+It is rebuilt from `main` on every push. The site is public; the **source repository is
+not**, so there are no "Edit this page" links and there is no public issue tracker. To read
+it offline, or to preview a change before pushing it:
 
 ```bash
 uv run --extra docs mkdocs serve      # http://127.0.0.1:8000
@@ -275,13 +296,13 @@ environment. There is no public issue tracker.
   and a verify-before-trusting checklist.
 - `docs/DESIGN.md` — architecture contract, for *modifying* the framework.
 - `docs/ROADMAP.md` — what is built, partial, and not started. Next: **live adapter +
-  calibration** → remaining analytics (EV per attempt, PBO/DSR, walk-forward) → L1/L2/MBO
-  fill tiers; funded-account (XFA) modeling is deliberately parked.
+  calibration** → per-year / per-regime breakdowns → L1/L2/MBO fill tiers; funded-account
+  (XFA) modeling is deliberately parked.
 - `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict), `run_combine.py`
-  (synthetic end to end), `run_montecarlo.py` (outcome distribution + autopsy),
-  `run_windows.py` (a long tape replayed as consecutive independent Combine attempts),
-  `ema_cross.py`, `sma_cross.py`, `talib_macd.py`, `hand_wired.py` (what the facade
-  assembles).
+  (synthetic end to end), `run_tearsheet.py` (the same run as one HTML file),
+  `run_montecarlo.py` (outcome distribution + autopsy), `run_windows.py` (a long tape
+  replayed as consecutive independent Combine attempts), `ema_cross.py`, `sma_cross.py`,
+  `talib_macd.py`, `hand_wired.py` (what the facade assembles).
 
 ## Stack
 

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/README.md

@@ -120,6 +120,21 @@ silently is how a report lies:
   how to read every figure above. The same drawdown at 5% and at 95% exposure are not the same
   risk. Alongside `equity_peak` (what a trailing floor anchors to) and the run's window.
 
+The same report renders as an **interactive HTML tearsheet** — one self-contained file with
+no server and no network, so it opens offline and archives next to the run:
+
+```python
+report.to_html("tearsheet.html")  # name the file
+report.show()  # or write a temp file and open a browser
+```
+
+It draws the candlestick tape with every fill marked, the equity curve against the trailing
+MLL floor, daily P&L and the R-multiple distribution, plus every statistic the text render
+prints, basis labels included — the two renders share their formatting helpers, so they
+cannot disagree. For a sheet from *every* run without naming a file each time,
+`Backtest(...).run_with_tearsheet("runs")` writes `tearsheet-<UTC stamp>.html` and returns
+both the report and the path.
+
 Then stop trusting one sample:
 
 ```python
@@ -154,7 +169,7 @@ uv run python examples/run_montecarlo.py   # the same edge at two sizes, failing
 
 ## Status and limitations
 
-**Pre-alpha (0.1.0).** The engine core is well covered — exact-Decimal money on the tick
+**Pre-alpha (0.2.0).** The engine core is well covered — exact-Decimal money on the tick
 grid, FIFO lot accounting, a structurally enforced no-look-ahead firewall, byte-identical
 reruns — but read these before trusting a number:
 
@@ -165,10 +180,11 @@ reruns — but read these before trusting a number:
   landing within a tick or a fee of a limit. This applies with *more* force to the
   Monte-Carlo pass probability: a figure printed to one decimal from unverified constants is
   precise, not accurate.
-- **Analytics are single-run plus resampling.** There is no walk-forward, no PBO/DSR
-  overfitting guard, and no EV-per-attempt model. The Monte-Carlo resamples a strategy's own
-  observed days, so it cannot invent a market regime your tape never contained and will
-  understate tail risk on a short or single-regime sample.
+- **Analytics can only resample the tape you gave them.** Walk-forward, PBO, deflated Sharpe
+  and the EV-per-attempt model all ship (`metrics/walkforward.py`, `metrics/overfitting.py`,
+  `metrics/economics.py`), but none of them escapes your sample: the Monte-Carlo resamples a
+  strategy's own observed days, so it cannot invent a market regime your tape never contained
+  and will understate tail risk on a short or single-regime sample.
 - **No exchange holiday calendar ships with this package.** Bars on market holidays and
   past early-close halts are not detected, flagged or filtered anywhere — filter them
   upstream. (A built-in calendar was removed in 0.1.0: it disagreed with CME on several
@@ -212,8 +228,13 @@ built wheel into a clean venv and smoke-tests it. **`ruff format --check` is par
 
 There is a full documentation site — a browsable version of everything below, plus a
 quickstart, a page on reading the report, and an API reference generated from the live
-docstrings. The source repository is private, so it is **not hosted publicly**; build and
-read it locally from a checkout:
+docstrings:
+
+**<https://tarricsookdeo.github.io/topstep-backtest/>**
+
+It is rebuilt from `main` on every push. The site is public; the **source repository is
+not**, so there are no "Edit this page" links and there is no public issue tracker. To read
+it offline, or to preview a change before pushing it:
 
 ```bash
 uv run --extra docs mkdocs serve      # http://127.0.0.1:8000
@@ -235,13 +256,13 @@ environment. There is no public issue tracker.
   and a verify-before-trusting checklist.
 - `docs/DESIGN.md` — architecture contract, for *modifying* the framework.
 - `docs/ROADMAP.md` — what is built, partial, and not started. Next: **live adapter +
-  calibration** → remaining analytics (EV per attempt, PBO/DSR, walk-forward) → L1/L2/MBO
-  fill tiers; funded-account (XFA) modeling is deliberately parked.
+  calibration** → per-year / per-regime breakdowns → L1/L2/MBO fill tiers; funded-account
+  (XFA) modeling is deliberately parked.
 - `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict), `run_combine.py`
-  (synthetic end to end), `run_montecarlo.py` (outcome distribution + autopsy),
-  `run_windows.py` (a long tape replayed as consecutive independent Combine attempts),
-  `ema_cross.py`, `sma_cross.py`, `talib_macd.py`, `hand_wired.py` (what the facade
-  assembles).
+  (synthetic end to end), `run_tearsheet.py` (the same run as one HTML file),
+  `run_montecarlo.py` (outcome distribution + autopsy), `run_windows.py` (a long tape
+  replayed as consecutive independent Combine attempts), `ema_cross.py`, `sma_cross.py`,
+  `talib_macd.py`, `hand_wired.py` (what the facade assembles).
 
 ## Stack
 

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/docs/DESIGN.md

@@ -258,7 +258,7 @@ Violations are bugs, not style. Most are pinned by a named test.
    OHLCV bars are not the tape-built bars live produces. Require **Tier-1+ (quote/tick)
    validation** for any strategy whose edge is intrabar-timing-sensitive before trusting it live.
 
-> **What is actually proven today (0.1.0).** Rungs 1–4 hold: the sim constructs real SDK models,
+> **What is actually proven today (0.2.0).** Rungs 1–4 hold: the sim constructs real SDK models,
 > and `tests/parity/` asserts — pyright-strict *and* at runtime — that both `AsyncTopstepClient`
 > and `SimBroker` satisfy `Broker`, with a keyword-level signature diff on `place`. That is
 > **structural** conformance: same call surface, same types, same `APIError` codes. Rung 5 is

{topstep_backtest-0.2.0 → topstep_backtest-0.2.2}/docs/TUTORIAL_EMA_CROSSOVER.md

@@ -655,7 +655,7 @@ daily P&L  (6 closed: 1 win / 4 lose / 1 flat)
   best                  +84.04  (consistency ratio undefined: no net profit to share)
   stdev                 40.27   <- dollars, so it compares directly against the DLL
 
-topstep-backtest 0.1.0 — unofficial simulation, not affiliated with Topstep. Rule and fee constants are cited config, NOT calibrated against a live account (docs/topstep-rules.md §9): treat the verdict as a diagnostic, not an authoritative pass/fail.
+topstep-backtest 0.2.0 — unofficial simulation, not affiliated with Topstep. Rule and fee constants are cited config, NOT calibrated against a live account (docs/topstep-rules.md §9): treat the verdict as a diagnostic, not an authoritative pass/fail.
 ```
 
 Line by line:
@@ -681,7 +681,7 @@ Line by line:
   the rule and fee constants are not calibrated, so a screenshotted verdict
   carries its own caveat. The version is read from the installed distribution:
   this is the one line above that legitimately differs from your run (a source
-  checkout reports a `.devN` suffix, not `0.1.0`).
+  checkout reports a `.devN` suffix, not `0.2.0`).
 - **`REJECTED`** — *absent here, and its absence is information.* When the
   broker refuses any order placement the render grows a `REJECTED` line above
   the day trail, counting the refusals per gateway error code. Without it a