gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/__init__.py

@@ -0,0 +1,12 @@
+"""GINI gBuilder — next-generation topology builder for networks + cloud."""
+
+# Version is derived from git tags at build time by setuptools-scm, which writes _version.py into
+# the package. Running from a source checkout without a build falls back to a dev marker.
+try:
+    from ._version import version as __version__
+except Exception:  # noqa: BLE001 — no built _version.py (raw source tree)
+    try:
+        from importlib.metadata import version as _v
+        __version__ = _v("gini-toolkit")
+    except Exception:  # noqa: BLE001
+        __version__ = "0.0.0+unknown"

gini/__main__.py

@@ -0,0 +1,107 @@
+"""Launch gBuilder.
+
+    python -m gini                 # run the app
+    python -m gini --demo          # run with a sample hybrid topology
+    QT_QPA_PLATFORM=offscreen python -m gini --selftest   # headless smoke test
+"""
+from __future__ import annotations
+
+import sys
+
+
+def build_demo(api) -> None:
+    """A small hybrid networks + cloud topology for first-run / selftest."""
+    r1 = api.add_device("router", x=-260, y=-160)
+    s1 = api.add_device("switch", x=-260, y=-20)
+    h1 = api.add_device("host", x=-380, y=120)
+    api.add_device("host", x=-160, y=120)
+    api.connect(r1["name"], s1["name"])
+    api.connect(s1["name"], h1["name"])
+
+    vpc = api.add_device("vpc", x=160, y=-180)
+    lb = api.add_device("load_balancer", x=160, y=-40)
+    inst = api.add_device("instance", x=40, y=110)
+    api.add_device("instance", x=280, y=110)
+    db = api.add_device("database", x=160, y=240)
+    api.connect(vpc["name"], lb["name"])
+    api.connect(lb["name"], inst["name"])
+    api.connect(inst["name"], db["name"])
+    api.connect(r1["name"], vpc["name"], "hybrid uplink")
+
+
+def _apply_branding(app) -> None:
+    """Name + icon so the taskbar/dock shows the GINI mascot (not the Python launcher)."""
+    from .ui.branding import app_icon, icon_path
+    app.setApplicationName("gBuilder")
+    app.setApplicationDisplayName("gBuilder")
+    app.setOrganizationName("GINI")
+    app.setWindowIcon(app_icon())
+    if sys.platform == "win32":          # make Windows group + show OUR icon, not python.exe's
+        try:
+            import ctypes
+            ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID("GINI.gBuilder")
+        except Exception:
+            pass
+    elif sys.platform == "darwin":       # set the Dock icon when run from source (needs pyobjc)
+        try:
+            from AppKit import NSApplication, NSImage
+            img = NSImage.alloc().initByReferencingFile_(icon_path())
+            NSApplication.sharedApplication().setApplicationIconImage_(img)
+        except Exception:
+            pass                          # no pyobjc → bundle a .app for a permanent Dock icon
+
+
+def _setup_preflight() -> None:
+    """Soft check: Demo mode always works; live Run needs the container runtime + images from
+    `gini-setup`. We only nudge here — never block — so the app is explorable immediately."""
+    try:
+        from . import __version__
+        from .setup import marker
+        if not marker.is_setup_done():
+            print("[gini] Runtime not set up yet — Demo mode works now; run `gini-setup` to enable "
+                  "live Run (installs Docker/Colima + pulls images).")
+        elif marker.needs_update(__version__):
+            print(f"[gini] App is {__version__} but images were set up for {marker.setup_version()} "
+                  "— run `gini-setup --update` to refresh them.")
+    except Exception:
+        pass
+
+
+def main() -> int:
+    args = set(sys.argv[1:])
+    from PySide6.QtWidgets import QApplication
+
+    app = QApplication.instance() or QApplication(sys.argv)
+    _apply_branding(app)
+    from .ui import MainWindow
+
+    win = MainWindow(app)
+
+    if "--demo" in args or "--selftest" in args:
+        build_demo(win.api)
+
+    if "--selftest" in args:
+        s = win.api.summary()
+        assert s["devices"] >= 9, s
+        assert s["links"] >= 6, s
+        explanation = win.api.explain_topology()
+        assert "elements" in explanation
+        # exercise theme swap + node creation paths
+        win.theme.set_theme("Light")
+        win.theme.set_theme("GINI Brand")
+        print("SELFTEST OK:", s)
+        print("EXPLAIN:", explanation)
+        return 0
+
+    if not ({"--demo", "--selftest"} & args):
+        win.restore_last_project()                 # reopen last session's project
+
+    _setup_preflight()                             # non-blocking: Demo always works
+    win.show()
+    from PySide6.QtCore import QTimer
+    QTimer.singleShot(450, win.maybe_start_tour)   # feature tour, once the window is painted
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gini/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '6.0.1.dev0'
+__version_tuple__ = version_tuple = (6, 0, 1, 'dev0')
+
+__commit_id__ = commit_id = None

