harel

Durable, distributed statecharts for Python.

A hierarchical statechart engine for Python — with the durability and distribution of a workflow engine, but the right model underneath.

You author a machine in a small textual DSL (.stm), it compiles to an immutable Definition, and a pure, effects-based engine runs it against a serializable Execution that can be persisted, distributed across workers, and survive crashes.

This documentation is a step-by-step tutorial: each page introduces one capability and builds on the last, using machines you already know (a turnstile, an online order, a microwave, a keyboard). Every Python block on every page is executed in CI, so you can copy, paste, and run it as-is.

The tutorial, step by step

Each step introduces one capability and builds on the last, growing a single example — an online order — with side trips to a turnstile, a checkout, and a parcel shipment where they illustrate a feature better.

Tutorial

• 1. Your first machine
• 2. Making states do something
• 3. Reaching a conclusion: terminals and outcomes
• 4. Guarding transitions
• 5. Computed branching with selectors
• 6. Hierarchy: composite states
• 7. Time: durable timers
• 8. Doing things at once: orthogonal regions
• 9. Reuse: parametrized fragments
• 10. Splitting across files: imports
• 11. Composing machines: submachine invoke
• 12. Data-parallel work: fan-out
• 13. Passing data across boundaries
• 14. Catching mistakes early: static validation
• 15. Out-of-order events: defer

Operations & reference

How these machines run for real — and the reference material.

Operations & reference

• Command-line interface
• Visualization & tooling
• Durability
• Stores
• Distribution
• Transports
• Machine resolvers
• Control plane
• Remote actions (FaaS — Lambda / HTTP functions)
• Monitoring TUI (harel monitor)
• Architecture — how harel works
• DSL reference
• Public API

Is a statechart the right tool?

Use a statechart when your domain is a machine of named states with hierarchy, guarded transitions, and explicit terminal verdicts — an order, a subscription, a device, a claim, a deployment. These are routinely mislabelled “pipelines” or “workflows” and built with a DAG runner or a pile of if status == … branches, which is where the illegal states and the hard-to-follow retry/cancel logic come from. If your domain is genuinely “run these steps in order with retries”, a workflow engine is the better fit — harel is not trying to replace one.