topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/__init__.py

@@ -0,0 +1,43 @@
+"""topstep-backtest: event-driven Topstep Combine backtesting with live parity.
+
+Strategies are written once against the ``Broker``/``Clock`` protocols in
+:mod:`topstep_backtest.protocols` and run unchanged against the ``SimBroker``
+(backtest) or ``topstep_sdk.AsyncTopstepClient`` (live).
+
+Quick start (docs/STRATEGY_API.md §3)::
+
+    from topstep_backtest import AccountSize, Backtest
+
+    report = Backtest(bars, MyStrategy("CON.F.US.MNQ.U26"),
+                      account=AccountSize.S50K).run()
+    print(report)          # verdict + balance path + day trail + summary stats
+    report.result          # the unchanged frozen BacktestResult
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from . import indicators
+from .harness import Backtest, DataValidationError, Report
+from .metrics import SummaryStats
+from .rules.params import AccountSize
+from .strategy import Strategy, SymbolStrategy
+
+try:
+    __version__ = _version("topstep-backtest")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "AccountSize",
+    "Backtest",
+    "DataValidationError",
+    "Report",
+    "Strategy",
+    "SummaryStats",
+    "SymbolStrategy",
+    "__version__",
+    "indicators",
+]

topstep_backtest/clock/__init__.py

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

topstep_backtest/clock/live_clock.py

@@ -0,0 +1,82 @@
+"""Wall-time clock — proves ``protocols.Clock`` is implementable on real time.
+
+Minimal by design: the M1 backtest engine never drives it. ``now_ns`` reads
+``time.time_ns()``; alerts/timers are scheduled on the running asyncio event
+loop and a clear ``RuntimeError`` is raised when no loop is running.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+
+from ..core.time import NS_PER_SEC
+from ..protocols import TimeEvent
+
+__all__ = ["LiveClock"]
+
+
+class LiveClock:
+    """Wall-clock ``Clock``: real time, asyncio-scheduled timers/alerts.
+
+    Same replace-by-name / cancel-by-name semantics as ``TestClock`` so
+    time-driven logic is parity-safe across sim and live.
+    """
+
+    def __init__(self) -> None:
+        self._handles: dict[str, asyncio.TimerHandle] = {}
+
+    # -- Clock protocol -----------------------------------------------------
+
+    def now_ns(self) -> int:
+        return time.time_ns()
+
+    def now(self) -> datetime:
+        """Current wall time as a tz-aware UTC datetime."""
+        return datetime.now(UTC)
+
+    def set_time_alert(self, name: str, at_ns: int, cb: Callable[[TimeEvent], None]) -> None:
+        """One-shot alert at UTC-ns instant ``at_ns`` (already-past fires ASAP)."""
+        loop = self._running_loop()
+        self.cancel_timer(name)  # replace-by-name
+
+        def _fire() -> None:
+            self._handles.pop(name, None)
+            cb(TimeEvent(name=name, ts_ns=at_ns))
+
+        delay_s = max(0.0, (at_ns - time.time_ns()) / NS_PER_SEC)
+        self._handles[name] = loop.call_later(delay_s, _fire)
+
+    def set_timer(self, name: str, interval_ns: int, cb: Callable[[TimeEvent], None]) -> None:
+        """Repeating timer every ``interval_ns``, first due one interval from now."""
+        if interval_ns <= 0:
+            raise ValueError(f"interval_ns must be positive, got {interval_ns}")
+        loop = self._running_loop()
+        self.cancel_timer(name)  # replace-by-name
+        interval_s = interval_ns / NS_PER_SEC
+
+        def _fire() -> None:
+            self._handles[name] = loop.call_later(interval_s, _fire)  # re-arm first
+            cb(TimeEvent(name=name, ts_ns=time.time_ns()))
+
+        self._handles[name] = loop.call_later(interval_s, _fire)
+
+    def cancel_timer(self, name: str) -> None:
+        """Cancel an alert OR timer by name; unknown names are a no-op."""
+        handle = self._handles.pop(name, None)
+        if handle is not None:
+            handle.cancel()
+
+    # -- internals ----------------------------------------------------------
+
+    @staticmethod
+    def _running_loop() -> asyncio.AbstractEventLoop:
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError as exc:
+            raise RuntimeError(
+                "LiveClock alerts/timers require a running asyncio event loop: "
+                "call set_time_alert/set_timer from within async code"
+            ) from exc