gini/agent/__init__.py

@@ -0,0 +1,17 @@
+"""Agent package.
+
+`GiniAPI` is exposed lazily: importing it pulls in `app.context` -> PySide6, and headless consumers
+(the Teaching Center server, CI, scripts) need the pure pieces of this package — `authoring`,
+`teaching_center`, `lesson_resolver` — WITHOUT a GUI dependency. `from gini.agent import GiniAPI`
+still works exactly as before; it just doesn't happen at package-import time.
+"""
+
+
+def __getattr__(name):                      # PEP 562 lazy attribute
+    if name == "GiniAPI":
+        from .api import GiniAPI
+        return GiniAPI
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["GiniAPI"]

gini/agent/agent_gamemaster.py

@@ -0,0 +1,140 @@
+"""AgentGameMaster — a drop-in for `GameMaster` whose reasoning runs through the multi-agent stack
+(blackboard + personas), so the live mission loop is *exercised* by the new architecture without
+touching MissionController's proven mechanics (panel, guided steps, scoring, completion, flags).
+
+It exposes the exact method surface the controller drives — `brief_line`, `present_step`,
+`react_reply`, `decide`, `flag_note` — but:
+  • grounds every line in the blackboard's live objective verdicts (fed from the mission's own
+    results, so no double evaluation);
+  • routes a student question (decide with an utterance) through the full MissionAgent turn
+    (classify → understand → reason → critic), and a quiet canvas-reaction through the Reasoning
+    persona alone (fast, no extra model calls per drop);
+  • returns a `contracts.Move` whose `kind == "quiet"` is what the controller treats as silence.
+
+Missions stay LLM-gated: with `llm=None` every method degrades to the authored text (inert), matching
+`GameMaster`.
+"""
+from __future__ import annotations
+
+from .blackboard import Blackboard
+from .contracts import Move, Notification
+from .meaning import MissionAgent
+from .personas import PersonaRunner
+from .reasoning import REASONING
+
+
+class AgentGameMaster:
+    def __init__(self, lesson, llm=None, *, persona: str | None = None,
+                 twin_enabled: bool = False) -> None:
+        self.lesson = lesson
+        self.llm = llm
+        self.persona = persona or getattr(lesson, "persona", "coach")
+        self.runner = PersonaRunner(llm)
+        self.bb = Blackboard()
+        self.bb.load_lesson(lesson)
+        # Reasoning 2.0: the Twin audits covered turns. Model-gated — with no LLM the persona
+        # answers are authored text and a coverage dialogue would only add noise.
+        twin = None
+        if twin_enabled and llm is not None:
+            from .twin.dialectic import Twin
+            twin = Twin()
+        self.agent = MissionAgent(self.runner, self.bb, lesson, twin=twin)
+        self.reasoning = self.agent.reasoning
+        self._prev_met: int | None = None
+        self._get_world = None                          # bound by the controller (for the explainer)
+
+    def bind_world(self, getter) -> None:
+        """The controller hands us a way to read the live world, so the Reasoning persona can ground
+        its 'why is this red' diagnosis in the actual board (the predicate explainer)."""
+        self._get_world = getter
+
+    def _sync_world(self) -> None:
+        if self._get_world is not None:
+            try:
+                self.bb._world = self._get_world()
+            except Exception:
+                self.bb._world = None
+
+    # -- narration (Reasoning persona, grounded in mission intent) ----------- #
+    def brief_line(self) -> str:
+        if self.llm is None:
+            return self.lesson.brief
+        return self.runner.call(
+            REASONING, context=self.reasoning._intent(),
+            task=f"Brief the student on this mission in 1-2 short lines, in character, ending by "
+                 f"starting the clock. The task: {self.lesson.brief}") or self.lesson.brief
+
+    def present_step(self, step, index: int, total: int, *, acked: str = "") -> str:
+        if self.llm is None:
+            return step.say
+        lead = (f"The student just finished the previous beat ({acked}); acknowledge it in a few "
+                "words, then ") if acked else ""
+        return self.runner.call(
+            REASONING, context=self.reasoning._context(),
+            task=f"This is a guided lab, beat {index}/{total}. {lead}give the student THIS one "
+                 f"instruction in 1-2 short lines — just this step: {step.say}") or step.say
+
+    def react_reply(self, step, utterance: str, results) -> str:
+        self.bb.ingest_results(results)
+        if self.llm is None:
+            return "Good — let's continue."
+        return self.runner.call(
+            REASONING, context=self.reasoning._context(),
+            task=f"The student was asked: {step.say!r} and replied: {utterance!r}. Respond in 1-2 "
+                 "short lines — affirm or gently correct, grounded in the goal; then we move on."
+        ) or "Good — let's continue."
+
+    def run_note(self, failed) -> str:
+        """React to a Run whose live checks FAILED — grounded so the model can't claim a false win."""
+        joined = "; ".join(failed)
+        if self.llm is None:
+            return f"The live check didn't pass yet: {joined}. Check the real connection."
+        return self.runner.call(
+            REASONING, context=self.reasoning._context(),
+            task=f"The student ran the system and a LIVE check FAILED: {joined}. In ONE short line, "
+                 "tell them the live verification did not pass yet and to check the actual "
+                 "connection — do NOT claim it succeeded.") or f"The live check didn't pass: {joined}."
+
+    def flag_note(self, reasons) -> str:
+        joined = "; ".join(reasons)
+        if self.llm is None:
+            return "Heads up — " + joined
+        return self.runner.call(
+            REASONING, context=self.reasoning._context(),
+            task=f"The student just placed something off-task: {joined}. In ONE short in-character "
+                 "line, flag it and tell them to fix it — do NOT remove it for them."
+        ) or ("Heads up — " + joined)
+
+    # -- the reasoning turn (what the controller calls on change / ask) ------ #
+    def decide(self, mission, results, *, utterance: str = "", world_digest: str = "") -> Move:
+        if self.llm is None:
+            return Move("quiet")
+        self.bb.ingest_results(results)                     # sync truth from the mission's own eval
+        self._sync_world()                                  # give the explainer the live board
+
+        if utterance:                                       # a question → full trio (grounded + audited)
+            return self.agent.turn(utterance=utterance)
+
+        met = sum(1 for r in results if r.met)
+        first = self._prev_met is None
+        prev = self._prev_met
+        self._prev_met = met
+
+        if mission.complete:
+            trigger = Notification("mission_complete", salience=1.0)
+        elif getattr(mission, "state", "") == "done":
+            trigger = Notification("objective_unmet", salience=0.4)   # ran out — encourage
+        elif self.lesson.help == "none":
+            return Move("quiet")                            # proctored: silent except completion
+        elif not first and met > prev:
+            trigger = Notification("objective_met", salience=0.6)
+        elif not first and met < prev:
+            trigger = Notification("objective_unmet", salience=0.4)
+        else:
+            return Move("quiet")                            # no salient change → stay quiet
+
+        return self.reasoning.react(trigger)                # quiet reaction path: Reasoning only (fast)
+
+    # parity with GameMaster's convenience method
+    def observe(self, mission, results) -> Move:
+        return self.decide(mission, results)

