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

gini/agent/narration.py

@@ -0,0 +1,116 @@
+"""Mission narration — the LLM writes the story, GINI checks it against the truth.
+
+A mission has two faces. The **objectives** are the truth: they come from verified fragments, they
+are what gets graded, and the model never writes them. The **title and description** are the story
+told about that truth — and prose is exactly what a small model is good at.
+
+The failure this module exists to prevent: the model narrating a mission that isn't the one being
+graded (a "decouple your web tier with a message queue" title sitting on top of VPC-isolation
+objectives). Note that title and brief agreeing with *each other* proves nothing — they're written
+in one breath, so they always agree. The only agreement worth checking is narrative ⟷ objectives.
+
+So we check it, deterministically:
+
+    the elements the objectives grade  =  the only elements the prose may claim
+
+If the story mentions a queue and no objective grades a queue, the story is false — reject it and
+ask again, or fall back to the fragment's own summary. The model gets to be eloquent; it does not
+get to be wrong. No LLM is asked to police itself.
+"""
+from __future__ import annotations
+
+import re
+
+from ..domain import devices as _devices
+from ..domain import objectives as _obj
+from ..domain import probes as _probes
+
+# words that name an element but are also ordinary English — only count them as a CLAIM about an
+# element when the objectives don't already license them (checked below), never as free-text.
+_STOP = {"internet", "cloud", "network", "host", "machine", "function", "gateway"}
+
+
+def graded_types(lesson) -> set[str]:
+    """Every element type the lesson's objectives actually grade — the licensed vocabulary."""
+    out: set[str] = set()
+    for o in lesson.objectives:
+        if o.check:
+            out.update(_obj.element_types_in_check(o.check))
+        if o.probe:
+            try:
+                p = _probes.parse(o.probe)
+            except _probes.ProbeError:
+                continue
+            out.update(x for x in (p.src, p.dst) if x)
+    return {t for t in out if _devices.get(t) is not None}
+
+
+def _phrases() -> list[tuple[str, str]]:
+    """(phrase, type_key) for every element, longest phrase first so 'load balancer' beats 'balancer'."""
+    out: list[tuple[str, str]] = []
+    for dt in _devices.all_devices():
+        out.append((dt.label.lower(), dt.key))
+        out.append((dt.key.replace("_", " ").lower(), dt.key))
+    return sorted(set(out), key=lambda p: -len(p[0]))
+
+
+def false_claims(text: str, allowed: set[str]) -> list[str]:
+    """Element types the prose names that NO objective grades. These are the lies."""
+    low = " " + re.sub(r"[^a-z0-9 ]+", " ", (text or "").lower()) + " "
+    bad: list[str] = []
+    for phrase, key in _phrases():
+        if key in allowed or key in bad:
+            continue
+        if phrase in _STOP:
+            continue                      # too ordinary to read as a claim about an element
+        if re.search(rf"\b{re.escape(phrase)}s?\b", low):
+            bad.append(key)
+    return bad
+
+
+_PROMPT = (
+    "You are writing the brief for a hands-on lab mission a student is about to play.\n\n"
+    "The student asked for: {intent!r}\n\n"
+    "These are the EXACT tasks they will be graded on — the mission IS these and nothing else:\n"
+    "{tasks}\n\n"
+    "Write:\n"
+    "  title — a SHORT name, at most 6 words, no trailing period. Name the idea, not the steps.\n"
+    "  description — 3 to 4 sentences. Say what they're building, WHY an engineer would want it, "
+    "and what 'done' looks like. Speak to the student as 'you'. Do not number the tasks or repeat "
+    "them one by one — they can already see them.\n\n"
+    "HARD RULE: mention ONLY these components: {allowed}. Do not mention any other technology "
+    "(no queues, caches, dashboards, load balancers, etc. unless listed). Naming something that "
+    "isn't in that list makes the brief WRONG.\n\n"
+    'Reply ONLY as JSON: {{"title": "...", "description": "..."}}'
+)
+
+
+def narrate(lesson, intent: str, llm, *, retries: int = 1) -> tuple[str, str]:
+    """Ask the model for a short title + a longer description, and REFUSE anything that claims an
+    element the objectives don't grade. Returns ("", "") if the model can't tell the truth — the
+    caller then falls back to the fragment's own summary, which is always true by construction."""
+    from .personas import first_json
+    allowed = graded_types(lesson)
+    if not allowed or llm is None:
+        return "", ""
+    labels = sorted((_devices.get(t).label for t in allowed), key=str.lower)
+    tasks = "\n".join(f"  - {o.say}" for o in lesson.objectives)
+    prompt = _PROMPT.format(intent=intent, tasks=tasks, allowed=", ".join(labels))
+
+    for _ in range(retries + 1):
+        try:
+            obj = first_json(llm(prompt))
+        except Exception:                                    # noqa: BLE001
+            return "", ""
+        if not isinstance(obj, dict):
+            continue
+        title = " ".join(str(obj.get("title", "")).split()).strip(" .")
+        desc = " ".join(str(obj.get("description", "")).split())
+        if not title or not desc:
+            continue
+        if len(title.split()) > 8:                           # "short" is part of the brief
+            continue
+        if false_claims(title, allowed) or false_claims(desc, allowed):
+            continue                                         # it narrated a mission we aren't grading
+        return title, desc
+    return "", ""

