Metadata-Version: 2.4
Name: culsma
Version: 1.0.1
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: 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>

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/`
- minimal public `examples/`
- `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:

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

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

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

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

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

## 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
examples/             minimal current-surface examples
tests/                regression and runtime tests
```

## Quick Run

```bash
culsma examples/minimal/public_minimal.culs
```

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

The explicit run form is equivalent:

```bash
culsma run examples/minimal/public_minimal.culs
```

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

```bash
culsma run examples/minimal/public_minimal.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 examples/minimal/public_minimal.culs --output tmp/result.json
```

If you want intermediate and debug artifacts as well:

```bash
culsma run \
  examples/minimal/public_minimal.culs \
  --artifacts-dir tmp/run
```

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

```bash
python -m culsma examples/minimal/public_minimal.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.dev/paper-and-citation](https://culsma.dev/paper-and-citation)
  (arXiv preprint forthcoming)
- Software DOI: [10.5281/zenodo.20059616](https://doi.org/10.5281/zenodo.20059616)
  (latest/versioned software archive)
- Culsma v1.0.1 DOI: [10.5281/zenodo.20059617](https://doi.org/10.5281/zenodo.20059617)
- Reference DOI: [10.5281/zenodo.20059696](https://doi.org/10.5281/zenodo.20059696)
  (latest/versioned language reference archive)
- Culsma Reference v1.0.1 DOI: [10.5281/zenodo.20059697](https://doi.org/10.5281/zenodo.20059697)
- GitHub Releases: [github.com/culsma/culsma/releases](https://github.com/culsma/culsma/releases)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Support policy: [SUPPORT.md](SUPPORT.md)

## Release Boundary

- This repository is the public code boundary for Culsma v1.0.x.
- The `examples/` directory contains small runnable CLI examples used for
  public smoke validation.
- 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.
