MBDlyb-UI

MBDlyb-UI is a web interface for MBDlyb, a prototype Python library for design-driven, model-based diagnostics. It provides an editor and diagnostic tools for functional models stored in a Neo4j graph database.

For background, examples, and user documentation, see the MBDlyb user guide.

Documentation

The docs/ folder contains the user guide for this interface in Sphinx / Read the Docs format. It covers the modelling concepts and every part of the front-end, with screenshots. Build the HTML version with:

uv run --group docs sphinx-build -b html docs/source docs/build/html

Then open docs/build/html/index.html. The screenshots are generated by docs/tools/capture_screenshots.py; see the chapter "Maintaining this documentation" for details.

Requirements

• Python 3.13
• A running Neo4j database
• A matching MBDlyb package (mbdlyb 0.6.0)

Development installation

The project uses uv and keeps its Python sources in src/. For development, the local MBDlyb base project is expected at ../MBDlyb-base, as configured in pyproject.toml.

From the MBDlyb-UI repository root, synchronize the project environment and install the project in editable mode:

uv sync

Run commands inside the project environment with uv run:

uv run mbdlyb-ui --help

Build a wheel for distribution with:

uv build --wheel

If the MBDlyb base checkout is not alongside this repository, update the local source path in pyproject.toml or install the matching MBDlyb package by another method before syncing.

Installing a pre-built wheel

MBDlyb-UI requires Python 3.13. Create an isolated environment with uv, pip, or Conda, then install the UI wheel and its matching MBDlyb wheel. Installing both wheels together lets the installer resolve their dependencies.

uv

uv venv --python 3.13
uv pip install /path/to/mbdlyb-0.6.0.whl /path/to/mbdlyb_ui-<version>-py3-none-any.whl

pip

python -m venv .venv

Activate the environment (.venv\Scripts\Activate.ps1 in Windows PowerShell, or source .venv/bin/activate on macOS/Linux), then install:

python -m pip install /path/to/mbdlyb-0.6.0.whl /path/to/mbdlyb_ui-<version>-py3-none-any.whl

Conda

conda create --name mbdlyb-ui python=3.13 pip
conda activate mbdlyb-ui
python -m pip install /path/to/mbdlyb-0.6.0.whl /path/to/mbdlyb_ui-<version>-py3-none-any.whl

Use the MBDlyb wheel that matches the version required by the UI. The MBDlyb project's pre-built packages are available from its GitHub releases; obtain the UI wheel from the distribution channel for this project.

Running the web interface

Start the interface with the Neo4j database name and, if needed, connection options. In a development checkout, prefix the command with uv run; in an activated environment with the wheel installed, run mbdlyb-ui directly:

uv run mbdlyb-ui --database <database-name>

The command accepts --host, --port, --protocol, --username, and --password options for the Neo4j connection. For example:

uv run mbdlyb-ui --host localhost --port 7687 --protocol bolt --username neo4j --password <your-password> --database <database-name>

Then open http://localhost:8080/ in a browser. To see all available command line options, run mbdlyb-ui --help.

Package structure

• mbdlyb_ui/ contains shared application setup, page and table components, navigation helpers, dialogs, Mermaid diagram rendering, and validation.
• mbdlyb_ui/functional/ contains the functional diagnostics application, including routes and pages for clusters, functions, hardware, observables, diagnostic tests and results, and operating modes. It also includes the diagnoser, design-for-diagnostics views, and functional model helpers.

The Python package uses the src/mbdlyb_ui source layout.

Contact

For questions about MBDlyb-UI or the supported methodology, contact Thomas Nägele. General project information is available from TNO-ESI.