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.