Skip to content

PyStator

Configuration-driven, stateless finite state machines for Python — YAML/JSON definitions, guards, actions, optional API, worker, and UI

PyPI version Python versions License CI

PyStator is a library for defining finite state machines in declarative config (YAML or JSON), computing transitions from current state + event + context, and running guards and actions. The same model powers an optional REST API, worker queue, and UI when you install the corresponding extras.

At a glance

Area What it is
Core Stateless StateMachine / builder, process(), hierarchical and parallel states
EntitySession Per-entity wrapper: send(), snapshots, generated helpers
Persistence Pluggable state stores (memory, Postgres, Redis, MongoDB, custom)
Runtime Schedulers (asyncio, Redis, Celery), worker + submit_event, deployment guides
Discovery Inferred FSM candidates, shadow-mode comparison, classification APIs
Quality Lint, hooks, metrics, visualization (Mermaid, DOT, SCXML)

See Concepts, Architecture, and the API Reference.

Key features

  • Declarative FSMs

    Define states, transitions, guards, and actions in YAML or JSON. StateMachineBuilder and declarative check: / effects keep configs readable.

    Declarative features

  • Hierarchical & parallel

    Compound states, regions, and parallel execution patterns for real workflows.

    Concepts

  • State stores

    In-memory, PostgreSQL, Redis, MongoDB, or bring your own StateStore adapter.

    State stores

  • Worker & schedulers

    Queue-backed processing with pystator worker, delayed transitions, and scaling notes.

    Worker · Schedulers

  • REST API & UI

    Optional HTTP API and UI on configurable ports; same FSM definitions end to end.

    Tutorial: API and UI

  • Discovery

    Infer candidate machines from observations, compare in shadow mode, and classify state from data.

    Discovery guide

Quick example

Load a machine and process an event

from pathlib import Path
from pystator import StateMachineBuilder

machine = StateMachineBuilder.from_yaml(Path("order_fsm.yaml")).build()
ctx = machine.create_context(entity_id="ord-1")
result = machine.process(ctx, "submit")
print(result.new_state, result.effects)

Installation

pip install pystator

pip install pystator[api]

pip install pystator[worker]

pip install pystator[all]

Default local ports (see pystator.config.ports): API 8004, UI 3004, pystator docs serve 5004. Details: Installation.

Architecture overview

flowchart LR
  subgraph Config["Config"]
    Y[YAML / JSON FSM]
  end
  subgraph Core["PyStator core"]
    SM[StateMachine]
    G[Guards & actions]
  end
  subgraph Optional["Optional extras"]
    API[REST API]
    W[Worker]
    UI[UI]
    ST[(State stores)]
  end
  Y --> SM
  SM --> G
  SM --> ST
  API --> SM
  W --> SM
  UI --> API

Next steps

  • Get started

    Install, first FSM, process(), EntitySession, and pointers to the API.

    Getting started

  • How-to guides

    Architecture, persistence, workers, discovery, linting, and observability.

    How-To Guides

  • Tutorials

    Order workflow and API/UI walkthroughs.

    Tutorials

  • API reference

    Docstring-generated pages for public Python APIs.

    API Reference

  • Contribute

    Contributing, publishing, and release workflow.

    Contributing