topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/harness.py

@@ -0,0 +1,446 @@
+"""Two-line backtest assembly: ``Backtest(bars, strategy).run()`` -> ``Report``.
+
+Sim-side convenience ONLY — the facade wires the exact same components a
+hand-written main would (feed -> broker -> engine) and changes no semantics:
+``Report.result`` is the engine's frozen ``BacktestResult``, byte-identical to
+a hand-wired run over the same inputs. What the facade adds is assembly
+correctness (docs/STRATEGY_API.md §§3-4):
+
+* ONE ``TestClock`` shared by broker and engine. A second clock stuck at 0
+  would stamp every order ``accepted_ts=0`` (eligible for the CURRENT bar —
+  silent look-ahead) and run session checks in 1970; the facade makes that
+  footgun unbuildable.
+* Instruments derived from the feed's contract ids: the broker registers
+  instruments at construction only, and a bar for an unregistered contract is
+  a mid-run ``KeyError``.
+* Strict data validation by default: each contract's bars are checked with
+  ITS spec and any ERROR finding refuses to run (``validate=False`` skips;
+  the feed's ordering invariant is enforced regardless).
+* Real economics always: ``combine_params(account)`` and ``TopstepFees``.
+  backtesting.py's economics/semantics knobs (``cash=``, ``commission=``,
+  ``trade_on_close=``, ...) are rejected with the project's alternative named.
+
+Engine, broker, kernel, and strategy state are single-use, so each
+``Backtest`` runs exactly once; build a fresh ``Backtest`` (with a fresh
+strategy instance) for another run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from decimal import Decimal
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from typing import TYPE_CHECKING, Any, Literal
+
+from .clock.test_clock import TestClock
+from .core.instruments import SPECS, spec_for_symbol, symbol_of_contract_id
+from .data.feed import ListBarFeed
+from .data.validator import INFO_CODES, validate_bars
+from .data.wrangler import bars_from_dataframe
+from .engine.backtest import BacktestEngine
+from .execution.sim_broker import SimBroker
+from .fills.bar_fill import BarFillModel
+from .fills.fees import TopstepFees
+from .metrics.stats import SummaryStats, compute_summary
+from .rules.kernel import CombineKernel
+from .rules.params import AccountSize, combine_params
+from .strategy.symbol import SymbolStrategy
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from topstep_sdk import AggregateBarUnit, HalfTradeModel
+
+    from .core.instruments import InstrumentSpec
+    from .data.validator import ValidationIssue
+    from .engine.backtest import BacktestResult
+    from .execution.sim_broker import SimBrokerConfig
+    from .fills.bar_fill import BarFillConfig
+    from .protocols import Bar
+    from .rules.params import CombineParams
+    from .strategy.base import Strategy
+
+__all__ = ["Backtest", "DataValidationError", "Report"]
+
+_CENT = Decimal("0.01")
+
+
+def _engine_version() -> str:
+    """The installed package version, or a dev marker in a bare source tree."""
+    try:
+        return _dist_version("topstep-backtest")
+    except PackageNotFoundError:  # pragma: no cover - source tree without install
+        return "0.0.0.dev0"
+
+
+# Stamped on every rendered Report. A verdict line gets screenshotted and shared
+# out of context, so it has to carry its own provenance and caveat.
+_PROVENANCE = (
+    f"topstep-backtest {_engine_version()} — unofficial simulation, not affiliated "
+    "with Topstep. Rule and fee constants are cited config, NOT calibrated against "
+    "a live account (docs/topstep-rules.md §9): treat the verdict as a diagnostic, "
+    "not an authoritative pass/fail."
+)
+
+# backtesting.py knobs the §4 ledger REJECTS, each with the alternative named.
+_REJECTED_KNOBS: dict[str, str] = {
+    "cash": (
+        "account economics are fixed by the Combine — pick "
+        "account=AccountSize.S50K/S100K/S150K instead"
+    ),
+    "commission": (
+        "fees are the real Topstep schedule (fills.fees.TopstepFees), applied "
+        "always; they are not a per-trade knob. To correct a rate against your "
+        "own blotter, pass the whole schedule: "
+        "fee_model=TopstepFees(overrides={...})"
+    ),
+    "margin": (
+        "there is no margin model — the Combine's MLL floor and position cap "
+        "(combine_params) are the risk limits"
+    ),
+    "spread": (
+        "execution costs come from the Tier-0 bar fill model "
+        "(fills.bar_fill.BarFillConfig slippage ticks), not a synthetic spread"
+    ),
+    "trade_on_close": (
+        "filling at the decided bar's close is the exact look-ahead the "
+        "accepted_ts firewall forbids; orders fill from the NEXT bar"
+    ),
+    "hedging": "the venue nets positions per contract — hedged positions cannot exist",
+    "exclusive_orders": (
+        "hidden auto-close orders would mutate the strategy's intent sequence "
+        "(the parity gate); make reversals explicit awaits"
+    ),
+    "finalize_trades": (
+        "end-of-session positions are governed by the 16:10 ET flatten rule, never a stats toggle"
+    ),
+}
+
+
+def _refuse_unknown_kwargs(rejected: dict[str, object]) -> None:
+    for name in rejected:
+        alternative = _REJECTED_KNOBS.get(name)
+        if alternative is not None:
+            raise ValueError(f"Backtest() does not support {name!r}: {alternative}")
+    if rejected:
+        names = ", ".join(repr(name) for name in rejected)
+        raise TypeError(f"Backtest() got unexpected keyword argument(s) {names}")
+
+
+def _refuse_strategy_class(strategy: object) -> None:
+    # §4 REJECT: passing the strategy CLASS (backtesting.py's class+attr
+    # injection defeats typed constructor parameters). Without this guard the
+    # mistake surfaces as an unrelated TypeError deep inside engine.run().
+    if isinstance(strategy, type):
+        raise TypeError(
+            f"Backtest() takes a strategy INSTANCE, not the class "
+            f"{strategy.__name__!r} — construct it with its typed parameters, "
+            f'e.g. Backtest(bars, {strategy.__name__}("CON.F.US.MNQ.U26")) '
+            "(docs/STRATEGY_API.md §4)"
+        )
+
+
+def _spec_for_contract_id(contract_id: str) -> InstrumentSpec:
+    symbol = symbol_of_contract_id(contract_id)
+    try:
+        return spec_for_symbol(symbol)
+    except KeyError:
+        raise ValueError(
+            f"unknown product {symbol!r} (from contract id {contract_id!r}); "
+            f"built-in specs cover {sorted(SPECS)}"
+        ) from None
+
+
+class DataValidationError(ValueError):
+    """Bar data failed validation; ``issues`` carries every ERROR finding."""
+
+    def __init__(self, issues: tuple[ValidationIssue, ...]) -> None:
+        self.issues = issues
+        shown = [f"[{issue.code}] {issue.message}" for issue in issues[:20]]
+        if len(issues) > 20:
+            shown.append(f"... and {len(issues) - 20} more")
+        super().__init__(
+            "bar data failed validation (pass validate=False to run anyway):\n  "
+            + "\n  ".join(shown)
+        )
+
+
+def _money(value: Decimal) -> str:
+    return str(value.quantize(_CENT))
+
+
+def _signed(value: Decimal) -> str:
+    text = _money(value)
+    return text if value < 0 else f"+{text}"
+
+
+class Report:
+    """One run's full report: the untouched frozen ``BacktestResult``, derived
+
+    ``SummaryStats``, the broker's half-turn trade list, and the
+    ``CombineParams`` the run used. ``str(report)`` renders the combine
+    verdict, balance path, day-by-day trail, and summary stats as plain
+    aligned text — deterministically (pure function of the held frozen data;
+    no wall clock, no unordered iteration).
+    """
+
+    __slots__ = ("bars_gated", "params", "result", "stats", "trades")
+
+    result: BacktestResult
+    stats: SummaryStats
+    trades: tuple[HalfTradeModel, ...]
+    params: CombineParams
+    bars_gated: int | None
+    """Warmup-gated bars before the strategy's first decision (``None`` when
+    the strategy is not a ``SymbolStrategy``)."""
+
+    def __init__(
+        self,
+        *,
+        result: BacktestResult,
+        stats: SummaryStats,
+        trades: tuple[HalfTradeModel, ...],
+        params: CombineParams,
+        bars_gated: int | None = None,
+    ) -> None:
+        self.result = result
+        self.stats = stats
+        self.trades = trades
+        self.params = params
+        self.bars_gated = bars_gated
+
+    def __str__(self) -> str:
+        result = self.result
+        stats = self.stats
+        pct = (self.params.consistency_pct * 100).quantize(Decimal("1"))
+        cap = self.params.consistency_pct * result.total_profit
+        lines = [
+            f"== Topstep Combine {self.params.size.value}: {result.verdict.name} ==",
+            f"   {result.reason}",
+            "",
+            f"balance        {_money(result.starting_balance)} -> "
+            f"{_money(result.ending_balance)}  (net {_signed(stats.net_pnl)})",
+            f"total profit   {_money(result.total_profit)}  "
+            f"(target {_money(result.profit_target)})",
+            f"best day       {_money(result.best_day)}  (cap {_money(cap)} = {pct}% of total)",
+            f"MLL floor      {_money(result.floor)}  (distance {_money(stats.distance_to_floor)})",
+            f"days traded    {result.days_traded}   closing trades {stats.closed_trades}   "
+            f"half-turns {result.trade_count}",
+        ]
+        if result.breach is not None:
+            lines.append(
+                f"breach         {result.breach.kind.name} at equity "
+                f"{_money(result.breach.equity)} (limit {_money(result.breach.limit)})"
+            )
+        if self.bars_gated is not None:
+            lines.append(f"warmup         {self.bars_gated} bars gated before the first decision")
+        if result.rejections:
+            total = sum(count for _, count in result.rejections)
+            detail = ", ".join(f"{count}x code {code}" for code, count in result.rejections)
+            lines.append(
+                f"REJECTED       {total} order placement(s) refused by the broker "
+                f"({detail}) — intent diverged from execution"
+            )
+        lines.extend(("", "day trail"))
+        if result.day_records:
+            for record in result.day_records:
+                flag = " *" if record.had_trade else ""
+                lines.append(
+                    f"  {record.day}  eod={_money(record.eod_balance):>12}  "
+                    f"pnl={_signed(record.day_pnl):>10}  "
+                    f"floor={_money(record.floor_after):>10}{flag}"
+                )
+        else:
+            lines.append("  (no closed trading days)")
+        win_rate = "n/a" if stats.win_rate is None else f"{(stats.win_rate * 100).quantize(_CENT)}%"
+        expectancy = "n/a" if stats.expectancy is None else _signed(stats.expectancy)
+        factor = "n/a" if stats.profit_factor is None else str(stats.profit_factor.quantize(_CENT))
+        lines.extend(
+            (
+                "",
+                "summary stats",
+                f"  closed trades         {stats.closed_trades}",
+                f"  win rate (gross)      {win_rate}",
+                f"  expectancy (gross)    {expectancy}",
+                f"  profit factor (gross) {factor}",
+                f"  max drawdown (close)  {_money(stats.max_drawdown)}",
+                f"  net P&L               {_signed(stats.net_pnl)}",
+                f"  distance to floor     {_money(stats.distance_to_floor)}",
+                f"  consistency headroom  {_signed(stats.consistency_headroom)}",
+                f"  days traded           {stats.days_traded}",
+            )
+        )
+        lines.extend(("", _PROVENANCE))
+        return "\n".join(lines)
+
+    __repr__ = __str__
+
+
+class Backtest:
+    """The two-line runner: assemble the sim stack correctly and run it once.
+
+    ``data`` is a time-ordered ``Bar`` sequence (feed ordering is enforced at
+    construction); ``strategy`` is a bound-ready instance with typed
+    constructor parameters — never a class (docs/STRATEGY_API.md §4). Knobs
+    are only things that exist in this project: the account size (and its
+    optional Personal DLL), validation strictness, the sim account id, and
+    the fill/broker fidelity configs. Economics are never knobs.
+    """
+
+    def __init__(
+        self,
+        data: Sequence[Bar],
+        strategy: Strategy,
+        *,
+        account: AccountSize = AccountSize.S50K,
+        dll_enabled: bool = False,
+        validate: bool = True,
+        account_id: int = 1,
+        fill_config: BarFillConfig | None = None,
+        broker_config: SimBrokerConfig | None = None,
+        fee_model: TopstepFees | None = None,
+        **rejected: object,
+    ) -> None:
+        _refuse_strategy_class(strategy)
+        _refuse_unknown_kwargs(rejected)
+        self._bars: tuple[Bar, ...] = tuple(data)
+        self._strategy = strategy
+        self._account = account
+        self._dll_enabled = dll_enabled
+        self._account_id = account_id
+        self._fill_config = fill_config
+        self._broker_config = broker_config
+        self._fee_model = TopstepFees() if fee_model is None else fee_model
+        self._ran = False
+
+        # Instruments derive from the feed's contract ids — never hand-passed;
+        # each contract validates against ITS spec (validate_bars is single-spec).
+        groups: dict[str, list[Bar]] = {}
+        for bar in self._bars:
+            groups.setdefault(bar.bar_type.contract_id, []).append(bar)
+        self._instruments = {cid: _spec_for_contract_id(cid) for cid in groups}
+        if validate:
+            errors: list[ValidationIssue] = []
+            for cid, group in groups.items():
+                report = validate_bars(group, self._instruments[cid])
+                # The refuse/proceed decision is the validator's (report.ok:
+                # INFO-only findings proceed); the filter below only strips
+                # INFO findings from the error listing.
+                if not report.ok:
+                    errors.extend(i for i in report.issues if i.code not in INFO_CODES)
+            if errors:
+                raise DataValidationError(tuple(errors))
+        # Construction enforces the ordering invariant even under validate=False:
+        # the engine trusts the DataFeed contract unconditionally.
+        self._feed = ListBarFeed(self._bars)
+
+    @classmethod
+    def from_dataframe(
+        cls,
+        df: Any,
+        strategy: Strategy,
+        *,
+        contract_id: str,
+        stamp: Literal["open", "close"],
+        unit: AggregateBarUnit,
+        unit_number: int,
+        account: AccountSize = AccountSize.S50K,
+        dll_enabled: bool = False,
+        validate: bool = True,
+        account_id: int = 1,
+        fill_config: BarFillConfig | None = None,
+        broker_config: SimBrokerConfig | None = None,
+        fee_model: TopstepFees | None = None,
+        **rejected: object,
+    ) -> Backtest:
+        """Wrangle a pandas OHLCV DataFrame, then assemble as usual.
+
+        ``stamp``, ``unit``, and ``unit_number`` stay REQUIRED (no defaults),
+        exactly as on the wrangler: the caller must declare whether source
+        timestamps are bar opens or closes AND the bar span — guessing the
+        stamp is the classic silent one-bar look-ahead, and defaulting the
+        span would mis-stamp every non-1-minute bar's close (a 5-minute bar
+        stamped with a 60s span acts 4 minutes early against the session
+        clock).
+        """
+        # Refusals come BEFORE the wrangle: a wrangler error (naive
+        # timestamps, off-grid row) must never mask a §4 rejection.
+        _refuse_strategy_class(strategy)
+        _refuse_unknown_kwargs(rejected)
+        bars = bars_from_dataframe(
+            df,
+            contract_id=contract_id,
+            spec=_spec_for_contract_id(contract_id),
+            unit=unit,
+            unit_number=unit_number,
+            stamp=stamp,
+        )
+        return cls(
+            bars,
+            strategy,
+            account=account,
+            dll_enabled=dll_enabled,
+            validate=validate,
+            account_id=account_id,
+            fill_config=fill_config,
+            broker_config=broker_config,
+            fee_model=fee_model,
+            **rejected,
+        )
+
+    def run(self) -> Report:
+        """Run to completion synchronously (wraps ``asyncio.run``).
+
+        Raises:
+            RuntimeError: If called from inside a running event loop — use
+                ``await backtest.arun()`` there instead.
+        """
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self.arun())
+        raise RuntimeError(
+            "Backtest.run() was called from a running event loop; "
+            "use `await backtest.arun()` instead"
+        )
+
+    async def arun(self) -> Report:
+        """Assemble fresh engine state, run once, and report.
+
+        Clock, kernel, broker, engine, and the strategy instance are all
+        stateful and single-use, so a ``Backtest`` refuses to run twice.
+        """
+        if self._ran:
+            raise RuntimeError(
+                "this Backtest has already run — engine, broker, and strategy "
+                "state are single-use; construct a new Backtest (with a fresh "
+                "strategy instance) for another run"
+            )
+        self._ran = True
+        params = combine_params(self._account, dll_enabled=self._dll_enabled)
+        # ONE clock for broker AND engine — the assembly invariant this facade
+        # exists to enforce (a broker on its own clock stamps accepted_ts=0,
+        # making every order eligible for the current bar: silent look-ahead).
+        clock = TestClock()
+        broker = SimBroker(
+            account_id=self._account_id,
+            instruments=self._instruments,
+            fill_model=BarFillModel(self._fill_config),
+            fee_model=self._fee_model,
+            kernel=CombineKernel(params),
+            clock=clock,
+            config=self._broker_config,
+        )
+        engine = BacktestEngine(
+            feed=self._feed, broker=broker, strategy=self._strategy, clock=clock
+        )
+        result = await engine.run()
+        trades = broker.trades
+        stats = compute_summary(result, trades=trades, consistency_pct=params.consistency_pct)
+        bars_gated = (
+            self._strategy.bars_gated if isinstance(self._strategy, SymbolStrategy) else None
+        )
+        return Report(
+            result=result, stats=stats, trades=trades, params=params, bars_gated=bars_gated
+        )

topstep_backtest/indicators/__init__.py

@@ -0,0 +1,46 @@
+"""topstep_backtest.indicators — every indicator is TA-Lib.
+
+``TalibIndicator`` drives any of TA-Lib's ~160 functions bar by bar; the named
+classes are typed spellings of the common ones. See ``talib_adapter`` for the
+causality, streaming-equals-batch, and bounded-history parity guarantees.
+"""
+
+from .base import Indicator, NotReadyError, ValueSource
+from .library import (
+    Adx,
+    Atr,
+    BBands,
+    Cross,
+    Ema,
+    Highest,
+    Lowest,
+    Macd,
+    Obv,
+    Rsi,
+    Sma,
+    StdDev,
+    Stoch,
+)
+from .talib_adapter import TalibIndicator, TalibLine, talib_function_names
+
+__all__ = [
+    "Adx",
+    "Atr",
+    "BBands",
+    "Cross",
+    "Ema",
+    "Highest",
+    "Indicator",
+    "Lowest",
+    "Macd",
+    "NotReadyError",
+    "Obv",
+    "Rsi",
+    "Sma",
+    "StdDev",
+    "Stoch",
+    "TalibIndicator",
+    "TalibLine",
+    "ValueSource",
+    "talib_function_names",
+]

topstep_backtest/indicators/base.py

@@ -0,0 +1,57 @@
+"""The indicator surface every consumer depends on.
+
+Kept in its own module so ``protocols``-style contracts stay separable from the
+TA-Lib machinery that implements them: ``SymbolStrategy.use()`` needs only
+``Indicator``, and ``Cross`` needs only ``_ValueSource`` — neither imports
+TA-Lib.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from decimal import Decimal
+
+    from ..protocols import Bar
+
+__all__ = ["Indicator", "NotReadyError"]
+
+
+class NotReadyError(Exception):
+    """``value`` was read before the indicator had seen ``lookback`` bars."""
+
+
+@runtime_checkable
+class Indicator(Protocol):
+    """The surface ``SymbolStrategy.use()`` requires of a registered indicator."""
+
+    @property
+    def lookback(self) -> int:
+        """Bars needed before the indicator is ready."""
+        ...
+
+    @property
+    def ready(self) -> bool: ...
+
+    def update(self, bar: Bar) -> None: ...
+
+
+@runtime_checkable
+class ValueSource(Protocol):
+    """Minimal structural input for ``Cross``: anything exposing a Decimal series.
+
+    Runtime-checkable so ``use()`` can refuse a ``Cross`` over something with no
+    ``value`` (notably another ``Cross``) at registration, rather than letting it
+    die with an ``AttributeError`` hours into a run — and only once both inner
+    inputs happen to be ready.
+    """
+
+    @property
+    def lookback(self) -> int: ...
+
+    @property
+    def ready(self) -> bool: ...
+
+    @property
+    def value(self) -> Decimal: ...