stochastic-sh 1.0.0__tar.gz

stochastic_sh-1.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: stochastic-sh
+Version: 1.0.0
+Summary: Stochastic strategy SDK — write and run trading strategies against the engine
+Requires-Python: >=3.12
+Requires-Dist: grpcio>=1.80
+Requires-Dist: protobuf>=6.31
+Requires-Dist: polars>=1.40

stochastic_sh-1.0.0/README.md

@@ -0,0 +1,50 @@
+# Stochastic SDK
+
+The Python SDK for writing and running trading strategies against a local
+Stochastic engine. `import stochastic` to build a strategy; the `examples/`
+directory has runnable strategies to start from.
+
+## Prerequisites
+
+- Python 3.12+ on your PATH
+- A running Stochastic engine — install the CLI, then bring up the stack:
+
+```
+brew install stochastic-sh/tap/stochastic-ctl
+
+stochastic-ctl infra up
+```
+
+## Install
+
+Create a virtual environment and install the SDK into it:
+
+```
+python -m venv .venv
+
+. .venv/bin/activate
+
+pip install -e .
+```
+
+`pip install -e .` resolves the runtime dependencies (grpcio, protobuf, polars)
+from `pyproject.toml`. If you would rather not install, add this directory to
+`PYTHONPATH` instead — but the editable install is the supported path.
+
+## Run an example
+
+```
+python examples/interval_trader.py
+```
+
+The example strategies connect to the engine's gateway on localhost, so bring
+the engine up first (`stochastic-ctl infra up`, then start a run). See
+<https://docs.stochastic.sh> for the full backtest walkthrough.
+
+## What's in here
+
+- `stochastic/` — the SDK package: strategy base classes, runtime, metrics,
+  windowing, plus the generated gRPC stubs under `stochastic/v1/`
+- `examples/` — runnable example strategies + `examples/requirements.txt`
+- `pyproject.toml` — packaging metadata + runtime dependencies
+- `requirements.txt` — the runtime dependencies (mirror of `pyproject.toml`)

stochastic_sh-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stochastic-sh"
+version = "1.0.0"
+description = "Stochastic strategy SDK — write and run trading strategies against the engine"
+requires-python = ">=3.12"
+# Runtime deps the package actually imports. Pins are dictated by the
+# generated gRPC/protobuf stubs under stochastic/v1: the *_pb2_grpc.py carry a
+# hard GRPC_GENERATED_VERSION = 1.80.0 guard, and the *_pb2.py validate against
+# protobuf gencode 6.31.1 — older runtimes are rejected at import time. polars
+# powers the frame-stored metrics runtime (metrics_polars).
+dependencies = [
+    "grpcio>=1.80",
+    "protobuf>=6.31",
+    "polars>=1.40",
+]
+
+# Distribution name is `stochastic-sh` — matching the GitHub org, because the
+# bare `stochastic` is taken on PyPI. The IMPORT name stays `stochastic`: all
+# example code and the ibkr-wrapper already `import stochastic` /
+# `from stochastic.v1 import ...`, and the two names are independent. Same
+# shape as `pip install scikit-learn` / `import sklearn` — you type the
+# distribution once and the import every day.
+#
+# VERSION TRACKS THE PRODUCT, not the SDK's own history. It jumped 0.14.0 ->
+# 1.0.0 with the v1 release so `pip show stochastic-sh` and the app's About
+# box agree. A PyPI version can never be reused, so this is a one-way door.
+[tool.setuptools.packages.find]
+include = ["stochastic*"]

stochastic_sh-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stochastic_sh-1.0.0/stochastic/__init__.py

