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

gini/domain/games/thrash_game.py

@@ -0,0 +1,75 @@
+"""Thrashing diagnosis game — riding on the page-replacement simulator.
+
+Each case is a real LRU run over a generated reference string; the student reads the run's signature
+(fault rate, frames vs working set, locality, working-set growth) and names WHY it is faulting:
+
+  healthy              — low fault rate; frames cover the working set
+  too few frames       — good locality, stable working set, but frames < working set (more RAM helps)
+  working set too big  — the distinct-page set grows past the frames (a phase change)
+  poor locality        — random access; more frames barely helps until they cover the whole set
+
+Ground truth is the generator's label (deterministic). classify_thrash() is the practice-mode hint.
+Simulator-backed, so this game is offline (a live xv6 mechanism would add real cases later).
+"""
+from __future__ import annotations
+
+import random
+
+from ..diagnose import Case, GameSpec
+from ..paging_sim import run_features
+
+THRASH_CLASSES = ["healthy", "too few frames", "working set too big", "poor locality"]
+THRASH_ABBR = {"healthy": "ok", "too few frames": "frames",
+               "working set too big": "ws-big", "poor locality": "local"}
+THRASH_SPEC = GameSpec("thrash-diagnose", "Diagnose the thrashing",
+                       "Why is this workload faulting?", THRASH_CLASSES, THRASH_ABBR)
+
+
+def _loop(pages, reps) -> list:
+    return [p for _ in range(reps) for p in range(pages)]
+
+
+def gen_healthy(rng) -> tuple:
+    return _loop(3, 12), 4                       # 3-page loop, 4 frames -> ~no faults after warmup
+
+
+def gen_too_few(rng) -> tuple:
+    return _loop(8, 8), 3                        # 8-page loop, 3 frames -> ~100% fault, good locality
+
+
+def gen_ws_big(rng) -> tuple:
+    refs = _loop(4, 4) + _loop(10, 3) + _loop(20, 3)     # growing distinct set (phase changes)
+    return refs, 4
+
+
+def gen_poor_local(rng) -> tuple:
+    return [rng.randrange(40) for _ in range(140)], 5     # random over 40 pages -> weak locality
+
+
+_GENERATORS = [("healthy", gen_healthy), ("too few frames", gen_too_few),
+               ("working set too big", gen_ws_big), ("poor locality", gen_poor_local)]
+
+
+def classify_thrash(f: dict, thresholds: dict | None = None) -> str:
+    """Heuristic used for the hint. Low faults -> healthy; else the distinguishing signal wins:
+    a growing distinct set -> working set too big; poor locality -> poor locality; otherwise the
+    frames are simply too few."""
+    th = {"fault": 0.25, "growth": 0.5, "local": 0.4}
+    th.update(thresholds or {})
+    if f["fault_rate"] < th["fault"]:
+        return "healthy"
+    if f["ws_growth"] >= th["growth"]:
+        return "working set too big"
+    if f["locality"] < th["local"]:
+        return "poor locality"
+    return "too few frames"
+
+
+def demo_cases(seed: int = 0) -> list:
+    rng = random.Random(seed)
+    out = []
+    for name, gen in _GENERATORS:
+        refs, frames = gen(rng)
+        f = run_features(refs, frames)
+        out.append(Case(f"thr-{name}", f, name, subtitle=name, hint=classify_thrash(f)))
+    return out

gini/domain/games/translate_game.py