topstep_backtest/clock/test_clock.py

@@ -0,0 +1,133 @@
+"""Deterministic simulated clock — the engine's only time source in backtests.
+
+``TestClock`` conforms to ``protocols.Clock``. Time only moves via
+``advance_to``: every alert/timer due at or before the target fires
+synchronously, ordered by ``(due_ts, registration order)``, and ``now_ns()``
+reads the firing event's due timestamp DURING each callback so any logic
+reading the clock inside a handler sees the event's own time. Time never
+moves backward.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from typing import ClassVar
+
+from ..protocols import TimeEvent
+
+__all__ = ["TestClock"]
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+class _Entry:
+    """One scheduled alert (``interval_ns is None``) or repeating timer."""
+
+    __slots__ = ("cb", "due_ns", "interval_ns", "name", "seq")
+
+    def __init__(
+        self,
+        name: str,
+        due_ns: int,
+        interval_ns: int | None,
+        cb: Callable[[TimeEvent], None],
+        seq: int,
+    ) -> None:
+        self.name = name
+        self.due_ns = due_ns
+        self.interval_ns = interval_ns
+        self.cb = cb
+        self.seq = seq
+
+
+class TestClock:
+    """Simulated clock: time advances only when the engine says so.
+
+    Semantics (binding):
+      - ``advance_to(ns)`` with ``ns < now_ns()`` raises ``ValueError``;
+        ``ns == now_ns()`` is a no-op advance that still fires anything due
+        at exactly ``ns`` not yet fired.
+      - Due callbacks fire synchronously in ``(due_ts, registration order)``;
+        repeating timers re-arm at ``due + interval`` (original registration
+        order kept) and can fire multiple times within one advance.
+      - ``set_time_alert`` with ``at_ns <= now`` is immediately due: it fires
+        on the next advance, stamped with its scheduled ``at_ns``.
+      - Re-registering a name replaces the prior entry (SDK handler
+        semantics); ``cancel_timer`` removes either kind by name (missing
+        name is a no-op). Alerts are one-shot.
+    """
+
+    # Not a pytest test class despite the name (pytest collects Test*).
+    __test__: ClassVar[bool] = False
+
+    def __init__(self, start_ns: int = 0) -> None:
+        self._now_ns = start_ns
+        self._entries: dict[str, _Entry] = {}
+        self._seq = 0
+
+    # -- Clock protocol -----------------------------------------------------
+
+    def now_ns(self) -> int:
+        return self._now_ns
+
+    def now(self) -> datetime:
+        """Current time as a tz-aware UTC datetime (exact to the microsecond)."""
+        return _EPOCH + timedelta(microseconds=self._now_ns // 1_000)
+
+    def set_time_alert(self, name: str, at_ns: int, cb: Callable[[TimeEvent], None]) -> None:
+        """One-shot alert at ``at_ns``; ``at_ns <= now`` fires on the next advance."""
+        self._register(_Entry(name, at_ns, None, cb, self._next_seq()))
+
+    def set_timer(self, name: str, interval_ns: int, cb: Callable[[TimeEvent], None]) -> None:
+        """Repeating timer, first due at ``now + interval_ns``."""
+        if interval_ns <= 0:
+            raise ValueError(f"interval_ns must be positive, got {interval_ns}")
+        self._register(_Entry(name, self._now_ns + interval_ns, interval_ns, cb, self._next_seq()))
+
+    def cancel_timer(self, name: str) -> None:
+        """Remove an alert OR timer by name; unknown names are a no-op."""
+        self._entries.pop(name, None)
+
+    # -- advancement --------------------------------------------------------
+
+    def advance_to(self, ns: int) -> None:
+        """Move time forward to ``ns``, firing everything due on the way.
+
+        Raises:
+            ValueError: If ``ns`` is before the current time (time never
+                moves backward).
+        """
+        if ns < self._now_ns:
+            raise ValueError(f"cannot advance backward: target {ns} < now {self._now_ns}")
+        while (entry := self._pop_next_due(ns)) is not None:
+            due = entry.due_ns
+            if entry.interval_ns is not None:  # re-arm BEFORE the callback so a
+                entry.due_ns = due + entry.interval_ns  # cancel/replace inside cb sticks
+                self._entries[entry.name] = entry
+            # The callback observes the event's time (never moving backward
+            # for an alert that was registered already past due).
+            self._now_ns = max(self._now_ns, due)
+            entry.cb(TimeEvent(name=entry.name, ts_ns=due))
+        self._now_ns = ns
+
+    # -- internals ----------------------------------------------------------
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    def _register(self, entry: _Entry) -> None:
+        self._entries[entry.name] = entry  # replace-by-name
+
+    def _pop_next_due(self, horizon_ns: int) -> _Entry | None:
+        """Remove and return the earliest entry due at/before ``horizon_ns``."""
+        best: _Entry | None = None
+        for entry in self._entries.values():
+            if entry.due_ns > horizon_ns:
+                continue
+            if best is None or (entry.due_ns, entry.seq) < (best.due_ns, best.seq):
+                best = entry
+        if best is not None:
+            del self._entries[best.name]
+        return best

topstep_backtest/core/__init__.py

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

topstep_backtest/core/ids.py

@@ -0,0 +1,23 @@
+"""Deterministic 64-bit id generation (gateway-parity id shapes)."""
+
+from __future__ import annotations
+
+__all__ = ["IdGenerator"]
+
+
+class IdGenerator:
+    """Monotonic int id source. Seeded above 2^31 so downstream code that
+
+    incorrectly stores ids in int32 fails fast in backtests, exactly as it
+    would against production gateway ids (which exceed 2^31).
+    """
+
+    __slots__ = ("_next",)
+
+    def __init__(self, start: int = 5_000_000_000) -> None:
+        self._next = start
+
+    def next(self) -> int:
+        value = self._next
+        self._next += 1
+        return value

topstep_backtest/core/instruments.py

@@ -0,0 +1,167 @@
+"""Instrument specifications: tick economics, venue, session class, cap weight.
+
+The runtime source of truth for tick size/value is the SDK ``ContractModel``;
+the built-in ``SPECS`` table is the offline reference (and consistency check)
+for the products commonly traded on Topstep. ``point_value`` is always derived
+as ``tick_value / tick_size`` and the triple is asserted consistent on load.
+
+Position caps count **micro-units**: a mini counts 10, a micro counts 1
+(Topstep's 10:1 ratio), so cap math is pure integer arithmetic.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from enum import StrEnum
+
+import msgspec
+from topstep_sdk import ContractModel
+
+__all__ = [
+    "SPECS",
+    "InstrumentSpec",
+    "SessionClass",
+    "Venue",
+    "spec_for_contract",
+    "spec_for_symbol",
+]
+
+
+class Venue(StrEnum):
+    """Exchange within CME Group (matters for calendars and fees)."""
+
+    CME = "CME"
+    CBOT = "CBOT"
+    NYMEX = "NYMEX"
+    COMEX = "COMEX"
+
+
+class SessionClass(StrEnum):
+    """Asset-class RTH template (ET). Globex hours are shared by all."""
+
+    EQUITY = "EQUITY"  # RTH 09:30-16:15 ET
+    ENERGY = "ENERGY"  # RTH 09:00-14:30 ET
+    GOLD = "GOLD"  # RTH 08:20-13:30 ET
+    SILVER = "SILVER"  # RTH 08:25-13:25 ET
+
+
+class InstrumentSpec(msgspec.Struct, frozen=True):
+    """Frozen per-product economics and session metadata.
+
+    ``cap_units`` is the product's weight toward Topstep's position cap in
+    micro-units (mini=10, micro=1).
+    """
+
+    symbol: str
+    venue: Venue
+    session_class: SessionClass
+    tick_size: Decimal
+    tick_value: Decimal
+    is_micro: bool
+
+    @property
+    def point_value(self) -> Decimal:
+        """Dollars per full 1.00 price move (= tick_value / tick_size)."""
+        return self.tick_value / self.tick_size
+
+    @property
+    def cap_units(self) -> int:
+        """Weight toward the position cap in micro-units (mini=10, micro=1)."""
+        return 1 if self.is_micro else 10
+
+
+def _spec(
+    symbol: str,
+    venue: Venue,
+    session: SessionClass,
+    tick_size: str,
+    tick_value: str,
+    *,
+    micro: bool,
+    expect_point: str,
+) -> InstrumentSpec:
+    spec = InstrumentSpec(
+        symbol=symbol,
+        venue=venue,
+        session_class=session,
+        tick_size=Decimal(tick_size),
+        tick_value=Decimal(tick_value),
+        is_micro=micro,
+    )
+    if spec.point_value != Decimal(expect_point):  # consistency assertion on load
+        raise AssertionError(f"{symbol}: point_value {spec.point_value} != expected {expect_point}")
+    return spec
+
+
+_TABLE: tuple[tuple[str, Venue, SessionClass, str, str, bool, str], ...] = (
+    ("ES", Venue.CME, SessionClass.EQUITY, "0.25", "12.50", False, "50"),
+    ("MES", Venue.CME, SessionClass.EQUITY, "0.25", "1.25", True, "5"),
+    ("NQ", Venue.CME, SessionClass.EQUITY, "0.25", "5.00", False, "20"),
+    ("MNQ", Venue.CME, SessionClass.EQUITY, "0.25", "0.50", True, "2"),
+    ("YM", Venue.CBOT, SessionClass.EQUITY, "1", "5.00", False, "5"),
+    ("MYM", Venue.CBOT, SessionClass.EQUITY, "1", "0.50", True, "0.50"),
+    ("RTY", Venue.CME, SessionClass.EQUITY, "0.10", "5.00", False, "50"),
+    ("M2K", Venue.CME, SessionClass.EQUITY, "0.10", "0.50", True, "5"),
+    ("CL", Venue.NYMEX, SessionClass.ENERGY, "0.01", "10.00", False, "1000"),
+    ("MCL", Venue.NYMEX, SessionClass.ENERGY, "0.01", "1.00", True, "100"),
+    ("NG", Venue.NYMEX, SessionClass.ENERGY, "0.001", "10.00", False, "10000"),
+    ("GC", Venue.COMEX, SessionClass.GOLD, "0.10", "10.00", False, "100"),
+    ("MGC", Venue.COMEX, SessionClass.GOLD, "0.10", "1.00", True, "10"),
+    ("SI", Venue.COMEX, SessionClass.SILVER, "0.005", "25.00", False, "5000"),
+    ("SIL", Venue.COMEX, SessionClass.SILVER, "0.005", "5.00", True, "1000"),
+)
+
+SPECS: dict[str, InstrumentSpec] = {
+    sym: _spec(sym, venue, sess, tick, value, micro=micro, expect_point=point)
+    for sym, venue, sess, tick, value, micro, point in _TABLE
+}
+
+
+def symbol_of_contract_id(contract_id: str) -> str:
+    """Extract the product symbol from a gateway contract id.
+
+    ``"CON.F.US.MNQ.U26"`` -> ``"MNQ"``; a bare symbol passes through unchanged.
+    """
+    parts = contract_id.split(".")
+    if len(parts) >= 4 and parts[0] == "CON":
+        return parts[3]
+    if len(parts) == 3 and parts[0] == "F":  # symbol_id form "F.US.MNQ"
+        return parts[2]
+    return contract_id
+
+
+def spec_for_symbol(symbol: str) -> InstrumentSpec:
+    """Look up the built-in spec for a product symbol (raises KeyError if unknown)."""
+    return SPECS[symbol]
+
+
+def spec_for_contract(contract: ContractModel) -> InstrumentSpec:
+    """Build a spec from a live SDK ``ContractModel``, validated against the table.
+
+    The contract's ``tick_size``/``tick_value`` are authoritative; if the symbol
+    is in ``SPECS`` the values must agree (a mismatch means the reference table
+    is stale and must be corrected — a silent override would corrupt P&L).
+    """
+    symbol = symbol_of_contract_id(contract.symbol_id or contract.id)
+    reference = SPECS.get(symbol)
+    if reference is not None:
+        if (contract.tick_size, contract.tick_value) != (
+            reference.tick_size,
+            reference.tick_value,
+        ):
+            raise ValueError(
+                f"{symbol}: gateway tick economics ({contract.tick_size}, {contract.tick_value})"
+                f" disagree with reference table ({reference.tick_size}, {reference.tick_value})"
+            )
+        return reference
+    # Unknown product: trust the gateway's tick economics, default conservative
+    # metadata, and treat it as a mini (cap-weight 10) so position caps are
+    # never accidentally loosened for an unrecognized symbol.
+    return InstrumentSpec(
+        symbol=symbol,
+        venue=Venue.CME,
+        session_class=SessionClass.EQUITY,
+        tick_size=contract.tick_size,
+        tick_value=contract.tick_value,
+        is_micro=False,
+    )

topstep_backtest/core/money.py

@@ -0,0 +1,160 @@
+"""Exact futures money math: the Decimal <-> integer-tick accounting spine.
+
+Every price that enters the engine must land on its instrument's tick grid, and
+every P&L figure is derived from *integer tick deltas* times the tick value —
+never from raw float arithmetic. All grid conversion lives here so "every fill
+price is on the tick grid" is one enforced invariant, not a convention.
+
+Rounding is always **explicit and directional** (`RoundMode`); there is no
+silent default rounding anywhere in the engine.
+"""
+
+from __future__ import annotations
+
+from decimal import ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_EVEN, Decimal
+from typing import Literal
+
+from topstep_sdk import OrderSide
+
+__all__ = [
+    "OffGridError",
+    "RoundMode",
+    "from_ticks",
+    "is_on_grid",
+    "position_unrealized",
+    "realized_pnl",
+    "round_to_tick",
+    "signed_tick_delta",
+    "to_ticks",
+    "unrealized_pnl",
+]
+
+RoundMode = Literal["nearest", "up", "down"]
+
+_ROUNDING = {
+    "nearest": ROUND_HALF_EVEN,
+    "up": ROUND_CEILING,
+    "down": ROUND_FLOOR,
+}
+
+
+class OffGridError(ValueError):
+    """A price does not lie on the instrument's tick grid."""
+
+    def __init__(self, price: Decimal, tick_size: Decimal) -> None:
+        super().__init__(f"price {price} is not a multiple of tick size {tick_size}")
+        self.price = price
+        self.tick_size = tick_size
+
+
+def is_on_grid(price: Decimal, tick_size: Decimal) -> bool:
+    """Whether ``price`` is an exact multiple of ``tick_size``."""
+    return price % tick_size == 0
+
+
+def to_ticks(price: Decimal, tick_size: Decimal) -> int:
+    """Convert an on-grid price to its integer tick index.
+
+    Raises:
+        OffGridError: If ``price`` is not an exact multiple of ``tick_size``.
+    """
+    quotient, remainder = divmod(price, tick_size)
+    if remainder != 0:
+        raise OffGridError(price, tick_size)
+    return int(quotient)
+
+
+def from_ticks(ticks: int, tick_size: Decimal) -> Decimal:
+    """Convert an integer tick index back to its exact Decimal price."""
+    return ticks * tick_size
+
+
+def round_to_tick(price: Decimal, tick_size: Decimal, *, mode: RoundMode) -> Decimal:
+    """Snap an arbitrary price onto the tick grid with an explicit direction.
+
+    ``mode="up"`` rounds toward +infinity, ``"down"`` toward -infinity, and
+    ``"nearest"`` uses banker's rounding on the tick index. Use directional
+    modes when conservatism matters (e.g. rounding a computed level *against*
+    the trader).
+    """
+    ticks = (price / tick_size).to_integral_value(rounding=_ROUNDING[mode])
+    return ticks * tick_size
+
+
+def signed_tick_delta(entry: Decimal, exit: Decimal, tick_size: Decimal) -> int:
+    """Integer tick move from ``entry`` to ``exit`` (positive = price went up)."""
+    return to_ticks(exit, tick_size) - to_ticks(entry, tick_size)
+
+
+def _direction(side: OrderSide | int) -> int:
+    """+1 for a long (entry side BUY), -1 for a short (entry side SELL)."""
+    return 1 if int(side) == int(OrderSide.BUY) else -1
+
+
+def realized_pnl(
+    entry: Decimal,
+    exit: Decimal,
+    *,
+    entry_side: OrderSide | int,
+    qty: int,
+    tick_size: Decimal,
+    tick_value: Decimal,
+) -> Decimal:
+    """Exact realized P&L for closing ``qty`` contracts entered at ``entry``.
+
+    Both prices must be on the tick grid; the result is an exact Decimal
+    (integer ticks x tick_value x qty), before fees.
+    """
+    if qty <= 0:
+        raise ValueError(f"qty must be positive, got {qty}")
+    ticks = signed_tick_delta(entry, exit, tick_size)
+    return ticks * _direction(entry_side) * tick_value * qty
+
+
+def unrealized_pnl(
+    avg_entry: Decimal,
+    mark: Decimal,
+    *,
+    entry_side: OrderSide | int,
+    qty: int,
+    tick_size: Decimal,
+    tick_value: Decimal,
+) -> Decimal:
+    """Exact open P&L marking ``qty`` contracts at ``mark``.
+
+    This is THE shared unrealized-P&L computation: the sim broker, the rule
+    engine's breach checks, and any live shadow-monitor must all mark through
+    this one function so breach timing can never diverge between them.
+    """
+    return realized_pnl(
+        avg_entry,
+        mark,
+        entry_side=entry_side,
+        qty=qty,
+        tick_size=tick_size,
+        tick_value=tick_value,
+    )
+
+
+def position_unrealized(
+    *,
+    cost: Decimal,
+    qty: int,
+    mark: Decimal,
+    direction: int,
+    point_value: Decimal,
+) -> Decimal:
+    """Exact open P&L for a netted position from its COST BASIS (no division).
+
+    ``cost`` = sum(entry_price_i * qty_i) over the position's open lots;
+    ``direction`` = +1 long / -1 short. Division-free, so it stays exact even
+    when the weighted-average entry price would be a non-terminating decimal
+    (e.g. three lots averaging to thirds of a tick). This is THE shared
+    unrealized computation for netted positions — sim broker, rule-engine
+    breach checks, and any live shadow-monitor must all mark through it.
+    """
+    if qty <= 0:
+        raise ValueError(f"qty must be positive, got {qty}")
+    if direction not in (1, -1):
+        raise ValueError(f"direction must be +1 or -1, got {direction}")
+    return (mark * qty - cost) * direction * point_value