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

gini/agent/verifiers.py

@@ -0,0 +1,106 @@
+"""Tiny, single-aspect verifiers — the deterministic truth-agents (GINI_MISSIONS_AGENT_ARCHITECTURE
+.md §3). Each checks ONE aspect and returns Verdicts; none of them reason. They wrap the evaluators we
+already have (`domain/objectives`, `domain/legality`) so P1 is mostly a reframing, not new logic.
+
+State-dependency keys (coarse for now — the exact scheme is an open decision): "topology" for
+structural checks over the graph, "runtime" for behavioral probes. The blackboard re-runs a verifier
+only when a changed key intersects its `deps()`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..domain import legality as _legality
+from ..domain import objectives as _obj
+from .contracts import Fact, Verdict
+
+TOPOLOGY, RUNTIME = "topology", "runtime"
+
+
+@dataclass
+class WorldView:
+    """What a verifier is handed: the live topology, an objectives World over it, the lesson, and an
+    optional behavioral runner. Built once per blackboard update and shared across verifiers."""
+    topology: object
+    world: object
+    lesson: object
+    runner: object = None
+
+    @classmethod
+    def of(cls, topology, lesson, *, runner=None):
+        return cls(topology=topology, world=_obj.TopologyWorld(topology), lesson=lesson, runner=runner)
+
+
+class ObjectiveVerifier:
+    """One tiny verifier per objective — met/unmet (behavioral → pending counts as not-yet-met)."""
+
+    def __init__(self, objective) -> None:
+        self.objective = objective
+        self.id = f"objective:{objective.id}"
+
+    def deps(self) -> tuple[str, ...]:
+        return (RUNTIME,) if self.objective.is_behavioral() else (TOPOLOGY,)
+
+    def check(self, view: WorldView) -> list[Verdict]:
+        r = _obj.evaluate(self.objective, view.world, view.runner)
+        return [Verdict(self.id, subject=self.objective.id, value=r.met,
+                        evidence=Fact("status", r.status), deps=self.deps())]
+
+
+class OffTaskVerifier:
+    """Off-task element aspect: are any placed elements outside the mission's relevant family?"""
+    id = "legality:off_task"
+
+    def __init__(self, lesson) -> None:
+        self.lesson = lesson
+
+    def deps(self) -> tuple[str, ...]:
+        return (TOPOLOGY,)
+
+    def check(self, view: WorldView) -> list[Verdict]:
+        devices = _legality.off_task_devices(self.lesson, view.topology)
+        return [Verdict(self.id, subject="off_task", value=(not devices),
+                        evidence=Fact("devices", list(devices)), deps=(TOPOLOGY,))]
+
+
+class IllegalLinkVerifier:
+    """Connection-grammar aspect: are any drawn links disallowed?"""
+    id = "legality:illegal_links"
+
+    def deps(self) -> tuple[str, ...]:
+        return (TOPOLOGY,)
+
+    def check(self, view: WorldView) -> list[Verdict]:
+        bad = _legality.illegal_links(view.topology)
+        return [Verdict(self.id, subject="illegal_links", value=(not bad),
+                        evidence=Fact("links", list(bad)), deps=(TOPOLOGY,))]
+
+
+class ForbidVerifier:
+    """One tiny verifier per lesson forbid-rule — the rule must stay FALSE (value True = still safe)."""
+
+    def __init__(self, index: int, forbid) -> None:
+        self.index = index
+        self.forbid = forbid
+        self.id = f"forbid:{index}"
+
+    def deps(self) -> tuple[str, ...]:
+        return (TOPOLOGY,)
+
+    def check(self, view: WorldView) -> list[Verdict]:
+        try:
+            tripped = bool(self.forbid.check) and _obj.evaluate_check(self.forbid.check, view.world)
+        except _obj.PredicateError:
+            tripped = False
+        return [Verdict(self.id, subject=f"forbid:{self.index}", value=(not tripped),
+                        evidence=Fact("say", self.forbid.say), deps=(TOPOLOGY,))]
+
+
+def for_lesson(lesson) -> list:
+    """The full set of tiny verifiers a lesson needs: one per objective + the legality aspects + one
+    per forbid rule. This is 'many tiny', assembled per mission."""
+    vs: list = [ObjectiveVerifier(o) for o in lesson.objectives]
+    vs.append(OffTaskVerifier(lesson))
+    vs.append(IllegalLinkVerifier())
+    vs.extend(ForbidVerifier(i, f) for i, f in enumerate(getattr(lesson, "forbid", []) or []))
+    return vs

