Metadata-Version: 2.5
Name: stateous
Version: 0.1.0
Summary: A process as a graph of states. A control plane keeps every token durable.
Project-URL: Homepage, https://github.com/StateousLabs/stateous
Project-URL: Source, https://github.com/StateousLabs/stateous
Project-URL: Issues, https://github.com/StateousLabs/stateous/issues
Project-URL: Documentation, https://github.com/StateousLabs/stateous/blob/main/docs/guide.md
Author: The Stateous Authors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,durable execution,orchestration,state machine,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: alembic<2,>=1.13
Requires-Dist: httpx2>=2.13
Requires-Dist: jsonschema>=4.21
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: starlette>=0.40
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: phd
Requires-Dist: poly-harness-dispatcher>=0.1; extra == 'phd'
Description-Content-Type: text/markdown

# 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.

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

Then run the `stateous` command in that environment. The control plane keeps its data in SQLite or in Postgres.

## The example

[`examples/sdlc/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc) is a workflow with two states: `coding` and `testing`. [`examples/sdlc-supervisor/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc-supervisor) is the supervisor's folder for it.

```bash
# on the control plane's computer
stateous compile sdlc/flow.py                         # writes sdlc/build/sdlc.json
stateous serve sdlc/build/sdlc.json --listen 0.0.0.0:8080

# on the supervisor's computer
stateous init http://cp.internal:8080 sdlc-supervisor # contract.py, stubs, stateous.yaml, pyproject.toml
stateous supervise sdlc-supervisor                    # runs the routines

# anywhere
stateous token start TICKET-1 '{"repo": "acme/api"}' --url http://cp.internal:8080
stateous token show TICKET-1 --url http://cp.internal:8080
```

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

To try the example on one computer, follow [the guide](https://github.com/StateousLabs/stateous/blob/main/docs/guide.md#try-it-on-one-computer).

## Learn more

- [`docs/guide.md`](https://github.com/StateousLabs/stateous/blob/main/docs/guide.md): the guide, on one page.
- [`examples/`](https://github.com/StateousLabs/stateous/tree/main/examples): the example.

## Licence

Apache License 2.0. See [`LICENSE`](https://github.com/StateousLabs/stateous/blob/main/LICENSE) and [`NOTICE`](https://github.com/StateousLabs/stateous/blob/main/NOTICE).
