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

gini/agent/twin/justify.py

@@ -0,0 +1,156 @@
+"""Justification validation — the crux of the dialectic (REASONING_2.0_DESIGN.md §3.6).
+
+The Twin never takes the model's word for an omission. Each stated `why` is classified into a
+small set of checkable patterns and validated DETERMINISTICALLY:
+
+  • pedagogical ("it would give the answer away")  → allowed by POLICY for hint-shaped moves
+    (Socratic withholding is legitimate); logged either way.
+  • scope ("that's not what they asked")           → checked lexically against the utterance:
+    valid only when there IS a question and its words genuinely don't touch the concern.
+  • already-addressed ("covered in an earlier hint") → checked against the Twin's history of
+    concern ids the model actually covered in prior turns of this mission.
+  • state ("not needed — the LAN is single-subnet") → the free text is TRANSLATED (one focused,
+    schema-constrained LLM call) onto the oracle's OWN predicate grammar, then EVALUATED with
+    `objectives.evaluate_check` against the live world. The translation may use a model; the
+    verdict never does. Untranslatable / no world → unvalidated → the objection stands.
+  • unknown                                        → unvalidated → the objection stands.
+
+An objection is DEFEATED only by a validated justification — defeasible reasoning with ground
+truth as the referee."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# move kinds where withholding detail is a legitimate teaching move (the mission GM's hint;
+# coach surfaces extend this in phase C)
+PEDAGOGICAL_OK_KINDS = {"hint"}
+
+_PED_RE = re.compile(r"give\s*(it|the answer)?\s*away|reveal|spoil|socratic|full answer|"
+                     r"answer for them|figure it out", re.I)
+_SCOPE_RE = re.compile(r"not what (they|the student) asked|off.?topic|different question|"
+                       r"unrelated|about .+ not|this question'?s topic|other topic", re.I)
+# must pair with a COVERAGE verb — a bare "already" is usually a state claim ("there are
+# already two hosts"), which belongs to the oracle-checked STATE path, not this one.
+_ALREADY_RE = re.compile(
+    r"already (covered|addressed|mentioned|said|explained|answered|hinted|told)|"
+    r"covered (before|earlier|previously|that)|previous (hint|turn|answer|line)|"
+    r"(earlier|last) (hint|turn|answer|time|line)", re.I)
+
+PEDAGOGICAL, SCOPE, ALREADY, STATE, UNKNOWN = "pedagogical", "scope", "already", "state", "unknown"
+
+
+def classify(why: str) -> str:
+    """Deterministic keyword classification of a stated omission reason. Order matters:
+    pedagogical/scope/already are specific idioms; anything else that *asserts something about
+    the world* is treated as a state claim (and must survive translation + evaluation)."""
+    w = (why or "").strip()
+    if not w:
+        return UNKNOWN
+    if _PED_RE.search(w):
+        return PEDAGOGICAL
+    if _SCOPE_RE.search(w):
+        return SCOPE
+    if _ALREADY_RE.search(w):
+        return ALREADY
+    return STATE
+
+
+# -- state-claim translation (LLM proposes, the oracle disposes) -------------- #
+TRANSLATE_SCHEMA: dict = {
+    "type": "object",
+    "properties": {"predicate": {"type": ["string", "null"]}},
+    "required": ["predicate"],
+}
+
+_TRANSLATE_SYSTEM = (
+    "You translate ONE claim about a network lab board into ONE predicate from this exact "
+    "grammar (nothing else): exists(type) · count(type) >= n · link(a, b) · path(a, b) · "
+    "through(a, b, gate) · contains_type(group, type) · all_linked(type). Types are element "
+    "type keys (host, switch, router, …). Output ONLY JSON: {\"predicate\": \"<one predicate>\"} "
+    "or {\"predicate\": null} if the claim cannot be expressed in this grammar. No prose.")
+
+
+def llm_translate(runner, why: str) -> str | None:
+    """One focused, schema-constrained call turning a free-text state claim into a predicate the
+    oracle can evaluate. Returns None when there's no model, no clean parse, or the model says
+    the claim isn't expressible — all of which leave the justification unvalidated."""
+    if runner is None or getattr(runner, "_llm", None) is None:
+        return None
+    from ..personas import Persona, first_json
+    persona = Persona("Translator", system=_TRANSLATE_SYSTEM, temperature=0.0,
+                      schema=TRANSLATE_SCHEMA)
+    out = runner.call(persona, task=f"Claim: {why!r}")
+    obj = first_json(out)
+    pred = obj.get("predicate") if isinstance(obj, dict) else None
+    return pred if isinstance(pred, str) and pred.strip() else None
+
+
+def state_holds(predicate: str, world) -> bool | None:
+    """Evaluate a translated predicate against the live world with the oracle's OWN evaluator
+    (`objectives.evaluate_check`) — one predicate semantics, never a second one. None = cannot
+    evaluate (bad predicate / no world) — which leaves the objection standing."""
+    if not predicate or world is None:
+        return None
+    try:
+        from ...domain import objectives as _obj
+        if not _obj.check_ok(predicate):
+            return None
+        # accept either the predicate-World interface (has .exists) or a bare Topology
+        view = world if hasattr(world, "exists") else _obj.TopologyWorld(world)
+        return bool(_obj.evaluate_check(predicate, view))
+    except Exception:
+        return None
+
+
+# -- adjudication ------------------------------------------------------------- #
+@dataclass(frozen=True)
+class Adjudication:
+    valid: bool
+    kind: str
+    reason: str = ""     # why it failed (feeds the objection question) / how it was validated
+
+
+def _tokens(text: str) -> set:
+    return {t for t in re.findall(r"[a-z0-9]+", (text or "").lower()) if len(t) > 2}
+
+
+def adjudicate(concern, why: str, ctx) -> Adjudication:
+    """Validate one omission justification against ground truth. `ctx` carries move_kind,
+    utterance, world, history (concern ids covered in prior turns), and a translate callable."""
+    kind = classify(why)
+
+    if kind == PEDAGOGICAL:
+        if getattr(ctx, "move_kind", "") in PEDAGOGICAL_OK_KINDS:
+            return Adjudication(True, kind, "withholding is legitimate for a hint")
+        return Adjudication(False, kind,
+                            "this turn isn't a hint — answering shouldn't withhold this")
+
+    if kind == SCOPE:
+        utterance = getattr(ctx, "utterance", "") or ""
+        if not utterance:
+            return Adjudication(False, kind, "nothing was asked — there is no topic to be off")
+        overlap = _tokens(utterance) & (_tokens(concern.statement) | _tokens(concern.id))
+        if overlap:
+            return Adjudication(False, kind,
+                                f"the question mentions {', '.join(sorted(overlap))} — it IS on topic")
+        return Adjudication(True, kind, "the question doesn't touch this concern")
+
+    if kind == ALREADY:
+        if concern.id in (getattr(ctx, "history", None) or set()):
+            return Adjudication(True, kind, "it was covered in an earlier turn")
+        return Adjudication(False, kind, "it was never actually covered in an earlier turn")
+
+    if kind == STATE:
+        translate = getattr(ctx, "translate", None)
+        pred = translate(why) if callable(translate) else None
+        if not pred:
+            return Adjudication(False, kind, "the claim couldn't be checked against the board")
+        held = state_holds(pred, getattr(ctx, "world", None))
+        if held is True:
+            return Adjudication(True, kind, f"checked: {pred} holds")
+        if held is False:
+            return Adjudication(False, kind, f"checked: {pred} is FALSE on this board")
+        return Adjudication(False, kind, "the claim couldn't be checked against the board")
+
+    return Adjudication(False, UNKNOWN, "no checkable reason was given")

