topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/data/wrangler.py

@@ -0,0 +1,306 @@
+"""Wrangle user-supplied OHLCV rows into validated, time-ordered ``Bar`` tuples.
+
+The single most dangerous bug in bar-based backtesting is the silent
+off-by-one-bar look-ahead: treating a bar's OPEN timestamp as if it were its
+CLOSE (or vice versa) hands the strategy one bar of the future. This module
+kills that bug at the API level — the caller MUST declare what the source
+timestamp means via ``stamp``:
+
+  - ``stamp="open"``:  ``ts_event = ts``      and ``ts_init = ts + step``
+  - ``stamp="close"``: ``ts_init = ts``       and ``ts_event = ts - step``
+
+where ``step = unit x unit_number`` in nanoseconds. There is no default.
+
+Other hard guarantees:
+  - NAIVE timestamps are rejected with an error naming the fix — never guessed.
+  - Prices convert via ``str() -> Decimal`` (never ``float -> Decimal``) and
+    must land exactly on the instrument's tick grid (``RowOffGridError`` with
+    the offending row index otherwise). NaN/Infinity prices and negative
+    volumes are rejected with the row context.
+  - Only fixed-span intraday units (SECOND/MINUTE/HOUR) are accepted:
+    a Globex trading day is 23 hours, so DAY-and-above bars belong to the
+    session-aware calendar-resampling layer, not a fixed nanosecond step.
+  - Output is sorted ascending by ``ts_init`` (stable), ready for a feed.
+
+pandas is imported lazily — only ``bars_from_dataframe`` needs it.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from typing import TYPE_CHECKING, Any, Literal
+
+from topstep_sdk import AggregateBarUnit
+
+from ..core.money import OffGridError, is_on_grid
+from ..core.time import NS_PER_SEC, dt_to_ns
+from ..protocols import Bar, BarType
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from ..core.instruments import InstrumentSpec
+
+__all__ = [
+    "RowOffGridError",
+    "bars_from_dataframe",
+    "bars_from_records",
+    "step_ns",
+]
+
+_STEP_NS_PER_UNIT: dict[AggregateBarUnit, int] = {
+    AggregateBarUnit.SECOND: NS_PER_SEC,
+    AggregateBarUnit.MINUTE: 60 * NS_PER_SEC,
+    AggregateBarUnit.HOUR: 3_600 * NS_PER_SEC,
+}
+
+_SESSION_UNITS = (AggregateBarUnit.DAY, AggregateBarUnit.WEEK, AggregateBarUnit.MONTH)
+
+_TS_COLUMN_ALIASES = ("timestamp", "ts", "time", "datetime", "ts_event")
+_OHLCV_FIELDS = ("open", "high", "low", "close", "volume")
+
+
+class RowOffGridError(OffGridError):
+    """An input price is off the tick grid; carries the offending row index."""
+
+    def __init__(self, price: Decimal, tick_size: Decimal, *, row: int, field: str) -> None:
+        super().__init__(price, tick_size)
+        self.row = row
+        self.field = field
+        # Re-point the message at the row context (OffGridError.__init__ set a
+        # generic one); ``price``/``tick_size`` attributes remain intact.
+        self.args = (f"row {row}: {field}={price} is not on the {tick_size} tick grid",)
+
+
+def step_ns(unit: AggregateBarUnit, unit_number: int) -> int:
+    """The bar step (open -> close span) in nanoseconds.
+
+    Supports SECOND / MINUTE / HOUR only. TICK bars have no fixed time span.
+    DAY / WEEK / MONTH bars are session-scoped, not fixed-span: a Globex
+    trading day runs 23 hours (18:00 ET -> 17:00 ET), so a fixed 86,400s step
+    would mis-stamp every daily bar and mis-attribute its trading day.
+    Session-aware daily bars arrive with the calendar-resampling layer —
+    supply intraday bars here.
+    """
+    if unit_number < 1:
+        raise ValueError(f"unit_number must be >= 1, got {unit_number}")
+    per_unit = _STEP_NS_PER_UNIT.get(unit)
+    if per_unit is None:
+        if unit in _SESSION_UNITS:
+            raise ValueError(
+                f"unsupported bar unit {unit!r}: a Globex trading day is 23 hours "
+                "(18:00 ET -> 17:00 ET), so DAY-and-above bars have no fixed "
+                "nanosecond step; session-aware daily bars arrive with the "
+                "calendar-resampling layer — supply intraday (SECOND/MINUTE/HOUR) "
+                "bars instead"
+            )
+        raise ValueError(
+            f"unsupported bar unit {unit!r}: only SECOND/MINUTE/HOUR have a fixed time step"
+        )
+    return per_unit * unit_number
+
+
+def _ts_to_ns(value: object, *, row: int) -> int:
+    """Coerce one source timestamp to int UTC nanoseconds.
+
+    Accepts int (already ns), tz-aware ``datetime``, or tz-aware pandas
+    ``Timestamp`` (exact ``.value`` ns, no float round-trip). Naive timestamps
+    are rejected with the fix spelled out.
+    """
+    if isinstance(value, bool):
+        raise TypeError(f"row {row}: bool is not a valid timestamp")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise ValueError(
+                f"row {row}: naive timestamp {value!r} — localize it first (e.g. "
+                "df['timestamp'].dt.tz_localize('UTC') for Databento UTC data, or "
+                "tz_localize('America/New_York') for ET wall-clock data); "
+                "guessing a timezone would silently shift every bar"
+            )
+        # pandas Timestamp: use its exact integer ns instead of float seconds.
+        ns_value: object = getattr(value, "value", None)
+        if isinstance(ns_value, int):
+            return ns_value
+        return dt_to_ns(value)
+    raise TypeError(
+        f"row {row}: cannot interpret timestamp {value!r} of type "
+        f"{type(value).__name__}; pass int UTC ns or a tz-aware datetime"
+    )
+
+
+def _price_to_decimal(value: object, *, row: int, field: str) -> Decimal:
+    """Convert a price via ``str() -> Decimal`` — never float -> Decimal.
+
+    NaN / Infinity inputs (float or Decimal) are rejected with a ValueError
+    carrying the row index, field, and value — never a raw
+    ``decimal.InvalidOperation`` from downstream grid math.
+    """
+    if isinstance(value, bool):
+        raise TypeError(f"row {row}: bool is not a valid {field} price")
+    if isinstance(value, Decimal):
+        result = value
+    else:
+        try:
+            result = Decimal(str(value))
+        except InvalidOperation:
+            raise ValueError(
+                f"row {row}: cannot parse {field} price {value!r} as a Decimal"
+            ) from None
+    if not result.is_finite():
+        raise ValueError(
+            f"row {row}: {field} price {value!r} is not a finite number "
+            "(NaN/Infinity are not valid prices)"
+        )
+    return result
+
+
+def _volume_to_int(value: object, *, row: int) -> int:
+    if isinstance(value, bool):
+        raise TypeError(f"row {row}: bool is not a valid volume")
+    if isinstance(value, int):
+        volume = value
+    else:
+        try:
+            as_decimal = Decimal(str(value))
+        except InvalidOperation:
+            raise ValueError(f"row {row}: cannot parse volume {value!r} as an integer") from None
+        if not as_decimal.is_finite() or as_decimal != as_decimal.to_integral_value():
+            raise ValueError(f"row {row}: volume {value!r} is not a whole number")
+        volume = int(as_decimal)
+    if volume < 0:
+        raise ValueError(f"row {row}: volume {volume} is negative")
+    return volume
+
+
+def bars_from_records(
+    rows: Iterable[tuple[object, ...]],
+    *,
+    contract_id: str,
+    spec: InstrumentSpec,
+    unit: AggregateBarUnit,
+    unit_number: int,
+    stamp: Literal["open", "close"],
+) -> tuple[Bar, ...]:
+    """Build tick-grid-validated ``Bar`` objects from ``(ts, o, h, l, c, v)`` rows.
+
+    ``stamp`` declares what the source timestamp means — see module docstring.
+    Rows are sorted ascending by the resulting ``ts_init`` (stable sort), so
+    the output is feed-ready regardless of input order.
+    """
+    if stamp not in ("open", "close"):
+        raise ValueError(f'stamp must be "open" or "close", got {stamp!r}')
+    step = step_ns(unit, unit_number)
+    bar_type = BarType(contract_id=contract_id, unit=unit, unit_number=unit_number)
+
+    bars: list[Bar] = []
+    for row_index, row in enumerate(rows):
+        if len(row) != 6:
+            raise ValueError(
+                f"row {row_index}: expected 6 fields (ts, open, high, low, close, "
+                f"volume), got {len(row)}"
+            )
+        ts = _ts_to_ns(row[0], row=row_index)
+        prices: dict[str, Decimal] = {}
+        for field, raw in zip(_OHLCV_FIELDS[:4], row[1:5], strict=True):
+            price = _price_to_decimal(raw, row=row_index, field=field)
+            if not is_on_grid(price, spec.tick_size):
+                raise RowOffGridError(price, spec.tick_size, row=row_index, field=field)
+            prices[field] = price
+        volume = _volume_to_int(row[5], row=row_index)
+
+        if stamp == "open":
+            ts_event, ts_init = ts, ts + step
+        else:
+            ts_event, ts_init = ts - step, ts
+        bars.append(
+            Bar(
+                bar_type=bar_type,
+                ts_event=ts_event,
+                ts_init=ts_init,
+                open=prices["open"],
+                high=prices["high"],
+                low=prices["low"],
+                close=prices["close"],
+                volume=volume,
+            )
+        )
+    bars.sort(key=lambda b: b.ts_init)
+    return tuple(bars)
+
+
+def _import_pandas() -> Any:
+    try:
+        import pandas  # pyright: ignore[reportMissingTypeStubs]
+    except ImportError as exc:  # pragma: no cover - exercised only without pandas
+        raise ImportError(
+            "bars_from_dataframe requires pandas — install it with "
+            "`pip install 'topstep-backtest[data]'` (or `uv add pandas`), or use "
+            "bars_from_records with plain tuples instead"
+        ) from exc
+    return pandas
+
+
+def bars_from_dataframe(
+    df: Any,
+    *,
+    contract_id: str,
+    spec: InstrumentSpec,
+    unit: AggregateBarUnit,
+    unit_number: int,
+    stamp: Literal["open", "close"],
+) -> tuple[Bar, ...]:
+    """Build ``Bar`` objects from a pandas DataFrame of OHLCV candles.
+
+    The timestamp may be a column (case-insensitive: timestamp / ts / time /
+    datetime / ts_event) or the index — but the index is used ONLY when it is
+    a ``DatetimeIndex`` or is named (case-insensitively) after one of those
+    timestamp columns. A default ``RangeIndex`` (or any anonymous integer
+    index) is rejected: its 0, 1, 2, ... would otherwise be read as epoch
+    nanoseconds and every bar would silently land in 1970. OHLCV column names
+    are matched case-insensitively. Everything else — stamping,
+    naive-timestamp rejection, tick-grid enforcement, sorting — is delegated
+    to ``bars_from_records``.
+    """
+    pd = _import_pandas()
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"expected a pandas DataFrame, got {type(df).__name__}")
+
+    by_lower: dict[str, object] = {}
+    for column in df.columns:
+        by_lower.setdefault(str(column).lower(), column)
+
+    ts_column = next((by_lower[a] for a in _TS_COLUMN_ALIASES if a in by_lower), None)
+    if ts_column is not None:
+        ts_values: list[object] = df[ts_column].tolist()
+    else:
+        index_name = str(df.index.name).lower() if df.index.name is not None else None
+        if not isinstance(df.index, pd.DatetimeIndex) and (index_name not in _TS_COLUMN_ALIASES):
+            raise ValueError(
+                "no timestamp column found and the index "
+                f"({type(df.index).__name__}) is neither a DatetimeIndex nor named "
+                f"after one of the accepted timestamp columns "
+                f"{list(_TS_COLUMN_ALIASES)}; refusing to interpret a plain "
+                "integer index as epoch nanoseconds"
+            )
+        ts_values = df.index.tolist()
+
+    missing = [f for f in _OHLCV_FIELDS if f not in by_lower]
+    if missing:
+        raise ValueError(
+            f"DataFrame is missing required OHLCV columns {missing} "
+            f"(case-insensitive); found columns {[str(c) for c in df.columns]}"
+        )
+    series: list[list[object]] = [df[by_lower[f]].tolist() for f in _OHLCV_FIELDS]
+
+    rows = zip(ts_values, *series, strict=True)
+    return bars_from_records(
+        rows,
+        contract_id=contract_id,
+        spec=spec,
+        unit=unit,
+        unit_number=unit_number,
+        stamp=stamp,
+    )

topstep_backtest/engine/__init__.py

@@ -0,0 +1 @@
+"""topstep_backtest.engine"""

topstep_backtest/engine/backtest.py

@@ -0,0 +1,209 @@
+"""The deterministic backtest engine: one loop, strict time order, no look-ahead.
+
+Per bar (the three-phase settle):
+  1. session boundaries due before the bar are enforced (16:10 ET flatten,
+     17:00 ET session close -> MLL ratchet, day roll);
+  2. the SimBroker matches the bar (fills + intrabar rule breaches, in path
+     order) and queued user events (on_order/on_fill/on_position) dispatch;
+  3. the strategy sees the completed bar (``on_bar``) and may submit orders,
+     which are accepted at the bar's close timestamp — eligible from the NEXT
+     bar (the accepted_ts firewall).
+
+Determinism: single-threaded, a single monotonic event order, all state
+transitions driven by feed timestamps through the TestClock. Two runs over the
+same inputs produce byte-identical results.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+import msgspec
+from topstep_sdk import HalfTradeModel, OrderModel
+
+from ..core.time import TOPSTEP_SESSION, SessionTimes, trading_day_of
+from ..rules.kernel import Breach, DayRecord, Verdict
+from ..strategy.base import Strategy, StrategyContext
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from ..clock.test_clock import TestClock
+    from ..execution.sim_broker import SimBroker
+    from ..protocols import DataFeed
+
+__all__ = ["BacktestEngine", "BacktestResult"]
+
+
+class BacktestResult(msgspec.Struct, frozen=True):
+    """End-of-run outcome (msgspec-serializable -> golden-master friendly)."""
+
+    verdict: Verdict
+    reason: str
+    ending_balance: Decimal
+    starting_balance: Decimal
+    profit_target: Decimal
+    floor: Decimal
+    best_day: Decimal
+    total_profit: Decimal
+    days_traded: int
+    day_records: tuple[DayRecord, ...]
+    breach: Breach | None
+    trade_count: int
+    equity_curve: tuple[tuple[int, Decimal], ...]
+    # Rejected order placements as (gateway error_code, count), ascending by
+    # code. Empty on a clean run. A strategy whose orders were all rejected
+    # otherwise reports a flawless zero-trade run indistinguishable from one
+    # that simply never signalled.
+    rejections: tuple[tuple[int, int], ...] = ()
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict is Verdict.PASSED
+
+
+class BacktestEngine:
+    """Drives feed -> broker -> strategy under a TestClock."""
+
+    def __init__(
+        self,
+        *,
+        feed: DataFeed,
+        broker: SimBroker,
+        strategy: Strategy,
+        clock: TestClock,
+        session: SessionTimes = TOPSTEP_SESSION,
+    ) -> None:
+        self._feed = feed
+        self._broker = broker
+        self._strategy = strategy
+        self._clock = clock
+        self._session = session
+
+    async def run(self) -> BacktestResult:
+        broker = self._broker
+        strategy = self._strategy
+        session = self._session
+
+        strategy.bind(
+            StrategyContext.from_broker(
+                broker,
+                clock=self._clock,
+                account_id=broker.account_id,
+                instruments=broker.instruments,
+            )
+        )
+        strategy.on_start()
+
+        equity_curve: list[tuple[int, Decimal]] = []
+        current_day: date | None = None
+        flattened_today = False
+        last_ts = -1
+
+        try:
+            for bar in self._feed:
+                # --- no-look-ahead ordering invariant -----------------------
+                if bar.ts_init < last_ts:
+                    raise AssertionError(
+                        f"feed violated time order: bar ts_init {bar.ts_init} < {last_ts}"
+                    )
+                last_ts = bar.ts_init
+
+                day = trading_day_of(bar.ts_init)
+                if current_day is None:
+                    current_day = day
+                elif day != current_day:
+                    self._roll_session(current_day, flattened=flattened_today)
+                    current_day = day
+                    flattened_today = False
+                    if broker.dead:
+                        break
+
+                # --- 16:10 ET flatten enforcement --------------------------
+                # Strictly AFTER the deadline: a bar closing exactly at 16:10
+                # still contains tradable prints and must be matched first.
+                # The clock lands on the deadline BEFORE the flatten fires so
+                # anything a strategy tries from the resulting fill callbacks
+                # is correctly rejected as OutsideTradingHours.
+                if not flattened_today and bar.ts_init > session.flatten_ns(day):
+                    flatten_ns = session.flatten_ns(day)
+                    if flatten_ns > self._clock.now_ns():
+                        self._clock.advance_to(flatten_ns)
+                    broker.flatten_all(flatten_ns, reason="eod_flatten")
+                    flattened_today = True
+                    await self._dispatch()
+
+                self._clock.advance_to(bar.ts_init)
+
+                # --- phase 1: match, then deliver resulting user events ----
+                broker.on_bar(bar)
+                await self._dispatch()
+                if broker.dead:
+                    equity_curve.append((bar.ts_init, broker.equity()))
+                    break
+
+                # --- phase 2: strategy acts on the completed bar -----------
+                await strategy.handle_bar(bar)
+                await self._dispatch()
+
+                equity_curve.append((bar.ts_init, broker.equity()))
+
+            if current_day is not None and not broker.dead:
+                self._roll_session(current_day, flattened=flattened_today)
+        finally:
+            strategy.on_stop()
+
+        kernel = broker.kernel
+        reason = self._reason(kernel.verdict, kernel.breach)
+        return BacktestResult(
+            verdict=kernel.verdict,
+            reason=reason,
+            ending_balance=broker.balance,
+            starting_balance=kernel.params.starting_balance,
+            profit_target=kernel.params.profit_target,
+            floor=kernel.floor,
+            best_day=kernel.best_day,
+            total_profit=kernel.total_profit,
+            days_traded=kernel.days_traded,
+            day_records=kernel.day_records,
+            breach=kernel.breach,
+            trade_count=len(broker.trades),
+            equity_curve=tuple(equity_curve),
+            rejections=tuple(sorted(broker.rejections.items())),
+        )
+
+    def _roll_session(self, day: date, *, flattened: bool) -> None:
+        """End the trading day: enforce the flatten backstop, then snapshot the
+
+        closed balance for the kernel's EOD-MLL ratchet at 17:00 ET. The clock
+        lands on each boundary before its action so no callback can observe a
+        stale (pre-16:10) time.
+        """
+        if not flattened:
+            flatten_ns = self._session.flatten_ns(day)
+            if flatten_ns > self._clock.now_ns():
+                self._clock.advance_to(flatten_ns)
+            self._broker.flatten_all(flatten_ns, reason="eod_flatten")
+        close_ns = self._session.close_ns(day)
+        if close_ns > self._clock.now_ns():
+            self._clock.advance_to(close_ns)
+        self._broker.session_close(close_ns)
+
+    async def _dispatch(self) -> None:
+        """Deliver queued user-hub-shaped events to the strategy, in order."""
+        for event in self._broker.drain_events():
+            if isinstance(event, OrderModel):
+                await self._strategy.handle_order(event)
+            elif isinstance(event, HalfTradeModel):
+                await self._strategy.handle_fill(event)
+            else:
+                await self._strategy.handle_position(event)
+
+    @staticmethod
+    def _reason(verdict: Verdict, breach: Breach | None) -> str:
+        if verdict is Verdict.PASSED:
+            return "profit target reached with consistency satisfied"
+        if verdict is Verdict.FAILED and breach is not None:
+            return f"maximum loss limit breached (equity {breach.equity} <= floor {breach.limit})"
+        return "combine still in progress at end of data"