gini/agent/notifier.py

@@ -0,0 +1,86 @@
+"""Notification / salience — the deterministic layer that decides which changes are worth waking the
+Reasoning persona (GINI_MISSIONS_AGENT_ARCHITECTURE.md §3-4). Salience is **rules-only** (decided): a
+fixed table, no LLM on the hot path. Input = the verdicts that FLIPPED on the last blackboard update
+(plus explicit events like a student question or a run completing); output = salient Notifications.
+
+`MissionMonitor` ties the deterministic swarm together: world change → blackboard re-verify → salient
+notifications. It's the seam the live UI and the Reasoning persona both sit against.
+"""
+from __future__ import annotations
+
+from .blackboard import Blackboard
+from .contracts import Notification
+
+# rules-only salience table (0..1). Tune the RULES if noisy — never add a model here.
+SALIENCE = {
+    "objective_met": 0.6,
+    "objective_unmet": 0.4,
+    "off_task_added": 0.9,
+    "off_task_cleared": 0.3,
+    "illegal_link_added": 0.9,
+    "illegal_link_cleared": 0.3,
+    "forbid_tripped": 1.0,
+    "forbid_cleared": 0.3,
+    "mission_complete": 1.0,
+    "question": 1.0,
+    "run_complete": 0.7,
+}
+
+
+def _note(change: str, subjects=(), data=None) -> Notification:
+    return Notification(change, subjects=tuple(subjects), salience=SALIENCE.get(change, 0.5), data=data)
+
+
+def notifications_from_flips(flipped, blackboard: Blackboard) -> list[Notification]:
+    """Map flipped verdicts → salient notifications by rule. `flipped` is what `Blackboard.update`
+    returned (verdicts whose value changed or newly appeared)."""
+    notes: list[Notification] = []
+    for v in flipped:
+        if v.verifier_id.startswith("objective:"):
+            notes.append(_note("objective_met" if v.value else "objective_unmet", subjects=(v.subject,)))
+        elif v.subject == "off_task":
+            data = list(v.evidence.data) if v.evidence else []
+            notes.append(_note("off_task_cleared" if v.value else "off_task_added",
+                               subjects=tuple(data), data=data))
+        elif v.subject == "illegal_links":
+            data = list(v.evidence.data) if v.evidence else []
+            notes.append(_note("illegal_link_cleared" if v.value else "illegal_link_added",
+                               subjects=tuple(data), data=data))
+        elif v.subject.startswith("forbid:"):
+            say = v.evidence.data if v.evidence else ""
+            notes.append(_note("forbid_cleared" if v.value else "forbid_tripped",
+                               subjects=(v.subject,), data=say))
+    # a completion is derived from the whole board, not a single flip
+    if flipped and blackboard.all_objectives_met():
+        notes.append(_note("mission_complete"))
+    return notes
+
+
+def top(notes) -> Notification | None:
+    """The single most salient notification (what the reasoner should react to first), or None."""
+    return max(notes, key=lambda n: n.salience) if notes else None
+
+
+class MissionMonitor:
+    """The deterministic swarm, packaged: keeps a blackboard current and emits salient notifications
+    on every world change. The Reasoning persona reads the blackboard; this tells it when to wake."""
+
+    def __init__(self) -> None:
+        self.bb = Blackboard()
+
+    def load(self, lesson, *, pack=None, runner=None) -> None:
+        verifiers = pack.verifiers(lesson) if pack is not None else None
+        self.bb.load_lesson(lesson, verifiers=verifiers, runner=runner)
+
+    def clear(self) -> None:
+        self.bb.clear()
+
+    def on_world_change(self, topology, *, changed: set[str] | None = None) -> list[Notification]:
+        flipped = self.bb.update(topology, changed=changed)
+        return notifications_from_flips(flipped, self.bb)
+
+    def on_question(self, text: str) -> Notification:
+        return _note("question", data=text)
+
+    def on_run_complete(self) -> Notification:
+        return _note("run_complete")

