Mas interactive gui

[frederikmuthers]

Pull Request

Added a gui for LocalMAS object based on dash that can be called by mas.show_gui() and is closed by mas.stop_gui(). Will show all agents and their flows of communication as well as the way in which the communication was declared in the configs.

An example can be found in examples\multi-agent-systems\room_mas\room_mas.py.

[Copilot]

Pull request overview

This PR introduces an interactive Dash/Cytoscape GUI to visualize LocalMAS agent communication dependencies, exposed via LocalMASAgency.show_gui() / stop_gui(), and demonstrates usage in the room_mas example.

Changes:

• Add a new Dash-based dependency graph dashboard (agentlib/utils/plotting/dependency_graph.py).
• Add show_gui() / stop_gui() to LocalMASAgency to start/stop the GUI in a background process.
• Update the room_mas example to call the new GUI methods.

Change Classification: Feature
Backward Compatibility: Compatible (additive API), but introduces optional-runtime behavior for GUI usage
CI Risk: High (example currently blocks/hangs tests; new file likely triggers pylint warnings)

Key Issues:

1. The room_mas example currently calls stop_gui() before mas.run(), which blocks on input() and will break automated example tests.
2. LocalMASAgency is a Pydantic model; _gui_process should be declared as a PrivateAttr to avoid runtime errors when assigning it.
3. dependency_graph.py has multiple lint/CI hazards (invalid OptionalDependencyError install hint, unused imports, misplaced docstring, late import).
4. The new dependency extraction logic is non-trivial and should have unit tests similar to simulator_dashboard utilities.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
examples/multi-agent-systems/room_mas/room_mas.py	Demonstrates new GUI API, but currently blocks execution/tests due to stop_gui() placement.
agentlib/utils/plotting/dependency_graph.py	New Dash/Cytoscape dashboard and dependency extraction logic for MAS visualization.
agentlib/utils/multi_agent_system.py	Adds public GUI start/stop methods to LocalMASAgency and manages a GUI subprocess.

Comments suppressed due to low confidence (7)

agentlib/utils/multi_agent_system.py:183

• stop_gui() uses input(); in non-interactive contexts (e.g., stdin closed) this can raise EOFError and crash callers. Catch EOFError alongside KeyboardInterrupt so stop_gui() can still terminate the GUI cleanly.

                    time.sleep(3)
                    input(f"\n{prompt}\n")
            except KeyboardInterrupt:

agentlib/utils/multi_agent_system.py:189

• Library code should use the module logger instead of print() to avoid noisy stdout and to integrate with AgentLib's logging configuration.

                self._gui_process.terminate()
                self._gui_process.join()
                self._gui_process = None
                print("Terminated GUI.")

agentlib/utils/plotting/dependency_graph.py:108

• run_dashboard() has a stray string literal because the docstring is not the first statement in the function; this triggers pylint warnings and the function effectively has no docstring. Move the docstring to the top of the function body.

def run_dashboard(deps: List[Tuple[str, str, str, str]], agent_ids: List[str]):

    log = logging.getLogger("werkzeug")
    log.setLevel(logging.ERROR)

agentlib/utils/plotting/dependency_graph.py:373

• logger is defined at module scope but never used, which will trigger an unused-variable warning. Either remove it or use it for useful runtime info (e.g., where the dashboard is served).

    port = get_port()
    webbrowser.open_new_tab(f"http://localhost:{port}")
    app.run(debug=False, port=port, use_reloader=False)

agentlib/utils/plotting/dependency_graph.py:61

• New dependency extraction logic (_extract_dependencies/_get_var_mechanism) is non-trivial and similar interactive utilities in this repo have unit tests (e.g., tests/test_simulator_dashboard.py). Please add focused unit tests for dependency extraction/tagging to prevent regressions.

def _extract_dependencies(
    mas: "LocalMASAgency",
) -> List[Tuple[str, str, str, str]]:
    """Extract individual variable dependencies between agents.

    Returns a list of (producer_agent, subscriber_agent, variable_label, mechanism_tag)
    where mechanism_tag is one of "shared+sub", "svf+sub", or "source".
    """

agentlib/utils/plotting/dependency_graph.py:16

• The OptionalDependencyError currently suggests an invalid install command (pip install interactive (needs dash-cytoscape)). dependency_install should be a valid pip install argument (e.g., the missing packages), and it’s helpful to chain the original ImportError.

    import dash_cytoscape as cyto
except ImportError:
    raise OptionalDependencyError("mas_dependency_graph", "interactive (needs dash-cytoscape)")

agentlib/utils/plotting/dependency_graph.py:378

• Now that multiprocessing is imported at the top of the file, remove the late import here to avoid pylint import-order warnings.

import multiprocessing

def show_dependency_graph(mas: "LocalMASAgency") -> multiprocessing.Process:

[sarahleidolf]

Further testing of the GUI on large agent systems is necessary

[sarahleidolf]

Isn't it possible to do this in a single step, since I always want to continue the simulation after calling the GUI?
Or, using multiprocessing, just call show_gui() and then let the simulation run in parallel without needing to call stop_gui().