gini/agent/twin/learner.py

@@ -0,0 +1,64 @@
+"""The learner-model concern source (REASONING_2.0_DESIGN.md phase D; LEARNER_MODEL_DESIGN.md
+§6.1 / L-F). This is the CONSUMPTION seam: the learner model itself is built on a parallel
+track (`domain/learner.py`); this module duck-types against its ratified shape so the Twin is
+ready the moment it lands.
+
+Expected learner-state shape (duck-typed, all optional):
+  • .misconceptions — iterable of active misconceptions with .id, .concept, .statement and an
+    evidence count (`.evidence` list or `.evidence_count`);
+  • .band(concept) -> "unknown" | "weak" | "developing" | "solid" (counters+decay, auditable).
+
+Rules (per the ratified design):
+  • an ACTIVE misconception on a concept the current work touches → salience 3; other active
+    misconceptions → salience 2;
+  • a WEAK-band concept touched by the current work → salience 2;
+  • `unknown` band = cold start = NO concern (unknown ≠ weak — no adaptation, not remediation);
+  • every concern carries evidence (the misconception's evidence count / the band), same as
+    every other Twin source: no evidence, no concern."""
+from __future__ import annotations
+
+from .contracts import Concern
+from .salience import cap
+
+
+def _evidence_count(m) -> int:
+    ev = getattr(m, "evidence", None)
+    if isinstance(ev, (list, tuple)):
+        return len(ev)
+    return int(getattr(m, "evidence_count", 0) or 0)
+
+
+def learner_concerns(learner, *, concepts=()) -> list[Concern]:
+    """Concerns about THIS student, for the current work. `concepts` = the concept keys the
+    current mission/lab teaches (e.g. from the fragment's `teaches:`)."""
+    if learner is None:
+        return []
+    touched = set(concepts or ())
+    concerns: list[Concern] = []
+
+    for m in getattr(learner, "misconceptions", None) or []:
+        n = _evidence_count(m)
+        if n <= 0:
+            continue                                   # no evidence, no concern
+        relevant = getattr(m, "concept", "") in touched
+        concerns.append(Concern(
+            id=f"misconception:{m.id}", kind="misconception",
+            statement=f"the student likely {m.statement}",
+            evidence=f"detector evidence x{n} on {getattr(m, 'concept', '?')}",
+            salience=3 if relevant else 2, source="learner-model"))
+
+    band_of = getattr(learner, "band", None)
+    if callable(band_of):
+        for concept in sorted(touched):
+            try:
+                band = band_of(concept)
+            except Exception:
+                continue
+            if band == "weak":                          # unknown = cold start = NO concern
+                concerns.append(Concern(
+                    id=f"learner:weak:{concept}", kind="misconception",
+                    statement=f"the student is weak on {concept}",
+                    evidence=f"mastery band: weak on {concept}",
+                    salience=2, source="learner-model"))
+
+    return cap(concerns)