gini/agent/personas.py

@@ -0,0 +1,79 @@
+"""One small model, many narrow personas (GINI_MISSIONS_AGENT_ARCHITECTURE.md §5). A Persona is a
+first-class object — a "you do ONLY this" system prompt, decoding params, and a stateful flag. The
+PersonaRunner is the single, clean-isolation call site: it builds a prompt from exactly
+`system + context + task` and carries NOTHING else across a call (the defence against persona-leak).
+
+State lives on the blackboard (the shared curated memory), never inside the runner — so the runner is
+stateless and any persona's "history" is reconstructed per call from the memory slice it's handed.
+"""
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+
+
+def first_json(text: str):
+    """The first balanced {...} object in a model reply, parsed — or None. Small models wrap JSON in
+    prose; this is the tolerant extractor every persona uses to read structured output."""
+    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
+
+
+@dataclass(frozen=True, eq=False)
+class Persona:
+    name: str
+    system: str                 # "you do ONLY this" — no general-assistant framing
+    temperature: float = 0.3
+    stateful: bool = False       # only the Reasoning persona is stateful (reads shared memory)
+    schema: dict | None = None   # optional JSON Schema → decoder-constrained output (Reasoning 2.0)
+
+
+class PersonaRunner:
+    """Invokes personas on one injected model. `llm` is `llm(prompt) -> str`, optionally accepting
+    `temperature=` and/or `schema=` keyword args (the runner passes each only when the callable
+    accepts it — so simple lambdas in tests and older backends keep working unchanged)."""
+
+    def __init__(self, llm) -> None:
+        self._llm = llm
+        self._accepts_temp = False
+        self._accepts_schema = False
+        try:
+            params = inspect.signature(llm).parameters
+            self._accepts_temp = "temperature" in params
+            self._accepts_schema = "schema" in params
+        except (TypeError, ValueError):
+            pass
+        self.last_prompt = ""    # for tests / debugging — the exact text last sent
+
+    def call(self, persona: Persona, *, context: str = "", task: str = "") -> str:
+        parts = [persona.system]
+        if context:
+            parts.append(context)
+        if task:
+            parts.append(task)
+        prompt = "\n\n".join(p for p in parts if p).strip()
+        self.last_prompt = prompt
+        if self._llm is None:
+            return ""
+        kwargs = {}
+        if self._accepts_temp:
+            kwargs["temperature"] = persona.temperature
+        if self._accepts_schema and persona.schema is not None:
+            kwargs["schema"] = persona.schema
+        try:
+            return (self._llm(prompt, **kwargs) or "").strip()
+        except Exception:
+            return ""

gini/agent/reasoning.py

