culsma 1.0.3

Public execution-kernel release boundary for the current Culsma reference implementation

Culsma is the public reference implementation of the current Culsma language and execution stack. The public release is distributed as a Python-based CLI.

This repository intentionally contains only the executable core:

• src/culsma/parser/
• src/culsma/pipeline/
• src/culsma/runtime/
• src/culsma/driver/
• src/culsma/stdlib/
• tests/

It intentionally leaves out manuscript sources, MCP tooling, editor integrations, and internal design-workspace documents.

Install

For the current public release, install from PyPI:

python -m pip install culsma

You can also install directly from the v1.0.3 tag:

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

Release notes are in CHANGELOG.md.

The public language reference is maintained in the companion culsma-reference repository/worktree.

Repository Layout

src/culsma/parser/    grammar, AST, and source loading
src/culsma/pipeline/  compile, validate, typecheck, and plan lowering
src/culsma/runtime/   execution state, events, and material compute
src/culsma/driver/    backend boundary and concrete drivers
src/culsma/stdlib/    bundled standard-library source
tests/                regression and runtime tests

Quick Run

Create a small protocol file:

cat > /tmp/culsma-smoke.culs <<'CULSMA'
protocol CliSmoke {
  let sample = tube(label = "AcquisitionSample", capacity = 2000uL, load = [content(kind = "biosample", code = "S1", type = "cell_sample"):1000uL]);
  return sample;
}
CULSMA

Then run it:

culsma /tmp/culsma-smoke.culs

This prints a compact terminal result, including the returned tube/container state.

The explicit run form is equivalent:

culsma run /tmp/culsma-smoke.culs

If you want the machine-readable run output on stdout:

culsma run /tmp/culsma-smoke.culs --json

The run output separates the protocol return from the generated lab report: returns is the program output, while report is the execution/reporting summary.

If you want to save the machine-readable run output explicitly:

culsma run /tmp/culsma-smoke.culs --output tmp/result.json

If you want intermediate and debug artifacts as well:

culsma run \
  /tmp/culsma-smoke.culs \
  --artifacts-dir tmp/run

If you are running from a source checkout without the console entrypoint on PATH, use:

python -m culsma /tmp/culsma-smoke.culs

You can also replay a saved run artifact:

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

Run Tests

python -m pytest -q

More

• Documentation: culsma.dev
• Paper and citation: Culsma: A Formal Language for Laboratory Protocols (bioRxiv preprint)
• Software DOI: 10.5281/zenodo.20059616
• Reference DOI: 10.5281/zenodo.20059696
• Latest GitHub release: github.com/culsma/culsma/releases/latest
• Changelog: CHANGELOG.md
• Release process: RELEASE.md
• Support policy: SUPPORT.md

Release Boundary

• This repository is the public code boundary for Culsma v1.0.x.
• Public smoke validation uses generated protocol source rather than bundled example files.
• This repository is licensed under Apache-2.0. See LICENSE.

Support and Maintenance Policy

Culsma is a public open-source reference implementation of the Culsma language and execution stack.

The repository is published as-is. Maintainer review is limited to narrowly scoped, reproducible defects in the current public baseline. General support, custom integration help, roadmap requests, and broad feature requests are out of scope for the public issue tracker.