@@ -0,0 +1,41 @@
+"""
+Stochastic Python SDK
+
+Public surface:
+    Bar, unpack_tick    consume the Tick wire format
+    Reason              recommended OrderRequest.reason constants
+    RollingWindow       rolling-window primitive with built-in reductions
+    WilderRSI           recursive RSI — state a rolling window cannot express
+    WilderRSIPanel      one WilderRSI per (instrument, period)
+    Strategy, Context   strategy framework (decorator + class shape)
+    strategy            decorator alternative to subclassing Strategy
+    run                 top-level entry point — runs a strategy against the gateway
+    MetricsJob          metrics-job framework (pre-computed metric-sets)
+    MetricsContext      per-stream context passed to metrics-job hooks
+    run_metrics         top-level entry point — runs a metrics job against the engine
+"""
+
+from stochastic.indicators import WilderRSI, WilderRSIPanel
+from stochastic.metrics import MetricsContext, MetricsJob, run_metrics
+from stochastic.reason import Reason
+from stochastic.runtime import Bar, unpack_tick
+from stochastic.strategy import Context, Strategy, run, strategy
+from stochastic.windowing import RollingWindow
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "Bar",
+    "Context",
+    "MetricsContext",
+    "MetricsJob",
+    "Reason",
+    "RollingWindow",
+    "Strategy",
+    "WilderRSI",
+    "WilderRSIPanel",
+    "run",
+    "run_metrics",
+    "strategy",
+    "unpack_tick",
+]

stochastic_sh-1.0.0/stochastic/fingerprint.py

@@ -0,0 +1,194 @@
+"""
+Content hashing for strategy identity
+
+Answers "did anything change since the backtest?" without requiring git
+
+A vcs_ref answers that question only for people who use git, and only when the
+tree is clean — a dirty tree means the ref describes code that is not what ran.
+A content hash answers it always, which is why it is the fingerprint's code
+component and the ref is only corroborating detail
+"""
+
+import hashlib
+import json
+import sys
+import sysconfig
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Iterable
+
+__all__ = ["code_sha256", "params_sha256", "canonical_json", "first_party_modules"]
+
+# region Scope
+
+def _stdlib_and_site_roots() -> set[Path]:
+    """
+    Directories whose contents are NOT the researcher's code
+
+    Everything under these is a dependency: the standard library, site-packages,
+    and the SDK's own installation. Hashing them would make the fingerprint
+    change on an unrelated `pip install`, and would take seconds rather than
+    milliseconds
+
+    :return: set of resolved directory paths
+    """
+    roots: set[Path] = set()
+    for key in ("stdlib", "platstdlib", "purelib", "platlib"):
+        path = sysconfig.get_paths().get(key)
+        if path:
+            roots.add(Path(path).resolve())
+    # A strategy importing the SDK must not hash the SDK — the engine already
+    # knows its own version, and an SDK upgrade is not a strategy change
+    roots.add(Path(__file__).resolve().parent)
+    return roots
+
+
+def _is_first_party(path: Path, roots: set[Path]) -> bool:
+    """
+    Whether a module file belongs to the researcher rather than to a dependency
+
+    :param path: resolved module file path
+    :param roots: dependency directories from _stdlib_and_site_roots
+    :return: True when the file is the researcher's own code
+    """
+    for root in roots:
+        try:
+            path.relative_to(root)
+        except ValueError:
+            continue
+        return False
+    return True
+
+
+def first_party_modules(entry: ModuleType | None = None) -> list[Path]:
+    """
+    Every first-party source file currently loaded, sorted by path
+
+    Reads sys.modules rather than walking imports statically, because a
+    strategy that imports conditionally or inside a function would defeat a
+    static walk — and what ran is what we want to describe, not what the source
+    appears to import
+
+    The consequence to know about: a module imported LATER than the hello is not
+    in the hash. Strategies import at module scope, so this is rare, and the
+    alternative (hashing at first bar) would mean the identity arrives after the
+    engine has already accepted the connection
+
+    :param entry: unused today; accepted so callers can pin an entry point later
+    :return: sorted list of resolved paths
+    """
+    roots = _stdlib_and_site_roots()
+    found: set[Path] = set()
+    for module in list(sys.modules.values()):
+        source = getattr(module, "__file__", None)
+        if not source or not source.endswith(".py"):
+            continue
+        try:
+            resolved = Path(source).resolve()
+        except OSError:
+            continue
+        if not resolved.is_file():
+            continue
+        if _is_first_party(resolved, roots):
+            found.add(resolved)
+    return sorted(found)
+
+# endregion
+
+# region Hashing
+
+def code_sha256(entry: ModuleType | None = None) -> str:
+    """
+    Hash of the strategy's own source — every first-party module, sorted by path
+
+    Each file contributes its path RELATIVE to the common root plus its bytes.
+    The relative path is deliberate: hashing absolute paths would make the same
+    code hash differently on two machines, which defeats the whole purpose when
+    a backtest runs on a laptop and the live session runs on a server
+
+    File bytes are hashed raw rather than normalised. Reformatting IS a change
+    to the code; pretending otherwise means a fingerprint that says "unchanged"
+    about a file someone edited
+
+    :param entry: optional entry module, forwarded to first_party_modules
+    :return: hex sha256, or "" when no first-party source could be identified
+    """
+    paths = first_party_modules(entry)
+    if not paths:
+        return ""
+
+    # Common root so the hash is machine-independent. With a single file the
+    # root is its directory, so the relative name is just the filename
+    try:
+        root = _common_root(paths)
+    except ValueError:
+        root = paths[0].parent
+
+    digest = hashlib.sha256()
+    for path in paths:
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            rel = Path(path.name)
+        digest.update(str(rel).encode("utf-8"))
+        digest.update(b"\0")
+        try:
+            digest.update(path.read_bytes())
+        except OSError:
+            # A file that vanished between listing and reading contributes its
+            # name only. Better a hash that still distinguishes runs than an
+            # exception that stops a strategy connecting
+            digest.update(b"<unreadable>")
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _common_root(paths: Iterable[Path]) -> Path:
+    """
+    Deepest directory containing every path
+
+    :param paths: resolved file paths
+    :return: the common parent directory
+    """
+    parts = [p.parent.parts for p in paths]
+    common: list[str] = []
+    for chunk in zip(*parts):
+        if len(set(chunk)) != 1:
+            break
+        common.append(chunk[0])
+    if not common:
+        raise ValueError("no common root")
+    return Path(*common)
+
+
+def canonical_json(value: Any) -> str:
+    """
+    Deterministic JSON — sorted keys, no insignificant whitespace
+
+    Canonicalisation happens HERE rather than in the engine so the SDK's form is
+    authoritative. Two sides independently deciding how to order keys is two
+    chances to disagree, and the disagreement would surface as a fingerprint
+    mismatch nobody could explain
+
+    :param value: any JSON-serialisable value
+    :return: canonical JSON text
+    """
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def params_sha256(params: Any) -> str:
+    """
+    Hash of the canonical form of a strategy's declared parameters
+
+    :param params: the params mapping, or None
+    :return: hex sha256, or "" when there are no params
+    """
+    if params is None:
+        return ""
+    try:
+        canonical = canonical_json(params)
+    except (TypeError, ValueError):
+        return ""
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+# endregion

