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

gini/agent/gamemaster.py

@@ -0,0 +1,256 @@
+"""The Game Master — the pivotal per-turn reasoning loop of a Mission.
+
+Each turn the game master reasons over three inputs and emits ONE move:
+
+    TEACHER INTENT   — the lesson's goal + spirit + misconceptions (from its Game-Catalog
+                       archetype); what success really means, mechanism-free.
+    STUDENT INTENT   — what the student means / is attempting, interpreted (never keyword-matched)
+                       from their words and the change in the canvas.
+    RUNTIME FACTS    — the objective results GINI's runtime produced (met / unmet / pending).
+
+Deterministic *guards* frame the decision (completion, expiry, help level), but the interpretation
+of the student and the phrasing of every message are the reasoning LLM's job — this is where the AI
+is genuinely drawn into the loop. GINI owns the facts; the game master owns the understanding.
+
+Missions are hard-gated on a reasoning LLM: with `llm=None` the game master is inert (returns a
+`quiet` move), matching the design's "no model → no Mission." Pure orchestration + prompts; the
+`llm` callable is injected, so the whole loop is unit-testable with a scripted model.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+# student progress reads
+ATTEMPTING, STUCK, ASKING_HINT, SYMPTOM, OFF_TASK, CELEBRATING, SILENT = (
+    "attempting", "stuck", "asking_hint", "reporting_symptom", "off_task", "celebrating", "silent")
+
+# move kinds
+BRIEF, NUDGE, HINT, INTERPRET, ANSWER, CELEBRATE, DEFEAT, QUIET = (
+    "brief", "nudge", "hint", "interpret", "answer", "celebrate", "defeat", "quiet")
+
+_PERSONA_VOICE = {
+    "coach": "You are a warm, encouraging coach on the student's side. Be supportive and concise.",
+    "challenger": "You are a playful challenger running a contest. Be spirited and a little "
+                  "competitive, but never mean. Keep it short.",
+}
+
+
+@dataclass
+class StudentRead:
+    progress: str = SILENT
+    objective_ref: str = ""
+    is_question: bool = False
+    raw: str = ""
+
+
+@dataclass
+class Move:
+    kind: str
+    text: str = ""
+    objective_ref: str = ""
+    logged: bool = False        # help usage recorded to the profile (full_tutor_logged)
+
+
+def _first_json(text: str):
+    depth, start = 0, 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
+
+
+class GameMaster:
+    def __init__(self, lesson, llm=None, *, persona: str | None = None) -> None:
+        self.lesson = lesson
+        self.llm = llm
+        self.persona = persona or getattr(lesson, "persona", "coach")
+        self._prev_met: int | None = None       # for warmer/colder deltas
+
+    # -- LLM plumbing ------------------------------------------------------- #
+    def _ask(self, prompt: str) -> str:
+        if self.llm is None:
+            return ""
+        try:
+            return self.llm(prompt) or ""
+        except Exception:
+            return ""
+
+    def _voice(self) -> str:
+        return _PERSONA_VOICE.get(self.persona, _PERSONA_VOICE["coach"])
+
+    def _intent(self) -> str:
+        it = self.lesson.intent
+        parts = [f"Lesson goal: {it.goal}"] if it.goal else []
+        if it.spirit:
+            parts.append(f"What success means (the SPIRIT — any mechanism counts): {it.spirit}")
+        if it.misconceptions:
+            parts.append("Common misconceptions: " + "; ".join(it.misconceptions))
+        return "\n".join(parts)
+
+    # -- student intent interpretation (reasoning, not keyword) ------------- #
+    def interpret(self, utterance: str, results) -> StudentRead:
+        """Interpret what the student means / is attempting. With an utterance the LLM classifies
+        it against THIS lesson's objectives; with none, infer a light read from the facts."""
+        if not (utterance or "").strip():
+            met = sum(1 for r in results if r.met)
+            return StudentRead(progress=ATTEMPTING if met < len(results) else CELEBRATING)
+        objs = "; ".join(f"{r.id}: {r.say} [{r.status}]" for r in results)
+        prompt = (
+            f"{self._voice()}\nYou interpret a student mid-lab. {self._intent()}\n"
+            f"Objectives (id: goal [state]): {objs}\n"
+            f'Student said: {utterance!r}\n'
+            "Reply ONLY as JSON: {\"progress\": attempting|stuck|asking_hint|reporting_symptom|"
+            "off_task|celebrating, \"objective_ref\": \"<objective id or empty>\", "
+            "\"is_question\": true|false}. No prose.")
+        obj = _first_json(self._ask(prompt))
+        if not isinstance(obj, dict):
+            # couldn't parse → treat a '?' as a question, else attempting (never keyword-decide meaning)
+            return StudentRead(progress=ASKING_HINT if "?" in utterance else ATTEMPTING,
+                               is_question="?" in utterance, raw=utterance)
+        prog = obj.get("progress")
+        prog = prog if prog in (ATTEMPTING, STUCK, ASKING_HINT, SYMPTOM, OFF_TASK, CELEBRATING) \
+            else ATTEMPTING
+        return StudentRead(progress=prog, objective_ref=str(obj.get("objective_ref", "")),
+                           is_question=bool(obj.get("is_question", False)), raw=utterance)
+
+    # -- the reasoning loop ------------------------------------------------- #
+    def decide(self, mission, results, *, utterance: str = "", world_digest: str = "") -> Move:
+        """Reason over teacher intent + student intent + runtime facts → one move."""
+        if self.llm is None:
+            return Move(QUIET)                       # no model → inert (Missions are LLM-gated)
+
+        help_level = self.lesson.help
+        met_now = sum(1 for r in results if r.met)
+        first_turn = self._prev_met is None
+        delta = 0 if first_turn else met_now - self._prev_met
+        self._prev_met = met_now
+        read = self.interpret(utterance, results)
+
+        # --- deterministic guards frame the move; the LLM interprets + phrases ---
+        if mission.complete:
+            return Move(CELEBRATE, self._say_victory(mission))
+        if getattr(mission, "state", "") == "done" and not mission.complete:
+            return Move(DEFEAT, self._say_encourage(results))
+
+        # a question / explicit ask — governed by the lesson's help level
+        if read.is_question or read.progress in (ASKING_HINT, SYMPTOM):
+            if help_level == "none":
+                return Move(QUIET)                   # proctored / no-help: stay silent
+            if help_level == "full_tutor_logged":
+                return Move(ANSWER, self._answer(utterance, results), logged=True)
+            return Move(HINT, self._hint(read, results), objective_ref=read.objective_ref)
+
+        # warmer / colder — grounded in the change in met objectives
+        if help_level != "none" and not first_turn and delta > 0:
+            return Move(NUDGE, self._warmer(results))
+        if help_level != "none" and not first_turn and delta < 0:
+            return Move(NUDGE, self._colder(results))
+
+        # stuck or drifting → interpret + guide (spirit-aware), if help allows
+        if help_level != "none" and read.progress == STUCK:
+            return Move(HINT, self._hint(read, results), objective_ref=read.objective_ref)
+        if read.progress == OFF_TASK:
+            return Move(INTERPRET, self._redirect(results))
+
+        return Move(QUIET)
+
+    def observe(self, mission, results) -> Move:
+        """Convenience for an action-only turn (no utterance) — e.g. the canvas changed."""
+        return self.decide(mission, results)
+
+    # -- phrasing (the LLM's voice, grounded in intent + facts) ------------- #
+    def _unmet(self, results):
+        return [r for r in results if not r.met]
+
+    def _facts(self, results) -> str:
+        return "; ".join(f"{r.say} [{r.status}]" for r in results)
+
+    def brief_line(self) -> str:
+        """Narrate the mission brief in character (falls back to the authored brief text)."""
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nBrief the student on this mission in 1-2 short "
+            f"lines, in character, ending by starting the clock. The task: {self.lesson.brief}"
+        ) or self.lesson.brief
+
+    # -- guided beats (multi-turn) ----------------------------------------- #
+    def present_step(self, step, index: int, total: int, *, acked: str = "") -> str:
+        """Present ONE beat in character. `acked` (optional) is a one-line acknowledgement of what
+        the student just did, so consecutive beats feel like a conversation, not a list."""
+        lead = (f"The student just completed the previous beat ({acked}). Acknowledge it in a few "
+                "words, then " if acked else "")
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nThis is a guided lab, beat {index}/{total}. "
+            f"{lead}give the student THIS one instruction, in character, in 1-2 short lines — just "
+            f"this step, don't reveal later steps: {step.say}") or step.say
+
+    def react_reply(self, step, utterance: str, results) -> str:
+        """Respond to the student's answer on a read/reflect beat, then they move on."""
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nThe student was asked: {step.say!r} and replied: "
+            f"{utterance!r}. Respond in 1-2 short lines — affirm or gently correct, grounded in the "
+            "lesson's goal; then we move on.") or "Good — let's continue."
+
+    def off_step_nudge(self, step, results) -> str:
+        """The student did something that doesn't satisfy the current beat — a spirit-aware nudge."""
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nThe current beat asks: {step.say!r}. The student "
+            f"acted but hasn't satisfied it yet. Objectives: {self._facts(results)}. Give ONE short "
+            "nudge toward THIS beat's goal — don't do it for them.") or "Not quite yet — keep at this step."
+
+    def flag_note(self, reasons) -> str:
+        """Call out an off-task / wrongly-wired move the student just made — playfully firm, and
+        it tells them to FIX it (the game master never deletes anything itself)."""
+        joined = "; ".join(reasons)
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nThe student just did something that doesn't fit "
+            f"this mission: {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)
+
+    def _say_victory(self, mission) -> str:
+        return self._ask(f"{self._voice()}\n{self._intent()}\nThe student just completed the "
+                         f"mission ({mission.score().summary}). Congratulate them in ONE short, "
+                         "specific line tied to what they achieved.") or "Nice — you did it!"
+
+    def _say_encourage(self, results) -> str:
+        return self._ask(f"{self._voice()}\nThe attempt ended incomplete. Objectives: "
+                         f"{self._facts(results)}. Encourage the student in ONE short line and "
+                         "point at what's still open — no solution.") or "Out of time — give it another go."
+
+    def _warmer(self, results) -> str:
+        return self._ask(f"{self._voice()}\n{self._intent()}\nThe student just got CLOSER. "
+                         f"Objectives: {self._facts(results)}. Say 'warmer' in ONE short line, "
+                         "naming what improved — do NOT reveal the next step.") or "Warmer — keep going."
+
+    def _colder(self, results) -> str:
+        return self._ask(f"{self._voice()}\nThe student just moved AWAY from the goal. Objectives: "
+                         f"{self._facts(results)}. Say 'colder' gently in ONE short line — no "
+                         "solution.") or "Hmm, that went the wrong way."
+
+    def _hint(self, read: StudentRead, results) -> str:
+        # prefer an authored hint for the referenced/nearest-unmet objective if the lesson has one
+        target = read.objective_ref or (self._unmet(results)[0].id if self._unmet(results) else "")
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nThe student seems stuck on objective {target!r}. "
+            f"Objectives: {self._facts(results)}. Give ONE nudging hint toward the GOAL (spirit, "
+            "not a specific mechanism) — do not hand them the answer.") or "Think about the goal, not the tool."
+
+    def _answer(self, utterance: str, results) -> str:
+        return self._ask(
+            f"{self._voice()}\n{self._intent()}\nObjectives: {self._facts(results)}. The student "
+            f"asked: {utterance!r}. Answer helpfully and concisely, grounded in the lesson's goal; "
+            "guide, don't just solve it for them.") or "Let's think it through together."
+
+    def _redirect(self, results) -> str:
+        return self._ask(f"{self._voice()}\n{self._intent()}\nThe student drifted off-task. In ONE "
+                         "friendly line, steer them back to the mission's goal.") or "Let's refocus on the task."

