mbse 0.1.0

Python runtime and local web viewer for MBSE JSON models.

MBSE

Python runtime and local web viewer for MBSE JSON models.

Install

pip install mbse

The web viewer requires Graphviz and its dot command on PATH.

# Ubuntu/Debian
sudo apt install graphviz

# macOS
brew install graphviz

On Windows, install Graphviz from its download page and add its bin directory to PATH.

Model Validation And Discovery

Load a project to validate its project document and every recognized MBSE JSON model below project_root. The registry rejects duplicate model ids, multiple contexts, and invalid entrypoints.

from mbse.model.project.project_registry import ProjectRegistry

registry = ProjectRegistry.load("project.json")
models = registry.iterExecutableModels()
print([model.getDocumentId() for model in models])

The registry validates JSON shape. Action-language handlers are normal Python imports and must be available in the active environment when the runtime executes them.

Automated Runtime Tests

from mbse.model.project.project_registry import ProjectRegistry
from mbse.runtime.runtime import Runtime

registry = ProjectRegistry.load("project.json")
runtime = Runtime()
runtime.init(registry)
runtime.play()
runtime.sendEvent("start")  # A declared HSM event.

assert runtime.getState()["id"] == "running"

Use getExecutionLog(), getVariable(), and getState() for assertions. sendEvent() and getState() require an HSM project entrypoint. See the Runtime Layer for stepping and inspection.

Web Viewer

mbse-view project.json --open-browser

Run the packaged elevator example with nested Activity models:

mbse-example-view

The viewer lists every executable model, renders its diagram, and provides events, typed variables, execution logs, model-call stepping, and breakpoints. It is a local debugging tool that listens on 127.0.0.1 by default.

The viewer requires an HSM project entrypoint. Activity models can be rendered, listed, and debugged when called from that entrypoint.

Documentation

• Model Layer: JSON schemas, validation, and project discovery.
• Context Model, HSM Model, Activity Model, and Project Model: authoring formats.
• Runtime Layer: execution and test API.
• HSM Runtime and Activity Runtime: execution semantics.
• Viewer Server, Render Layer, and Browser Viewer: local visual debugging architecture.
• Reference Project: runnable multi-model fixture used by the test suite.
• Elevator Example: packaged viewer demonstration with nested Activity models.
• Test Suite: executable coverage and fixture documentation.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
ruff check .
pytest

VS Code users can run the ✅ Run CI status-bar button to create .venv when needed and execute the same validation steps as CI locally.

Releases

One-Time Setup

Configure a branch protection rule for main that requires pull requests and the CI / test status check before merging. Do not push directly to main.

Configure a PyPI pending publisher with:

• Project name: mbse
• GitHub owner: <owner>
• Repository: <repository>
• Workflow: release.yml
• Environment: pypi

Change Flow

1. Create a branch and open a pull request against main.
2. Merge only after CI / test passes.

Release Flow

1. After the release changes are merged, create and push a version tag:

git tag v0.1.0
git push origin v0.1.0

The publish workflow validates, builds, and uploads the package to PyPI. A failed workflow never uploads a package, but does not remove the pushed tag.