Getting Started

This page gets you from a checkout of the public Culsma package to one successful end-to-end run.

Requirements

• Python 3.11 or newer
• pip
• Runtime dependency: lark>=1.1.0

Install

For local source development:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

For the release tag:

python -m pip install "culsma @ git+https://github.com/culsma/culsma.git@v1.0.0"

TIP

Wheel installation is supported for release artifacts, but a fresh environment still needs access to lark>=1.1.0 unless that dependency is already cached or available from a package mirror.

Run the Minimal Protocol

From the public repository checkout:

culsma run --input examples/minimal/public_minimal.culs --artifacts-dir tmp/run

If the console entrypoint is not on PATH, use:

python -m culsma.cli run \
  --input examples/minimal/public_minimal.culs \
  --artifacts-dir tmp/run

Inspect Output

The command writes staged JSON artifacts into the output directory.

Expected files:

File	Meaning
summary.json	Short run summary and diagnostic counts.
ast.json	Parsed source program.
ir.json	Canonical IR after compilation.
validate.json	Semantic diagnostics.
typecheck.json	Type and unit diagnostics.
plan.json	Lowered execution plan.
run.json	Runtime result, final state, events, and user result.
result.json	User-facing derived result projection.

Replay

Replay reconstructs runtime state from a saved run artifact.

culsma replay --run-json tmp/run/run.json --out tmp/replayed_state.json

Next

Read Minimal Protocol to understand the example source, then Execution Pipeline to understand the generated artifacts.