gini/agent/kb.py

@@ -0,0 +1,148 @@
+"""GINI knowledge base — retrieval over the four assets that ground the agent.
+
+Assets: the element catalog (`devices`), the connection grammar (`connection_rules`), the
+concept notes (`concepts`), and the recipes (`recipes`). Two tiers:
+
+  • `always_on_context()` — the compact element index + connection groups injected EVERY
+    turn (~1.3K tokens, flat as the palette grows). Keeps the model on GINI's vocabulary.
+  • `retrieve(intent, topology)` — the question-specific detail: concept notes for the
+    topics (depth-gated), per-element cards with grammar-valid partners, and the recipe to
+    describe/build. Pulled on demand and folded into the session accumulator by the caller.
+
+Pure logic (no Qt); `topology` is duck-typed (needs `.devices` values with `.name`/`.type`).
+`intent` is duck-typed too (`.topics`, `.anchor`, `.output_form`, `.refs`, `.depth`) so this
+module doesn't depend on `understand` and stays independently testable.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..domain import connection_rules as _cr
+from ..domain.devices import REGISTRY, all_devices
+
+_HIDDEN = {"k8s_node"}          # not on the palette; never surface it
+
+
+@dataclass
+class Card:
+    """A titled knowledge snippet destined for the reasoning prompt."""
+    kind: str                   # element | grammar | concept | recipe
+    key: str
+    title: str
+    text: str
+
+
+@dataclass
+class Retrieval:
+    cards: list[Card] = field(default_factory=list)
+    recipe: object | None = None      # recipes.Recipe when a build/show is implied
+    strength: str = "empty"           # recall confidence (strong|thin|empty) → grounding stance
+
+    def as_context(self) -> str:
+        """Flatten to a context block for the model (empty string if nothing retrieved)."""
+        if not self.cards:
+            return ""
+        return "Relevant GINI knowledge:\n" + "\n".join(f"- {c.text}" for c in self.cards)
+
+
+# -- always-on tier --------------------------------------------------------- #
+def _palette():
+    return [d for d in all_devices() if d.key not in _HIDDEN]
+
+
+def element_index() -> str:
+    """Compact one-line-per-element catalog, grouped by category."""
+    by_cat: dict[str, list[str]] = {}
+    for d in _palette():
+        by_cat.setdefault(d.category.value, []).append(f"{d.key} — {d.description}")
+    lines = [f"[{cat}] " + "; ".join(items) for cat, items in by_cat.items()]
+    return "GINI elements (the ONLY elements available):\n" + "\n".join(lines)
+
+
+def group_defs() -> str:
+    """The connection grammar's reusable groups — the compressed shape of the matrix."""
+    parts = [f"{g}={{{', '.join(v)}}}" for g, v in _cr.GROUPS.items()]
+    return "Connection groups: " + "; ".join(parts) + "."
+
+
+def always_on_context() -> str:
+    return element_index() + "\n" + group_defs()
+
+
+# -- per-question tier ------------------------------------------------------ #
+def _partners_line(type_key: str, cap: int = 10) -> str:
+    ps = _cr.partners_for(type_key)
+    if not ps:
+        return "no standard connections"
+    bits = [f"{p.type_key}{'*' if p.required else ''}" for p in ps[:cap]]
+    more = "" if len(ps) <= cap else f", +{len(ps) - cap} more"
+    return "connects to " + ", ".join(bits) + more + " (*=required)"
+
+
+def element_card(type_key: str) -> Card | None:
+    dt = REGISTRY.get(type_key)
+    if dt is None or type_key in _HIDDEN:
+        return None
+    text = f"{dt.key} ({dt.label}): {dt.description} — {_partners_line(type_key)}"
+    return Card("element", type_key, dt.label, text)
+
+
+def concept_card(c) -> Card:
+    return Card("concept", c.key, c.title, f"{c.title}: {c.body}")
+
+
+def retrieve(intent, topology=None, *, llm=None, embedder=None) -> Retrieval:
+    """Question-specific knowledge for an Intent. See module docstring for the contract.
+
+    Retrieval runs through the hybrid `recall` layer (lexical → LLM-expansion → embeddings);
+    pass `llm`/`embedder` to enable the L1/L2 fallbacks (they do I/O, so the caller only wires
+    them on the worker thread). `out.strength` reports match confidence for the grounding
+    stance."""
+    from . import recall as _recall
+
+    anchor = getattr(intent, "anchor", "concept")
+    output_form = getattr(intent, "output_form", "tell")
+    depth = getattr(intent, "depth", "shallow")
+    topics = list(getattr(intent, "topics", []) or [])
+    refs = list(getattr(intent, "refs", []) or [])
+    query = getattr(intent, "query", "") or " ".join(topics)
+
+    out = Retrieval()
+    elem_keys: list[str] = []
+
+    res = _recall.recall(query, topics, llm=llm, embedder=embedder, deep=(depth == "deep"))
+    out.strength = res.strength
+
+    # concept notes (depth-gated): deep questions get more of the "how it works" layer
+    for h in res.concept_hits[: (2 if depth == "deep" else 1)]:
+        c = h.obj
+        out.cards.append(concept_card(c))
+        elem_keys.extend(c.elements)
+
+    # recipe pick — for generative/build asks, choose the pattern to describe or build
+    if anchor in ("concept", "hybrid") and res.recipe_hits:
+        out.recipe = res.recipe_hits[0].obj
+        elem_keys.extend(el.type_key for el in out.recipe.elements)
+        uniq = list(dict.fromkeys(el.type_key for el in out.recipe.elements))
+        verb = "Example to build" if output_form in ("show", "guide") else "Canonical pattern"
+        out.cards.append(Card("recipe", out.recipe.id, out.recipe.name,
+                              f"{verb} — {out.recipe.name}: {out.recipe.summary} "
+                              f"(uses ONLY these GINI elements: {', '.join(uniq)})"))
+
+    # canvas anchor: pull the referenced devices' element cards (map name -> type)
+    if anchor in ("canvas", "hybrid") and refs and topology is not None:
+        by_name = {d.name: d for d in topology.devices.values()}
+        for r in refs:
+            d = by_name.get(r)
+            if d is not None:
+                elem_keys.append(d.type.key if hasattr(d, "type") else d.type_key)
+
+    # element cards (dedup, order-preserving)
+    seen: set[str] = set()
+    for k in elem_keys:
+        if k and k not in seen and k not in _HIDDEN:
+            seen.add(k)
+            card = element_card(k)
+            if card is not None:
+                out.cards.append(card)
+    return out

