Stateous

Stateous runs a process as a graph of states, and keeps every token of it durable.

You write the graph in Python. A control plane keeps every token and chooses each next state. A supervisor, on any computer, does the work and reports what happened. The supervisor never sees the graph. It knows only which states it serves, and which outcomes each state allows.

Status: alpha. The API can change before version 1.0.

Install

Stateous needs Python 3.12 or newer.

pip install stateous            # or: uv add stateous
pip install "stateous[phd]"     # also PHD, to run agents in routines

The control plane keeps its data in SQLite or in Postgres.

A short example

stateous init workflow orders                               # a starter workflow that compiles
stateous serve orders/build/orders.json                     # the control plane
stateous init supervisor orders/flow.py orders-supervisor   # contract.py and a stub for each state
stateous supervise orders-supervisor                        # runs your routines
stateous token start ORDER-1 '{"title": "first order"}'     # starts a token

Write the routines in orders-supervisor/ before you run supervise. examples/sdlc/ and examples/sdlc-supervisor/ are a larger example.

Stateous has no authentication. Keep a control plane that listens on a wider address behind a VPN or a proxy.

Documentation

The documentation is at stateouslabs.github.io/stateous. It explains the model, then tells you how to do the work, then gives the reference. To run the short example step by step, follow Getting started.

Licence

Apache License 2.0. See LICENSE and NOTICE.