topstep_backtest/execution/__init__.py

@@ -0,0 +1 @@
+"""topstep_backtest.execution"""

topstep_backtest/execution/rejections.py

@@ -0,0 +1,53 @@
+"""Gateway-parity domain rejections.
+
+The SimBroker surfaces every rejection as the SDK's ``APIError`` with the same
+numeric ``error_code`` the real gateway would use, so ``except APIError`` code
+paths (and ``e.error_code`` branching) behave identically in sim and live.
+"""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from topstep_sdk import APIError
+from topstep_sdk.enums import (
+    CANCEL_ORDER_ERRORS,
+    MODIFY_ORDER_ERRORS,
+    PLACE_ORDER_ERRORS,
+    error_code_name,
+)
+
+__all__ = [
+    "UnsupportedInBacktestError",
+    "reject_cancel",
+    "reject_modify",
+    "reject_place",
+]
+
+
+class UnsupportedInBacktestError(RuntimeError):
+    """A live-only usage pattern that has no deterministic backtest equivalent.
+
+    Raised instead of silently diverging (e.g. ``wait_for_fill`` busy-polling,
+    which cannot advance a deterministic TestClock). The message names the
+    parity-safe alternative.
+    """
+
+
+def reject_place(code: int, detail: str = "") -> NoReturn:
+    """Raise the place-order rejection the gateway would return."""
+    name = error_code_name(PLACE_ORDER_ERRORS, code)
+    message = f"{name}: {detail}" if detail else name
+    raise APIError(message, error_code=code)
+
+
+def reject_modify(code: int, detail: str = "") -> NoReturn:
+    name = error_code_name(MODIFY_ORDER_ERRORS, code)
+    message = f"{name}: {detail}" if detail else name
+    raise APIError(message, error_code=code)
+
+
+def reject_cancel(code: int, detail: str = "") -> NoReturn:
+    name = error_code_name(CANCEL_ORDER_ERRORS, code)
+    message = f"{name}: {detail}" if detail else name
+    raise APIError(message, error_code=code)