gini/agent/twin/mission.py

@@ -0,0 +1,60 @@
+"""The mission-GM concern enumerator — a deterministic projection of what already sits on the
+blackboard into the Twin's Concern set. Nothing is sensed anew and nothing is judged: every
+concern is backed by a cached Verdict (and, for objectives, the predicate explainer's
+board-grounded why). REASONING_2.0_DESIGN.md §3.2, first row of the surface table."""
+from __future__ import annotations
+
+from .contracts import Concern
+from .salience import cap, salience_for
+
+
+def _why(objective, world) -> str:
+    """The deterministic, board-grounded reason an objective is red (domain/explain.py) —
+    the same explainer the Reasoning persona uses; '' when the world isn't on hand."""
+    if objective is None or world is None:
+        return ""
+    try:
+        from ...domain import explain as _explain
+        return _explain.diagnose(objective, world) or ""
+    except Exception:
+        return ""
+
+
+def mission_concerns(blackboard, lesson) -> list[Concern]:
+    """Enumerate this turn's concerns for the mission game-master, salience-capped.
+
+    Sources (all already deterministic, all already computed):
+      • every UNMET objective — statement is its `say`, evidence is the explainer's why
+        (or the bare verdict when no world is cached);
+      • legality flags (off-task elements, illegal links) — evidence is the flagged names.
+    """
+    concerns: list[Concern] = []
+    say = {o.id: o for o in getattr(lesson, "objectives", [])}
+    world = getattr(blackboard, "_world", None)
+
+    for oid in blackboard.unmet_objectives():
+        obj = say.get(oid)
+        why = _why(obj, world)
+        statement = getattr(obj, "say", oid)
+        concerns.append(Concern(
+            id=f"objective:{oid}", kind="objective",
+            statement=f"'{statement}' is unmet",
+            evidence=why or "objective verdict: unmet",
+            salience=salience_for("objective"), source="blackboard"))
+
+    flags = blackboard.flags()
+    if flags.get("off_task"):
+        names = ", ".join(flags["off_task"])
+        concerns.append(Concern(
+            id="legality:off_task", kind="legality",
+            statement=f"off-task element(s) on the board: {names}",
+            evidence=f"off_task verdict lists: {names}",
+            salience=salience_for("legality"), source="blackboard"))
+    if flags.get("illegal_links"):
+        concerns.append(Concern(
+            id="legality:illegal_links", kind="legality",
+            statement="illegal connection(s) present",
+            evidence="illegal_links verdict is failing",
+            salience=salience_for("legality"), source="blackboard"))
+
+    return cap(concerns)

