umbi

Library for input/output of transition systems in a unified Markov binary (UMB) format. See the format specification for details.

Installation:

(optional) create and activate a python environment:

python -m venv .venv
source .venv/bin/activate

Install umbi via

pip install umbi

Quick start

Read a umbfile into an ExplicitAts object, modify initial states, and write it back:

import umbi
ats : ExplicitAts = umbi.ats.read("in.umb")
ats.set_initial_states([ats.num_states - 1])
umbi.ats.write(ats, "out.umb")

More examples can be found in the ./examples folder.

API

umbi offers three levels of abstraction for working with UMB files:

TarFile and TarCoder - Low-level access to tarfile contents.

ExplicitUmb - In-memory representation of a typical umbfile. Attributes are standard Python objects (lists, dicts, dataclasses) providing a deserialized view of the file contents.

ExplicitAts - Format-agnostic abstraction for annotated transition systems (states, transitions, annotations). Recommended for most use cases: easiest to use programmatically and remains stable across UMB format changes.

CLI

umbi provides a basic CLI for umbfile manipulation.

Options:

• --import-umb <path> - Import .umb file as ExplicitUmb
• --import-ats <path> - Import .umb file as ExplicitAts
• --export <path> - Export to .umb file (requires --import-umb or --import-ats)
• --log-level <LEVEL> - Set logging level: DEBUG, INFO (default), WARNING, ERROR, CRITICAL

Example:

umbi --import-umb input.umb --export output.umb --log-level DEBUG

Development

Setup

Install development dependencies:

pip install .[dev]

Code Quality

Pre-commit hooks automatically run code quality checks before each commit. Configuration: .pre-commit-config.yaml

Set up the hooks with:

pre-commit install

Run hooks manually on all files:

pre-commit run --all-files

Individual tools can be run manually:

Ruff -- Code formatting and linting. Config: pyproject.toml ([tool.ruff])

ruff check .       # check for issues
ruff format .      # format code
ruff check . --fix # check and fix

Pyright -- Static type checking. Config: pyproject.toml ([tool.pyright])

pyright             # check entire project
pyright umbi/       # check specific directory

Lockfiles

Dependencies are pinned in the uv.lock lockfile for reproducible builds. To update the lockfile:

uv lock

Release

New versions are published to PyPI via the release workflow. The workflow is triggered automatically when:

• A new version tag is pushed (format: v*.*.*)
• The bump version workflow completes successfully

Alternatively, the workflow can be triggered manually via GitHub Actions.

The release workflow:

1. Updates the uv.lock lockfile to reflect any dependency changes
2. Builds the distribution packages
3. Publishes to PyPI via trusted publishing
4. Updates the stable branch pointer to track the latest release