Metadata-Version: 2.4
Name: culsma
Version: 1.0.8
Summary: Public execution-kernel release boundary for the current Culsma reference implementation
License-Expression: Apache-2.0
Project-URL: Homepage, https://culsma.dev/
Project-URL: Documentation, https://culsma.dev/
Project-URL: Paper, https://doi.org/10.64898/2026.05.07.723509
Project-URL: Source, https://github.com/culsma/culsma
Project-URL: Issues, https://github.com/culsma/culsma/issues
Project-URL: Changelog, https://github.com/culsma/culsma/blob/main/CHANGELOG.md
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: third_party/licenses/Orbitron-OFL-1.1.txt
Requires-Dist: lark>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/culsma/culsma/main/docs/assets/culsma-wordmark.png" alt="Culsma" width="720">
</p>

<p align="center">
  <a href="https://pypi.org/project/culsma/"><img alt="PyPI" src="https://img.shields.io/pypi/v/culsma.svg"></a>
  <a href="https://pypi.org/project/culsma/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/culsma.svg"></a>
  <a href="https://github.com/culsma/culsma/actions/workflows/release-check.yml"><img alt="Release check" src="https://github.com/culsma/culsma/actions/workflows/release-check.yml/badge.svg"></a>
  <a href="https://doi.org/10.64898/2026.05.07.723509"><img alt="bioRxiv" src="https://img.shields.io/badge/bioRxiv-10.64898%2F2026.05.07.723509-B31B1B.svg"></a>
  <a href="https://doi.org/10.5281/zenodo.20059616"><img alt="Software DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.20059616.svg"></a>
  <a href="https://doi.org/10.5281/zenodo.20059696"><img alt="Reference DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.20059696.svg"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg"></a>
</p>

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

The executable core is organized in:

- `src/culsma/parser/`
- `src/culsma/pipeline/`
- `src/culsma/runtime/`
- `src/culsma/driver/`
- `src/culsma/stdlib/`
- `tests/`

The repository also maintains the Patterns benchmark cases and reproduction tools under
[`benchmarks/`](benchmarks/README.md), separate from the language
implementation and its PyPI package. This is the canonical maintenance location
for the paper's cases. Culsma 1.0.7 is available on PyPI; the benchmark is
included in the [v1.0.7 source release](https://github.com/culsma/culsma/releases/tag/v1.0.7).

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

## Install

For the current public release, install from PyPI:

```bash
python -m pip install culsma
```

You can also install directly from the `v1.0.4` tag:

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

Release notes are in [CHANGELOG.md](CHANGELOG.md).

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

## VS Code Support

Install [Culsma Language Support from the Visual Studio Code
Marketplace](https://marketplace.visualstudio.com/items?itemName=culsma.culsma)
for syntax highlighting and editor language configuration. The extension binds
canonical `.culs` files and retains `.lw` association during the transition
from LabWord naming. Its source and VSIX releases are maintained in the
[culsma-vscode repository](https://github.com/culsma/culsma-vscode).

## Repository Layout

```text
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
benchmarks/   fixed paper benchmark, expected results and reproduction tools
```

## Quick Run

Create a small protocol file:

```bash
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:

```bash
culsma /tmp/culsma-smoke.culs
```

This prints three compact sections: material use, resources (including
container capacities), and the explicit protocol return.

The explicit run form is equivalent:

```bash
culsma run /tmp/culsma-smoke.culs
```

To save those results as JSON:

```bash
culsma run /tmp/culsma-smoke.culs --results results.json
```

The file has exactly three fields: `materials`, `resources`, and `returns`.
Material rows contain `name`, `amount`, and `unit`; processed samples use their
declared input amount, while stock reagents use the amount withdrawn at runtime.
Container resource rows contain `kind`, `capacity_uL`, and `count`. Explicit
device references use `kind`, `name`, and `count`. `returns` preserves the complete protocol return
objects, including fields omitted from the console preview.

For multiple input files, `--results` saves an array of these result objects
in input order. A failed run writes partial results, reports the failure on
stderr, and exits with status 1. `--results` requires a file path and cannot
be combined with `--json` or `--output`.

The existing complete run-output format remains available on stdout:

```bash
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:

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

If you want intermediate and debug artifacts as well:

```bash
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:

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

You can also replay a saved run artifact:

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

## Run Tests

```bash
python -m pytest -q
```

## More

- Documentation: [culsma.dev](https://culsma.dev/)
- Paper and citation: [Culsma: A Formal Language for Laboratory Protocols](https://doi.org/10.64898/2026.05.07.723509)
  (bioRxiv preprint)
- Software DOI: [10.5281/zenodo.20059616](https://doi.org/10.5281/zenodo.20059616)
- Reference DOI: [10.5281/zenodo.20059696](https://doi.org/10.5281/zenodo.20059696)
- Latest GitHub release: [github.com/culsma/culsma/releases/latest](https://github.com/culsma/culsma/releases/latest)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Release process: [RELEASE.md](RELEASE.md)
- Support policy: [SUPPORT.md](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.

<p align="center">
  <a href="https://brodinlab.com/">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="docs/assets/Brodin_Logo_OffWhite.png">
      <source media="(prefers-color-scheme: light)" srcset="docs/assets/Brodin_Logo_Black500.png">
      <img src="docs/assets/Brodin_Logo_Black500.png" alt="Brodin Lab affiliation mark" width="150">
    </picture>
  </a>
</p>