gini/agent/twin/os_coach.py

@@ -0,0 +1,79 @@
+"""The OS-Coach concern enumerator (REASONING_2.0_DESIGN.md §5, second surface).
+
+The coach streams a single Socratic nudge straight to chat, so phase C gives it the Twin's
+FEED-FORWARD half: a deterministic concern set (watcher events, scheduling flags, a faulted
+shadow) whose TOP concern is injected into the prompt as the thing the hint should target —
+"did the hint target the most salient event?" answered by construction. The same concern set
+is the upgraded no-model fallback ("things worth looking at"). The audit/revision half needs
+the coach to become a structured turn (not a fire-and-forget stream) — deferred, by design.
+
+Socratic withholding is ALWAYS legitimate here: the coach's job is one nudge, so no coverage
+obligation is imposed on it."""
+from __future__ import annotations
+
+from .contracts import Concern
+from .salience import cap
+
+
+def coach_concerns(events, machine_state) -> list[Concern]:
+    """Enumerate what matters for one coach nudge — all deterministic, all evidence-backed.
+
+    `events` are the drained StateWatcher OsEvents (the teachable moments); `machine_state`
+    contributes the currently-active scheduling flags and the shadow manifest (a student shadow
+    that crashed back to the primary outranks everything — they think their code is running)."""
+    concerns: list[Concern] = []
+
+    for e in events or []:
+        concerns.append(Concern(
+            id=f"watcher:{e.kind}" + (f":{e.pid}" if e.pid is not None else ""),
+            kind="watcher-event", statement=e.detail, evidence=e.detail,
+            salience=2, source="watcher"))
+
+    try:
+        for name, s in (machine_state.shadows() or {}).items():
+            if getattr(s, "faults", 0) and getattr(s, "is_student", False):
+                concerns.append(Concern(
+                    id=f"shadow:{name}:faulted", kind="watcher-event",
+                    statement=(f"your {name} shadow crashed {s.faults}x and the shipped "
+                               "primary is running instead"),
+                    evidence=f"manifest: faults={s.faults} active={int(bool(s.active))}",
+                    salience=3, source="shadow-manifest"))
+    except Exception:
+        pass
+
+    try:
+        flags = machine_state.scheduling_flags() or {}
+        seen = {c.id for c in concerns}
+        for kind, pids in flags.items():
+            for pid in pids:
+                cid = f"watcher:{kind}:{pid}"
+                if cid not in seen:            # active-but-already-drained conditions still show
+                    concerns.append(Concern(
+                        id=cid, kind="watcher-event",
+                        statement=f"pid {pid} is currently in {kind.replace('_', ' ')}",
+                        evidence=f"scheduling flag {kind} active for pid {pid}",
+                        salience=2, source="watcher"))
+    except Exception:
+        pass
+
+    return cap(concerns)
+
+
+def focus_line(concerns: list[Concern]) -> str:
+    """The feed-forward injection for the coach prompt: the single most salient concern the
+    nudge should target (deterministically chosen — the model words it, never picks it)."""
+    if not concerns:
+        return ""
+    top = concerns[0]
+    return (f"The most salient issue RIGHT NOW (target your nudge at this): "
+            f"{top.statement} [{top.evidence}]")
+
+
+def fallback_text(concerns: list[Concern]) -> str:
+    """The no-model coach reply — the concern set rendered directly (better than the old raw
+    event list: salience-ordered, evidence-backed, still zero-LLM)."""
+    if not concerns:
+        return ("The run looks steady. Try slowing the time-slice or spawning another "
+                "CPU-bound process, and watch the switches.")
+    lines = [f"- {c.statement}" for c in concerns[:3]]
+    return "Worth looking at right now:\n" + "\n".join(lines)