gini/agent/wizard.py

@@ -0,0 +1,178 @@
+"""Wizard brain — LLM-driven, goal-directed building.
+
+The Wizard is "X-ray with a goal", and the goal-relevance is decided by the model, per
+step, in the context of the canvas so far:
+
+  1. **Pick a starter** — given the goal + the element catalog (with descriptions), the
+     model names the single best first element. We place it.
+  2. **Walk the build** — around the current element the grammar proposes the *valid*
+     neighbours; the model filters them to the ones that serve the goal (one batched
+     call) and gives a one-line reason each. The student taps one; it's added + connected;
+     repeat from there.
+
+The grammar guarantees validity (the model only ever sees valid candidates); the model
+adds goal-relevance. This module is the *pure* part — building prompts and parsing
+replies — so it's testable without a live model. The threading/UI lives in the assistant.
+"""
+from __future__ import annotations
+
+from ..domain.devices import REGISTRY, by_category
+
+
+def element_catalog() -> str:
+    """A compact 'Label: one-line description' list of the placeable elements."""
+    lines = []
+    for items in by_category().values():
+        for d in items:
+            desc = d.description.split(". ")[0].rstrip(".")
+            lines.append(f"- {d.label}: {desc}.")
+    return "\n".join(lines)
+
+
+def _label_key_map() -> dict[str, str]:
+    m: dict[str, str] = {}
+    for key, d in REGISTRY.items():
+        if not d.hidden:
+            m[d.label.lower()] = key
+            m[key.lower()] = key
+    return m
+
+
+# ---------------------------------------------------------------- starter ---- #
+def starter_prompt(goal: str, catalog: str) -> str:
+    # NOTE: do NOT put a concrete element in the example — a small model will copy it and
+    # answer the same element for every goal. Use a neutral placeholder, and make the model
+    # state its final choice on an explicit PICK: line so we read its CONCLUSION, not the
+    # first element it happens to mention while reasoning.
+    return (f'A student wants to build this and nothing else: "{goal}".\n\n'
+            f"Choose the single best FIRST element strictly from this list:\n{catalog}\n\n"
+            "Match the goal's DOMAIN:\n"
+            "- An IP / LAN / subnet / routing / Ethernet / VLAN goal is a COMPUTER-NETWORKING "
+            "goal — start with a Router or Switch. Do NOT start with a VPC, Kubernetes, or "
+            "any cloud element just because the goal contains the word 'network'.\n"
+            "- A cloud / Kubernetes / serverless / database / web-service goal is a CLOUD "
+            "goal — start with the cloud element it's built around.\n"
+            "Pick the ONE element that is the foundation for THAT specific goal. "
+            "You may reason briefly, but END with ONE final line in EXACTLY this form, "
+            "copying a real element name from the list:\n"
+            "    PICK: <element name> - <short reason it fits this goal>")
+
+
+def coach_prompt(issues, canvas_summary: str) -> str:
+    """Coach mode: the issues are DETECTED deterministically (the advisory lint) — the model
+    only coaches. `issues` = [{level, device, message}]. The model must prioritize + explain,
+    never invent problems and never claim it's fine when issues were found."""
+    lines = "\n".join(f"- {(i.get('device') or 'topology')}: {i.get('message', '')}"
+                      for i in issues)
+    return (f"You are reviewing a student's GINI network/cloud topology and coaching them on "
+            f"what to fix.\nCanvas: {canvas_summary or '(empty)'}\n\n"
+            f"These problems were detected (ground truth — do NOT invent any others, and do "
+            f"NOT say the topology is fine):\n{lines}\n\n"
+            "In 2-4 short sentences, tell the student what to fix FIRST and why, in plain "
+            "language, referring to devices by name. Prioritize and guide — don't just "
+            "restate the list.")
+
+
+def os_coach_prompt(events, card: str, remaining: int, focus: str = "") -> str:
+    """OS Coach: measured, Socratic help grounded in the LIVE xv6 kernel state. `events` are
+    detected deterministically by the StateWatcher (ground truth — the model coaches, it does
+    not invent). The model gives ONE nudge, never the full answer, so the help is a hint-ladder
+    rather than an offload — the 'measured' delivery on top of the state-grounded moat."""
+    ev = "\n".join(f"- {e.kind}: {e.detail}" for e in events) \
+        or "- (no new events — the run looks steady right now)"
+    return (
+        "You are Coaching a student through an experiment on a REAL xv6 kernel running inside "
+        "GINI. Below is the live kernel state (ground truth) and the teachable moments GINI "
+        "detected in it. Coach SOCRATICALLY: ask ONE guiding question, or give ONE targeted "
+        "hint, that leads the student to NOTICE and reason about what is happening. Do NOT dump "
+        "the full explanation, do NOT write code, and do NOT invent processes or values that "
+        "aren't in the state. Refer to processes by pid.\n\n"
+        f"Live kernel state:\n{card}\n\nDetected moments:\n{ev}\n\n"
+        + (f"{focus}\n\n" if focus else "")
+        + f"(The student has {remaining} Coach hint(s) left this session, so make it count.)\n"
+        "Reply with 2-3 sentences: one nudge.")
+
+
+def starter_retry_prompt(goal: str, names: str) -> str:
+    """A terse re-ask used when the model didn't return a clean, valid pick."""
+    return (f'Goal: "{goal}".\nValid elements: {names}.\n'
+            "Reply with ONLY this one line and nothing else:\n"
+            "PICK: <one exact element name from the list above>")
+
+
+def element_names() -> str:
+    """Just the comma-separated element labels (for the terse retry prompt)."""
+    from .. domain.devices import by_category
+    return ", ".join(d.label for items in by_category().values() for d in items)
+
+
+def _validate(name: str) -> str | None:
+    """Strict: a candidate string is accepted ONLY if it is exactly one element label/key
+    (after dropping a leading article). No fuzzy matching, no guessing among several."""
+    n = (name or "").strip().strip(".\"'`").lower()
+    for art in ("a ", "an ", "the "):
+        if n.startswith(art):
+            n = n[len(art):].strip()
+    return _label_key_map().get(n)
+
+
+def parse_starter(text: str) -> tuple[str | None, str]:
+    """Return (type_key, reason) ONLY when the model gave a clean, validated pick:
+    1) a 'PICK: <element> - <reason>' line whose element validates exactly; or
+    2) a line that IS '<element> - <reason>' (its lead segment validates exactly).
+    Anything ambiguous/rambling returns (None, '') — the caller re-asks rather than guess."""
+    for raw in (text or "").splitlines():
+        line = raw.strip()
+        if line[:5].lower() == "pick:":
+            line = line[5:].strip()
+        elif not line:
+            continue
+        head, _, reason = line.partition(" - ")
+        if " — " in head and not _validate(head):     # tolerate an em-dash separator
+            head, _, reason = line.partition(" — ")
+        key = _validate(head)
+        if key is not None:
+            return key, reason.strip(" -:–—\t").strip()
+    return None, ""
+
+
+# ------------------------------------------------------------- neighbours ---- #
+def filter_prompt(goal: str, current_label: str, candidates, canvas_summary: str) -> str:
+    """`candidates` = list[(type_key, label)] — the grammar-valid neighbours of the
+    current element. Ask the model which serve the goal."""
+    opts = "\n".join(f"- {lbl}" for _k, lbl in candidates)
+    canvas = f"\nWhat's built so far: {canvas_summary}\n" if canvas_summary else "\n"
+    return (f'The student\'s goal is: "{goal}".\n'
+            f"They just placed a {current_label}.{canvas}"
+            f"These elements can validly connect to the {current_label}:\n{opts}\n\n"
+            "List ONLY the ones that move the design toward the goal, best first, each on "
+            "its own line as:  <Element name> - <short reason it helps the goal>. "
+            "Omit ones that don't serve this goal.")
+
+
+def parse_filter(text: str, candidates) -> list[tuple[str, str]]:
+    """Parse the model's picks back to (type_key, reason), restricted to `candidates`."""
+    by_label = {lbl.lower(): key for key, lbl in candidates}
+    out: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for raw in (text or "").splitlines():
+        line = raw.strip(" -*•\t")
+        if not line:
+            continue
+        low = line.lower()
+        for lbl in sorted(by_label, key=len, reverse=True):     # longest label first
+            if low.startswith(lbl) and by_label[lbl] not in seen:
+                key = by_label[lbl]
+                reason = line[len(lbl):].lstrip(" -:–—").strip()
+                out.append((key, reason or "fits the goal"))
+                seen.add(key)
+                break
+    if out:
+        return out
+    # fallback: scan the whole text for any candidate label mentioned, in candidate order
+    low = (text or "").lower()
+    for key, lbl in candidates:
+        if lbl.lower() in low and key not in seen:
+            out.append((key, "fits the goal"))
+            seen.add(key)
+    return out

