topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/rules/kernel.py

@@ -0,0 +1,281 @@
+"""The Topstep Combine rule kernel — the canonical combine-rulebook state machine.
+
+A PURE state machine (docs/topstep-rules.md §§1-5): no I/O, no clock reads, no
+randomness. Callers push int-ns UTC timestamps and exact ``Decimal`` balances
+in; the kernel answers with breaches and a verdict.
+
+The single biggest correctness item is the **two-state trailing Maximum Loss
+Limit** (§2):
+
+* State A — floor ratchet, END OF DAY ONLY: the floor starts at
+  ``starting_balance - mll_buffer`` and ratchets up only on end-of-day CLOSED
+  balance, never intraday, never down. Once the ratcheted floor would reach
+  the starting balance it **locks there permanently**.
+* State B — breach check, REAL TIME: every tick the caller pushes live equity
+  (realized + unrealized) into :meth:`CombineKernel.check_equity`; touching
+  the floor (``equity <= floor``) fails the account immediately (terminal).
+
+The optional Daily Loss Limit (§3) is a same-day lockout, not a violation:
+tripping it returns a :class:`Breach` of kind ``DLL`` and sets ``day_locked``
+until the next session close. An MLL breach takes precedence when both trip
+on the same tick. The stored ``breach`` property holds only the terminal MLL
+breach; DLL breaches are returned to the caller but never stored.
+
+Breach ``limit`` semantics: for MLL it is the floor; for DLL it is the equity
+threshold ``day_start_balance - dll`` (the level at which the day locks).
+
+Pass evaluation (§§1, 4) happens only in :meth:`CombineKernel.on_session_close`
+and only while IN_PROGRESS: the closed balance must reach
+``starting_balance + profit_target``, total profit must be positive, and the
+best traded day must satisfy ``best_day <= consistency_pct * total_profit``
+(Topstep's target inflation: a too-big best day forces more total profit,
+implying the ~2-day minimum). ``best_day`` only considers days on which
+:meth:`CombineKernel.on_trade_activity` was called; losing days never reset it.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+from enum import IntEnum
+
+import msgspec
+
+from ..core.time import trading_day_of
+from .params import CombineParams
+
+__all__ = ["Breach", "BreachKind", "CombineKernel", "DayRecord", "Verdict"]
+
+
+class Verdict(IntEnum):
+    """Combine outcome. Transitions only ``IN_PROGRESS -> {PASSED, FAILED}``."""
+
+    IN_PROGRESS = 0
+    PASSED = 1
+    FAILED = 2
+
+
+class BreachKind(IntEnum):
+    """Which limit was breached."""
+
+    MLL = 1
+    DLL = 2
+
+
+class Breach(msgspec.Struct, frozen=True):
+    """A limit breach at ``ts_ns``. ``limit`` is the equity threshold breached:
+
+    the trailing floor for MLL, ``day_start_balance - dll`` for DLL.
+    """
+
+    kind: BreachKind
+    ts_ns: int
+    equity: Decimal
+    limit: Decimal
+
+
+class DayRecord(msgspec.Struct, frozen=True):
+    """One closed trading day. ``floor_after`` is the MLL floor in effect after
+
+    this close's end-of-day ratchet; ``had_trade`` records whether trade
+    activity occurred during the day.
+    """
+
+    day: date
+    eod_balance: Decimal
+    day_pnl: Decimal
+    floor_after: Decimal
+    had_trade: bool
+
+
+_ZERO = Decimal("0")
+
+
+class CombineKernel:
+    """The single canonical implementation of the Topstep Combine rulebook.
+
+    Drive it with three calls: :meth:`on_trade_activity` when a fill happens,
+    :meth:`check_equity` on every tick with live equity (realized +
+    unrealized), and :meth:`on_session_close` at the 17:00 ET Globex close
+    with the day's closed balance. Once the verdict is terminal (PASSED or
+    FAILED) all mutating calls become no-ops.
+    """
+
+    __slots__ = (
+        "_best_day",
+        "_breach",
+        "_day_locked",
+        "_day_records",
+        "_day_start_balance",
+        "_days_traded",
+        "_floor",
+        "_had_trade",
+        "_last_closed_balance",
+        "_locked",
+        "_params",
+        "_peak_eod",
+        "_verdict",
+    )
+
+    def __init__(self, params: CombineParams) -> None:
+        self._params = params
+        self._floor = params.starting_balance - params.mll_buffer
+        self._peak_eod = params.starting_balance
+        self._locked = False
+        self._verdict = Verdict.IN_PROGRESS
+        self._breach: Breach | None = None
+        self._best_day = _ZERO
+        self._days_traded = 0
+        self._day_records: list[DayRecord] = []
+        self._day_start_balance = params.starting_balance
+        self._last_closed_balance = params.starting_balance
+        self._had_trade = False
+        self._day_locked = False
+
+    # -- read-only state ---------------------------------------------------
+
+    @property
+    def params(self) -> CombineParams:
+        return self._params
+
+    @property
+    def floor(self) -> Decimal:
+        """The current MLL floor (equity at/below this level is a fail)."""
+        return self._floor
+
+    @property
+    def locked(self) -> bool:
+        """Whether the floor has permanently locked at the starting balance."""
+        return self._locked
+
+    @property
+    def verdict(self) -> Verdict:
+        return self._verdict
+
+    @property
+    def best_day(self) -> Decimal:
+        """Largest ``day_pnl`` over traded days so far (never below zero)."""
+        return self._best_day
+
+    @property
+    def total_profit(self) -> Decimal:
+        """Last end-of-day closed balance minus the starting balance."""
+        return self._last_closed_balance - self._params.starting_balance
+
+    @property
+    def days_traded(self) -> int:
+        """Number of closed days on which trade activity occurred."""
+        return self._days_traded
+
+    @property
+    def day_records(self) -> tuple[DayRecord, ...]:
+        return tuple(self._day_records)
+
+    @property
+    def breach(self) -> Breach | None:
+        """The terminal MLL breach, if the combine has failed."""
+        return self._breach
+
+    @property
+    def day_start_balance(self) -> Decimal:
+        """Balance at the current trading day's start (prior session's close)."""
+        return self._day_start_balance
+
+    @property
+    def day_locked(self) -> bool:
+        """Whether the DLL has locked out trading for the rest of the day."""
+        return self._day_locked
+
+    # -- transitions -------------------------------------------------------
+
+    def on_trade_activity(self, ts_ns: int) -> None:
+        """Mark that a trade happened; makes the current day a traded day."""
+        if self._verdict is not Verdict.IN_PROGRESS:
+            return
+        self._had_trade = True
+
+    def check_equity(self, ts_ns: int, equity: Decimal) -> Breach | None:
+        """Real-time breach check on live equity (realized + unrealized).
+
+        Touching the MLL floor (``equity <= floor``) fails the account
+        terminally and returns (and stores) the MLL breach. Otherwise, with a
+        DLL configured, a day loss at/past the limit returns a DLL breach and
+        sets ``day_locked`` (not terminal; MLL takes precedence when both
+        trip). Once terminal, returns the stored breach without mutating.
+        """
+        if self._verdict is not Verdict.IN_PROGRESS:
+            return self._breach
+        if equity <= self._floor:
+            breach = Breach(kind=BreachKind.MLL, ts_ns=ts_ns, equity=equity, limit=self._floor)
+            self._breach = breach
+            self._verdict = Verdict.FAILED
+            return breach
+        dll = self._params.dll
+        if dll is not None and not self._day_locked:
+            dll_floor = self._day_start_balance - dll
+            if equity <= dll_floor:
+                self._day_locked = True
+                return Breach(kind=BreachKind.DLL, ts_ns=ts_ns, equity=equity, limit=dll_floor)
+        return None
+
+    def on_session_close(self, ts_ns: int, closed_balance: Decimal) -> None:
+        """Close the trading day at ``closed_balance`` (the 17:00 ET snapshot).
+
+        Closes the day's record first (``day_pnl`` against the day's starting
+        balance), then applies the end-of-day floor ratchet, then evaluates
+        the pass condition, then rolls day state (DLL lockout clears; the next
+        day's starting balance becomes ``closed_balance``). No-op once the
+        verdict is terminal.
+        """
+        if self._verdict is not Verdict.IN_PROGRESS:
+            return
+        params = self._params
+        if closed_balance <= self._floor:
+            # A closed balance at/below the floor is an MLL breach even if no
+            # intraday check ever observed it (e.g. flatten fees dropped the
+            # balance after the last equity check of the day).
+            self._breach = Breach(
+                kind=BreachKind.MLL, ts_ns=ts_ns, equity=closed_balance, limit=self._floor
+            )
+            self._verdict = Verdict.FAILED
+            return
+        day_pnl = closed_balance - self._day_start_balance
+        had_trade = self._had_trade
+        if had_trade:
+            self._days_traded += 1
+            if day_pnl > self._best_day:
+                self._best_day = day_pnl
+        # End-of-day ratchet: closed balance only, never intraday, never down.
+        if not self._locked and closed_balance > self._peak_eod:
+            self._peak_eod = closed_balance
+            new_floor = closed_balance - params.mll_buffer
+            if new_floor >= params.starting_balance:
+                self._floor = params.starting_balance
+                self._locked = True  # permanent
+            else:
+                self._floor = new_floor
+        self._day_records.append(
+            DayRecord(
+                day=trading_day_of(ts_ns),
+                eod_balance=closed_balance,
+                day_pnl=day_pnl,
+                floor_after=self._floor,
+                had_trade=had_trade,
+            )
+        )
+        self._last_closed_balance = closed_balance
+        total_profit = closed_balance - params.starting_balance
+        if (
+            closed_balance >= params.starting_balance + params.profit_target
+            and total_profit > _ZERO
+            and self._best_day <= params.consistency_pct * total_profit
+        ):
+            self._verdict = Verdict.PASSED
+        # Roll to the next trading day.
+        self._day_start_balance = closed_balance
+        self._had_trade = False
+        self._day_locked = False
+
+    def max_position_micro_units(self) -> int:
+        """The fixed position cap in micro-units for the whole Combine."""
+        return self._params.max_cap_micro_units

topstep_backtest/rules/params.py

@@ -0,0 +1,74 @@
+"""Trading Combine parameters per account size (docs/topstep-rules.md §1).
+
+These numbers are **cited config, not constants**: they come from Topstep's
+help center as researched July 2026. The DOLLAR FIGURES are canonical — no
+cross-size ratio holds (the oft-cited 1.5x/0.5x ratios are true only at $50K;
+$100K/$150K have target = 2 x MLL and DLL = 2/3 x MLL). The DLL is OPTIONAL
+and off by default (Topstep removed the default DLL in Aug 2024);
+enable it with ``dll_enabled=True`` to model a Personal Daily Loss Limit.
+
+All money values are exact ``Decimal``; the position cap is counted in
+micro-units (mini = 10, micro = 1) so cap math stays pure integer arithmetic.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from enum import StrEnum
+
+import msgspec
+
+__all__ = ["AccountSize", "CombineParams", "combine_params"]
+
+
+class AccountSize(StrEnum):
+    """The three Trading Combine account sizes Topstep offers."""
+
+    S50K = "50K"
+    S100K = "100K"
+    S150K = "150K"
+
+
+class CombineParams(msgspec.Struct, frozen=True):
+    """Frozen rule parameters for one Trading Combine account.
+
+    ``dll`` is ``None`` when no Personal Daily Loss Limit is set (the default
+    since Aug 2024); when set, it is the positive dollar amount of allowed
+    daily loss. ``max_cap_micro_units`` is the fixed position cap for the
+    whole Combine, in micro-units (5/10/15 minis x 10).
+    """
+
+    size: AccountSize
+    starting_balance: Decimal
+    profit_target: Decimal
+    mll_buffer: Decimal
+    dll: Decimal | None
+    max_cap_micro_units: int
+    consistency_pct: Decimal
+
+
+# starting_balance, profit_target, mll_buffer, dll (when enabled), cap micro-units
+_TABLE: dict[AccountSize, tuple[str, str, str, str, int]] = {
+    AccountSize.S50K: ("50000", "3000", "2000", "1000", 50),
+    AccountSize.S100K: ("100000", "6000", "3000", "2000", 100),
+    AccountSize.S150K: ("150000", "9000", "4500", "3000", 150),
+}
+
+
+def combine_params(size: AccountSize, *, dll_enabled: bool = False) -> CombineParams:
+    """Build the canonical ``CombineParams`` for an account size.
+
+    ``dll_enabled`` models a Personal Daily Loss Limit at the table's dollar
+    amount for the size; the default (``False``) matches Topstep's
+    post-Aug-2024 behavior of no DLL.
+    """
+    start, target, buffer, dll, cap = _TABLE[size]
+    return CombineParams(
+        size=size,
+        starting_balance=Decimal(start),
+        profit_target=Decimal(target),
+        mll_buffer=Decimal(buffer),
+        dll=Decimal(dll) if dll_enabled else None,
+        max_cap_micro_units=cap,
+        consistency_pct=Decimal("0.5"),
+    )

topstep_backtest/strategy/__init__.py

@@ -0,0 +1,20 @@
+"""topstep_backtest.strategy"""
+
+from .base import Strategy, StrategyContext
+from .symbol import SymbolStrategy
+from .tracker import (
+    TERMINAL_ORDER_STATUSES,
+    NetPosition,
+    OrderTracker,
+    PositionTracker,
+)
+
+__all__ = [
+    "TERMINAL_ORDER_STATUSES",
+    "NetPosition",
+    "OrderTracker",
+    "PositionTracker",
+    "Strategy",
+    "StrategyContext",
+    "SymbolStrategy",
+]

topstep_backtest/strategy/base.py

@@ -0,0 +1,118 @@
+"""The write-once Strategy base class and its injected context.
+
+A strategy subclasses :class:`Strategy` and talks ONLY to ``self.ctx`` —
+protocol-typed edges (``OrderApi``/``PositionApi``/``HistoryApi``/``Clock``).
+The SAME subclass runs in backtest (wired to a ``SimBroker``) and live (wired
+to ``topstep_sdk.AsyncTopstepClient``), because both satisfy the identical
+structural protocols. Never import a concrete broker or fill model here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from topstep_sdk import HalfTradeModel, OrderModel, PositionModel
+
+from ..core.instruments import InstrumentSpec, spec_for_symbol, symbol_of_contract_id
+from ..protocols import Bar, Broker, Clock, HistoryApi, OrderApi, PositionApi
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["Strategy", "StrategyContext"]
+
+
+@dataclass(slots=True)
+class StrategyContext:
+    """Everything a strategy may touch. Protocol-typed: sim and live inject
+
+    different concretions behind the same names.
+    """
+
+    orders: OrderApi
+    positions: PositionApi
+    history: HistoryApi
+    clock: Clock
+    account_id: int
+    instruments: Mapping[str, InstrumentSpec] = field(default_factory=dict[str, InstrumentSpec])
+
+    @classmethod
+    def from_broker(
+        cls,
+        broker: Broker,
+        *,
+        clock: Clock,
+        account_id: int,
+        instruments: Mapping[str, InstrumentSpec] | None = None,
+    ) -> StrategyContext:
+        return cls(
+            orders=broker.orders,
+            positions=broker.positions,
+            history=broker.history,
+            clock=clock,
+            account_id=account_id,
+            instruments=dict(instruments or {}),
+        )
+
+    def instrument(self, contract_id: str) -> InstrumentSpec:
+        """Spec for a contract id (registered mapping first, table fallback)."""
+        found = self.instruments.get(contract_id)
+        if found is not None:
+            return found
+        return spec_for_symbol(symbol_of_contract_id(contract_id))
+
+
+class Strategy:
+    """Base strategy. Override the hooks you need; all are optional.
+
+    Lifecycle: ``on_start`` -> (``on_bar`` / ``on_order`` / ``on_fill`` /
+    ``on_position``)* -> ``on_stop``. Order-state changes arrive via
+    ``on_order``; executions via ``on_fill`` (the parity-safe pattern in both
+    sim and live — never busy-poll ``wait_for_fill`` in a backtest).
+
+    Drivers (the ``BacktestEngine``, the future live runner) deliver events
+    through ``handle_*`` — pure pass-throughs here. User strategies override
+    ``on_*``; framework base classes interpose in ``handle_*``, so overriding
+    a user hook can never sever framework bookkeeping.
+    """
+
+    ctx: StrategyContext
+
+    def bind(self, ctx: StrategyContext) -> None:
+        self.ctx = ctx
+
+    def on_start(self) -> None:
+        pass
+
+    async def on_bar(self, bar: Bar) -> None:
+        pass
+
+    async def on_order(self, order: OrderModel) -> None:
+        pass
+
+    async def on_fill(self, trade: HalfTradeModel) -> None:
+        pass
+
+    async def on_position(self, position: PositionModel) -> None:
+        pass
+
+    def on_stop(self) -> None:
+        pass
+
+    async def handle_bar(self, bar: Bar) -> None:
+        """Driver entry point for a completed bar (drivers call ``handle_*``,
+        never ``on_*``); the default simply awaits the user hook."""
+        await self.on_bar(bar)
+
+    async def handle_order(self, order: OrderModel) -> None:
+        """Driver entry point for an order-state event (see ``handle_bar``)."""
+        await self.on_order(order)
+
+    async def handle_fill(self, trade: HalfTradeModel) -> None:
+        """Driver entry point for an execution event (see ``handle_bar``)."""
+        await self.on_fill(trade)
+
+    async def handle_position(self, position: PositionModel) -> None:
+        """Driver entry point for a position event (see ``handle_bar``)."""
+        await self.on_position(position)