gini/agent/twin/salience.py

@@ -0,0 +1,30 @@
+"""Salience — rules only, never a model (the notifier philosophy: tune the RULES if noisy).
+
+The caps are the anti-noise guarantee: at most MAX_CONCERNS reach a turn, and only concerns at
+or above MUST_ADDRESS must be covered by the model (lower ones are context the Twin tracks but
+never objects about)."""
+from __future__ import annotations
+
+MAX_CONCERNS = 5     # hard cap per turn — the Twin whispers, it does not checklist
+MUST_ADDRESS = 2     # salience >= this must appear in the coverage report (addressed or justified)
+
+# base salience per concern kind (0..3). 3 = urgent (objection even under coverage-silence).
+KIND_SALIENCE = {
+    "legality": 3,          # off-task / illegal links — active rule violations
+    "objective": 2,         # an unmet objective with a grounded why
+    "watcher-event": 2,     # OS pedagogical events (starvation, monopoly…) — phase C
+    "composition-gap": 2,   # unfilled requires / authoring disagreements — phase C
+    "misconception": 2,     # learner-model concerns (3 when touching the current work) — phase D
+    "grammar-option": 1,    # a valid-but-unused possibility — context, never an objection
+}
+
+
+def salience_for(kind: str) -> int:
+    return KIND_SALIENCE.get(kind, 1)
+
+
+def cap(concerns: list) -> list:
+    """Highest-salience first, capped at MAX_CONCERNS; stable within a salience band so
+    enumeration order (objectives before flags, etc.) is preserved deterministically."""
+    ranked = sorted(concerns, key=lambda c: -c.salience)
+    return ranked[:MAX_CONCERNS]

gini/agent/understand.py

