Actus

Actus is a graph-based execution framework that separates structure (graph topology) from behavior (actions). It focuses on explicit action-to-action binding, controlled cycles, and simulation-first execution with ledgered change intent.

What It Does

• Models complex systems as executable graphs (nodes + edges).
• Executes actions through a scoped traversal engine.
• Records WriteSet-based change intent in a SimulationLedger (no auto-commit).
• Supports read-your-own-writes within a run.

Quick Start

From the project root:

python -m examples.execution_demo

This runs a ticket booking simulation and prints a ledger trace plus table state.

Development Setup

Option A: venv + pip

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Option B: uv (recommended for fast installs)

uv init
uv venv --python 3.13
uv add -r requirements.txt
uv sync

Project Layout

actus/
  core/            # core runtime: execution, graph, registry, infra
examples/          # runnable demos
  execution_demo.py
  README.md

Tests

pytest -q

Documentation

• Design docs: docs/design_document/
• MkDocs config: mkdocs.yml

Notes

• Execution is simulation-first: WriteSet changes are recorded in the ledger and can be committed later.
• The execution engine uses context binding (current_ctx()) for action access.