topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/indicators/talib_adapter.py

@@ -0,0 +1,657 @@
+"""TA-Lib as the single source of every technical indicator.
+
+Every indicator in this framework is TA-Lib: bars are buffered as float64
+arrays and handed to ``talib``'s abstract API, which computes the indicator and
+yields the value for the just-closed bar. Nothing here re-implements an
+indicator formula, so there is no second implementation to drift. 152 of
+TA-Lib's 161 functions are wrappable; the other nine are refused at
+construction because they could only fail silently (see ``_probe``,
+``_INDEX_OUTPUT_FUNCTIONS``, and ``_input_slots``).
+
+Three properties make a batch C library safe to drive bar-by-bar:
+
+**Causal by construction.** ``update(bar)`` appends to a buffer that holds only
+already-closed bars 0…t and reads the LAST element of TA-Lib's output. The
+adapter structurally cannot see bar t+1, so the no-look-ahead invariant in
+AGENTS.md holds for free. Swept across every wrappable function in
+``tests/property/test_indicator_props.py``.
+
+**Streaming == batch, bit for bit.** TA-Lib recomputes from index 0 on every
+call, and every function it exposes is causal, so ``FUNC(bars[:t+1])[-1] ==
+FUNC(bars)[t]`` exactly — over the SAME bars. Feeding a prefix cannot produce a
+number that a batch run over those bars would not. (The one class of exception
+is index-valued outputs, which report an offset into the array they were given
+rather than a value; those functions are refused outright — see
+``_INDEX_OUTPUT_FUNCTIONS``.)
+
+**Bounded, deterministic history — the parity decision.** The buffer keeps the
+last ``history_bars`` bars, not everything since inception. That is not a
+memory optimisation, it is what makes ``Ema(20)`` the SAME number in sim and
+live: an unbounded buffer would make every value depend on where the series
+happened to start, and a live session (which warms up from a finite history
+fetch) could never reproduce a backtest that began two years earlier. With a
+fixed window the value is a pure function of the last ``history_bars`` bars, so
+preloading exactly ``history_bars`` bars live reproduces the backtest's Decimal
+bit-for-bit.
+
+Two consequences of the window that callers must know:
+
+*Parity begins at ``history_bars``, not at ``lookback``.* ``ready`` flips as
+soon as a value EXISTS (TA-Lib's lookback), but until ``warm`` is True the
+buffer is still shorter than the window and the value therefore depends on
+where this particular run started. Bars in ``[lookback, warm)`` are cold-start
+dependent. Gate on ``warm`` where exact sim/live agreement matters.
+
+*Windowed == unbounded holds for the decaying family, not universally.*
+Recursive functions whose weights decay exponentially (EMA, Wilder RSI/ATR/ADX,
+MACD, DEMA/TEMA, T3, MAMA, HT_TRENDLINE) reach a point past which the truncated
+tail falls below float64 resolution, and ``_STABILITY_FACTOR`` (64x ``lookback``,
+floor ``_MIN_HISTORY``) sits above it — those ARE bit-identical to an unbounded
+run, asserted in ``tests/property/test_indicator_props.py``. Three other classes
+are NOT, by construction rather than by accident:
+
+- **Accumulators** (OBV, AD) sum with weight 1.0 forever, so their LEVEL is
+  window-relative. Use slope or divergence, never the absolute level.
+- **Running-sum functions** (SMA and anything built on it — STOCH's slowd, CCI,
+  MFI, ACCBANDS, BETA, ADOSC) carry float rounding that depends on where the
+  sum began, so they sit within an ulp or so of an unbounded run rather than
+  exactly on it.
+- **Adaptive smoothers** (KAMA, HT_DCPERIOD) can drop their effective smoothing
+  constant far below what ``lookback`` suggests in choppy data, so 64x is not
+  always enough; functions whose memory is set by a RATE rather than by a period
+  (SAR/SAREXT via ``acceleration``, MAMA via ``slowlimit``) get an explicitly
+  derived window instead — see ``_rate_driven_window``.
+
+None of this weakens backtest/live parity, which is what the framework actually
+depends on: both sides run the same window over the same bars, so both get the
+same number regardless of which class the function falls into.
+
+Values cross into ``Decimal`` at this boundary and are NOT tick-snapped — an
+indicator level is not a tradeable price and rounding it to the grid would be a
+lie. TA-Lib computes in float64, so indicator values are float-precise, not
+Decimal-exact; float arithmetic is deterministic, so reruns remain byte-equal.
+"""
+
+from __future__ import annotations
+
+import operator
+from decimal import Decimal
+from math import ceil, isfinite
+from typing import TYPE_CHECKING, Final, Protocol, cast
+
+import numpy as np
+from talib import abstract as _talib_abstract  # pyright: ignore[reportMissingTypeStubs]
+
+from .base import NotReadyError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Mapping
+
+    from numpy.typing import NDArray
+
+    from ..protocols import Bar
+
+__all__ = ["TalibIndicator", "TalibLine", "talib_function_names"]
+
+
+# --------------------------------------------------------------------------- #
+# The typed seam over TA-Lib's untyped abstract API
+# --------------------------------------------------------------------------- #
+
+# ``talib.abstract.Function`` is a plain untyped factory (its .pyi does not
+# declare it), so the whole untyped surface is pinned to this Protocol ONCE,
+# here, and every use downstream is fully typed.
+
+
+class _TalibFunction(Protocol):
+    """The slice of ``talib.abstract.Function`` this adapter drives."""
+
+    lookback: int
+    parameters: Mapping[str, int | float]
+    input_names: Mapping[str, str | list[str]]
+    output_names: list[str]
+
+    def __call__(
+        self, inputs: Mapping[str, NDArray[np.float64]], **params: int | float
+    ) -> NDArray[np.float64] | list[NDArray[np.float64]]: ...
+
+
+_make_function: Final = cast(
+    "Callable[[str], _TalibFunction]",
+    _talib_abstract.Function,  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
+)
+
+_BAR_FIELDS: Final[frozenset[str]] = frozenset({"open", "high", "low", "close", "volume"})
+"""The input names TA-Lib may ask for that a Tier-0 OHLCV bar can supply."""
+
+_INDEX_OUTPUT_FUNCTIONS: Final[frozenset[str]] = frozenset({"MAXINDEX", "MININDEX", "MINMAXINDEX"})
+"""Functions whose output is an OFFSET into the array passed in, not a value.
+
+A bounded buffer makes that offset meaningless: before the window fills it is
+an index from the series start, after it is a window-relative position that
+shifts every bar. Refused rather than silently reinterpreted.
+"""
+
+_MIN_HISTORY: Final = 512
+"""Window floor: short-period indicators still get a generous tail."""
+
+_STABILITY_FACTOR: Final = 64
+"""Window = this many multiples of ``lookback`` — see the module docstring."""
+
+_DECAY_TARGET: Final = 40.0
+"""e-folds of decay to retain.
+
+``ln(2**-53) ≈ -36.7``, so 40 e-folds puts the truncated tail below float64
+resolution. Used to size the functions whose memory is governed by a RATE
+parameter that ``lookback`` does not reflect at all.
+"""
+
+_KAMA_MIN_HISTORY: Final = 9000
+"""KAMA's smoothing constant floors at ``(2/31)**2 ≈ 0.00416`` in flat/choppy
+data — a regime its ``lookback`` gives no hint of — needing ~8800 bars to decay
+below float64 resolution."""
+
+
+def talib_function_names() -> tuple[str, ...]:
+    """Every TA-Lib function name ``TalibIndicator`` can wrap, sorted."""
+    import talib
+
+    return tuple(sorted(cast("list[str]", talib.get_functions())))
+
+
+# --------------------------------------------------------------------------- #
+# Bounded bar history
+# --------------------------------------------------------------------------- #
+
+
+class _RingBuffer:
+    """Last ``window`` float64 samples, contiguous for a zero-copy TA-Lib call.
+
+    Writes forward into an over-allocated array and compacts only when it
+    fills, so appends are amortised O(1) and ``view()`` is a plain slice — no
+    per-bar allocation and no ``np.roll``.
+    """
+
+    __slots__ = ("_data", "_n", "_window")
+
+    def __init__(self, window: int) -> None:
+        self._window = window
+        self._data: NDArray[np.float64] = np.empty(2 * window, dtype=np.float64)
+        self._n = 0
+
+    def append(self, value: float) -> None:
+        if self._n == self._data.shape[0]:
+            keep = self._window - 1
+            if keep > 0:
+                self._data[:keep] = self._data[self._n - keep : self._n]
+            self._n = keep
+        self._data[self._n] = value
+        self._n += 1
+
+    def view(self) -> NDArray[np.float64]:
+        """The last ``min(seen, window)`` samples, oldest first.
+
+        A BORROWED view into the backing store: valid only until the next
+        ``append``, which may recycle exactly this memory during compaction.
+        Callers must consume it within the call they pass it to.
+        """
+        return self._data[max(0, self._n - self._window) : self._n]
+
+
+# --------------------------------------------------------------------------- #
+# Multi-output views
+# --------------------------------------------------------------------------- #
+
+
+class TalibLine:
+    """One named output of a multi-output indicator, usable wherever a single
+    value series is (notably as a ``Cross`` input).
+
+    A line does NOT update itself — it reads whatever its owner last computed,
+    so registering the OWNER with ``use()`` is what keeps it current.
+    ``SymbolStrategy.use()`` resolves a ``Cross`` input through ``owner`` for
+    exactly this reason.
+
+    Deliberately NO ``update`` method: that keeps a line from satisfying
+    ``Indicator``, so ``use(macd.line("macd"))`` — which would register
+    something that can never advance and would gate the strategy forever — is a
+    type error, and ``use()`` rejects it at runtime too. Register the owner.
+    """
+
+    __slots__ = ("_name", "_owner")
+
+    def __init__(self, owner: TalibIndicator, name: str) -> None:
+        self._owner = owner
+        self._name = name
+
+    @property
+    def owner(self) -> TalibIndicator:
+        """The indicator that computes this line (what ``use()`` registers)."""
+        return self._owner
+
+    @property
+    def name(self) -> str:
+        """This line's TA-Lib output name (e.g. ``"macdsignal"``)."""
+        return self._name
+
+    @property
+    def lookback(self) -> int:
+        return self._owner.lookback
+
+    @property
+    def ready(self) -> bool:
+        return self._owner.ready
+
+    @property
+    def warm(self) -> bool:
+        return self._owner.warm
+
+    @property
+    def value(self) -> Decimal:
+        return self._owner.get(self._name)
+
+    def __repr__(self) -> str:
+        return f"{self._owner!r}.line({self._name!r})"
+
+
+# --------------------------------------------------------------------------- #
+# The generic adapter
+# --------------------------------------------------------------------------- #
+
+
+class TalibIndicator:
+    """Any TA-Lib function, driven bar by bar.
+
+    ``TalibIndicator("RSI", timeperiod=14)`` is the whole API; the named
+    classes in ``library.py`` are thin, typed spellings of it. Parameters are
+    TA-Lib's own (``timeperiod``, ``fastperiod``, ``nbdevup``, ``matype``, …),
+    validated against the function's declared signature AND run past TA-Lib
+    once at construction, so a typo or an out-of-range value raises here rather
+    than silently using a default or dying mid-backtest.
+
+    ``price`` redirects a single-series function onto another bar field —
+    ``TalibIndicator("MAX", price="high", timeperiod=20)`` is a rolling high.
+    Functions that declare their own multi-field inputs (ATR wants high/low/
+    close) reject it.
+
+    **Thread-safety.** ``talib``'s ``Function`` keeps its configured parameters
+    in a ``threading.local``, so a Function configured on one thread silently
+    reverts to TA-Lib's DEFAULTS on another — an ``EMA(50)`` built on the main
+    thread would quietly compute ``EMA(30)`` inside a worker, with no error.
+    This adapter therefore treats the Function object as stateless: parameters
+    are held here as plain data and passed on EVERY call, and a redirected
+    ``price`` is applied by choosing which bar field fills the input slot rather
+    than by mutating ``input_names``. Instances are safe to build on one thread
+    and drive on another (though a single instance is still not safe to drive
+    from two threads at once — it has per-bar state).
+    """
+
+    __slots__ = (
+        "_buffers",
+        "_dirty",
+        "_func",
+        "_latest",
+        "_lookback",
+        "_name",
+        "_params",
+        "_seen",
+        "_slots",
+        "_window",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        price: str | None = None,
+        history: int | None = None,
+        **params: int | float,
+    ) -> None:
+        self._name = name.upper()
+        func = _resolve_function(self._name)
+        # Assigning `parameters` is what makes `lookback` reflect OUR periods —
+        # a fresh Function reports the DEFAULT period's lookback. We then keep
+        # the values here as well and re-pass them on every call, because that
+        # assignment is thread-local (see the class docstring).
+        self._params = _coerce_params(func, self._name, params)
+        if self._params:
+            func.parameters = self._params
+        self._func = func
+        self._lookback = func.lookback + 1
+        self._slots = _input_slots(func, self._name, price)
+        self._window = _resolve_window(self._name, func, self._lookback, history)
+        _probe(func, self._name, self._params, self._slots)
+        self._buffers = {key: _RingBuffer(self._window) for key, _ in self._slots}
+        self._latest: dict[str, float] = {}
+        self._seen = 0
+        self._dirty = True
+
+    # -- the Indicator surface ----------------------------------------------
+
+    @property
+    def lookback(self) -> int:
+        """Bars needed before the first value exists (TA-Lib's lookback + 1)."""
+        return self._lookback
+
+    @property
+    def history_bars(self) -> int:
+        """Bars retained. Preload this many live for bit-exact sim/live parity."""
+        return self._window
+
+    @property
+    def warm(self) -> bool:
+        """True once the buffer is full, i.e. from the first PARITY-exact bar.
+
+        ``ready`` says a value exists; ``warm`` says the value no longer depends
+        on where this run started. Gate on this when sim and live must agree
+        bit-for-bit (see the module docstring).
+        """
+        return self._seen >= self._window
+
+    @property
+    def outputs(self) -> tuple[str, ...]:
+        """This function's output names, TA-Lib's order (``value`` is the first)."""
+        return tuple(self._func.output_names)
+
+    @property
+    def function_name(self) -> str:
+        """The wrapped TA-Lib function, upper-cased (e.g. ``"MACD"``)."""
+        return self._name
+
+    @property
+    def ready(self) -> bool:
+        if self._seen < self._lookback:
+            return False
+        self._compute()
+        return bool(self._latest)
+
+    @property
+    def value(self) -> Decimal:
+        """The primary (first) output for the most recent bar."""
+        return self.get(self._func.output_names[0])
+
+    def get(self, output: str) -> Decimal:
+        """A named output for the most recent bar."""
+        if output not in self._func.output_names:
+            raise KeyError(f"{self!r} has no output {output!r}; it has {self.outputs}")
+        if self._seen < self._lookback:
+            raise NotReadyError(f"{self!r} needs {self._lookback} bars, has seen {self._seen}")
+        self._compute()
+        if not self._latest:
+            raise NotReadyError(
+                f"{self!r} has seen {self._seen} bars but produced no finite value for this "
+                f"bar — degenerate input for this function, not warmup"
+            )
+        return _to_decimal(self._latest[output])
+
+    def line(self, output: str) -> TalibLine:
+        """A ``Cross``-compatible view of one named output."""
+        if output not in self._func.output_names:
+            raise KeyError(f"{self!r} has no output {output!r}; it has {self.outputs}")
+        return TalibLine(self, output)
+
+    def lines(self) -> Iterator[TalibLine]:
+        """A view per output, in TA-Lib's order."""
+        return (TalibLine(self, name) for name in self._func.output_names)
+
+    def update(self, bar: Bar) -> None:
+        for key, field in self._slots:
+            self._buffers[key].append(_bar_field(bar, field))
+        self._seen += 1
+        self._dirty = True
+
+    # -- the one TA-Lib call -------------------------------------------------
+
+    def _compute(self) -> None:
+        """Run TA-Lib over the buffered window and latch the last row.
+
+        Lazy and memoised per bar: a strategy that never reads a value pays
+        only for the buffer append, and reading three lines of a MACD costs one
+        TA-Lib call, not three. The dirty flag is cleared only AFTER the call
+        succeeds, so a raising TA-Lib call is never memoised as a benign
+        "no value yet".
+
+        The arrays handed over are borrowed views into the ring buffers, valid
+        only for the duration of this call — never read them back off the
+        Function afterwards.
+        """
+        if not self._dirty:
+            return
+        self._latest = {}
+        if self._seen < self._lookback:
+            self._dirty = False
+            return
+        raw = self._func(
+            {key: buffer.view() for key, buffer in self._buffers.items()}, **self._params
+        )
+        arrays = raw if isinstance(raw, list) else [raw]
+        latest: dict[str, float] = {}
+        for name, array in zip(self._func.output_names, arrays, strict=True):
+            value = float(array[-1])
+            # NaN means "no value for this bar". Usually that is warmup, which
+            # the `_seen < _lookback` gate above already covers — but a few
+            # functions (IMI on a dead tape where every open == close) divide
+            # 0/0 and go non-finite long AFTER their lookback. Either way the
+            # value genuinely does not exist, so the whole row is withheld.
+            if not isfinite(value):
+                self._dirty = False
+                return
+            latest[name] = value
+        self._latest = latest
+        self._dirty = False
+
+    def __repr__(self) -> str:
+        parts = [repr(self._name)]
+        parts += [f"{key}={value}" for key, value in self._func.parameters.items()]
+        return f"TalibIndicator({', '.join(parts)})"
+
+
+# --------------------------------------------------------------------------- #
+# construction helpers
+# --------------------------------------------------------------------------- #
+
+
+def _resolve_function(name: str) -> _TalibFunction:
+    if name in _INDEX_OUTPUT_FUNCTIONS:
+        raise ValueError(
+            f"{name} returns an INDEX into the array it is given, not a value; a bounded "
+            f"history buffer makes that offset meaningless. Use the value-returning form "
+            f"(MAX/MIN/MINMAX) instead."
+        )
+    try:
+        return _make_function(name)
+    except Exception as error:  # talib raises bare Exception for a bad name
+        raise ValueError(f"unknown TA-Lib function {name!r}") from error
+
+
+def _coerce_params(
+    func: _TalibFunction, name: str, params: Mapping[str, int | float]
+) -> dict[str, int | float]:
+    """Validate parameter names and coerce values to TA-Lib's declared types.
+
+    TA-Lib type-checks int vs float strictly, so each value is converted to
+    whatever the function declares. The conversion REFUSES to be lossy: a
+    fractional value for an integer parameter (``Sma(14.7)``, ``matype=2.9``)
+    is a mistake, and silently truncating it would contradict this class's
+    promise that a bad parameter raises here.
+    """
+    if not params:
+        return {}
+    declared = dict(func.parameters)
+    unknown = set(params) - set(declared)
+    if unknown:
+        raise ValueError(
+            f"{name} takes no parameter(s) {sorted(unknown)}; it accepts {sorted(declared)}"
+        )
+    coerced: dict[str, int | float] = {}
+    for key, value in params.items():
+        if isinstance(value, bool):
+            raise ValueError(f"{name} parameter {key} must be a number, got {value!r}")
+        try:
+            if isinstance(declared[key], float):
+                coerced[key] = float(value)
+            elif isinstance(value, float):
+                if not value.is_integer():
+                    raise ValueError(
+                        f"{name} parameter {key} is an integer; got {value!r} "
+                        f"(truncating it would silently change the indicator)"
+                    )
+                coerced[key] = int(value)
+            else:
+                coerced[key] = operator.index(value)
+        except (TypeError, OverflowError) as error:
+            raise ValueError(f"{name} parameter {key}={value!r} is not a valid number") from error
+    return coerced
+
+
+def _input_slots(func: _TalibFunction, name: str, price: str | None) -> tuple[tuple[str, str], ...]:
+    """``(talib input key, bar field)`` pairs, deduplicated in TA-Lib's order.
+
+    Redirecting ``price`` changes which BAR FIELD fills TA-Lib's input slot
+    rather than mutating ``func.input_names`` — that assignment is thread-local
+    and would silently revert off-thread (see ``TalibIndicator``'s docstring).
+    """
+    declared = func.input_names
+    if price is not None:
+        if list(declared) != ["price"]:
+            raise ValueError(
+                f"price= only applies to single-series functions; {name} takes "
+                f"{_describe_inputs(declared)}"
+            )
+        if price not in _BAR_FIELDS:
+            raise ValueError(f"price must be one of {sorted(_BAR_FIELDS)}, got {price!r}")
+        return ((cast("str", declared["price"]), price),)
+
+    slots: list[tuple[str, str]] = []
+    for requested in declared.values():
+        keys = [requested] if isinstance(requested, str) else list(requested)
+        for key in keys:
+            if key not in _BAR_FIELDS:
+                raise ValueError(
+                    f"{name} needs a non-bar input {key!r}, which an OHLCV feed cannot supply"
+                )
+            if all(key != existing for existing, _ in slots):
+                slots.append((key, key))
+    return tuple(slots)
+
+
+def _rate_driven_window(name: str, params: Mapping[str, int | float]) -> int:
+    """Window for functions whose memory is set by a RATE, not by a period.
+
+    SAR's ``lookback`` is 2 no matter how small ``acceleration`` is, and MAMA's
+    is fixed while ``slowlimit`` sets its actual memory — so the usual
+    ``64 * lookback`` sizing is blind to them. Derive the window from the rate
+    instead: an update of rate ``r`` decays by ``(1 - r)`` per bar, so
+    ``_DECAY_TARGET / r`` bars puts the tail under float64 resolution.
+    """
+    if name == "KAMA":
+        return _KAMA_MIN_HISTORY
+    rates: list[float] = []
+    if name in {"SAR", "SAREXT"}:
+        rates = [float(v) for k, v in params.items() if "acceleration" in k and float(v) > 0]
+    elif name == "MAMA":
+        rates = [float(params.get("slowlimit", 0.05))]
+    positive = [r for r in rates if r > 0]
+    return ceil(_DECAY_TARGET / min(positive)) if positive else 0
+
+
+def _resolve_window(name: str, func: _TalibFunction, lookback: int, history: int | None) -> int:
+    if history is not None:
+        try:
+            history = operator.index(history)
+        except TypeError as error:
+            raise ValueError(f"history must be an integer, got {history!r}") from error
+        if history < lookback:
+            raise ValueError(
+                f"history={history} is below {name}'s lookback of {lookback} bars; "
+                f"the indicator could never become ready"
+            )
+        return history
+    return max(
+        _MIN_HISTORY,
+        _STABILITY_FACTOR * lookback,
+        _rate_driven_window(name, func.parameters),
+    )
+
+
+def _probe(
+    func: _TalibFunction,
+    name: str,
+    params: Mapping[str, int | float],
+    slots: tuple[tuple[str, str], ...],
+) -> None:
+    """Run the configured function once on synthetic bars, at construction.
+
+    Catches two failure modes that would otherwise surface far away:
+
+    *Out-of-range parameters.* TA-Lib validates ranges in C and raises only
+    when it actually runs, and each function's limits differ (``EMA`` accepts
+    ``timeperiod=1``, ``RSI`` and ``STDDEV`` need 2, …) with nothing in the
+    abstract API exposing them. Rather than hard-code a table that would drift
+    from the library, ask the library.
+
+    *Functions that can never produce a finite value at futures price levels.*
+    ``EXP``/``COSH``/``SINH`` overflow and ``ACOS``/``ASIN`` are out of domain
+    once prices leave [-1, 1], and a permanently non-finite indicator would
+    read as "not ready" forever — ``SymbolStrategy`` would silently swallow
+    every bar and ``on_bar`` would never fire. So the probe uses a
+    PRICE-REALISTIC series and rejects a non-finite result, rather than merely
+    checking that the call did not raise.
+    """
+    length = max(func.lookback + 1, 2)
+    steps = np.arange(length, dtype=np.float64)
+    close = 5000.0 + steps + 25.0 * np.sin(steps / 7.0)
+    inputs = {
+        "open": close - 0.5,
+        "high": close + 1.5,
+        "low": close - 1.5,
+        "close": close,
+        "volume": 1000.0 + 10.0 * (steps % 7),
+    }
+    probe_inputs = {key: inputs[field] for key, field in slots}
+    shown = ", ".join(f"{key}={value}" for key, value in params.items())
+    try:
+        raw = func(probe_inputs, **params)
+    except Exception as error:
+        raise ValueError(f"TA-Lib rejected {name}({shown}): {error}") from error
+    arrays = raw if isinstance(raw, list) else [raw]
+    if not all(isfinite(float(array[-1])) for array in arrays):
+        raise ValueError(
+            f"{name}({shown}) produces no finite value at futures price levels "
+            f"(~5000), so it could never become ready; it is not usable on price bars"
+        )
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+
+def _describe_inputs(inputs: Mapping[str, str | list[str]]) -> str:
+    parts: list[str] = []
+    for requested in inputs.values():
+        parts.extend([requested] if isinstance(requested, str) else requested)
+    return "/".join(parts)
+
+
+def _bar_field(bar: Bar, field: str) -> float:
+    if field == "open":
+        return float(bar.open)
+    if field == "high":
+        return float(bar.high)
+    if field == "low":
+        return float(bar.low)
+    if field == "close":
+        return float(bar.close)
+    return float(bar.volume)
+
+
+def _to_decimal(value: float) -> Decimal:
+    """float64 -> Decimal at the library boundary.
+
+    Via ``repr`` (shortest round-tripping form), so ``Decimal`` shows the
+    number a reader would recognise rather than the exact binary expansion.
+    Distinct finite floats round-trip to distinct Decimal strings — signed
+    zeros aside, which keep their sign but compare equal, as they do as floats.
+    """
+    return Decimal(repr(value))

topstep_backtest/metrics/__init__.py

@@ -0,0 +1,5 @@
+"""topstep_backtest.metrics"""
+
+from .stats import SummaryStats, compute_summary
+
+__all__ = ["SummaryStats", "compute_summary"]