topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/metrics/stats.py

@@ -0,0 +1,153 @@
+"""Combine-centric summary statistics derived from a finished backtest run.
+
+Every metric's basis is stated explicitly because most admit two honest bases
+(gross vs net of fees, bar-close vs intrabar) and mixing them silently is how
+reports lie:
+
+* A "closing half-turn" is a broker trade record whose ``profit_and_loss`` is
+  not ``None`` and that is not voided. ``profit_and_loss`` is the GROSS
+  realized P&L of the closed portion; fees and commissions are charged on
+  EVERY half-turn (open and close) and deducted from balance separately. So
+  per-close classification (win rate, expectancy, profit factor) is gross,
+  while the aggregate net figure is ``net_pnl`` (ending minus starting
+  balance, all fees included). Re-attributing opening fees to round trips
+  would need new FIFO pairing whose live-gateway equivalence is unverified
+  (docs/topstep-rules.md §9) — deliberately not offered.
+* Drawdown is measured on the per-bar CLOSE equity curve, closed with one
+  terminal mark at ``ending_balance``: the engine's final session roll (16:10
+  flatten slippage + liquidation fees) lands AFTER the last curve point, and
+  without the terminal mark ``max_drawdown`` could sit below the net loss
+  printed beside it. Intrabar excursions are not observable from
+  ``BacktestResult`` and no proxy is attempted.
+* Consistency (docs/topstep-rules.md §4): passing requires
+  ``best_day <= consistency_pct x total_profit``, where ``best_day`` is the
+  largest traded-day EOD-balance delta (net of fees, never below zero) and
+  ``total_profit`` is the last closed balance minus start.
+  ``consistency_pct`` is not a ``BacktestResult`` field — the caller passes
+  it from the ``CombineParams`` the run used.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+import msgspec
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from topstep_sdk import HalfTradeModel
+
+    from ..engine.backtest import BacktestResult
+
+__all__ = ["SummaryStats", "compute_summary"]
+
+_ZERO = Decimal("0")
+
+
+class SummaryStats(msgspec.Struct, frozen=True):
+    """Combine-centric summary metrics for one finished backtest run.
+
+    Empty-run conventions: with zero closing half-turns, ``win_rate``,
+    ``expectancy`` and ``profit_factor`` are ``None`` (undefined, not 0);
+    ``profit_factor`` is also ``None`` when there are no losing closes (the
+    ratio would be infinite). ``max_drawdown`` over an empty equity curve
+    reduces to the terminal mark alone: ``max(0, starting - ending)``, which
+    is 0 for a run with no bars (the balance never moved).
+    """
+
+    closed_trades: int
+    """Closing half-turns: trade records with ``profit_and_loss`` set and not
+    voided. NOT round trips — a flip's single half-turn closes one position
+    and opens the next."""
+
+    win_rate: Decimal | None
+    """Fraction of closing half-turns with gross ``profit_and_loss`` > 0
+    (fees are charged per half-turn separately, so this is a GROSS stat).
+    ``None`` when there are no closing half-turns."""
+
+    expectancy: Decimal | None
+    """Mean gross ``profit_and_loss`` per closing half-turn. ``None`` when
+    there are no closing half-turns; the aggregate NET counterpart is
+    ``net_pnl / closed_trades``."""
+
+    profit_factor: Decimal | None
+    """Sum of gross winning closes / |sum of gross losing closes|. ``None``
+    when undefined: no closing half-turns, or no losing closes."""
+
+    max_drawdown: Decimal
+    """Largest peak-to-trough decline of the per-bar CLOSE equity curve plus
+    one terminal mark at ``ending_balance`` (the final session roll's flatten
+    costs land after the last curve point), with the peak seeded at the
+    starting balance (always >= 0, and never below ``-net_pnl``). Close-basis
+    only: intrabar excursions are not in ``BacktestResult.equity_curve``."""
+
+    final_balance: Decimal
+    """Ending realized balance (``BacktestResult.ending_balance``)."""
+
+    net_pnl: Decimal
+    """``ending_balance - starting_balance``, net of ALL fees and commissions
+    (the engine's session roll flattens at end of run, so nothing is open)."""
+
+    distance_to_floor: Decimal
+    """``ending_balance - floor``: dollars of room above the trailing MLL
+    floor at end of run."""
+
+    consistency_headroom: Decimal
+    """``consistency_pct x total_profit - best_day`` — dollar slack in the
+    consistency rule (docs/topstep-rules.md §4). Negative means the best day
+    is currently too large: the effective target inflates until
+    ``best_day <= consistency_pct x total_profit`` holds."""
+
+    days_traded: int
+    """Closed trading days with trade activity (``BacktestResult.days_traded``)."""
+
+
+def compute_summary(
+    result: BacktestResult,
+    *,
+    trades: Sequence[HalfTradeModel],
+    consistency_pct: Decimal,
+) -> SummaryStats:
+    """Derive ``SummaryStats`` from a run's frozen result and trade list.
+
+    Pure and deterministic: a function of its arguments only (``Decimal``
+    arithmetic at the default context), no clock reads, no randomness.
+    ``trades`` is the broker's half-turn list (``SimBroker.trades``);
+    ``consistency_pct`` comes from the ``CombineParams`` the run used.
+    """
+    closes = [
+        trade.profit_and_loss
+        for trade in trades
+        if trade.profit_and_loss is not None and not trade.voided
+    ]
+    closed = len(closes)
+    wins = sum(1 for pnl in closes if pnl > _ZERO)
+    gross_profit = sum((pnl for pnl in closes if pnl > _ZERO), _ZERO)
+    gross_loss = sum((-pnl for pnl in closes if pnl < _ZERO), _ZERO)
+
+    peak = result.starting_balance
+    max_drawdown = _ZERO
+    # The final ending_balance is one more equity mark: the terminal session
+    # roll's flatten costs land after the last curve point (module docstring).
+    marks = [equity for _ts_ns, equity in result.equity_curve]
+    marks.append(result.ending_balance)
+    for equity in marks:
+        if equity > peak:
+            peak = equity
+        elif peak - equity > max_drawdown:
+            max_drawdown = peak - equity
+
+    return SummaryStats(
+        closed_trades=closed,
+        win_rate=Decimal(wins) / closed if closed else None,
+        expectancy=sum(closes, _ZERO) / closed if closed else None,
+        profit_factor=gross_profit / gross_loss if closed and gross_loss > _ZERO else None,
+        max_drawdown=max_drawdown,
+        final_balance=result.ending_balance,
+        net_pnl=result.ending_balance - result.starting_balance,
+        distance_to_floor=result.ending_balance - result.floor,
+        consistency_headroom=consistency_pct * result.total_profit - result.best_day,
+        days_traded=result.days_traded,
+    )

topstep_backtest/protocols.py

@@ -0,0 +1,473 @@
+"""THE canonical interface module — every subsystem imports from here.
+
+This file is the frozen contract that resolves cross-subsystem interface
+drift (the #1 composition risk identified at design time). It defines:
+
+  - the time contract  (``Clock``, ``TimeEvent``)
+  - the data contract  (``Bar``, ``BarType``, ``DataFeed`` — bars stamped at
+    CLOSE; feeds yield in non-decreasing ``ts_init`` order)
+  - the parity seam    (``OrderApi`` / ``PositionApi`` / ``HistoryApi`` /
+    ``Broker`` — method surfaces copied verbatim from the topstep-sdk
+    resources, so ``AsyncTopstepClient`` satisfies ``Broker`` structurally
+    and ``SimBroker`` implements the identical protocol)
+  - the fill contract  (``MarketContext``, ``PricePath``, ``WorkingOrder``,
+    ``Fill``, ``FillModel``, ``FeeModel`` — the only realism component that
+    changes across data tiers; strategies never import it)
+
+Conventions (binding):
+  - Timestamps are ``int`` nanoseconds since the UTC epoch. Every event
+    carries ``ts_event`` (venue occurrence) and ``ts_init`` (engine ingest);
+    dispatch order is strictly non-decreasing ``ts_init``.
+  - A ``Bar``'s ``ts_init`` equals its CLOSE time — a strategy physically
+    cannot act on an unfinished bar.
+  - All prices are ``Decimal`` on the instrument's tick grid.
+  - Backtest data feeds are synchronous iterators (deterministic pull);
+    live feeds adapt the SDK market hub separately.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Sequence
+from datetime import datetime
+from decimal import Decimal
+from enum import IntEnum
+from typing import Protocol, runtime_checkable
+
+import msgspec
+from topstep_sdk import (
+    AggregateBarUnit,
+    OrderModel,
+    OrderSide,
+    OrderType,
+    PlaceOrderBracket,
+    PositionModel,
+)
+from topstep_sdk.models.history import AggregateBarModel
+from topstep_sdk.models.realtime import MarketTradeData, QuoteData
+
+from .core.instruments import InstrumentSpec
+
+__all__ = [
+    "Bar",
+    "BarType",
+    "Broker",
+    "Clock",
+    "DataFeed",
+    "FeeModel",
+    "Fill",
+    "FillModel",
+    "HistoryApi",
+    "Liquidity",
+    "MarketContext",
+    "OrderApi",
+    "PathPoint",
+    "PositionApi",
+    "PricePath",
+    "TimeEvent",
+    "WorkingOrder",
+]
+
+
+# ---------------------------------------------------------------------------
+# Time
+# ---------------------------------------------------------------------------
+
+
+class TimeEvent(msgspec.Struct, frozen=True):
+    """A named timer/alert firing at ``ts_ns``."""
+
+    name: str
+    ts_ns: int
+
+
+@runtime_checkable
+class Clock(Protocol):
+    """Swappable time source. ALL time-based logic flows through this —
+
+    never ``datetime.now()``. ``TestClock`` advances only as the engine drains
+    events; ``LiveClock`` is wall time. Identical API in both, so time-driven
+    strategy/rule logic is parity-safe.
+    """
+
+    def now_ns(self) -> int: ...
+
+    def now(self) -> datetime:
+        """Current time as a tz-aware UTC datetime."""
+        ...
+
+    def set_time_alert(self, name: str, at_ns: int, cb: Callable[[TimeEvent], None]) -> None: ...
+
+    def set_timer(self, name: str, interval_ns: int, cb: Callable[[TimeEvent], None]) -> None: ...
+
+    def cancel_timer(self, name: str) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Data
+# ---------------------------------------------------------------------------
+
+
+class BarType(msgspec.Struct, frozen=True):
+    """Identifies a bar stream: instrument + step + unit.
+
+    ``contract_id`` is the gateway contract id (e.g. ``"CON.F.US.MNQ.U26"``).
+    """
+
+    contract_id: str
+    unit: AggregateBarUnit
+    unit_number: int
+
+
+class Bar(msgspec.Struct, frozen=True):
+    """An OHLCV bar. ``ts_init`` == bar CLOSE time (the no-look-ahead anchor);
+
+    ``ts_event`` == bar OPEN time (when the bar's window began at the venue).
+    """
+
+    bar_type: BarType
+    ts_event: int
+    ts_init: int
+    open: Decimal
+    high: Decimal
+    low: Decimal
+    close: Decimal
+    volume: int
+
+
+@runtime_checkable
+class DataFeed(Protocol):
+    """A time-ordered source of bars for backtests.
+
+    MUST yield bars in non-decreasing ``ts_init`` order across ALL instruments
+    (one merged stream). The engine asserts this invariant on dispatch.
+    """
+
+    def __iter__(self) -> Iterator[Bar]: ...
+
+    def instruments(self) -> Sequence[str]:
+        """The contract ids this feed emits."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Parity seam: Broker (method surfaces copied verbatim from topstep-sdk)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class OrderApi(Protocol):
+    """Order surface — matches ``topstep_sdk.resources.order.OrderResource``."""
+
+    async def place(
+        self,
+        account_id: int,
+        contract_id: str,
+        *,
+        side: OrderSide | int,
+        type: OrderType | int,
+        size: int,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int: ...
+
+    async def buy(
+        self,
+        account_id: int,
+        contract_id: str,
+        size: int,
+        *,
+        type: OrderType | int = OrderType.MARKET,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int: ...
+
+    async def sell(
+        self,
+        account_id: int,
+        contract_id: str,
+        size: int,
+        *,
+        type: OrderType | int = OrderType.MARKET,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int: ...
+
+    async def modify(
+        self,
+        account_id: int,
+        order_id: int,
+        *,
+        size: int | None = None,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+    ) -> None: ...
+
+    async def cancel(self, account_id: int, order_id: int) -> None: ...
+
+    async def cancel_all(self, account_id: int) -> list[int]: ...
+
+    async def search_open(self, account_id: int) -> list[OrderModel]: ...
+
+    async def get(self, account_id: int, order_id: int) -> OrderModel | None: ...
+
+    async def wait_for_fill(
+        self,
+        account_id: int,
+        order_id: int,
+        *,
+        timeout: float = 30.0,  # noqa: ASYNC109 - mirrors the SDK signature
+        poll_interval: float = 1.0,
+    ) -> OrderModel: ...
+
+
+@runtime_checkable
+class PositionApi(Protocol):
+    """Position surface — matches ``topstep_sdk.resources.position.PositionResource``."""
+
+    async def search_open(self, account_id: int) -> list[PositionModel]: ...
+
+    async def close(self, account_id: int, contract_id: str) -> None: ...
+
+    async def partial_close(self, account_id: int, contract_id: str, size: int) -> None: ...
+
+    async def close_all(self, account_id: int) -> list[str]: ...
+
+
+@runtime_checkable
+class HistoryApi(Protocol):
+    """History surface — matches ``topstep_sdk.resources.history.HistoryResource``."""
+
+    async def retrieve_bars(
+        self,
+        contract_id: str,
+        *,
+        unit: AggregateBarUnit | int,
+        unit_number: int,
+        start_time: datetime | str,
+        end_time: datetime | str,
+        limit: int = 1000,
+        live: bool = False,
+        include_partial_bar: bool = False,
+    ) -> list[AggregateBarModel]: ...
+
+
+@runtime_checkable
+class Broker(Protocol):
+    """The write-once seam: ``AsyncTopstepClient`` satisfies this structurally
+
+    (its ``.orders``/``.positions``/``.history`` resources match the protocols
+    above verbatim) and ``SimBroker`` implements the identical surface —
+    swapping sim <-> live is pure wiring, with zero strategy change.
+    """
+
+    @property
+    def orders(self) -> OrderApi: ...
+
+    @property
+    def positions(self) -> PositionApi: ...
+
+    @property
+    def history(self) -> HistoryApi: ...
+
+
+# ---------------------------------------------------------------------------
+# Fills (the only realism component; strategies never import this section)
+# ---------------------------------------------------------------------------
+
+
+class Liquidity(IntEnum):
+    MAKER = 0
+    TAKER = 1
+
+
+class PointKind(IntEnum):
+    """Kind of a point on the deterministic intrabar price path."""
+
+    OPEN = 0
+    EXTREME_FIRST = 1
+    EXTREME_SECOND = 2
+    CLOSE = 3
+
+
+class PathPoint(msgspec.Struct, frozen=True):
+    """One waypoint of the intrabar path; consecutive points bound a monotonic
+
+    price segment. ``seq`` orders all intrabar happenings (fills, rule-breach
+    liquidations) deterministically along the path.
+    """
+
+    seq: int
+    kind: PointKind
+    price: Decimal
+
+
+PricePath = tuple[PathPoint, ...]
+"""The deterministic intrabar price path: OPEN -> first extreme -> second
+extreme -> CLOSE. Pessimistic ordering: with an open position, the ADVERSE
+extreme comes first (long -> low first, short -> high first); flat defaults to
+the extreme nearer the open. Built once per bar by ``fills.path.build_path``
+and shared by the fill model AND the rule engine's breach check so their
+relative ordering within a bar is decided by ONE walk, never two opinions.
+"""
+
+
+class MarketContext(msgspec.Struct, frozen=True):
+    """Tier-polymorphic market slice the engine feeds a ``FillModel``.
+
+    Exactly one of the tier fields is populated per event (Tier 0: ``bar``).
+    A fill model may read only data at/before ``ts_event`` — never ahead.
+    """
+
+    ts_event: int
+    ts_init: int
+    instrument: InstrumentSpec
+    bar: Bar | None = None
+    quote: QuoteData | None = None
+    last_trade: MarketTradeData | None = None
+    prev_close: Decimal | None = None
+
+
+class WorkingOrder:
+    """Mutable engine-owned order lifecycle state (NOT part of any message).
+
+    ``accepted_ts`` is the no-look-ahead firewall: an order participates in a
+    bar only if ``accepted_ts <= bar.ts_event`` (i.e. it existed at or before
+    the bar's open) — a close-signal order can never fill inside its own bar.
+    """
+
+    __slots__ = (
+        "accepted_ts",
+        "account_id",
+        "avg_fill_price",
+        "contract_id",
+        "custom_tag",
+        "filled_qty",
+        "limit_price",
+        "linked_order_id",
+        "order_id",
+        "parent_order_id",
+        "reduce_only",
+        "side",
+        "size",
+        "status",
+        "stop_price",
+        "trail_distance_ticks",
+        "trail_stop_price",
+        "type",
+    )
+
+    def __init__(
+        self,
+        *,
+        order_id: int,
+        account_id: int,
+        contract_id: str,
+        side: OrderSide,
+        type: OrderType,
+        size: int,
+        accepted_ts: int,
+        limit_price: Decimal | None = None,
+        stop_price: Decimal | None = None,
+        trail_stop_price: Decimal | None = None,
+        trail_distance_ticks: int | None = None,
+        custom_tag: str | None = None,
+        parent_order_id: int | None = None,
+        linked_order_id: int | None = None,
+        reduce_only: bool = False,
+    ) -> None:
+        from topstep_sdk import OrderStatus  # local import avoids cycle at module load
+
+        self.order_id = order_id
+        self.account_id = account_id
+        self.contract_id = contract_id
+        self.side = side
+        self.type = type
+        self.size = size
+        self.accepted_ts = accepted_ts
+        self.limit_price = limit_price
+        self.stop_price = stop_price
+        self.trail_stop_price = trail_stop_price
+        self.trail_distance_ticks = trail_distance_ticks
+        self.custom_tag = custom_tag
+        self.parent_order_id = parent_order_id
+        self.linked_order_id = linked_order_id
+        self.reduce_only = reduce_only
+        self.filled_qty = 0
+        self.avg_fill_price: Decimal | None = None
+        self.status = OrderStatus.OPEN
+
+    @property
+    def remaining(self) -> int:
+        return self.size - self.filled_qty
+
+
+class Fill(msgspec.Struct, frozen=True):
+    """One execution produced by a fill model.
+
+    ``seq`` is the path point starting the segment where the fill triggers;
+    ``trigger_price`` is the LEVEL that was touched (stop/limit level, or the
+    open) — the broker orders intrabar events by (seq, |trigger - seg_start|),
+    NOT by the slippage-adjusted fill ``price``. Ties resolve by order id.
+    """
+
+    order_id: int
+    price: Decimal
+    qty: int
+    ts_event: int
+    seq: int
+    liquidity: Liquidity
+    trigger_price: Decimal | None = None
+    note: str = ""
+
+
+@runtime_checkable
+class FillModel(Protocol):
+    """The ONLY component that changes across data tiers (bar -> L1 -> L2 -> MBO).
+
+    Given one order and the current market slice + shared intrabar path, decide
+    whether/where it fills. Must be deterministic (any randomness seeded) and
+    must never read past ``ctx.ts_event``.
+    """
+
+    def try_fill(
+        self,
+        order: WorkingOrder,
+        ctx: MarketContext,
+        path: PricePath,
+    ) -> list[Fill]: ...
+
+
+@runtime_checkable
+class FeeModel(Protocol):
+    """Per-side, per-instrument cost, charged on entry AND exit.
+
+    Returns ``(exchange_and_nfa_fees, broker_commission)`` per the SDK's
+    ``HalfTradeModel`` split (``fees`` vs ``commissions``).
+    """
+
+    def fee(
+        self,
+        instrument: InstrumentSpec,
+        side: OrderSide,
+        qty: int,
+        liquidity: Liquidity,
+    ) -> tuple[Decimal, Decimal]: ...

topstep_backtest/rules/__init__.py

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