gini/agent/api.py

@@ -0,0 +1,291 @@
+"""GiniAPI — the programmatic surface AI agents drive.
+
+This is the single, UI-independent entry point for *building*, *inspecting*, and
+*explaining* topologies. The in-app assistant calls it directly; the MCP server
+(`mcp_server.py`) wraps these same methods as tools for external agents like Claude.
+
+The `explain_*` methods are deterministic (rule-based) so they work with no LLM and
+are unit-testable; an LLM assistant can layer richer narration on top of them.
+"""
+from __future__ import annotations
+
+from ..app import AppContext
+from ..domain import Category, all_devices, devices
+from ..domain.topology import DeviceInstance
+
+
+class GiniAPI:
+    def __init__(self, ctx: AppContext) -> None:
+        self.ctx = ctx
+
+    # -- resolution --------------------------------------------------------- #
+    def _resolve(self, ref: str) -> DeviceInstance:
+        t = self.ctx.topology
+        if ref in t.devices:
+            return t.devices[ref]
+        d = t.find_by_name(ref)
+        if d is None:
+            raise KeyError(f"no device named or id'd {ref!r}")
+        return d
+
+    # -- catalog ------------------------------------------------------------ #
+    def list_device_types(self) -> list[dict]:
+        return [
+            {"key": d.key, "label": d.label, "category": d.category.value,
+             "cloud": d.cloud, "description": d.description}
+            for d in all_devices()
+        ]
+
+    # -- build -------------------------------------------------------------- #
+    def add_device(self, type_key: str, name: str | None = None,
+                   x: float = 0.0, y: float = 0.0,
+                   properties: dict | None = None) -> dict:
+        if type_key not in devices.REGISTRY:
+            raise KeyError(f"unknown device type {type_key!r}")
+        inst = self.ctx.add_device(type_key, x=x, y=y, name=name, properties=properties)
+        return self._device_dict(inst)
+
+    def connect(self, a: str, b: str, label: str = "") -> dict:
+        da, db = self._resolve(a), self._resolve(b)
+        # ctx.connect auto-attaches Source/Sink riders (dotted edge) and links everything else —
+        # same behaviour as the canvas, so agent/recipe wiring matches what a teacher would draw.
+        link = self.ctx.connect(da.id, db.id, label)
+        return {"id": link.id, "source": da.name, "target": db.name, "label": label}
+
+    def remove_device(self, ref: str) -> None:
+        self.ctx.remove_device(self._resolve(ref).id)
+
+    def set_property(self, ref: str, key: str, value: str) -> dict:
+        d = self._resolve(ref)
+        d.properties[key] = value
+        if key == "Name":
+            self.ctx.topology.rename(d.id, value)
+        self.ctx.bus.device_changed.emit(d.id)
+        # The advisory lint reads PROPERTIES, not just shape — "No BoardID set",
+        # duplicate BoardID, overlapping PhysicalSubnet — but it only re-ran on
+        # topology_changed. So a warning raised when an element was dropped (every
+        # property still at its default) was never re-evaluated once the student
+        # filled the property in: a GINI32 board showed the amber "!" for a missing
+        # BoardID while simultaneously reporting itself online, which is impossible,
+        # since the relay matches boards BY that id. The badge was simply stale.
+        # This is debounced (120 ms) and text fields commit on editingFinished, so
+        # re-linting here costs nothing per edit.
+        self.ctx.bus.topology_changed.emit()
+        return self._device_dict(d)
+
+    # -- manual addressing -------------------------------------------------- #
+    def set_manual_addressing(self, on: bool) -> None:
+        """Toggle manual addressing: stop auto-assigning IPs and honor static_ips
+        (auto-filling any interface left blank)."""
+        self.ctx.topology.manual_addressing = bool(on)
+        self.ctx.bus.topology_changed.emit()
+
+    def set_interface_ip(self, ref: str, link_id: str, ip: str) -> dict:
+        """Set (or clear, with an empty string) a device's static IP on one interface
+        (identified by the link it sits on). Honored only in manual addressing mode."""
+        d = self._resolve(ref)
+        bare = (ip or "").strip().split("/")[0]
+        si = dict(getattr(d, "static_ips", None) or {})
+        if bare:
+            si[link_id] = bare
+        else:
+            si.pop(link_id, None)
+        d.static_ips = si
+        self.ctx.bus.topology_changed.emit()
+        return self._device_dict(d)
+
+    # -- recipes (Wizard blueprints) ---------------------------------------- #
+    def list_recipes(self) -> list[dict]:
+        from ..domain.recipes import RECIPES
+        return [{"id": r.id, "name": r.name, "summary": r.summary,
+                 "teaches": r.teaches, "intent": list(r.intent)} for r in RECIPES]
+
+    def suggest_recipes(self, query: str) -> list[dict]:
+        """Rank recipes against a free-text intent (deterministic; the LLM mirrors this
+        but can also explain). Returns the matching recipes, best first."""
+        from ..domain.recipes import suggest_recipes
+        return [{"id": r.id, "name": r.name, "summary": r.summary, "teaches": r.teaches}
+                for r in suggest_recipes(query)]
+
+    def apply_recipe(self, recipe_id: str) -> dict:
+        """Instantiate a curated blueprint onto the canvas — add its elements (laid out
+        on a grid), set their properties, and connect them. Deterministic: no LLM in this
+        path, so the result is always a valid, known-good topology."""
+        from ..domain.recipes import get_recipe
+        r = get_recipe(recipe_id)
+        if r is None:
+            raise KeyError(f"unknown recipe {recipe_id!r}")
+        # offset the layout below anything already on the canvas
+        base_y = 0.0
+        if self.ctx.topology.devices:
+            base_y = max(d.y for d in self.ctx.topology.devices.values()) + 170.0
+        refs: dict[str, str] = {}
+        for el in r.elements:
+            x = 60.0 + el.col * 220.0
+            y = base_y + 40.0 + el.row * 150.0
+            d = self.add_device(el.type_key, x=x, y=y, properties=el.props or None)
+            refs[el.ref] = d["id"]
+            # box containment (VPC / Subnet / Region): set parent_id so the compiler
+            # reads membership. Parents precede children in element order.
+            parent = getattr(el, "parent", "")
+            if parent and parent in refs:
+                dev = self.ctx.topology.devices.get(d["id"])
+                if dev is not None:
+                    dev.parent_id = refs[parent]
+        links = 0
+        for a, b in r.links:
+            self.connect(refs[a], refs[b])
+            links += 1
+        return {"recipe": r.id, "name": r.name, "added": list(refs.values()),
+                "links": links}
+
+    # -- inspect ------------------------------------------------------------ #
+    def get_topology(self) -> dict:
+        return self.ctx.topology.to_dict()
+
+    def inspect(self, ref: str) -> dict:
+        d = self._resolve(ref)
+        out = self._device_dict(d)
+        out["neighbors"] = [n.name for n in self.ctx.topology.neighbors(d.id)]
+        out["degree"] = self.ctx.topology.degree(d.id)
+        return out
+
+    def summary(self) -> dict:
+        t = self.ctx.topology
+        return {
+            "name": t.name,
+            "devices": len(t.devices),
+            "links": len(t.links),
+            "by_category": t.counts_by_category(),
+        }
+
+    # -- explain (deterministic narration) ---------------------------------- #
+    def explain_topology(self) -> str:
+        t = self.ctx.topology
+        if not t.devices:
+            return "The canvas is empty. Drag a device from the palette to begin."
+        counts = t.counts_by_category()
+        has_net = any(c in counts for c in (Category.NETWORKING.value, Category.SDN.value))
+        has_cloud = any(k in counts for k in (
+            Category.CONTAINERS.value, Category.CLOUD_NETWORK.value,
+            Category.STORAGE.value, Category.SERVERLESS.value))
+
+        parts = [f"This topology “{t.name}” has {len(t.devices)} elements "
+                 f"and {len(t.links)} links."]
+        cat_bits = [f"{n} {cat.lower()}" for cat, n in counts.items()]
+        parts.append("It spans " + ", ".join(cat_bits) + ".")
+        if has_net and has_cloud:
+            parts.append("It is a hybrid experiment combining classic network devices "
+                         "with cloud-computing primitives.")
+        elif has_cloud:
+            parts.append("This is primarily a cloud-computing scenario.")
+        else:
+            parts.append("This is primarily a computer-networking scenario.")
+
+        # connectivity notes
+        isolated = [d.name for d in t.devices.values() if t.degree(d.id) == 0]
+        if isolated:
+            parts.append("Not yet connected: " + ", ".join(isolated) + ".")
+        hubs = sorted(t.devices.values(), key=lambda d: t.degree(d.id), reverse=True)
+        if hubs and t.degree(hubs[0].id) >= 2:
+            parts.append(f"{hubs[0].name} is the most connected node "
+                         f"({t.degree(hubs[0].id)} links).")
+        return " ".join(parts)
+
+    def context_digest(self) -> str:
+        """A compact, ground-truth snapshot of the current canvas for the AI: every
+        device with its type, IP/subnet, and what it connects to. Injected into the
+        model each turn so the assistant always knows the topology without a tool call.
+        """
+        t = self.ctx.topology
+        if not t.devices:
+            return "The canvas is currently empty (no devices placed yet)."
+        try:
+            from ..services.compiler import address_map
+            addr = address_map(t)
+        except Exception:
+            addr = {}
+        lines = [f'Topology "{t.name}": {len(t.devices)} devices, {len(t.links)} links.']
+        subnets: set[str] = set()
+        for d in t.devices.values():
+            info = addr.get(d.name, {})
+            ifaces = info.get("interfaces", [])
+            ip_bits = []
+            for itf in ifaces:
+                if itf.get("ip"):
+                    ip_bits.append(itf["ip"])
+                if itf.get("subnet"):
+                    subnets.add(itf["subnet"])
+            ip_s = (" — " + ", ".join(ip_bits)) if ip_bits else ""
+            nbrs = [n.name for n in t.neighbors(d.id)]
+            conn = ("connected to " + ", ".join(nbrs)) if nbrs else "not connected yet"
+            gw = next((itf.get("gateway") for itf in ifaces if itf.get("gateway")), None)
+            gw_s = f", gateway {gw}" if gw else ""
+            lines.append(f"- {d.name} ({d.type.label}){ip_s} — {conn}{gw_s}")
+        if subnets:
+            lines.append("Subnets: " + ", ".join(sorted(subnets)) + ".")
+        return "\n".join(lines)
+
+    def explain_element_type(self, type_key: str) -> str:
+        """Teaching guide for a palette element TYPE (what it is + when to use it).
+        Falls back to the catalog description if the element isn't in the guide."""
+        from ..domain.devices import REGISTRY
+        from ..domain.element_guide import guide_for
+        dt = REGISTRY.get(type_key)
+        if dt is None:
+            return f"I don't recognize the element '{type_key}'."
+        return guide_for(type_key) or f"{dt.label} ({dt.category.value}). {dt.description}"
+
+    def trace_path(self, src: str, dst: str) -> list[str]:
+        """The hop-by-hop device path a packet takes from src to dst (by name).
+
+        Shortest path over the topology graph — which is exactly the forwarding path,
+        since routing follows it. Returns device names (e.g. [M1, S1, R1, R2, S2, M5])
+        or [] if there's no path. Drives the tutor's packet animation.
+        """
+        from collections import deque
+        s, d = self._resolve(src), self._resolve(dst)
+        t = self.ctx.topology
+        nbrs: dict[str, list] = {}
+        for l in t.links.values():
+            nbrs.setdefault(l.source_id, []).append(l.target_id)
+            nbrs.setdefault(l.target_id, []).append(l.source_id)
+        prev: dict[str, str | None] = {s.id: None}
+        q = deque([s.id])
+        while q:
+            cur = q.popleft()
+            if cur == d.id:
+                break
+            for nb in nbrs.get(cur, []):
+                if nb not in prev:
+                    prev[nb] = cur
+                    q.append(nb)
+        if d.id not in prev:
+            return []
+        path, cur = [], d.id
+        while cur is not None:
+            path.append(t.devices[cur].name)
+            cur = prev[cur]
+        path.reverse()
+        return path
+
+    def explain_device(self, ref: str) -> str:
+        d = self._resolve(ref)
+        dt = d.type
+        nbrs = [n.name for n in self.ctx.topology.neighbors(d.id)]
+        msg = f"{d.name} is a {dt.label} ({dt.category.value}). {dt.description}"
+        props = {k: v for k, v in d.properties.items() if v and k != "Name"}
+        if props:
+            msg += " Configured: " + ", ".join(f"{k}={v}" for k, v in props.items()) + "."
+        msg += (f" It connects to {', '.join(nbrs)}." if nbrs
+                else " It is not connected to anything yet.")
+        return msg
+
+    # -- helpers ------------------------------------------------------------ #
+    @staticmethod
+    def _device_dict(d: DeviceInstance) -> dict:
+        return {
+            "id": d.id, "name": d.name, "type": d.type_key,
+            "category": d.type.category.value,
+            "x": d.x, "y": d.y, "properties": dict(d.properties),
+        }