@@ -0,0 +1,60 @@
+"""Address-translation game — the one that makes live page tables playable.
+
+Given a page table (leaf VA→PA mappings) and a target virtual address, the student computes the
+physical address: PA = (PA base of the page holding VA) + (VA − VA base). Exact answer (tolerance 0),
+graded against the real mapping. Live cases come straight from the kernel's `vmprint` leaves; the
+demo deck synthesizes small tables.
+"""
+from __future__ import annotations
+
+import random
+
+from ..diagnose import Case, GameSpec
+
+PGSIZE = 4096
+
+TRANSLATE_SPEC = GameSpec(
+    "addr-translate", "Translate the address",
+    "Compute the physical address (PA) for the target VA — enter hex (0x…) or decimal.",
+    classes=[], answer="estimate", tolerance=0, unit="PA",
+)
+
+
+def _case(rows, va, cid) -> Case | None:
+    """rows = [(va_base, pa_base, perms)]; find the page holding `va` and compute its PA."""
+    for vb, pb, _perm in rows:
+        if vb <= va < vb + PGSIZE:
+            pa = pb + (va - vb)
+            return Case(cid, {"rows": rows, "va": va}, pa, subtitle=hex(pa),
+                        hint=f"page base VA {hex(vb)} → PA {hex(pb)}, offset {hex(va - vb)}")
+    return None
+
+
+def demo_cases(seed: int = 0) -> list:
+    rng = random.Random(seed)
+    out = []
+    for k in range(5):
+        vpns = sorted(rng.sample(range(0, 12), 4))
+        rows = [(v * PGSIZE, rng.randrange(0x80, 0x140) * PGSIZE,
+                 rng.choice(["r-x u", "rw- u", "r-- u"])) for v in vpns]
+        vb, _pb, _ = rng.choice(rows)
+        c = _case(rows, vb + rng.randrange(0, PGSIZE), f"tr-{k}")
+        if c is not None:
+            out.append(c)
+    return out
+
+
+def live_cases(leaves, seed: int = 0, window: int = 6) -> list:
+    """Cases from real vmprint leaves ([Pte with .va/.pa/.perms]). Each targets a mapped page and
+    shows a small window of the table around it."""
+    rows = [(p.va, p.pa, getattr(p, "perms", "----")) for p in (leaves or [])]
+    if not rows:
+        return []
+    rng = random.Random(seed)
+    out = []
+    for i, (vb, pb, _perm) in enumerate(rows[:5]):
+        lo = max(0, i - window // 2)
+        c = _case(rows[lo:lo + window], vb + rng.randrange(0, PGSIZE), f"trl-{i}")
+        if c is not None:
+            out.append(c)
+    return out

gini/domain/games/trap_game.py

@@ -0,0 +1,86 @@
+"""Case sources for two "decode the cause CSR" games — both grade against a deterministic scause
+decode (the RISC-V privileged encoding), so ground truth is exact.
+
+  trap-cause  — any trap's scause -> timer / external / software int, syscall, page fault, illegal.
+  fault-type  — a page fault's scause -> instruction / load / store access.
+
+The signature is the raw scause (+ stval/epc as context); the skill is knowing the encoding. Live
+cases come from the trap-taxonomy ring; the demo deck synthesizes one of each.
+"""
+from __future__ import annotations
+
+from ..diagnose import Case, GameSpec
+
+# ---- trap-cause game ------------------------------------------------------ #
+TRAP_CLASSES = ["timer int", "external int", "software int", "syscall", "page fault", "illegal"]
+TRAP_ABBR = {"timer int": "timer", "external int": "extern", "software int": "soft",
+             "syscall": "ecall", "page fault": "fault", "illegal": "illegal"}
+TRAP_SPEC = GameSpec("trap-cause", "Decode the trap", "What kind of trap is this scause?",
+                     TRAP_CLASSES, TRAP_ABBR)
+
+_INT = {1: "software int", 5: "timer int", 9: "external int"}
+_EXC = {8: "syscall", 12: "page fault", 13: "page fault", 15: "page fault", 2: "illegal"}
+
+
+def trap_class(scause: int) -> str:
+    code = scause & 0xFF
+    if scause >> 63:                       # top bit set -> interrupt
+        return _INT.get(code, "external int")
+    return _EXC.get(code, "illegal")
+
+
+# ---- fault-type game ------------------------------------------------------ #
+FAULT_CLASSES = ["instruction", "load", "store"]
+FAULT_ABBR = {"instruction": "insn", "load": "load", "store": "store"}
+FAULT_SPEC = GameSpec("fault-type", "Decode the page fault", "Which access caused this page fault?",
+                      FAULT_CLASSES, FAULT_ABBR)
+
+_FAULT = {12: "instruction", 13: "load", 15: "store"}
+
+
+def fault_class(scause: int) -> str | None:
+    return _FAULT.get(scause & 0xFF)
+
+
+def _event(scause: int, stval: str = "0x0", epc: str = "0x0"):
+    return [("scause", hex(scause)), ("stval", stval), ("epc", epc)]
+
+
+# demo scause values, one per class
+_TRAP_DEMO = [(0x8000000000000005, "timer int"), (0x8000000000000009, "external int"),
+              (0x8000000000000001, "software int"), (0x8, "syscall"),
+              (0xD, "page fault"), (0x2, "illegal")]
+_FAULT_DEMO = [(0xC, "instruction"), (0xD, "load"), (0xF, "store")]
+
+
+def trap_demo_cases() -> list:
+    return [Case(f"trap-{i}", _event(sc, epc="0x1a2c"), truth, subtitle=truth)
+            for i, (sc, truth) in enumerate(_TRAP_DEMO)]
+
+
+def fault_demo_cases() -> list:
+    vas = ["0x1330", "0x2f00", "0x3ff8"]
+    return [Case(f"flt-{i}", _event(sc, stval=vas[i % 3], epc="0x1a2c"), truth, subtitle=truth)
+            for i, (sc, truth) in enumerate(_FAULT_DEMO)]
+
+
+def _live(trap_events, labeler) -> list:
+    """Build cases from trap-ring TrapEvents (pid, kind, cause, epc, tval) whose scause labels."""
+    out = []
+    for e in trap_events or []:
+        try:
+            sc = int(e.cause, 16)
+        except (TypeError, ValueError):
+            continue
+        truth = labeler(sc)
+        if truth:
+            out.append(Case(f"live-{e.epc}-{sc}", _event(sc, e.tval, e.epc), truth, subtitle=truth))
+    return out
+
+
+def trap_live_cases(trap_events) -> list:
+    return _live(trap_events, trap_class)
+
+
+def fault_live_cases(trap_events) -> list:
+    return _live(trap_events, fault_class)

gini/domain/grader.py

@@ -0,0 +1,155 @@
+"""Server-side re-grade + gradebook — the buildable slice of the hybrid grading authority.
+
+The client grades a Mission instantly for feedback and submits the canvas **snapshot** + its
+reported objective results. To make the OFFICIAL result trustworthy, the Teaching Center re-grades
+deterministically:
+
+  • STRUCTURAL objectives — re-evaluated server-side from the submitted snapshot (pure graph
+    predicates, NO Docker). This is fully authoritative and catches tampering: if the client
+    claimed a structural objective met but the snapshot doesn't satisfy it, the server wins.
+  • BEHAVIORAL objectives — re-running them needs GINI's runtime (Docker); until that grader tier
+    exists (Phase 6.x, Mac/server-side), the server *trusts* the client's reported behavioral
+    results. So this module makes structural grading authoritative and leaves behavioral as a
+    documented trust boundary.
+
+Plus a `Gradebook` that aggregates submissions into the teacher's roster×lesson view. Pure Python;
+no Qt, no Docker, no network — fully unit-testable.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from types import SimpleNamespace
+
+from . import objectives as _obj
+from . import scoring as _scoring
+from .profile import band_rank, better_band
+
+
+# -- snapshot → world (no live Topology needed) ----------------------------- #
+def snapshot_of(topology) -> dict:
+    """Serialize the live topology to a portable snapshot (what a submission carries)."""
+    return topology.to_dict()
+
+
+def world_from_snapshot(snapshot) -> _obj.TopologyWorld:
+    """Build the objective World from a serialized snapshot (dict or JSON string), so structural
+    predicates can be re-evaluated server-side without reconstructing the full Topology model."""
+    if isinstance(snapshot, str):
+        snapshot = json.loads(snapshot)
+    devices = {}
+    for d in snapshot.get("devices", []):
+        devices[d["id"]] = SimpleNamespace(
+            id=d["id"], name=d.get("name", ""), type_key=d.get("type_key", ""),
+            parent_id=d.get("parent_id"), properties=d.get("properties", {}) or {})
+    links = {}
+    for i, l in enumerate(snapshot.get("links", [])):
+        lid = l.get("id", f"l{i}")
+        links[lid] = SimpleNamespace(source_id=l["source_id"], target_id=l["target_id"])
+    return _obj.TopologyWorld(SimpleNamespace(devices=devices, links=links))
+
+
+# -- re-grade --------------------------------------------------------------- #
+def regrade_structural(lesson, snapshot) -> list:
+    """Re-evaluate the lesson's STRUCTURAL objectives from the snapshot (behavioral → pending)."""
+    return _obj.evaluate_all(lesson.objectives, world_from_snapshot(snapshot), runner=None)
+
+
+@dataclass
+class OfficialResult:
+    band: str
+    server_results: list                 # per-objective (structural authoritative, behavioral from client)
+    regraded_down: bool                  # official band < the band the client claimed
+    note: str = ""
+
+
+def official_result(lesson, submission) -> OfficialResult:
+    """Compute the official result from a submission {snapshot, objective_results, time_taken, band}.
+
+    Structural objectives come from the server re-grade (authoritative); behavioral objectives are
+    trusted from the client's reported results (until the Docker re-grader lands)."""
+    client = dict(submission.get("objective_results", []))     # id -> status
+    server_struct = {r.id: r for r in regrade_structural(lesson, submission.get("snapshot", {}))}
+
+    merged = []
+    for o in lesson.objectives:
+        if o.kind == "behavioral":
+            status = client.get(o.id, _obj.PENDING)            # trust the client for behavioral
+            merged.append(_obj.ObjectiveResult(o.id, o.say, o.kind, status))
+        else:
+            merged.append(server_struct.get(
+                o.id, _obj.ObjectiveResult(o.id, o.say, o.kind, _obj.UNMET)))
+
+    limit = lesson.time_limit_s
+    on_time = limit is None or float(submission.get("time_taken", 0)) <= limit
+    sc = _scoring.score(merged, complete_when=lesson.complete_when, on_time=on_time)
+
+    claimed = submission.get("band", "")
+    down = band_rank(sc.band) < band_rank(claimed)
+    note = ("official band is lower than the client claimed — structural re-grade disagreed"
+            if down else "")
+    return OfficialResult(band=sc.band, server_results=merged, regraded_down=down, note=note)
+
+
+# -- gradebook -------------------------------------------------------------- #
+@dataclass
+class Gradebook:
+    # student -> lesson_id -> best band
+    rows: dict
+
+    def band(self, student: str, lesson_id: str) -> str:
+        return self.rows.get(student, {}).get(lesson_id, "")
+
+    def students(self) -> list:
+        return sorted(self.rows)
+
+    def lessons(self) -> list:
+        out = set()
+        for lessons in self.rows.values():
+            out.update(lessons)
+        return sorted(out)
+
+    def completed_count(self, student: str) -> int:
+        return sum(1 for b in self.rows.get(student, {}).values()
+                   if band_rank(b) >= band_rank("pass"))
+
+
+def gradebook(submissions) -> Gradebook:
+    """Aggregate raw submissions into a roster×lesson best-band table (the teacher face)."""
+    rows: dict[str, dict[str, str]] = {}
+    for s in submissions:
+        student = s.get("student", "")
+        lesson_id = s.get("lesson_id", "")
+        if not student or not lesson_id:
+            continue
+        cur = rows.setdefault(student, {}).get(lesson_id, "")
+        rows[student][lesson_id] = better_band(cur, s.get("band", ""))
+    return Gradebook(rows=rows)
+
+
+def official_from_composition(spec, submission) -> OfficialResult:
+    """Re-grade a submission against a COMPOSITION (assemble the referenced fragments locally, then
+    apply the structural authority). The Center's server side of the M4/M6 bridge."""
+    from . import composition as _comp
+    lesson = _comp.from_composition(spec)
+    return official_result(lesson, submission)
+
+
+def gradebook_official(submissions, resolve_lesson) -> Gradebook:
+    """The authoritative gradebook: each submission is SERVER re-graded (structural authority) before
+    aggregation, so a tampered client band is downgraded. `resolve_lesson(lesson_id) -> Lesson`
+    (return None to fall back to the client-claimed band, e.g. an unknown lesson)."""
+    rows: dict[str, dict[str, str]] = {}
+    for s in submissions:
+        student = s.get("student", "")
+        lesson_id = s.get("lesson_id", "")
+        if not student or not lesson_id:
+            continue
+        les = resolve_lesson(lesson_id)
+        try:
+            band = official_result(les, s).band if les is not None else s.get("band", "")
+        except Exception:
+            band = s.get("band", "")
+        cur = rows.setdefault(student, {}).get(lesson_id, "")
+        rows[student][lesson_id] = better_band(cur, band)
+    return Gradebook(rows=rows)

gini/domain/grouping.py

@@ -0,0 +1,67 @@
+"""Spatial containment for canvas grouping boxes (VPC / Subnet / Region).
+
+Membership is decided by geometry: an element belongs to the *innermost* box whose
+rectangle contains the element's centre, mirroring how you'd read a cloud diagram —
+a database drawn inside a Subnet drawn inside a VPC belongs to that Subnet (and through
+it, that VPC). This module is pure (no Qt) so the rule is unit-testable; the canvas feeds
+it scene rectangles and applies the resulting parent_id assignments.
+"""
+from __future__ import annotations
+
+# The element types drawn as grouping boxes (not every is_container type — k8s_cluster and
+# Pod are containers too but are real nodes that take part in the grammar / X-ray).
+BOX_TYPES = ("vpc", "cloud_subnet", "region")
+
+# A box on the canvas: (id, x, y, w, h) in scene coordinates.
+Box = tuple[str, float, float, float, float]
+
+
+def _contains(box: Box, cx: float, cy: float) -> bool:
+    _id, x, y, w, h = box
+    return x <= cx <= x + w and y <= cy <= y + h
+
+
+def _area(box: Box) -> float:
+    return box[3] * box[4]
+
+
+def innermost_box(cx: float, cy: float, boxes, exclude=(), min_area: float = 0.0) -> str | None:
+    """The id of the smallest-area box containing (cx, cy), or None. `exclude` lists ids
+    to ignore (never self, nor a descendant). `min_area` filters to boxes strictly larger
+    than this — so a container only nests inside a *bigger* container, never a smaller box
+    it happens to overlap (a VPC is never captured by a Subnet drawn over its centre)."""
+    hits = [b for b in boxes
+            if b[0] not in exclude and _area(b) > min_area and _contains(b, cx, cy)]
+    if not hits:
+        return None
+    return min(hits, key=_area)[0]
+
+
+def _descendants(box_id: str, parent_of: dict) -> set:
+    """Every id whose parent chain currently passes through box_id (so an inner box can't
+    accidentally 'capture' its own ancestor when boxes overlap)."""
+    kids = {box_id}
+    while True:
+        nxt = {i for i, p in parent_of.items() if p in kids and i not in kids}
+        if not nxt:
+            return kids - {box_id}
+        kids |= nxt
+
+
+def recompute(centers: dict, boxes, parent_of: dict) -> dict:
+    """Compute fresh parent_id for every placeable item.
+
+    centers   : {id: (cx, cy)} for every node AND box on the canvas.
+    boxes     : iterable of Box (the grouping rectangles).
+    parent_of : current {id: parent_id|None}, used only to skip self/descendants.
+
+    Returns {id: new_parent_id_or_None}.
+    """
+    boxes = list(boxes)
+    area_of = {b[0]: _area(b) for b in boxes}      # a box's own area (0 for plain nodes)
+    out: dict = {}
+    for iid, (cx, cy) in centers.items():
+        exclude = {iid} | _descendants(iid, parent_of)
+        out[iid] = innermost_box(cx, cy, boxes, exclude=exclude,
+                                 min_area=area_of.get(iid, 0.0))
+    return out

gini/domain/legality.py

@@ -0,0 +1,103 @@
+"""Move legality & relevance for Missions — the deterministic layer behind the red "that's wrong"
+flag. Fast (no model), so the flag is INSTANT and reliable; the game master supplies the spoken
+reasoning separately (async).
+
+Three kinds of flag, all non-destructive (nothing is ever deleted — the flag clears when the
+student fixes it):
+
+  • off-task element — a placed element whose TYPE is outside the mission's relevant family. The
+    family is generous (the taught concept's elements + the types the objectives mention + all
+    their grammar-legal neighbours), so a SUPERSET of the requirement is welcome — more hosts,
+    switches, routers are fine on a LAN mission. Only genuinely off-domain drops (a K8s cluster in
+    a switching lesson) fall out here. That superset-vs-off-domain distinction is the reasoning.
+  • illegal link — a connection the grammar says can't exist.
+  • forbid violation — a lesson `forbid:` rule (a predicate that must stay false) that got tripped
+    (e.g. `link(database, cloud)` — the DB wired to the Internet).
+
+Pure logic; evaluated against the live topology / an objectives World.
+"""
+from __future__ import annotations
+
+from . import concepts as _concepts
+from . import connection_rules as _cr
+from .objectives import PredicateError, element_types_in_check, evaluate_check
+
+# grouping boxes are scaffolding, never "off-task"
+_CONTAINERS = {"vpc", "cloud_subnet", "region"}
+
+
+def relevant_types(lesson) -> set[str]:
+    """The element types that belong in this mission (generous — supersets welcome)."""
+    types: set[str] = set(_CONTAINERS)
+    concept = getattr(getattr(lesson, "intent", None), "concept", "") or ""
+    c = _concepts.by_key(concept)
+    if c is not None:
+        types.update(c.elements)
+    for o in getattr(lesson, "objectives", []):
+        if getattr(o, "check", ""):
+            types.update(element_types_in_check(o.check))
+    for f in getattr(lesson, "forbid", []):
+        chk = getattr(f, "check", "") or ""
+        if chk:
+            types.update(element_types_in_check(chk))
+    # a legit grammar-neighbour of an in-family element is in-domain too (e.g. an Internet for a
+    # router-based lesson) — this is what makes the family reason about the domain, not a fixed list
+    for tk in list(types):
+        types.update(_cr.partner_types(tk))
+    return types
+
+
+def off_task_devices(lesson, topology) -> list[str]:
+    """Device ids whose type is outside the relevant family (candidate off-task flags)."""
+    fam = relevant_types(lesson)
+    return [d.id for d in topology.devices.values()
+            if getattr(d, "type_key", "") and d.type_key not in fam]
+
+
+def illegal_links(topology) -> list[str]:
+    """Link ids whose endpoints the connection grammar says shouldn't connect."""
+    out: list[str] = []
+    for l in topology.links.values():
+        s = topology.devices.get(l.source_id)
+        t = topology.devices.get(l.target_id)
+        if s is None or t is None:
+            continue
+        if t.type_key not in _cr.partner_types(s.type_key):
+            out.append(l.id)
+    return out
+
+
+def forbid_violations(lesson, world) -> list:
+    """Forbid rules currently TRUE — a rule that must stay false was tripped."""
+    out = []
+    for f in getattr(lesson, "forbid", []):
+        chk = getattr(f, "check", "") or ""
+        try:
+            if chk and evaluate_check(chk, world):
+                out.append(f)
+        except PredicateError:
+            pass
+    return out
+
+
+def flags(lesson, topology, world=None) -> dict:
+    """The full flag set for the current board: {device_id -> reason} for off-task devices +
+    forbid-violation endpoints, plus illegal link ids. Drives the red badge/glow; recomputed on
+    every canvas change (cheap, deterministic)."""
+    from .objectives import TopologyWorld
+    world = world or TopologyWorld(topology)
+    dev_flags: dict[str, str] = {}
+    for did in off_task_devices(lesson, topology):
+        d = topology.devices.get(did)
+        label = getattr(d, "type", None)
+        name = getattr(label, "label", None) or getattr(d, "type_key", "element")
+        dev_flags[did] = f"A {name} isn't part of this mission — remove it or you're off-task."
+    bad_links = illegal_links(topology)
+    for lid in bad_links:                        # flag both endpoints of a bad connection
+        l = topology.links.get(lid)
+        if l is None:
+            continue
+        for did in (l.source_id, l.target_id):
+            dev_flags.setdefault(did, "This connection isn't allowed here — rewire it.")
+    forbids = forbid_violations(lesson, world)
+    return {"devices": dev_flags, "links": bad_links, "forbid": forbids}