gini/agent/lesson_resolver.py

@@ -0,0 +1,261 @@
+"""Lesson resolver — the "teacher can be vague" path.
+
+Because the arena is bounded, the games are pre-authored (the Game Catalog). So a professor need
+not hand-write objectives: they express intent loosely ("teach keeping a database private, ~25
+min"), the resolver **matches it to an archetype and proposes a concrete Lesson**, and the
+professor **ratifies** (approves/tweaks). This keeps the professor sovereign — the AI drafts, the
+human disposes.
+
+Two stages, cheap-first:
+  1. a lexical prefilter shortlists candidate archetypes (fast, deterministic);
+  2. a reasoning LLM picks the best archetype from the shortlist, fills its params, and suggests a
+     time limit / title (the reasoning step). With no model, the resolver degrades to the top
+     lexical candidate + demo params — still a usable proposal to ratify.
+
+Returns a `Proposal` (never auto-releases). Pure except the injected `llm`, so it's testable with
+a scripted model.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from ..domain import catalog as _catalog
+from ..domain import lexicon as _lex
+from ..domain import lesson as _lesson
+
+
+@dataclass
+class Proposal:
+    archetype_id: str
+    params: dict
+    lesson: object                       # domain.lesson.Lesson (None when infeasible)
+    rationale: str = ""
+    candidates: list = field(default_factory=list)   # shortlisted archetype ids (for the UI)
+    infeasible: str = ""                 # set (with lesson=None) when DOs and DON'Ts conflict
+    suppressed: str = ""                 # human note: what was left out to honour the DON'Ts
+
+
+def _archetype_text(a) -> str:
+    return " ".join((a.id.replace("-", " "), a.summary, a.spirit, a.teaches.replace("-", " ")))
+
+
+def shortlist(intent_text: str, k: int = 5) -> list:
+    """Lexically rank archetypes against the teacher's intent (the cheap prefilter)."""
+    want = set(_lex.normalize(intent_text, query=True))
+    scored = []
+    for a in _catalog.all_archetypes():
+        toks = set(_lex.normalize(_archetype_text(a)))
+        overlap = len(want & toks)
+        if overlap:
+            scored.append((overlap, a))
+    scored.sort(key=lambda s: -s[0])
+    picks = [a for _, a in scored[:k]]
+    return picks or list(_catalog.all_archetypes())[:k]
+
+
+def lexical_scores(intent_text: str) -> list[tuple[str, int]]:
+    """Archetypes scored by overlap with the intent, best first (score > 0 only). A word in the
+    archetype's DEFINING fields (id + summary) counts double a word that only appears incidentally in
+    the spirit/teaches — so a game that IS about a firewall (service-chain) outranks one that merely
+    mentions a firewall as one option (reachability-boundary)."""
+    want = set(_lex.normalize(intent_text, query=True))
+    scored = []
+    for a in _catalog.all_archetypes():
+        strong = set(_lex.normalize(a.id.replace("-", " ") + " " + a.summary))
+        weak = set(_lex.normalize(a.spirit + " " + a.teaches.replace("-", " ")))
+        score = 2 * len(want & strong) + len(want & (weak - strong))
+        if score:
+            scored.append((a.id, score))
+    scored.sort(key=lambda s: -s[1])
+    return scored
+
+
+def best_lexical(intent_text: str) -> str:
+    """The single best lexical match (or '' if nothing overlaps)."""
+    s = lexical_scores(intent_text)
+    return s[0][0] if s else ""
+
+
+_PROMPT = (
+    "A teacher wants a lab. Their intent: {intent!r}. Choose the best-fitting game from this "
+    "catalog and fill its parameters with short device names.\n{menu}\n"
+    "Reply ONLY as JSON: {{\"archetype\": \"<id>\", \"params\": {{<ref>: <name>, ...}}, "
+    "\"time_limit\": \"<e.g. 25m>\", \"title\": \"<short title>\"}}. No prose."
+)
+
+
+def _menu(cands) -> str:
+    lines = []
+    for a in cands:
+        refs = ", ".join(a.params)
+        lines.append(f"- {a.id} (params: {refs}) — {a.summary}")
+    return "Catalog:\n" + "\n".join(lines)
+
+
+def _first_json(text: str):
+    depth, start = 0, 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
+
+
+def resolve(intent_text: str, llm=None, *, lesson_id: str = "", **overrides) -> Proposal | None:
+    """Resolve a vague teacher intent into a proposed Lesson to ratify. `llm(prompt)->str` is the
+    reasoning step; omit it for a deterministic (lexical-only) proposal."""
+    cands = shortlist(intent_text)
+    if not cands:
+        return None
+
+    pick_id, params, time_limit, title, rationale = "", {}, "", "", ""
+    if llm is not None:
+        try:
+            obj = _first_json(llm(_PROMPT.format(intent=intent_text, menu=_menu(cands))))
+        except Exception:
+            obj = None
+        if isinstance(obj, dict):
+            pick_id = str(obj.get("archetype", ""))
+            if isinstance(obj.get("params"), dict):
+                params = {str(k): str(v) for k, v in obj["params"].items()}
+            time_limit = str(obj.get("time_limit", ""))
+            title = str(obj.get("title", ""))
+
+    arch = _catalog.get(pick_id) or cands[0]        # fall back to the top lexical candidate
+    # ensure every ref is bound: fill any gaps from the archetype's demo params
+    demo = _catalog.demo_params(arch.id)
+    for ref in arch.params:
+        params.setdefault(ref, demo.get(ref, ref.upper()))
+    params = {ref: params[ref] for ref in arch.params}     # drop stray keys, keep order
+
+    les = _lesson.from_archetype(
+        arch.id, params, id=lesson_id or f"resolved-{arch.id}",
+        title=title or arch.summary, brief=arch.summary,
+        time_limit=time_limit or overrides.get("time_limit", "20m"),
+        **{k: v for k, v in overrides.items() if k != "time_limit"})
+    return Proposal(archetype_id=arch.id, params=params, lesson=les,
+                    rationale=rationale or f"Matched intent to '{arch.id}'.",
+                    candidates=[a.id for a in cands])
+
+
+# -- student-facing composer ("describe a mission and I'll build it") -------- #
+# Unlike `resolve` (a teacher drafting a lesson to ratify), `compose` is the STUDENT path: it turns
+# a free-form wish into a playable mission on the spot. Crucially it does NOT invent objectives — it
+# *selects* the closest catalog archetype and may *combine* a second, so every win-condition comes
+# from a verified, gradable archetype. The LLM only interprets intent + reskins the framing; a
+# `validate()` guardrail drops the composition back to the primary archetype if it isn't gradable.
+# That keeps the "it made a mission just for me" magic without ever dropping a student into an
+# unwinnable mission — the exact split the design asks for (GINI owns structure; the LLM owns
+# understanding).
+
+_COMPOSE_PROMPT = (
+    "A student wants to practise with a hands-on lab mission. They said: {intent!r}.\n"
+    "Pick the SINGLE best-fitting game below. Only if their goal clearly needs a second game to be "
+    "complete, also pick a secondary to combine with it. Then write a short title and a 1-2 "
+    "sentence brief that frames the mission in the STUDENT'S own words. Optionally pick a genre — "
+    "experience (build it & watch), expedition (investigate toward a goal), or challenge (prove it, "
+    "little help). List anything the student explicitly does NOT want (e.g. 'metrics', 'dashboard') "
+    "in \"exclude\".\n{menu}\n"
+    "Reply ONLY as JSON: {{\"primary\": \"<id>\", \"secondary\": \"<id or empty>\", "
+    "\"genre\": \"<experience|expedition|challenge or empty>\", \"exclude\": [\"<thing to leave out>\"], "
+    "\"title\": \"<short title>\", \"brief\": \"<1-2 sentences>\"}}. No prose."
+)
+
+
+def compose(intent_text: str, llm=None, *, lesson_id: str = "", persona: str = "coach",
+            genre: str | None = None, level: int | None = None, fill: bool = False,
+            **overrides) -> Proposal | None:
+    """Compose a playable Lesson from a student's free-form wish by ASSEMBLING catalog fragments
+    (select the closest core, optionally a second the model explicitly names). Objectives are never
+    authored — only copied from verified fragments. Returns a Proposal (its `.lesson` is ready to
+    launch), or None if nothing is even lexically close.
+
+    `fill` defaults to FALSE for the describe box: a described mission stays LEAN — just what the
+    student asked for. We do NOT auto-add exercise/observe layers (load generators, dashboards,
+    metrics) they never requested. Enrichment is opt-in / for authored curricula, not terse wishes."""
+    from ..domain import assembly as _assembly
+    from ..domain import constraints as _con
+    from ..domain import fragments as _frag
+    cands = shortlist(intent_text)
+    if not cands:
+        return None
+
+    primary_id = secondary_id = title = brief = ""
+    g = genre
+    if llm is not None:
+        try:
+            obj = _first_json(llm(_COMPOSE_PROMPT.format(intent=intent_text, menu=_menu(cands))))
+        except Exception:
+            obj = None
+        if isinstance(obj, dict):
+            primary_id = str(obj.get("primary", ""))
+            secondary_id = str(obj.get("secondary", ""))
+            title = str(obj.get("title", ""))
+            brief = str(obj.get("brief", ""))
+            if g is None and obj.get("genre") in (_assembly.EXPERIENCE, _assembly.EXPEDITION,
+                                                  _assembly.CHALLENGE):
+                g = str(obj.get("genre"))
+
+    # DON'Ts: a reliable, model-free negation scan of the intent (the model's self-volunteered
+    # `exclude` was dropped — small models hallucinate exclusions, e.g. an unasked "no dashboard").
+    excl = _con.from_text(intent_text)
+
+    # Core selection is faithful to the LITERAL words: a STRONG lexical match is the primary (so the
+    # student gets what they typed, even if a small model over-elaborates and picks a different game).
+    # For fuzzy intent (no strong match) we trust the model's interpretation. A SECOND core is added
+    # only when the model explicitly names one — we do NOT auto-combine, which caused "private db,
+    # public web" to also drag in an unasked message-queue mission.
+    scores = lexical_scores(_con.positive_text(intent_text))
+    if scores and scores[0][1] >= 3:
+        primary = _catalog.get(scores[0][0]) or cands[0]
+    else:
+        primary = _catalog.get(primary_id) or cands[0]
+
+    # A mission must never MISREPRESENT itself. The model wrote title/brief from ITS reading of the
+    # intent, BEFORE we knew which fragments would actually be assembled — so that narrative is only
+    # a guess about the mission. Throw it away unconditionally; we re-narrate below against the
+    # assembled objectives, which is the only text that can be checked for truth.
+    title = brief = ""
+
+    core_ids = [primary.id]
+    if secondary_id and secondary_id != primary.id and _catalog.get(secondary_id) is not None:
+        core_ids.append(secondary_id)                    # a second core only on an explicit request
+    core_ids = core_ids[:2]
+
+    lid = lesson_id or f"described-{primary.id}"
+    lesson = _assembly.assemble(core_ids, genre=g, level=level, lesson_id=lid, title=title,
+                                brief=brief, persona=persona, exclude=excl, fill=fill, **overrides)
+
+    # feasibility: if a thing the student asked FOR still needs a thing they asked to leave OUT,
+    # don't quietly build a mismatched mission — report the conflict back
+    # NOW the mission exists, so now it can be described truthfully. The model writes a short title
+    # and a real description FROM the assembled objectives, and `narrate` rejects any prose that
+    # claims an element nothing grades. If it can't tell the truth we keep the fragments' own
+    # summary — which is true by construction, just less personal.
+    if llm is not None:
+        from . import narration as _narr
+        t, d = _narr.narrate(lesson, intent_text, llm)
+        if t and d:
+            lesson.title, lesson.brief = t, d
+
+    conflict = _con.objective_conflicts(lesson.objectives, excl)
+    if conflict:
+        want = ", ".join(conflict)
+        return Proposal(archetype_id=primary.id, params={}, lesson=None,
+                        candidates=[a.id for a in cands],
+                        infeasible=f"That doesn't quite work: this mission needs {want}, but you "
+                                   f"asked to leave that out. Drop that exclusion, or ask for a "
+                                   f"topology that doesn't rely on {want}.")
+    suppressed = excl.label() if excl else ""
+    return Proposal(archetype_id=primary.id, params={}, lesson=lesson, suppressed=suppressed,
+                    rationale=f"Assembled from {', '.join(lesson.fragments)}.",
+                    candidates=[a.id for a in cands])

gini/agent/llm/__init__.py

@@ -0,0 +1,5 @@
+from .backend import Chunk, LLMBackend, Message, ToolCall
+from .fake import ScriptedBackend
+from .ollama import OllamaBackend
+
+__all__ = ["Chunk", "LLMBackend", "Message", "ToolCall", "ScriptedBackend", "OllamaBackend"]