@@ -0,0 +1,172 @@
+"""The Reasoning persona — the centre of the loop (GINI_MISSIONS_AGENT_ARCHITECTURE.md §3,5,6). It
+reads TRUTH from the blackboard (never recomputes it), the mission intent, and the shared curated
+memory, then reasons out the next move for whatever woke it (a salient Notification or a student
+Intent). The deterministic layer decides *when* to wake it and supplies the facts; the wording and the
+pedagogy are entirely the model's.
+
+Grounding is by construction: the prompt carries the live objective/legality facts, so the answer is
+about the student's actual board — not canned. A non-LLM fallback keeps it usable offline (degraded).
+"""
+from __future__ import annotations
+
+from .contracts import Intent, Move, Notification
+from .personas import Persona, PersonaRunner, first_json
+
+_SYSTEM = (
+    "You are the game master of a hands-on lab mission — warm, concise, and in character. You ONLY "
+    "produce the next short line to the student (1-2 sentences). Ground every statement in the FACTS "
+    "you are given; never invent devices, connections, or states that aren't listed. If the facts "
+    "don't cover the question, say what IS known and stop — don't guess.")
+
+REASONING = Persona("Reasoning", system=_SYSTEM, temperature=0.35, stateful=True)
+
+# The covered variant (Reasoning 2.0): same voice, but the reply is ONE JSON object carrying the
+# line plus a coverage report the Twin diffs exactly. Decoder-constrained where the backend
+# supports structured outputs (schema); the tolerant first_json path handles the rest.
+def _covered_persona():
+    from .twin.dialectic import COVERAGE_SCHEMA
+    return Persona("Reasoning", system=_SYSTEM, temperature=0.35, stateful=True,
+                   schema=COVERAGE_SCHEMA)
+
+
+REASONING_COVERED = None   # built lazily (avoids a twin import at module load)
+
+# how a triggering change maps to the SHAPE of the move (routing, not reasoning — the model still
+# writes the content)
+_MOVE_KIND = {
+    "mission_complete": "advance", "objective_met": "say", "objective_unmet": "hint",
+    "off_task_added": "flag", "illegal_link_added": "flag", "forbid_tripped": "flag",
+    "question": "answer",
+}
+
+
+class ReasoningAgent:
+    def __init__(self, runner: PersonaRunner, blackboard, lesson) -> None:
+        self.runner = runner
+        self.bb = blackboard
+        self.lesson = lesson
+        self.last_coverage = None    # the last covered turn's report (None = coverage-silent)
+
+    # -- grounding: turn the blackboard's verdicts into a compact fact sheet -- #
+    def _situation(self) -> str:
+        say = {o.id: o.say for o in self.lesson.objectives}
+        met = [say.get(s, s) for s in
+               (v.subject for v in self.bb.verdicts() if v.verifier_id.startswith("objective:") and v.value)]
+        unmet_ids = self.bb.unmet_objectives()
+        unmet = [say.get(s, s) + self._why(s) for s in unmet_ids]   # each open item + WHY it's red
+        flags = self.bb.flags()
+        lines = [f"Objectives met ({len(met)}/{len(met) + len(unmet)}): " + ("; ".join(met) or "none"),
+                 "Still open: " + ("; ".join(unmet) or "none — all done")]
+        if flags.get("off_task"):
+            lines.append("Off-task elements on the board: " + ", ".join(flags["off_task"]))
+        if flags.get("illegal_links"):
+            lines.append("Illegal connections present.")
+        return "\n".join(lines)
+
+    def _why(self, objective_id: str) -> str:
+        """A deterministic, board-grounded reason an objective is red (the predicate explainer). We
+        need the live topology for this; the blackboard caches the world on evaluation."""
+        obj = next((o for o in self.lesson.objectives if o.id == objective_id), None)
+        world = getattr(self.bb, "_world", None)
+        if obj is None or world is None:
+            return ""
+        try:
+            from ..domain import explain as _explain
+            reason = _explain.diagnose(obj, world)
+        except Exception:
+            reason = ""
+        return f" — {reason}" if reason else ""
+
+    def _intent(self) -> str:
+        it = self.lesson.intent
+        parts = [f"Mission goal: {it.goal}"] if it.goal else []
+        if it.spirit:
+            parts.append(f"What success means: {it.spirit}")
+        if it.misconceptions:
+            parts.append("Watch for these misconceptions: " + "; ".join(it.misconceptions))
+        # the instructor's own nuance, authored on the Teaching Center and interpreted HERE (this is
+        # why the course server needs no LLM — the teacher writes plain language, we reason over it)
+        if getattr(it, "notes", ""):
+            parts.append(f"Your instructor's guidance for this lab: {it.notes}")
+        return "\n".join(parts)
+
+    def _context(self) -> str:
+        return "\n".join(p for p in (self._intent(), "FACTS:\n" + self._situation(),
+                                     self.bb.memory.digest()) if p)
+
+    # -- the reasoning turn ------------------------------------------------- #
+    def react(self, trigger, *, note: str = "", coverage_concerns=None) -> Move:
+        """React to a Notification or a student Intent → one grounded Move. `note` (optional) is a
+        critique from the Critic persona used to revise a first draft. `coverage_concerns`
+        (Reasoning 2.0) asks the persona to ALSO report coverage against the Twin's concern list;
+        the parsed report lands on `self.last_coverage` (None = coverage-silent)."""
+        change, task, refs = self._frame(trigger)
+        if note:
+            task = f"{task}\nA reviewer noted: {note}. Fix that in your line."
+        self.last_coverage = None
+        if coverage_concerns:
+            global REASONING_COVERED
+            if REASONING_COVERED is None:
+                REASONING_COVERED = _covered_persona()
+            from .twin.dialectic import concern_context, coverage_instruction
+            # twin-as-context: the concern set rides in the GROUNDING (guaranteed recall shapes
+            # the draft), and again as the coverage checklist the exact diff runs against.
+            ctx = "\n\n".join(p for p in (self._context(),
+                                          concern_context(coverage_concerns)) if p)
+            raw = self.runner.call(REASONING_COVERED, context=ctx,
+                                   task=task + coverage_instruction(coverage_concerns))
+            text = self._parse_covered(raw) or self._fallback(change)
+        else:
+            text = (self.runner.call(REASONING, context=self._context(), task=task)
+                    or self._fallback(change))
+        if not note:                        # don't double-record on a revision pass
+            self._remember(change, trigger)
+        return Move(kind=_MOVE_KIND.get(change, "say"), text=text, refs=refs)
+
+    def _parse_covered(self, raw: str) -> str:
+        """A covered reply -> the tutor line, with the coverage report set aside for the Twin.
+        Tolerant: a model that ignored the JSON shape just becomes coverage-silent prose."""
+        from .twin.contracts import parse_coverage
+        obj = first_json(raw or "")
+        if isinstance(obj, dict) and isinstance(obj.get("text"), str):
+            self.last_coverage = parse_coverage(obj.get("coverage"))
+            return obj["text"].strip()
+        return (raw or "").strip()
+
+    def _frame(self, trigger) -> tuple[str, str, tuple]:
+        if isinstance(trigger, Intent):
+            return ("question",
+                    f"The student asks: {trigger.text!r}. Answer using ONLY the facts above, tied to "
+                    "what they've built.", trigger.refs)
+        change = getattr(trigger, "change", "say")
+        subs = tuple(getattr(trigger, "subjects", ()) or ())
+        tasks = {
+            "mission_complete": "The student just completed every objective. Congratulate them in ONE "
+                                "specific line tied to what they achieved.",
+            "objective_met": "The student just satisfied an objective. Say 'warmer' in ONE line, naming "
+                             "what improved — do NOT reveal the next step.",
+            "objective_unmet": "The student moved away from a goal. Nudge in ONE line — no solution.",
+            "off_task_added": f"The student placed something off-task ({', '.join(subs)}). Flag it in "
+                              "ONE in-character line and tell them to remove it — do NOT remove it yourself.",
+            "illegal_link_added": "The student made a connection that isn't allowed. Flag it in ONE line "
+                                  "and tell them to rewire it.",
+            "forbid_tripped": f"The student tripped a rule that must stay false ({trigger.data}). Flag it "
+                              "in ONE line.",
+        }
+        return (change, tasks.get(change, "Give the student ONE short, helpful line for the current "
+                                            "situation."), subs)
+
+    def _remember(self, change: str, trigger) -> None:
+        if change == "question" and isinstance(trigger, Intent):
+            self.bb.memory.threads.append(trigger.text)
+        elif change == "objective_met":
+            self.bb.memory.note_fact("progress: an objective was satisfied")
+        elif change in ("off_task_added", "illegal_link_added", "forbid_tripped"):
+            self.bb.memory.note_tried(f"made a flagged move ({change})")
+        self.bb.memory.arc = self._situation().splitlines()[0]
+
+    def _fallback(self, change: str) -> str:
+        return {"mission_complete": "Nice — every objective is green. You did it!",
+                "off_task_added": "That doesn't belong in this mission — take it off the board.",
+                "objective_met": "Warmer — that helped.",
+                }.get(change, "Keep going — check what's still open above.")