topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest-0.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: topstep-backtest
+Version: 0.1.0
+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
+License-File: LICENSE
+Keywords: backtesting,combine,futures,prop-firm,topstep,trading
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: msgspec<1.0,>=0.18
+Requires-Dist: ta-lib<0.8,>=0.7.1
+Requires-Dist: topstep-sdk<0.2,>=0.1.2
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
+Provides-Extra: data
+Requires-Dist: pandas>=2.2; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pandas>=2.2; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# topstep-backtest
+
+An event-driven backtesting framework for developing futures strategies that can
+**profitably pass the Topstep Trading Combine**.
+
+Its defining property is **backtest/live parity** with the companion
+`topstep-sdk`: a strategy is written **once** against structural protocols that
+both the deterministic `SimBroker` *and* the live `AsyncTopstepClient` satisfy.
+Its core differentiator is a first-class **prop-firm rule engine**: the two-state
+trailing Maximum Loss Limit, optional Daily Loss Limit, consistency target,
+position caps, and session flatten are enforced *in real time* (including
+intrabar forced liquidation with adverse slippage), not scored after the fact.
+
+```python
+class SmaCross(SymbolStrategy):
+    def __init__(self, contract_id: str) -> None:
+        super().__init__(contract_id)
+        self.fast = self.use(Sma(20))  # TA-Lib, driven bar by bar, causal by construction
+        self.slow = self.use(Sma(50))
+        self.cross = self.use(Cross(self.fast, self.slow))
+
+    async def on_bar(self, bar: Bar) -> None:  # gated until every use()d indicator is ready
+        if self.cross.up and self.position.flat:
+            await self.buy(  # sugar over ctx.orders — the topstep-sdk surface
+                2,
+                stop_loss_ticks=40,
+                take_profit_ticks=80,  # signed-tick OCO bracket
+            )
+```
+
+## Install
+
+```bash
+pip install topstep-backtest
+pip install "topstep-backtest[data]"   # adds pandas, for DataFrame input
+```
+
+Requires Python 3.12+. TA-Lib is a core dependency and ships wheels for common
+platforms; on others you will need the TA-Lib C library first.
+
+```python
+from datetime import date
+from decimal import Decimal
+
+from topstep_backtest import AccountSize, Backtest, SymbolStrategy
+from topstep_backtest.core.instruments import spec_for_symbol
+from topstep_backtest.data.synthetic import synthetic_bars
+from topstep_backtest.indicators import Cross, Sma
+
+MNQ = "CON.F.US.MNQ.U26"
+
+
+class SmaCross(SymbolStrategy):
+    def __init__(self, contract_id: str) -> None:
+        super().__init__(contract_id)
+        self.fast = self.use(Sma(10))
+        self.slow = self.use(Sma(30))
+        self.cross = self.use(Cross(self.fast, self.slow))
+
+    async def on_bar(self, bar) -> None:
+        if self.cross.up and self.position.flat:
+            await self.buy(1, stop_loss_ticks=40, take_profit_ticks=80)
+        elif self.cross.down and self.position.is_long:
+            await self.close()
+
+
+bars = synthetic_bars(
+    contract_id=MNQ,
+    spec=spec_for_symbol("MNQ"),
+    start_day=date(2026, 5, 4),
+    days=5,
+    seed=7,
+    start_price=Decimal("23000.00"),
+    bars_per_day=120,
+    vol_ticks=12,
+)
+print(Backtest(bars, SmaCross(MNQ), account=AccountSize.S50K).run())
+```
+
+Feeding your own data (e.g. normalized Databento candles):
+
+```python
+from topstep_backtest.data.wrangler import bars_from_dataframe
+
+bars = bars_from_dataframe(
+    df,
+    contract_id="CON.F.US.MNQ.U26",
+    spec=spec,
+    unit=AggregateBarUnit.MINUTE,
+    unit_number=1,
+    stamp="open",
+)  # declare what your timestamps mean!
+```
+
+`bars_from_records` is the same loader without the pandas dependency.
+
+## Status and limitations
+
+**Pre-alpha (0.1.0).** The engine core is well covered — exact-Decimal money on
+the tick grid, FIFO lot accounting, a structurally enforced no-look-ahead
+firewall, and byte-identical reruns — but read these before trusting a number:
+
+- **The rule and fee constants are NOT calibrated against a live account.** They
+  are researched, source-cited config (docs/topstep-rules.md §9 has 8 unchecked
+  boxes). Treat a `PASSED`/`FAILED` verdict as a diagnostic, not an answer, and
+  distrust any result landing within a tick or a fee of a limit.
+- **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 dates a year and silently discarded tradable
+  sessions, which is worse than not having one.)
+- **One contract per run, inside a single front-month window.** There is no
+  continuous-contract stitching, and no roll detector. A multi-month export
+  spanning a quarterly roll is silently merged into one price series.
+- **Tier-0 bar fills only.** Market orders fill at the next bar's open and
+  default to zero slippage, so a strategy whose edge is thinner than roughly
+  8–10 ticks per round turn is inside the model's error bars. Event windows
+  (08:30 ET releases and the like) are not honestly modelled at bar resolution.
+- **Untested end to end:** multi-symbol runs, `dll_enabled=True`, and
+  non-quarter-tick products (CL, GC).
+
+What is proven is *structural* parity — pyright-strict conformance plus a
+signature-diff test against the live SDK. The behavioural gate (an intent-sequence
+test against a recording live broker) is **not built yet**; see docs/ROADMAP.md.
+
+## What works today
+
+- **Rule kernel** (`rules/`) — the canonical Topstep Combine rulebook: EOD-ratcheting
+  trailing MLL with permanent lock at the starting balance, real-time breach on
+  realized+unrealized equity, optional DLL (flatten-and-lock, not a fail),
+  consistency (`best_day ≤ 50% × total`), fixed 5/10/15-mini position caps —
+  golden-fixtured against the documented worked examples.
+- **Deterministic engine** (`engine/`, `clock/`) — single time-ordered loop,
+  `TestClock`, strict `ts_init` ordering assertions, bit-for-bit reproducible runs.
+- **SimBroker** (`execution/`) — full order lifecycle (market/limit/stop/trailing,
+  signed-tick OCO brackets), netting + exact-Decimal P&L, gateway-parity `APIError`
+  rejections tallied on the result, intrabar fill-vs-breach resolution along one
+  pessimistic price path, forced liquidation whose loss can exceed the floor.
+- **Tier-0 fills** (`fills/`) — pessimistic bar fills: adverse-extreme-first path,
+  next-bar-open for close signals, gap-through at the open, ≥1-tick stop slippage,
+  trade-through (not touch) limit fills; per-side/per-instrument Topstep fee stack,
+  correctable via `Backtest(..., fee_model=TopstepFees(overrides={...}))`.
+- **Data layer** (`data/`) — pandas/records → validated `Bar` streams (explicit
+  open/close stamping kills the off-by-one-bar look-ahead), tick-grid validation,
+  session/halt/weekend checks, deterministic synthetic generator.
+- **Indicators** (`indicators/`) — every indicator is TA-Lib: `TalibIndicator` drives 152 of
+  its 161 functions bar-by-bar (typed `Sma`/`Ema`/`Rsi`/`Atr`/`Macd`/`BBands`/… wrappers,
+  plus a pure-Python `Cross`), so no formula is re-implemented here to drift; the nine
+  refused are the ones that could only fail silently. Streaming values are bit-identical to a
+  batch run, and the bounded history window is a *parity* decision — preload `history_bars`
+  bars live and the live number equals the sim number. Parity begins at `warm` (the window is
+  full), not at `ready` (a value exists).
+- **Parity seam** (`protocols.py`) — pyright-strict conformance tests prove
+  `AsyncTopstepClient` and `SimBroker` satisfy the same `Broker` protocol, plus a
+  signature-diff test against the live SDK that fails the suite on drift.
+
+## Development
+
+From a checkout (the sibling `topstep-sdk` repo is expected at `../topstep-sdk`;
+set `UV_NO_SOURCES=1` to resolve it from PyPI instead):
+
+```bash
+uv sync --extra dev
+uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run pyright
+cd examples && uv run python run_combine.py   # end-to-end combine verdict
+```
+
+## Documentation
+
+The source repository is private, so there is no public issue tracker or docs
+site. Everything below ships **inside the sdist** — `pip download --no-binary
+:all: topstep-backtest` and unpack it, or read the copies in your environment.
+
+- **`docs/GUIDE.md` — start here**: the user guide (data in, writing strategies,
+  wiring runs, reading results, verification checklist).
+- `docs/TUTORIAL_EMA_CROSSOVER.md` — an in-depth walkthrough building one
+  strategy end to end.
+- `docs/STRATEGY_API.md` — the strategy dialect reference, including the
+  indicator surface.
+- `docs/topstep-rules.md` — the rulebook being enforced, with sources,
+  confidence levels, and a verify-before-trusting checklist.
+- `docs/DESIGN.md` — architecture contract (parity seam, no-look-ahead
+  invariants, fill tiers). Its §4 layout is the *target* architecture, not the
+  current tree.
+- `AGENTS.md` — dense maintainer/agent reference and the real module map.
+- `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict),
+  `run_combine.py` (synthetic end-to-end), `ema_cross.py`, `sma_cross.py`,
+  `talib_macd.py`.
+
+## Roadmap
+
+Analytics + Monte-Carlo pass-probability → live adapter + calibration → L1/L2/MBO
+fill tiers. Funded-account (XFA) modeling is deliberately parked. See
+`docs/ROADMAP.md` in the sdist.
+
+## Stack
+
+Python 3.12+ · `topstep-sdk` · `msgspec` · `TA-Lib` · `uv` · `ruff` · `pyright`
+(strict) · `pytest` + `hypothesis`. Canonical timezone: **ET** (`America/New_York`);
+internal hot path is int-ns UTC; all money is exact `Decimal` on the tick grid —
+indicator values cross from float64 into `Decimal` and are deliberately *not*
+tick-snapped (an indicator level is not a tradeable price).
+
+## License
+
+MIT — see LICENSE.
+
+> **Unofficial.** Not affiliated with, endorsed by, or sponsored by Topstep, LLC
+> or ProjectX Trading, LLC. "Topstep" is a trademark of its respective owner and
+> is used here only to identify the evaluation program this tool models. Rule
+> numbers researched July 2026 — re-verify against Topstep's help center before
+> trusting a pass verdict (see the checklist in docs/topstep-rules.md §9).
+>
+> **Not financial advice.** This software simulates a trading evaluation and can
+> be wrong. You are solely responsible for any capital you risk.

topstep_backtest-0.1.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+topstep_backtest/__init__.py,sha256=HIPZrU1l55a8MnwbbYV2cCv8W0rsBC8phNT4JXxC70o,1345
+topstep_backtest/harness.py,sha256=5EHYlPfZPI3elRAhlQowByJ20QSh9vrGdU9rPAH_PSU,18536
+topstep_backtest/protocols.py,sha256=JW3Rcc5FkmYlpDvdT2ggZlqTwK1LHzXSnRiomRxteuE,14496
+topstep_backtest/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+topstep_backtest/clock/__init__.py,sha256=-1bP9fiBx8mK5h7H2vvwaTrG7IUFSltphfbbq6bCASw,29
+topstep_backtest/clock/live_clock.py,sha256=Xu6bSftmpLU4s1vXTYJAUNk5wYJpLLXkhJM0wmLtdfs,2991
+topstep_backtest/clock/test_clock.py,sha256=t3mNe6mmkVvfPts-4x6pTu8ryQRL-_ykHBMUuT_9tx0,5232
+topstep_backtest/core/__init__.py,sha256=wZnQvx-BeE-p1W2iM-EdEesEL6uhDxJbL8OQfjxHNYY,28
+topstep_backtest/core/ids.py,sha256=x7OhTdHET3u7QBoQCNqq5dDuV9DECSdWewg5WjIjMaY,589
+topstep_backtest/core/instruments.py,sha256=IC90ZAjYSHJoDbIfTMObkStMsgyugFzZTwH675qeb-0,5913
+topstep_backtest/core/money.py,sha256=magYcXDi-6tfN1OuHa28e3Mq8hSlnN3cJj7Sh6CA6SY,5146
+topstep_backtest/core/time.py,sha256=qFUBfx3ERQopYqpMN7e1l9nVfOnj7CVamXa0FMwy5YM,4285
+topstep_backtest/data/__init__.py,sha256=VV89qwuA8bQjHYOKb9IZuZmKaxFjNBjs6N4OwP9cR60,28
+topstep_backtest/data/clean.py,sha256=RRhUAasPOC9-QIH2Djubtiws76wWuqEe3WIr980OTDg,3509
+topstep_backtest/data/feed.py,sha256=rV_qRmJlQc-12fTPaYAlYpcr9rBYW38CZagTUA0DSy0,2231
+topstep_backtest/data/synthetic.py,sha256=V1UiWe_bndefwRYqvxX8lf3WJVuqhHtrZ5zRnPPynTA,5327
+topstep_backtest/data/validator.py,sha256=GCLf7ziAe8c5E5sJIec-4fnJsTR5V7XJMMmTt_zO3Dc,8568
+topstep_backtest/data/wrangler.py,sha256=0cI23QMvOjN28YavQz4oXtgg5VkFVd8n6Pjxh2zgwtI,12222
+topstep_backtest/engine/__init__.py,sha256=N1G8vIKcwGZ-dL5XfFu83Q2K_vnZ0FyWh96dEx0Agx4,30
+topstep_backtest/engine/backtest.py,sha256=sH9oJZxuVKPjqWQQzqrDMvEF_RLtwBmvTRmGbnJADGM,8041
+topstep_backtest/execution/__init__.py,sha256=1QbZfFdYSjDz8JMbsARLYdwNHRjB0a4Su66zcaILf3g,33
+topstep_backtest/execution/rejections.py,sha256=8N05iizTHpaoub-2Bv5Oupoi8gmHYyObnXzr4ryPl-I,1647
+topstep_backtest/execution/sim_broker.py,sha256=hfF_Bg7srZ3oTsC52xNNWCCIOxNL8sRIQ93CU2i3qbc,57317
+topstep_backtest/fills/__init__.py,sha256=zN0kFAwMUM8RfQ4US3CxnxEc4sXpBRCmIEnyePeoWMY,29
+topstep_backtest/fills/bar_fill.py,sha256=s4fN1P9Q_mdFXcTf-l0mSdHtAX0MnADpXrp3MCOTsRU,11720
+topstep_backtest/fills/fees.py,sha256=t6mey1ivybe2wb61yC_QGm-skimp73EMLkwvxn3dEn4,4363
+topstep_backtest/fills/path.py,sha256=fCpFO2i7J5ELYj_nB7frAw6f91GnjaA6_dRRwIsWCkY,2307
+topstep_backtest/indicators/__init__.py,sha256=pyQCJ1IzxLXNlClqC3fEpIko_UZ-v_LDIsrEp5RnWEQ,890
+topstep_backtest/indicators/base.py,sha256=NBrX9A6VoEHBq3HFhnNGEjdd-_5tjTmNRBHil_wHX4I,1539
+topstep_backtest/indicators/library.py,sha256=TXK4s5h5aDrdNIpbLYIYOXiBPJ_jMoaicROqWYm707A,10484
+topstep_backtest/indicators/talib_adapter.py,sha256=4QxjyIYEHJl8rq_ClCyAigF1NXJHPwo_1D8sYPG2mL4,27125
+topstep_backtest/metrics/__init__.py,sha256=-P-K6NRm7PRxuvy-TmZQ6fWFZt5Z3D0lodypeZmqHpk,128
+topstep_backtest/metrics/stats.py,sha256=LcZ1o6BnH0yqNcCpy02726T77uT_mPnPM5P_jzBMxtg,6658
+topstep_backtest/rules/__init__.py,sha256=D3-Hn-6biaZu84I-gvbb5WcE1kKvKodPFn6_bA8_BGY,29
+topstep_backtest/rules/kernel.py,sha256=E2rwoxJTzUVhTxWKhDnzmAUovS_rJmyEXjyRM4Pmz6s,10394
+topstep_backtest/rules/params.py,sha256=-ljFgFDCWcUk_u6hvzosdYPXZpsUVlFWerbbAgbYIKk,2616
+topstep_backtest/strategy/__init__.py,sha256=iCvVXBha4Vudti9JEmeDdGsfPiSTxQeVEH6mDX8KzDM,391
+topstep_backtest/strategy/base.py,sha256=pvZvDFo38heroy0GO4hIMIKqTh1Ch35a-yJbv5xH0hU,3996
+topstep_backtest/strategy/symbol.py,sha256=Fnrid3S_tpT8wzxuneLIcV6oH58ezUQY9ahZdB5Hrps,13497
+topstep_backtest/strategy/tracker.py,sha256=b04RMU7CBDR7HVcqFUj5pXxyTu_5sJGnbwKiKQ5qsXA,5157
+topstep_backtest-0.1.0.dist-info/METADATA,sha256=yKeBs9fqcrqFjHUEfWeFGEtazUeIVjnrILGvAxfwwy8,11456
+topstep_backtest-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+topstep_backtest-0.1.0.dist-info/licenses/LICENSE,sha256=YKxnmeFF9Cf9zJwyjJLZMJ2ve0xCXNBCWCD-Mrw5Ctw,1071
+topstep_backtest-0.1.0.dist-info/RECORD,,

topstep_backtest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

topstep_backtest-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarric Sookdeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.