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

gini/agent/llm/backend.py

@@ -0,0 +1,43 @@
+"""LLM backend abstraction.
+
+One thin contract so the model is a config choice: Ollama (local/campus) by default,
+any OpenAI-compatible server, or cloud. `chat()` yields a stream of Chunks (text deltas
+and/or tool calls). The agent loop drives it; the deterministic core means the app
+still works if no backend is reachable.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class Message:
+    role: str                       # system | user | assistant | tool
+    content: str = ""
+    name: str | None = None         # tool name (role == "tool")
+    tool_calls: list["ToolCall"] = field(default_factory=list)
+
+
+@dataclass
+class ToolCall:
+    name: str
+    arguments: dict
+    id: str = ""
+
+
+@dataclass
+class Chunk:
+    text: str = ""
+    tool_call: ToolCall | None = None
+
+
+@runtime_checkable
+class LLMBackend(Protocol):
+    def chat(self, messages: list[Message], tools: list[dict] | None = None,
+             stream: bool = False) -> Iterator[Chunk]:
+        ...
+
+    def available(self) -> bool:
+        ...

gini/agent/llm/fake.py

@@ -0,0 +1,25 @@
+"""Scripted backend for tests and offline demos.
+
+Returns a pre-set list of Chunks per chat() call, so the agent loop can be exercised
+deterministically without a model. Each entry in `script` is the list of Chunks the
+n-th chat() call yields (e.g. a tool_call turn, then a text turn).
+"""
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from .backend import Chunk
+
+
+class ScriptedBackend:
+    def __init__(self, script: list[list[Chunk]]) -> None:
+        self.script = list(script)
+        self.calls: list[list] = []     # captured (messages, tools) per call
+
+    def available(self) -> bool:
+        return True
+
+    def chat(self, messages, tools=None, stream=False) -> Iterator[Chunk]:
+        self.calls.append((list(messages), tools))
+        chunks = self.script.pop(0) if self.script else [Chunk(text="(done)")]
+        yield from chunks

gini/agent/llm/ollama.py

@@ -0,0 +1,206 @@
+"""Ollama backend (self-hosted, local/campus).
+
+Talks to Ollama's /api/chat with OpenAI-style tools. Uses only the stdlib (urllib) so
+there's no extra dependency. The HTTP call is injectable (`transport=`) so the request
+shaping and response parsing are unit-testable without a running server.
+
+Config: url (e.g. http://gpu.cs.univ.edu:11434), model, timeout.
+"""
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Iterator
+
+from .backend import Chunk, Message, ToolCall
+
+# reasoning ("thinking") models wrap their chain-of-thought in tags — strip it so it
+# never reaches the chat or the JSON tool-parser. Covers <think>…</think> and Gemma's
+# <|think|>…<|/think|> styles, terminated or not.
+_THINK_BLOCK = re.compile(r"<\|?\s*think\s*\|?>.*?<\|?\s*/\s*think\s*\|?>",
+                          re.DOTALL | re.IGNORECASE)
+_THINK_TAG = re.compile(r"<\|?\s*/?\s*think[^>]*?\|?>", re.IGNORECASE)
+
+
+def strip_thinking(text: str) -> str:
+    """Remove a model's reasoning, returning just the answer it intends to show."""
+    if not text:
+        return text
+    for close in ("</think>", "<|/think|>", "<|end_think|>"):
+        if close in text:                     # answer follows the last closing tag
+            text = text.rsplit(close, 1)[1]
+    text = _THINK_BLOCK.sub("", text)
+    text = _THINK_TAG.sub("", text)           # drop any stray/open think markers
+    return text.strip()
+
+
+def _to_ollama_message(m: Message) -> dict:
+    msg: dict = {"role": m.role, "content": m.content}
+    if m.role == "tool" and m.name:
+        msg["tool_name"] = m.name
+    if m.tool_calls:
+        msg["tool_calls"] = [
+            {"function": {"name": tc.name, "arguments": tc.arguments}} for tc in m.tool_calls
+        ]
+    return msg
+
+
+class OllamaBackend:
+    def __init__(self, url: str = "http://localhost:11434", model: str = "llama3.1",
+                 timeout: float = 120.0, think: bool = False, stream: bool = True,
+                 num_ctx: int = 8192, embed_model: str = "all-minilm",
+                 transport: Callable[[str, dict], dict] | None = None) -> None:
+        self.url = url.rstrip("/")
+        self.model = model
+        self.embed_model = embed_model     # small embed model for L2 semantic recall (/api/embed)
+        self.timeout = timeout
+        # Ollama's DEFAULT context window is only 2048 tokens — far smaller than the model's
+        # real window — and it SILENTLY TRUNCATES the prompt when exceeded. Set it explicitly
+        # so the catalog/canvas/question always fit. (Ollama clamps to the model's real max.)
+        self.num_ctx = num_ctx
+        self.think = think          # ask reasoning models to think (Ollama `think` flag)
+        self.stream = stream        # stream tokens for a live "typing" feel
+        self._injected = transport is not None   # tests inject a transport (non-streaming)
+        self._transport = transport or self._http_post
+
+    # -- HTTP ---------------------------------------------------------------- #
+    def _http_post(self, path: str, payload: dict) -> dict:
+        req = urllib.request.Request(
+            self.url + path,
+            data=json.dumps(payload).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            return json.loads(resp.read().decode())
+
+    def available(self) -> bool:
+        try:
+            req = urllib.request.Request(self.url + "/api/tags", method="GET")
+            urllib.request.urlopen(req, timeout=3.0)
+            return True
+        except (urllib.error.URLError, OSError):
+            return False
+
+    # -- embeddings (L2 semantic recall) ------------------------------------- #
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed one or more texts via Ollama's `/api/embed` (same server as chat). Returns a
+        list of vectors aligned with `texts`; [] on any failure so callers degrade to lexical."""
+        if not texts:
+            return []
+        try:
+            data = self._transport("/api/embed", {"model": self.embed_model, "input": texts})
+        except Exception:
+            return []
+        return data.get("embeddings") or []
+
+    # -- chat ---------------------------------------------------------------- #
+    def chat(self, messages: list[Message], tools: list[dict] | None = None,
+             stream: bool = False, schema: dict | None = None) -> Iterator[Chunk]:
+        """`schema` (optional) is a JSON Schema passed as Ollama's `format` field — the server
+        CONSTRAINS decoding so the reply is guaranteed to match (structured outputs). Used by the
+        structured personas (coverage/classifier/critic JSON) so malformed output becomes a rare
+        transport error instead of a routine small-model failure. Reasoning-2.0 §10 amendment."""
+        base = {
+            "model": self.model,
+            "messages": [_to_ollama_message(m) for m in messages],
+            "stream": False,            # tool turns are most reliable non-streamed
+            "options": {"num_ctx": self.num_ctx},   # don't let Ollama truncate to 2048
+        }
+        # Try the richest request first, then degrade: a small model may not support
+        # tools and/or thinking, and Ollama errors rather than ignoring them. Dropping
+        # tools is safe — the agent loop's JSON-action fallback still drives tools.
+        attempts: list[dict] = []
+        full = dict(base)
+        if self.think:
+            full["think"] = True
+        if tools:
+            full["tools"] = tools
+        attempts.append(full)
+        if tools:                                   # without tools (keep think)
+            p = dict(base)
+            if self.think:
+                p["think"] = True
+            attempts.append(p)
+        attempts.append(dict(base))                 # bare minimum
+        if schema is not None:
+            # constrain every attempt; keep ONE unconstrained fallback (an older server may
+            # reject `format` — the callers' tolerant first_json parsing still applies then).
+            attempts = [{**p, "format": schema} for p in attempts] + [dict(base)]
+
+        # Stream the answer token-by-token over real HTTP (live "typing" feel). Tool
+        # turns still come back whole in the final streamed object. Injected transports
+        # (tests) keep the simple non-streaming path. Structured (schema) calls are
+        # machine-consumed, never displayed — no reason to stream them.
+        if self.stream and not self._injected and schema is None:
+            last_err = None
+            for payload in attempts:
+                try:
+                    yield from self._chat_stream(payload)
+                    return
+                except Exception as e:              # noqa: BLE001 — degrade on reject
+                    last_err = e
+            raise last_err
+
+        data, last_err = None, None
+        for payload in attempts:
+            try:
+                data = self._transport("/api/chat", payload)
+                break
+            except Exception as e:                  # noqa: BLE001 — degrade on any server reject
+                last_err = e
+        if data is None:
+            raise last_err
+        yield from self._parse(data)
+
+    def _chat_stream(self, payload: dict) -> Iterator[Chunk]:
+        """Stream Ollama's NDJSON response — one JSON object per line, each carrying a
+        small content delta — yielding a Chunk per delta and tool calls at the end."""
+        body = json.dumps({**payload, "stream": True}).encode()
+        req = urllib.request.Request(self.url + "/api/chat", data=body,
+                                     headers={"Content-Type": "application/json"},
+                                     method="POST")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            for raw in resp:                        # iterate lines as they arrive
+                line = raw.decode(errors="replace").strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                msg = obj.get("message", {}) or {}
+                delta = msg.get("content") or ""
+                if delta:
+                    yield Chunk(text=delta)         # not stripped: deltas are tiny
+                for call in msg.get("tool_calls", []) or []:
+                    fn = call.get("function", {})
+                    args = fn.get("arguments", {})
+                    if isinstance(args, str):
+                        try:
+                            args = json.loads(args)
+                        except json.JSONDecodeError:
+                            args = {}
+                    yield Chunk(tool_call=ToolCall(name=fn.get("name", ""), arguments=args or {}))
+                if obj.get("done"):
+                    break
+
+    @staticmethod
+    def _parse(data: dict) -> Iterator[Chunk]:
+        msg = data.get("message", {}) or {}
+        # Ollama returns reasoning either in a separate `thinking` field or inline in
+        # `content`; in both cases we show only the final answer.
+        text = strip_thinking(msg.get("content") or "")
+        if text:
+            yield Chunk(text=text)
+        for call in msg.get("tool_calls", []) or []:
+            fn = call.get("function", {})
+            args = fn.get("arguments", {})
+            if isinstance(args, str):           # some models return JSON-as-string
+                try:
+                    args = json.loads(args)
+                except json.JSONDecodeError:
+                    args = {}
+            yield Chunk(tool_call=ToolCall(name=fn.get("name", ""), arguments=args or {}))

gini/agent/loop.py

@@ -0,0 +1,258 @@
+"""The agent loop: backend + tool registry -> a working assistant/tutor brain.
+
+Runs the standard cycle — model proposes tool calls, we execute them against the shared
+registry, feed results back, repeat until the model answers in prose. Supports native
+tool calling and a JSON-action fallback for models that can't call tools, so GINI isn't
+hostage to one model's tool-use quality.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+
+from .llm.backend import LLMBackend, Message, ToolCall
+from .tools.registry import ToolRegistry
+
+ASSISTANT_NAME = "GINI"
+
+SYSTEM_PROMPT = (
+    f"You are {ASSISTANT_NAME}, a friendly teaching assistant living inside the GINI "
+    "gBuilder lab, where students build and run computer-network and cloud topologies. "
+    "Before each question you are given the LIVE state of the student's canvas — every "
+    "device, its IP addresses and subnets, and how things connect. Treat that state as "
+    "ground truth and answer from it directly; you do NOT need a tool to see the canvas. "
+    "Refer to devices by their names (e.g. R1, M1). Help students build, inspect, and "
+    "understand their topology, and explain networking/cloud concepts clearly and "
+    "concisely.\n"
+    "You can TEACH ON THE CANVAS — when explaining how something works, use the present "
+    "tools to direct the student's eye: `spotlight` a device to focus on it, `highlight` "
+    "a set, `callout` to anchor a short note on a device, `narrate` a line of teaching, "
+    "and `trace_path` + `animate_packet` to show how a packet flows between two hosts. "
+    "Prefer showing on the canvas over long text. Use build tools only when asked to "
+    "change the topology: `add_device` (args: type_key e.g. 'router'/'switch'/'host', and "
+    "optional name), `connect_devices` (args: a, b), `set_property`, `remove_device`. "
+    "`callout` needs a device and text. When no tool is needed, answer in plain language.\n"
+    "If you cannot call tools natively, emit JSON objects of the form "
+    '{\"tool\": \"<name>\", \"args\": { ... }} — and write any explanation as plain prose, '
+    "NOT inside the JSON. Never write tool calls as prose (e.g. `add_device type_key=...`).\n"
+    "GROUNDING: GINI has a specific, fixed set of elements — the ones listed in the context "
+    "below. Answer USING those elements and the GINI knowledge provided; treat that "
+    "knowledge and the canvas as the only source of truth. EVERY element you name must "
+    "appear verbatim in that GINI elements list; if something is not listed, it does NOT "
+    "exist in GINI — never mention or invent it, even if it is common in the real world "
+    "(e.g. there is no 'SDN dashboard'). If GINI has no element for something, say so "
+    "plainly. Do NOT reach for generic infrastructure or other products from your training. "
+    "When a live xv6 Machine state card is provided, the SAME rule applies to the kernel: "
+    "reason only about the processes, pids, states, registers and stack frames shown in that "
+    "card — it is this student's actual running kernel. Do not invent pids or values that "
+    "aren't there; if a detail isn't in the card, say it isn't shown rather than guessing.\n"
+    "Format answers in Markdown."
+)
+
+
+def _extract_json_objects(text: str) -> list[dict]:
+    """Pull balanced-brace JSON objects out of free text (handles nested args)."""
+    objs: list[dict] = []
+    depth = 0
+    start: int | None = None
+    for i, ch in enumerate(text or ""):
+        if ch == "{":
+            if depth == 0:
+                start = i
+            depth += 1
+        elif ch == "}" and depth > 0:
+            depth -= 1
+            if depth == 0 and start is not None:
+                try:
+                    objs.append(json.loads(text[start:i + 1]))
+                except json.JSONDecodeError:
+                    pass
+                start = None
+    return objs
+
+
+_TOOL_TAG_RE = re.compile(r"<\s*(tool_call|tool|json|function_call)\s*>.*?</\s*\1\s*>",
+                          re.S | re.I)
+
+# Some small models write tool calls as PROSE (`add_device type_key='host' name='F1'`),
+# which is neither native nor JSON, so it slips past the tag/JSON strippers and leaks into
+# chat. Strip those pseudo-calls: a full build/present tool name, one optional device-ref
+# arg (R1/F1/…), then key=value pairs. We DON'T match bare words as args (so following prose
+# like "… Now that …" is never eaten) and we leave callout/narrate alone (their text is the
+# model teaching). Bare verb aliases (add/connect) are excluded — too common in real prose.
+_PSEUDO_CALL_RE = re.compile(
+    r"\b(?:add_device|connect_devices|set_property|remove_device|spotlight|highlight|"
+    r"animate_packet|trace_path|clear_stage|inspect_device|get_topology|summarize_topology|"
+    r"explain_topology|explain_device|explain_element|list_device_types)\b"
+    r"(?:"
+    r"[ \t]+[A-Za-z]{1,4}\d+(?:[ \t]+\w+=(?:'[^']*'|\"[^\"]*\"|[^\s]+))*"   # ref [+ key=val…]
+    r"|(?:[ \t]+\w+=(?:'[^']*'|\"[^\"]*\"|[^\s]+))+"                        # or one+ key=val
+    r")")     # require args, so a bare mention of a tool name in prose is NOT stripped
+
+
+def _strip_tool_objects(text: str) -> str:
+    """Remove top-level {...} JSON objects that are tool actions (have a 'tool' key)."""
+    spans: list[tuple[int, int]] = []
+    depth = 0
+    start: int | None = None
+    for i, ch in enumerate(text):
+        if ch == "{":
+            if depth == 0:
+                start = i
+            depth += 1
+        elif ch == "}" and depth > 0:
+            depth -= 1
+            if depth == 0 and start is not None:
+                try:
+                    obj = json.loads(text[start:i + 1])
+                    if isinstance(obj, dict) and "tool" in obj:
+                        spans.append((start, i + 1))
+                except json.JSONDecodeError:
+                    pass
+                start = None
+    if not spans:
+        return text
+    out, prev = [], 0
+    for a, b in spans:
+        out.append(text[prev:a])
+        prev = b
+    out.append(text[prev:])
+    return "".join(out)
+
+
+def visible_text(raw: str) -> str:
+    """The user-facing prose from a model reply: keep the natural language and the *text*
+    of any callout/narrate calls (that's the model talking), but drop all tool-call syntax
+    — `<tool_call>`/`<json>` tag blocks and bare {"tool": …} action objects. So the chat
+    shows what the model SAID, while the loop still executes what it DID."""
+    raw = raw or ""
+    spoken: list[str] = []
+    for obj in _extract_json_objects(raw):
+        if obj.get("tool") in ("callout", "narrate"):
+            args = obj.get("args") or {}
+            t = args.get("text") or args.get("line") or args.get("note")
+            if t:
+                spoken.append(str(t).strip())
+    prose = _strip_tool_objects(_TOOL_TAG_RE.sub(" ", raw))
+    prose = _PSEUDO_CALL_RE.sub(" ", prose)                  # prose-style tool calls
+    prose = re.sub(r"`{3}.*?`{3}", " ", prose, flags=re.S)   # stray code fences
+    prose = re.sub(r"[ \t]*\n[ \t]*", "\n", prose)
+    prose = re.sub(r"[ \t]{2,}", " ", prose).strip()
+    parts, seen = [], set()
+    for p in ([prose] if prose else []) + spoken:
+        if p and p not in seen:
+            parts.append(p)
+            seen.add(p)
+    return "\n".join(parts)
+
+
+class AgentLoop:
+    def __init__(self, backend: LLMBackend, registry: ToolRegistry,
+                 system_prompt: str = SYSTEM_PROMPT, max_steps: int = 6,
+                 context_provider: Callable[[], str] | None = None,
+                 max_history: int = 30) -> None:
+        self.backend = backend
+        self.registry = registry
+        self.max_steps = max_steps
+        # returns a fresh snapshot of the live canvas; injected every turn
+        self.context_provider = context_provider
+        # keep the recent conversation (so the tutor remembers what was discussed) but
+        # bound it so it never overflows the model's context window — a sliding window
+        # over whole turns. The live canvas context is re-injected each turn regardless.
+        self.max_history = max_history
+        self.history: list[Message] = [Message("system", system_prompt)]
+        # a per-project 'brief' — the teacher's framing for this lab. Always injected as a
+        # system message so every answer is shaped by it (set by the Ask GINI panel on
+        # project load). Empty by default.
+        self.brief: str = ""
+        # the Ask GINI pipeline sets this each turn to the fully-assembled grounded context
+        # (always-on index + canvas + session knowledge + retrieved cards). When set it
+        # REPLACES the bare canvas snapshot, so grounding all flows through one block.
+        self.extra_context: str = ""
+
+    def _trim(self) -> None:
+        if len(self.history) <= self.max_history:
+            return
+        cut = len(self.history) - self.max_history
+        # advance to the next 'user' message so we don't orphan assistant/tool turns
+        while cut < len(self.history) and self.history[cut].role != "user":
+            cut += 1
+        if cut < len(self.history):
+            self.history = [self.history[0]] + self.history[cut:]
+
+    def _messages(self) -> list[Message]:
+        """Base system prompt + a FRESH canvas-state message + the conversation.
+        The context is regenerated each call (never stored), so the model always sees
+        the current topology and the history doesn't fill up with stale snapshots."""
+        msgs = [self.history[0]]
+        if self.brief:
+            msgs.append(Message("system",
+                                "Project brief — the teacher's framing for this lab. Keep your "
+                                "guidance consistent with it:\n" + self.brief))
+        if self.extra_context:
+            msgs.append(Message("system", self.extra_context))     # pipeline-assembled
+        elif self.context_provider is not None:
+            try:
+                ctx = self.context_provider()
+            except Exception:
+                ctx = ""
+            if ctx:
+                msgs.append(Message("system", "Current canvas (ground truth):\n" + ctx))
+        return msgs + self.history[1:]
+
+    def send(self, user_text: str, on_text: Callable[[str], None] | None = None) -> str:
+        """Run a full turn (possibly several tool round-trips) and return final prose."""
+        self.history.append(Message("user", user_text))
+        final = ""
+        for _ in range(self.max_steps):
+            text = ""
+            calls: list[ToolCall] = []
+            for chunk in self.backend.chat(self._messages(), tools=self.registry.openai_tools()):
+                if chunk.text:
+                    text += chunk.text
+                    if on_text:
+                        on_text(chunk.text)
+                if chunk.tool_call:
+                    calls.append(chunk.tool_call)
+
+            # fallback: a model with no native tools may emit a JSON action in text
+            if not calls:
+                calls = self._parse_json_actions(text)
+
+            self.history.append(Message("assistant", text, tool_calls=calls))
+
+            if not calls:
+                final = text
+                break
+
+            for tc in calls:
+                result = self.registry.execute(tc.name, tc.arguments)
+                self.history.append(Message("tool", json.dumps(result, default=str), name=tc.name))
+        self._trim()                 # keep recent context, bound the window
+        return final
+
+    # forgiving aliases — local models follow the prose prompt and use short verb names /
+    # 'type' instead of the registry's exact 'add_device' / 'type_key', so normalize them
+    # (otherwise the call silently doesn't match and nothing happens).
+    _TOOL_ALIASES = {
+        "add": "add_device", "create": "add_device", "place": "add_device",
+        "connect": "connect_devices", "link": "connect_devices", "wire": "connect_devices",
+        "remove": "remove_device", "delete": "remove_device",
+        "rename": "set_property", "set": "set_property",
+    }
+    _ARG_ALIASES = {"type": "type_key", "kind": "type_key", "device_type": "type_key"}
+
+    def _parse_json_actions(self, text: str) -> list[ToolCall]:
+        calls: list[ToolCall] = []
+        names = self.registry.names()
+        for obj in _extract_json_objects(text):
+            raw = obj.get("tool")
+            if not raw:
+                continue
+            name = self._TOOL_ALIASES.get(raw, raw)
+            if name not in names:
+                continue
+            args = {self._ARG_ALIASES.get(k, k): v for k, v in (obj.get("args") or {}).items()}
+            calls.append(ToolCall(name=name, arguments=args))
+        return calls

gini/agent/mcp_server.py

@@ -0,0 +1,86 @@
+"""MCP server exposing the shared tool registry to external AI agents.
+
+The tool *behavior* lives in one place — `tools.registry` — and is shared with the
+in-app agent loop. Here we publish those same tools over MCP with explicit signatures
+(so clients get correct schemas), each delegating to `registry.execute`. Install the
+optional dep with: pip install gini-gbuilder[agent].
+
+Run standalone:  python -m gini.agent.mcp_server
+"""
+from __future__ import annotations
+
+import json
+
+from ..app import AppContext
+from .api import GiniAPI
+from .tools.registry import ToolRegistry, build_registry
+
+
+def build_server(api: GiniAPI, registry: ToolRegistry | None = None):
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("MCP server needs 'mcp'. Install: pip install gini-gbuilder[agent]") from e
+
+    reg = registry or build_registry(api)
+    server = FastMCP("gini-gbuilder")
+
+    def call(name: str, **kwargs) -> str:
+        return json.dumps(reg.execute(name, kwargs), default=str)
+
+    @server.tool()
+    def list_device_types() -> str:
+        """List every device/element type GINI can place (networking + cloud)."""
+        return call("list_device_types")
+
+    @server.tool()
+    def add_device(type_key: str, name: str = "", x: float = 0.0, y: float = 0.0) -> str:
+        """Add a device. type_key e.g. 'router','switch','vpc','container','instance'."""
+        return call("add_device", type_key=type_key, name=name, x=x, y=y)
+
+    @server.tool()
+    def connect_devices(a: str, b: str, label: str = "") -> str:
+        """Create a link between two devices (by name or id)."""
+        return call("connect_devices", a=a, b=b, label=label)
+
+    @server.tool()
+    def set_property(device: str, key: str, value: str) -> str:
+        """Set a property on a device (by name or id)."""
+        return call("set_property", device=device, key=key, value=value)
+
+    @server.tool()
+    def inspect_device(device: str) -> str:
+        """Inspect a device's type, properties, neighbors, and degree."""
+        return call("inspect_device", device=device)
+
+    @server.tool()
+    def get_topology() -> str:
+        """Return the full topology as JSON (devices + links)."""
+        return call("get_topology")
+
+    @server.tool()
+    def summarize_topology() -> str:
+        """Counts of devices, links, and categories."""
+        return call("summarize_topology")
+
+    @server.tool()
+    def explain_topology() -> str:
+        """Explain the whole topology in plain language for a student."""
+        return call("explain_topology")
+
+    @server.tool()
+    def explain_device(device: str) -> str:
+        """Explain a single device in plain language for a student."""
+        return call("explain_device", device=device)
+
+    return server
+
+
+def main() -> None:  # pragma: no cover
+    ctx = AppContext()
+    server = build_server(GiniAPI(ctx))
+    server.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()