@@ -0,0 +1,250 @@
+"""Understanding front-door — raw NL (question / sentence / fragment) -> structured Intent.
+
+Everything downstream (retrieval, routing, reasoning) keys off the Intent, so this is the
+gate. It runs on the always-on context (element index + canvas + recent turns) because a
+fragment ("why broke", "the db thing") only resolves against the canvas and history.
+
+Two-tier, cheap-first:
+  1. a deterministic parse handles the clear cases (element names, command verbs, concept
+     keywords) at zero latency;
+  2. an optional LLM refine (same model) only fires when the deterministic parse is
+     low-confidence — a small, focused prompt, NOT the full tutor prompt.
+
+The active mode biases the Intent (Coach -> diagnose, Wizard -> guide, Explain -> explain)
+but doesn't fully override it. Pure logic + an injectable `llm` callable, so it's testable.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+from ..domain import concepts as _concepts
+from ..domain import recipes as _recipes
+from ..domain.devices import all_devices
+
+TYPES = ("explain", "how_to", "build", "diagnose", "meta", "chitchat")
+ANCHORS = ("canvas", "concept", "hybrid")
+FORMS = ("tell", "show", "guide")
+
+
+@dataclass
+class Intent:
+    type: str = "explain"
+    anchor: str = "concept"
+    output_form: str = "tell"
+    topics: list[str] = field(default_factory=list)
+    refs: list[str] = field(default_factory=list)
+    depth: str = "shallow"
+    confidence: float = 0.5
+    query: str = ""
+
+    def to_dict(self) -> dict:
+        return {"type": self.type, "anchor": self.anchor, "output_form": self.output_form,
+                "topics": self.topics, "refs": self.refs, "depth": self.depth,
+                "confidence": round(self.confidence, 2)}
+
+
+# -- keyword tables --------------------------------------------------------- #
+_BUILD_CMD = ("add ", "connect ", "remove ", "delete ", "place ", "wire ", "attach ", "rename ")
+_HOWTO = ("how to", "how do i", "how do you", "how can i", "how would i", "how should i",
+          "how we", "how do we", "how can we", "show how", "show me how")
+# verbs that mean "materialise it" (vs. "use / work" which stay explanatory)
+_BUILD_WORDS = ("create", "build", "set up", "setup", "construct", "make", "deploy",
+                "implement", "scaffold")
+_SHOW = ("show me", "show an example", "give me an example", "construct", "build me",
+         "build a", "build an", "set up", "setup", "lay out", "demonstrate", "create a",
+         "create an", "make a", "make an")
+_GUIDE = ("walk me through", "guide me", "step by step", "step-by-step", "help me build")
+_EXPLAIN = ("explain", "what is", "what's a", "what are", "what does", "tell me about",
+            "describe", "when do i", "when to use", "when should i")
+_DIAGNOSE = ("what's wrong", "whats wrong", "is my", "are my", "check my", "not working",
+             "unreachable", "why isn't", "why can't", "why won't", "broken", "fix ",
+             "what is wrong", "isn't working", "doesn't work")
+_META = ("what can you do", "which elements", "what elements", "list the", "what do you",
+         "help me get started", "what can i build")
+_GREET = ("hi", "hello", "hey", "thanks", "thank you", "yo", "sup")
+_DEEP = ("why", "how does", "how do", "under the hood", "in detail", "explain how",
+         "difference between", "compare", "what happens when", "trade-off", "tradeoff",
+         "internally", "actually work")
+_DEMONSTRATIVE = ("this ", "these ", " my ", " here", "the current", "my canvas", "my setup",
+                  "my topology")
+
+
+def _has(text: str, needles) -> bool:
+    return any(n in text for n in needles)
+
+
+def _extract_topics(text: str) -> list[str]:
+    """Concept keywords, element keys, and recipe tags present in the text (dedup, ordered)."""
+    topics: list[str] = []
+
+    def add(t):
+        if t and t not in topics:
+            topics.append(t)
+
+    for c in _concepts.CONCEPTS:
+        for kw in c.keywords:
+            if kw in text:
+                add(kw)
+    for d in all_devices():
+        if re.search(rf"\b{re.escape(d.key)}\b", text) or d.label.lower() in text:
+            add(d.key)
+    for r in _recipes.RECIPES:
+        for tag in r.intent:
+            if tag in text:
+                add(tag)
+    return topics
+
+
+def _extract_refs(text: str, canvas_names) -> list[str]:
+    """Device names from the canvas that appear as whole words in the text."""
+    if not canvas_names:
+        return []
+    low = text.lower()
+    return [n for n in canvas_names if re.search(rf"\b{re.escape(n.lower())}\b", low)]
+
+
+# -- the parse -------------------------------------------------------------- #
+def understand(text: str, *, canvas_names=None, mode: str = "chat",
+               llm=None, min_confidence: float = 0.45) -> Intent:
+    """Interpret one user message. `canvas_names` is the list of placed device names;
+    `mode` is the active panel mode; `llm` is an optional callable(prompt)->str used only
+    when the deterministic parse is unsure."""
+    raw = (text or "").strip()
+    low = raw.lower()
+    words = low.split()
+    canvas_empty = not canvas_names
+
+    it = Intent(query=raw)
+    it.topics = _extract_topics(low)
+    it.refs = _extract_refs(raw, canvas_names or [])
+
+    # --- type ---
+    typed = True
+    if _has(low, _GREET) and len(words) <= 3:
+        it.type = "chitchat"
+    elif _has(low, _META):
+        it.type = "meta"
+    elif any(low.startswith(v) for v in _BUILD_CMD):
+        it.type = "build"                      # an imperative command
+    elif _has(low, _DIAGNOSE):
+        it.type = "diagnose"
+    elif _has(low, _HOWTO):
+        it.type = "how_to"
+    elif _has(low, _SHOW):
+        it.type = "how_to"                     # "show me / build a X" is a how-to-build
+    elif _has(low, _EXPLAIN):
+        it.type = "explain"
+    elif it.topics:
+        it.type = "explain"                    # a bare topic -> explain it
+        typed = False
+    else:
+        it.type = "explain"
+        typed = False
+
+    # --- output_form ---
+    if _has(low, _GUIDE):
+        it.output_form = "guide"
+    elif _has(low, _SHOW) or (it.type in ("how_to", "build")
+                              and _has(low, ("example",) + _BUILD_WORDS)):
+        it.output_form = "show"                # "show/how to CREATE/BUILD X" -> materialise
+    else:
+        it.output_form = "tell"                # "how to USE X" -> explain + offer to build
+
+    # --- anchor ---
+    generative = it.type in ("how_to", "build") and (
+        it.output_form in ("show", "guide") or _has(low, _BUILD_WORDS + ("add",)))
+    if canvas_empty:
+        it.anchor = "concept"
+    elif it.refs or _has(low, _DEMONSTRATIVE):
+        it.anchor = "hybrid" if generative else "canvas"
+    elif generative:
+        it.anchor = "hybrid"                   # build onto an existing canvas
+    elif it.type == "diagnose":
+        it.anchor = "canvas"
+    else:
+        it.anchor = "concept"
+
+    # --- depth ---
+    it.depth = "deep" if _has(low, _DEEP) else "shallow"
+
+    # --- confidence ---
+    conf = 0.5 + (0.3 if typed else 0.0) + (0.2 if it.topics else 0.0)
+    if len(words) < 3 and not it.topics and not it.refs:
+        conf -= 0.35
+    it.confidence = max(0.0, min(1.0, conf))
+
+    _apply_mode(it, mode, canvas_empty, low)
+
+    # --- LLM refine only when unsure ---
+    if it.confidence < min_confidence and llm is not None:
+        _llm_refine(it, canvas_names, llm)
+    return it
+
+
+def _apply_mode(it: Intent, mode: str, canvas_empty: bool, low: str = "") -> None:
+    """The active panel mode biases the Intent (doesn't fully override the parse)."""
+    if mode == "coach":
+        it.type = "diagnose"
+        it.anchor = "concept" if canvas_empty else "canvas"
+        it.output_form = "tell"
+    elif mode == "wizard":
+        # Wizard is for guided building: a bare goal ("a serverless api") is a build target
+        # unless the student explicitly asked to be told about something.
+        if not _has(low, _EXPLAIN) and not _has(low, _META):
+            it.type = "build"
+        it.output_form = "guide"
+    elif mode == "explain" and it.type not in ("diagnose", "build"):
+        it.type = "explain"
+
+
+_REFINE_PROMPT = (
+    "You interpret a student's message in the GINI network/cloud lab. Reply with ONLY a "
+    "JSON object: {\"type\": explain|how_to|build|diagnose|meta|chitchat, \"anchor\": "
+    "canvas|concept|hybrid, \"output_form\": tell|show|guide, \"topics\": [..], \"depth\": "
+    "shallow|deep}. No prose.\n"
+)
+
+
+def _llm_refine(it: Intent, canvas_names, llm) -> None:
+    """Ask the model to interpret an ambiguous fragment; merge if it returns valid JSON."""
+    ctx = f"Canvas devices: {', '.join(canvas_names) if canvas_names else '(empty)'}.\n"
+    try:
+        out = llm(_REFINE_PROMPT + ctx + f"Message: {it.query!r}")
+        obj = _first_json(out)
+    except Exception:
+        obj = None
+    if not isinstance(obj, dict):
+        return
+    if obj.get("type") in TYPES:
+        it.type = obj["type"]
+    if obj.get("anchor") in ANCHORS:
+        it.anchor = obj["anchor"]
+    if obj.get("output_form") in FORMS:
+        it.output_form = obj["output_form"]
+    if obj.get("depth") in ("shallow", "deep"):
+        it.depth = obj["depth"]
+    if isinstance(obj.get("topics"), list):
+        for t in obj["topics"]:
+            if isinstance(t, str) and t.strip() and t not in it.topics:
+                it.topics.append(t.strip())
+    it.confidence = max(it.confidence, 0.6)    # the model resolved it
+
+
+def _first_json(text: str):
+    depth = 0
+    start = 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:
+                    return json.loads(text[start:i + 1])
+                except json.JSONDecodeError:
+                    start = None
+    return None