gini/agent/xv6_pack.py

@@ -0,0 +1,74 @@
+"""Xv6Pack — the OS DomainPack.
+
+Plugs xv6/OS onto the domain-neutral engine (composition, probes, grader, catalog, Teaching Center)
+exactly the way NetworkingPack does for networking (see agent/domains.py: "Cloud and xv6/OS become
+future packs implementing the same protocol"). Nothing here is a new engine — it is adapters:
+
+  • fragments  — the OS assignments, authored as YAML in domain/missions/os/ (loaded like any pack).
+  • behavioral oracle — the OS win-conditions are ordinary `measure(...)` probes; the runner that
+    computes them from live kernel telemetry is `domain.xv6_runner.Xv6Runner` (built + tested). The
+    grader evaluates a behavioral objective via `objectives.evaluate(obj, world, runner=Xv6Runner)`.
+  • palette / vocabulary / knowledge — the xv6 element + reused capability roles + OS concept notes.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .contracts import Observation
+
+
+class Xv6Observer:
+    """Senses the running xv6 (its Machine state / telemetry) as an Observation for the blackboard.
+    Best-effort: whatever `world` the framework hands it (a MachineState or a serialised view)."""
+    id = "xv6"
+
+    def observe(self, world) -> list:
+        data = world.to_dict() if hasattr(world, "to_dict") else world
+        return [Observation(source="xv6", data=data)]
+
+
+def _os_missions_dir() -> Path:
+    return Path(__file__).resolve().parent.parent / "domain" / "missions" / "os"
+
+
+class Xv6Pack:
+    """The OS domain pack. Same seven-member protocol as NetworkingPack."""
+    name = "os"
+
+    def verifiers(self, lesson) -> list:
+        return []                                    # structural verifiers reused; OS grading is behavioral
+
+    def observers(self) -> list:
+        return [Xv6Observer()]
+
+    def vocabulary(self):
+        from ..domain import capabilities                # reuse the capability is-a hierarchy
+        return capabilities
+
+    def predicates(self) -> set:
+        from ..domain.objectives import _PREDICATES      # structural predicates reused as-is
+        return set(_PREDICATES)
+
+    def fragments(self) -> list:
+        """The OS assignments — YAML fragments in domain/missions/os/, loaded like any pack."""
+        from ..domain import fragment_yaml as _fy
+        loaded, _warn = _fy.load_dir(str(_os_missions_dir()), strict=False)
+        return list(loaded.values())
+
+    def palette(self) -> dict:
+        from ..domain.devices import REGISTRY
+        return {k: v for k, v in REGISTRY.items()
+                if k in ("xv6", "terminal", "storage_volume")}
+
+    def knowledge(self):
+        from . import kb
+        return kb
+
+    # -- the behavioral oracle seam (not in the protocol, but how OS probes get graded) --------- #
+    def runner(self, machine_state, window: int = 60):
+        """An `Xv6Runner` over the live kernel telemetry — the runner the grader passes to
+        `objectives.evaluate(...)` for this domain's behavioral (`measure(...)`) objectives."""
+        from ..domain.xv6_runner import Xv6Runner
+        shadows = machine_state.shadows() if hasattr(machine_state, "shadows") else {}
+        return Xv6Runner(getattr(machine_state, "latest", None),
+                         getattr(machine_state, "timeline", None), shadows, window)

gini/app/__init__.py

@@ -0,0 +1,3 @@
+from .context import AppContext, EventBus, Settings
+
+__all__ = ["AppContext", "EventBus", "Settings"]