stochastic_sh-1.0.0/stochastic/indicators.py

@@ -0,0 +1,157 @@
+"""
+Stateful indicators that a rolling window cannot express
+
+`ctx.window(...)` covers everything derivable from the last N bars — means,
+z-scores, EMAs. What it cannot cover is an indicator defined RECURSIVELY, where
+today's value depends on yesterday's value rather than on a window of prices.
+Wilder's RSI is the canonical one, and it is why this module exists
+
+# Why these carry their own state, and what that costs
+
+A recursive indicator holds price-denominated numbers between ticks, and the
+SDK cannot see inside them. Rolling windows re-base themselves across corporate
+actions; these cannot, so every one of them exposes `rebase(price_factor)` and
+the job MUST call it from `on_action`
+
+Skip that call and a 4:1 split reads as a 75% single-bar loss, which produces a
+plausible-looking RSI of ~0 that no assertion catches
+
+# Why this is in the SDK rather than copied into each job
+
+It was copied into each job — three times, with the same seeding logic and the
+same re-basing requirement, and a bug in one would have been a bug in all. The
+warm-up is the subtle part: Wilder seeds the averages with a SIMPLE mean of the
+first `period` moves and only then switches to recursive smoothing, and an
+implementation that starts smoothing immediately produces numbers that look
+right and drift
+
+`sdk/python/examples/metrics/core_indicators.py` still hand-rolls it on purpose,
+as the worked example of writing a stateful metric. Everything else imports it
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+
+@dataclass
+class WilderRSI:
+    """
+    Wilder's Relative Strength Index, one instrument, one period
+
+    Recursive smoothing, so it carries state between ticks rather than
+    re-deriving from a window
+    """
+
+    period: int = 14
+
+    _prev: float | None = None
+    _gain: float = 0.0
+    _loss: float = 0.0
+    _n: int = 0
+
+    def update(self, close: float) -> float:
+        """
+        Feed one close and get the current RSI
+
+        :param close: the bar's close price
+        :return: RSI in [0, 100], or NaN while warming up
+        """
+        if self._prev is None:
+            self._prev = close
+            return math.nan
+
+        change = close - self._prev
+        gain, loss = max(change, 0.0), max(-change, 0.0)
+        self._prev = close
+        self._n += 1
+
+        if self._n < self.period:
+            # Accumulating the seed. NaN means "there is no value", which is
+            # the same thing a gap means — one meaning, deliberately
+            self._gain += gain
+            self._loss += loss
+            return math.nan
+
+        if self._n == self.period:
+            # Wilder seeds with a SIMPLE mean of the first `period` moves and
+            # only then smooths. Starting the smoothing one bar early gives
+            # numbers that look plausible and drift from every reference
+            # implementation
+            self._gain = (self._gain + gain) / self.period
+            self._loss = (self._loss + loss) / self.period
+        else:
+            self._gain = (self._gain * (self.period - 1) + gain) / self.period
+            self._loss = (self._loss * (self.period - 1) + loss) / self.period
+
+        if self._loss == 0:
+            # No down moves in the window. RSI is 100 by definition — this is
+            # not a division-by-zero guard, it is the definition
+            return 100.0
+        return 100.0 - 100.0 / (1.0 + self._gain / self._loss)
+
+    def rebase(self, price_factor: float) -> None:
+        """
+        Re-base the price-denominated state across a corporate action
+
+        MUST be called from the job's `on_action`. The state holds price
+        DIFFERENCES, so they scale by the same factor the prices do
+
+        :param price_factor: the action's price factor (0.25 for a 4:1 split)
+        """
+        if self._prev is not None:
+            self._prev *= price_factor
+        self._gain *= price_factor
+        self._loss *= price_factor
+
+
+@dataclass
+class WilderRSIPanel:
+    """
+    One WilderRSI per (instrument, period), created on first sight
+
+    The bookkeeping every multi-instrument job would otherwise write itself.
+    Keyed by instrument_id rather than symbol so a ticker rename cannot split
+    one series in two
+    """
+
+    periods: tuple[int, ...] = (14,)
+    _state: dict[tuple[int, int], WilderRSI] = field(default_factory=dict)
+
+    def update(self, instrument_id: int, close: float, period: int) -> float:
+        """
+        Feed one close for one instrument at one period
+
+        :param instrument_id: durable instrument key
+        :param close: the bar's close price
+        :param period: RSI period; need not be in `periods`
+        :return: RSI in [0, 100], or NaN while warming up
+        """
+        key = (instrument_id, period)
+        rsi = self._state.get(key)
+        if rsi is None:
+            rsi = WilderRSI(period=period)
+            self._state[key] = rsi
+        return rsi.update(close)
+
+    def update_all(self, instrument_id: int, close: float) -> dict[int, float]:
+        """
+        Feed one close and get every configured period at once
+
+        :param instrument_id: durable instrument key
+        :param close: the bar's close price
+        :return: period -> RSI
+        """
+        return {p: self.update(instrument_id, close, p) for p in self.periods}
+
+    def rebase(self, instrument_id: int, price_factor: float) -> None:
+        """
+        Re-base every period held for one instrument
+
+        :param instrument_id: the instrument the action touched
+        :param price_factor: the action's price factor
+        """
+        for (iid, _period), rsi in self._state.items():
+            if iid == instrument_id:
+                rsi.rebase(price_factor)