Aidge GUI

A lightweight interactive visualizer for aidge_core graphs. Call visualize(graph) anywhere in your Python script and inspect your graph live in the browser, no separate tool to launch.

If you want to experiment with Aidge or its GUI you can call start_gui() so start up the GUI with an empty graph or call the CLI with aidge_gui_cli. More details down below.

What it does

The visualizer spins up a local web server in the background and opens a browser tab automatically. The graph is rendered as an interactive canvas where you can:

• Pan and zoom across the graph
• Inspect operator types and attributes on each node
• Edit attribute values inline by clicking on them, the change is sent back to Python over WebSocket

The graph state lives entirely in Python. The browser is a thin rendering layer that displays what Python sends and forwards user interactions back.

Quick start

System Requirements

• python >= 3.10
• Node.js >= 18
• npm >= 9
• aidge_core
• aidge_backend_cpu
• aidge_onnx

🛠 Build from Source

Prerequisite (in addition to previous one):

• Please review the global installation instructions before proceeding.
• If using a virtual environment, use the same one for all Aidge modules.

1. Python installation using setup scripts

Environment	Python Development
Windows	.\setup.ps1 -Modules gui -Tests
Unix	./setup.sh -m gui --tests

2. Python Installation (pip)

Run these commands from the aidge_gui/ directory:

# Standard install
pip install . -v

# Install with testing dependencies
pip install .[test] -v && pytest

Command-line interface

Aidge GUI can also be launched directly from a terminal after installation:

aidge_gui_cli

By default, this starts the GUI at http://127.0.0.1:8765, opens it in the default browser, and blocks until the server is stopped.

To visualize an existing Aidge or ONNX model, use:

aidge_gui_cli --model path/to/model.aidge

The server configuration and startup behavior can be changed, these options can be combined:

aidge_gui_cli \
    --model path/to/model.aidge \
    --host 127.0.0.1 \
    --port 8766 \
    --no-open-browser

Use the built-in help command to display all available options:

aidge_gui_cli --help

Example scripts

There are two ways of launching the GUI from a script.

Visualizing a graph:

import aidge_core
import aidge_onnx
import aidge_backend_cpu
from aidge_gui import visualize

graph = aidge_core.sequential([
    aidge_core.ReLU("node0"),
])

visualize(graph)

Or by starting it with an empty graph:

import aidge_core
import aidge_onnx
import aidge_backend_cpu
from aidge_gui import start_gui

start_gui()

Using these functions will start the server at http://localhost:8765 and open it in your default browser. The server runs in a background thread and shuts down automatically when your script exits.

The port and ip is configurable with the function arguments.

In a Jupyter notebook, either interrupt a blocking call or start the GUI without blocking and stop it explicitly:

from aidge_gui import start_gui, stop_gui

start_gui(block=False)
# ...
stop_gui()

API overview

visualize

visualize(
    graph: Union[aidge_core.GraphView, onnx.ModelProto],
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = True,
    block: bool = True,
) -> None

Launch the Aidge GUI and display an existing graph.

The input graph can be either an aidge_core.GraphView or an onnx.ModelProto. ONNX models are converted to Aidge before being displayed.

start_gui

start_gui(
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = True,
    block: bool = True,
) -> None

Launch the Aidge GUI with an empty graph.

This is useful when you want to experiment with the interface or create a graph directly from the GUI.

The host, port, open_browser, and block arguments behave the same way as in visualize.

Common issues

I replaced aidge_model_explorer with aidge_gui and it does not work anymore

Make sure that visualize() is used with the correct signature.

Unlike aidge_model_explorer, aidge_gui.visualize() does not take a graph name as second argument. For example:

visualize(graph, "my_graph")

will interpret "my_graph" as the host argument, which will likely generate an error.

Use:

visualize(graph)

or, if needed:

visualize(graph, host="127.0.0.1", port=8765)

It takes a long time to load or I cannot open multiple instances at once

This is often related to port availability. The default port may already be used by another process or by another Aidge GUI instance.

In that case, specify another available port:

visualize(graph, port=8766)

I updated Aidge GUI, but I do not see any difference in the browser

This is probably caused by the browser cache.

Try refreshing the page first. If the issue persists, clear the browser cache or force a hard refresh:

• Ctrl + F5 or Ctrl + Shift + R on Windows/Linux
• Cmd + Shift + R on macOS