Metadata-Version: 2.4
Name: stochastic-sh
Version: 1.0.1
Summary: Stochastic strategy SDK — write and run trading strategies against the engine
License-Expression: MIT
Project-URL: Homepage, https://stochastic.sh
Project-URL: Documentation, https://docs.stochastic.sh
Project-URL: Changelog, https://github.com/stochastic-sh/stochastic/releases
Keywords: backtesting,trading,quantitative-finance,algorithmic-trading,strategy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: grpcio>=1.80
Requires-Dist: protobuf>=6.31
Requires-Dist: polars>=1.40

# 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

```
pip install stochastic-sh
```

The distribution is `stochastic-sh`; the import is `stochastic`.

```python
from stochastic import Strategy, run
```

That pulls the runtime dependencies (grpcio, protobuf, polars) with it.

**Working from a source checkout instead?** `pip install -e .` from this
directory does the same thing against your working tree.

## Write one

```python
from stochastic import Strategy, run


class Momentum(Strategy):
    name = "momentum"
    slug = "momentum"
    version = "1"

    def on_tick(self, t, bars, ctx):
        for bar in bars.values():
            sma = ctx.metric(bar.instrument_id, "sma_20")
            if sma != sma:          # NaN — not enough history yet
                continue
            if bar.c > sma:
                ctx.buy(instrument_id=bar.instrument_id, dollar=10_000)


if __name__ == "__main__":
    run(Momentum())
```

`ctx.metric` reads a **pre-computed** series stored beside your bars, so the
signal survives a restart and a strategy never recomputes history it already
has. A metric with insufficient history is `NaN`, which is the signal to sit
out — the `sma != sma` check above.

## 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`)
