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

gini/domain/lesson.py

@@ -0,0 +1,241 @@
+"""Lesson Pack parsing + validation.
+
+A Lesson is the authored (or AI-resolved-then-ratified) unit a Mission plays. In Phase 1 a
+Lesson is read from a dict/YAML with concrete objectives; the `intent` block is carried for the
+game master to reason over (Phase 3). Validation catches authoring mistakes early — a structural
+predicate that doesn't parse, or an element type that doesn't exist — so a broken lesson never
+reaches a student.
+
+Pure data + parsing; no Qt. YAML is optional (falls back to a dict) so tests need no file I/O.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from . import catalog as _catalog
+from .objectives import Objective, check_ok, unknown_element_types
+
+_HELP = ("none", "warmer_colder", "full_tutor_logged")
+_PERSONA = ("coach", "challenger")
+_KINDS = ("structural", "behavioral")
+
+
+@dataclass
+class Intent:
+    """Teacher intent — the game master reasons over this; it is NOT a checklist.
+
+    `notes` is the teacher's free-text nuance ("stress that private doesn't mean unreachable —
+    the web tier still gets in"). It travels WITH the mission and is interpreted by the student's
+    game master at play time, so the course server never needs an LLM: the teacher writes plain
+    language, and the model that reads it is the one already running on the student's machine."""
+    concept: str = ""
+    goal: str = ""
+    spirit: str = ""
+    misconceptions: list[str] = field(default_factory=list)
+    notes: str = ""              # the teacher's nuance, reasoned over by the game master
+
+
+@dataclass
+class Forbid:
+    """A rule the student must NOT trip — a structural predicate that should stay FALSE. When it
+    becomes true (e.g. `link(database, cloud)` — the DB wired to the Internet), the offending move
+    is flagged (red badge) and the game master explains. `say` is the student-facing reason."""
+    say: str
+    check: str
+
+
+@dataclass
+class Step:
+    """One beat of a GUIDED mission: an instruction, and how the student advances past it.
+    `advance` is one of: 'reply'/'ack' (any student message — a read/reflect beat), a structural
+    predicate (drop/connect/configure — advances when the canvas satisfies it), or a behavioral
+    probe (run/observe — advances on a Run). The game master presents each beat and reasons about
+    what the student did before moving on."""
+    say: str
+    advance: str = "reply"
+    hint: str = ""
+
+    def kind(self) -> str:
+        return step_kind(self.advance)
+
+
+def step_kind(advance: str) -> str:
+    a = (advance or "reply").strip().lower()
+    if a in ("reply", "ack", "say", "read", "observe", ""):
+        return "reply"
+    from . import probes as _probes
+    if _probes.probe_ok(advance):
+        return "behavioral"
+    return "structural"
+
+
+@dataclass
+class Lesson:
+    id: str
+    title: str = ""
+    brief: str = ""
+    objectives: list[Objective] = field(default_factory=list)
+    steps: list[Step] = field(default_factory=list)   # optional GUIDED beats (empty = free-form)
+    forbid: list = field(default_factory=list)        # Forbid rules: predicates that must stay FALSE
+    complete_when: str = "all"          # all | any | at_least(n)
+    time_limit_s: int | None = None     # None = untimed
+    attempts: int = 3
+    help: str = "warmer_colder"
+    persona: str = "coach"
+    stage: str = ""                     # optional saved-canvas file to pre-build
+    intent: Intent = field(default_factory=Intent)
+    archetype: str = ""                 # the Game-Catalog archetype it was resolved from (if any)
+    params: dict = field(default_factory=dict)
+    genre: str = ""                     # experience | expedition | challenge (defaults from assembly)
+    level: int | None = None            # quest level 0..3 (defaults from assembly; may be pinned)
+    fragments: list = field(default_factory=list)   # fragment ids this lesson was assembled from
+    # optional difficulty FORKS (the golden-path model): each is
+    # {id, label, difficulty, kind, objectives: [Objective]}. Completing a fork lifts the band.
+    forks: list = field(default_factory=list)
+
+    def behavioral_ids(self) -> list[str]:
+        ids = [o.id for o in self.objectives if o.is_behavioral()]
+        for fk in self.forks:
+            ids += [o.id for o in fk.get("objectives", []) if o.is_behavioral()]
+        return ids
+
+    @property
+    def guided(self) -> bool:
+        """True when the lesson leads the student through beats turn-by-turn (vs. free-form)."""
+        return bool(self.steps)
+
+
+class LessonError(ValueError):
+    pass
+
+
+# -- time parsing ----------------------------------------------------------- #
+def parse_duration(v) -> int | None:
+    """'25m' / '90s' / '1h' / 1500 (seconds) → seconds. None/'' → untimed."""
+    if v is None or v == "":
+        return None
+    if isinstance(v, (int, float)):
+        return int(v)
+    s = str(v).strip().lower()
+    units = {"s": 1, "m": 60, "h": 3600}
+    if s and s[-1] in units:
+        try:
+            return int(float(s[:-1]) * units[s[-1]])
+        except ValueError as e:
+            raise LessonError(f"bad duration {v!r}") from e
+    try:
+        return int(s)
+    except ValueError as e:
+        raise LessonError(f"bad duration {v!r}") from e
+
+
+def _objective_from(d: dict) -> Objective:
+    if "id" not in d:
+        raise LessonError("objective missing 'id'")
+    kind = d.get("kind", "structural")
+    if kind not in _KINDS:
+        raise LessonError(f"objective {d['id']}: bad kind {kind!r}")
+    return Objective(id=d["id"], say=d.get("say", d["id"]), kind=kind,
+                     check=d.get("check", ""), probe=d.get("probe", ""), level=d.get("level"))
+
+
+def from_dict(d: dict) -> Lesson:
+    """Build a Lesson from a plain dict (already-parsed YAML)."""
+    if "id" not in d:
+        raise LessonError("lesson missing 'id'")
+    it = d.get("intent", {}) or {}
+    intent = Intent(concept=it.get("concept", ""), goal=it.get("goal", ""),
+                    spirit=it.get("spirit", ""),
+                    misconceptions=list(it.get("misconceptions", []) or []),
+                    notes=it.get("notes", "") or d.get("notes", ""))
+    objs = [_objective_from(o) for o in (d.get("objectives", []) or [])]
+    steps = [Step(say=s.get("say", ""), advance=s.get("advance", "reply"), hint=s.get("hint", ""))
+             for s in (d.get("steps", []) or [])]
+    forbid = [Forbid(say=f.get("say", ""), check=f.get("check", ""))
+              for f in (d.get("forbid", []) or [])]
+    return Lesson(
+        id=d["id"], title=d.get("title", ""), brief=d.get("brief", ""),
+        objectives=objs, steps=steps, forbid=forbid, complete_when=d.get("complete_when", "all"),
+        time_limit_s=parse_duration(d.get("time_limit")),
+        attempts=int(d.get("attempts", 3)), help=d.get("help", "warmer_colder"),
+        persona=d.get("persona", "coach"), stage=d.get("stage", ""), intent=intent,
+        archetype=d.get("archetype", ""), params=dict(d.get("params", {}) or {}),
+        genre=d.get("genre", ""), level=d.get("level"),
+        fragments=list(d.get("fragments", []) or []),
+    )
+
+
+def from_yaml(text: str) -> Lesson:
+    import yaml            # PyYAML ships with the app; imported lazily
+    return from_dict(yaml.safe_load(text))
+
+
+def from_archetype(archetype_id: str, params: dict, *, id: str, title: str = "",
+                   brief: str = "", **over) -> Lesson:
+    """Build a concrete Lesson by instantiating a Game-Catalog archetype (the shortcut the
+    resolver will use; handy for explicit authoring + tests)."""
+    arch = _catalog.get(archetype_id)
+    if arch is None:
+        raise LessonError(f"unknown archetype {archetype_id!r}")
+    missing = _catalog.unbound_refs(arch, params)
+    if missing:
+        raise LessonError(f"archetype {archetype_id!r} missing params: {missing}")
+    objs = _catalog.instantiate(arch, params)
+    intent = Intent(concept=arch.teaches, goal=arch.summary, spirit=arch.spirit,
+                    misconceptions=list(arch.misconceptions))
+    return Lesson(id=id, title=title or arch.summary, brief=brief or arch.summary,
+                  objectives=objs, complete_when=over.get("complete_when", arch.complete_when),
+                  time_limit_s=parse_duration(over.get("time_limit")),
+                  attempts=int(over.get("attempts", 3)), help=over.get("help", "warmer_colder"),
+                  persona=over.get("persona", "coach"),
+                  stage=over.get("stage") or getattr(arch, "stage", "") or "",
+                  intent=intent, archetype=archetype_id, params=dict(params))
+
+
+# -- validation ------------------------------------------------------------- #
+def validate(lesson: Lesson) -> list[str]:
+    """Return a list of problems (empty = valid). Catches bad predicates, unknown element
+    types, empty objectives, and bad enum values — the authoring safety net."""
+    problems: list[str] = []
+    if not lesson.objectives:
+        problems.append("lesson has no objectives")
+    if lesson.help not in _HELP:
+        problems.append(f"bad help level {lesson.help!r}")
+    if lesson.persona not in _PERSONA:
+        problems.append(f"bad persona {lesson.persona!r}")
+    cw = lesson.complete_when
+    if cw not in ("all", "any") and not cw.startswith("at_least("):
+        problems.append(f"bad complete_when {cw!r}")
+    if lesson.attempts < 1:
+        problems.append("attempts must be >= 1")
+    seen = set()
+    for o in lesson.objectives:
+        if o.id in seen:
+            problems.append(f"duplicate objective id {o.id!r}")
+        seen.add(o.id)
+        if o.kind == "structural":
+            if not o.check:
+                problems.append(f"structural objective {o.id!r} has no check")
+            elif not check_ok(o.check):
+                problems.append(f"objective {o.id!r}: check does not parse: {o.check!r}")
+            else:
+                bad = unknown_element_types(o.check)
+                if bad:
+                    problems.append(f"objective {o.id!r}: unknown element types {bad}")
+        elif o.kind == "behavioral" and not o.probe:
+            problems.append(f"behavioral objective {o.id!r} has no probe")
+    for i, s in enumerate(lesson.steps):
+        if not s.say:
+            problems.append(f"step {i + 1} has no instruction ('say')")
+        k = s.kind()
+        if k == "structural" and not check_ok(s.advance):
+            problems.append(f"step {i + 1}: advance predicate does not parse: {s.advance!r}")
+        elif k == "structural":
+            bad = unknown_element_types(s.advance)
+            if bad:
+                problems.append(f"step {i + 1}: unknown element types {bad}")
+    return problems
+
+
+def is_valid(lesson: Lesson) -> bool:
+    return not validate(lesson)

gini/domain/lexicon.py

@@ -0,0 +1,150 @@
+"""Lexical normalization for GINI retrieval — the dependency-free layer that closes most of
+the recall gap before we ever reach embeddings.
+
+Three cheap transforms turn a student's phrasing into the GINI vocabulary the (lexical)
+retriever indexes on:
+
+  1. tokenize   — split to lowercase word tokens, drop query-noise ("explain", "what", …);
+  2. stem       — a tiny suffix stemmer so "routing"/"routes" collapse to one form;
+  3. synonyms   — a small, HAND-OWNED map from student words / real-world product names to
+                  GINI's canonical terms (e.g. "vm" -> instance, "software defined" -> sdn).
+
+Pure data + functions, no dependencies. The synonym map is deliberately tiny and lives here
+beside the concepts it feeds; a test asserts every mapped target is a real concept keyword,
+so the map can't rot silently.
+"""
+from __future__ import annotations
+
+import re
+
+# words that carry no topic signal in a question — stripped from the QUERY side so a short
+# query like "explain SDN" reduces to its content term {sdn}.
+_QUERY_STOP = frozenset((
+    "a", "an", "the", "is", "are", "am", "of", "to", "in", "on", "for", "and", "or", "with",
+    "how", "what", "whats", "why", "when", "where", "which", "who", "do", "does", "did", "can",
+    "could", "would", "should", "i", "we", "you", "my", "me", "us", "explain", "tell", "about",
+    "show", "give", "describe", "please", "help", "want", "need", "use", "using", "work",
+    "works", "working", "it", "this", "that", "these", "those", "be", "get", "make", "set",
+    "up", "into", "from", "at", "as", "if", "so", "then", "than", "vs", "versus", "between",
+))
+
+# single-token synonyms → one or more canonical GINI terms (already in the KB's vocabulary).
+_SYNONYMS: dict[str, tuple[str, ...]] = {
+    "vm": ("instance",), "vms": ("instance",), "virtualmachine": ("instance",),
+    "lambda": ("function", "serverless"), "faas": ("function", "serverless"),
+    "serverlessfunction": ("function",),
+    "bucket": ("object", "storage"), "buckets": ("object", "storage"), "s3": ("object", "storage"),
+    "blob": ("object", "storage"),
+    "bus": ("queue", "messaging"), "broker": ("queue", "messaging"),
+    "kafka": ("stream",), "rabbitmq": ("queue",), "nats": ("messaging",),
+    "waf": ("firewall",), "iptables": ("firewall",),
+    "segmentation": ("security", "group", "isolation"),
+    "microsegmentation": ("security", "group", "isolation"),
+    "k8s": ("kubernetes",), "k3s": ("kubernetes",), "hpa": ("autoscaling", "pod"),
+    "db": ("database",), "rdbms": ("database",), "postgres": ("database",), "postgresql": ("database",),
+    "mongo": ("nosql",), "mongodb": ("nosql",), "redis": ("cache",), "memcached": ("cache",),
+    "lb": ("load", "balancer"), "nginx": ("load", "balancer"), "haproxy": ("load", "balancer"),
+    "traefik": ("proxy", "gateway"), "envoy": ("proxy",),
+    "prometheus": ("metrics",), "grafana": ("dashboard",), "jaeger": ("tracing",),
+    "microvm": ("kata", "isolation"), "hypervisor": ("kata", "isolation"),
+    "os": ("kernel", "process"), "syscall": ("system", "call"),
+    "vpn": ("gateway", "network"), "nat": ("internet", "gateway"),
+    "middlebox": ("vnf", "nfv"), "appliance": ("vnf", "nfv"),
+    "l2": ("switch", "layer"), "l3": ("router", "layer"),
+    "wifi": ("wap", "wireless"), "wlan": ("wap", "wireless"),
+}
+
+# multi-word phrases → canonical terms, matched on the raw (lowercased) query before tokenizing.
+# This is where "software defined" -> sdn lives (the exact case that exposed lexical brittleness).
+_PHRASES: dict[str, tuple[str, ...]] = {
+    "software defined": ("sdn", "openflow"),
+    "software-defined": ("sdn", "openflow"),
+    "control plane": ("sdn", "control"),
+    "data plane": ("sdn", "data"),
+    "message bus": ("queue", "messaging"),
+    "message queue": ("queue",),
+    "event log": ("stream",),
+    "object storage": ("object", "storage"),
+    "block storage": ("block", "volume"),
+    "virtual machine": ("instance", "vm"),
+    "load balancer": ("load", "balancer"),
+    "load balancing": ("load", "balancer"),
+    "reverse proxy": ("proxy",),
+    "service mesh": ("proxy", "sidecar"),
+    "security group": ("security", "group"),
+    "network function": ("vnf", "nfv"),
+    "service chain": ("sfc", "chain"),
+    "service function chain": ("sfc", "chain"),
+    "access point": ("wap", "wireless"),
+    "context switch": ("scheduler", "context"),
+    "page table": ("paging", "memory"),
+    "virtual memory": ("paging", "memory"),
+    "file system": ("filesystem", "inode"),
+    "operating system": ("kernel", "process"),
+    "system call": ("syscall", "kernel"),
+}
+
+_WORD = re.compile(r"[a-z0-9][a-z0-9+]*")
+
+
+def _stem(word: str) -> str:
+    """A deliberately tiny suffix stemmer — enough to fold common inflections without a
+    dictionary. Order matters (longest suffix first); never stem below 3 chars."""
+    w = word
+    for suf in ("ization", "isation", "ing", "ies", "ied", "ion", "ers", "er", "ed", "es", "s"):
+        if w.endswith(suf) and len(w) - len(suf) >= 3:
+            base = w[: -len(suf)]
+            if suf == "ies":
+                base += "y"
+            return base
+    return w
+
+
+def tokenize(text: str, *, drop_stop: bool = False) -> list[str]:
+    """Lowercase word tokens. With `drop_stop`, remove query-noise words (used on the QUERY
+    side; documents keep all their words)."""
+    toks = _WORD.findall((text or "").lower())
+    if drop_stop:
+        toks = [t for t in toks if t not in _QUERY_STOP]
+    return toks
+
+
+def _expand_phrases(low: str) -> list[str]:
+    extra: list[str] = []
+    for phrase, terms in _PHRASES.items():
+        if phrase in low:
+            extra.extend(terms)
+    return extra
+
+
+def normalize(text: str, *, query: bool = False) -> list[str]:
+    """Normalized, de-duplicated token list for scoring: phrase expansion + tokenization +
+    stemming + single-token synonym expansion. On the query side, noise words are dropped."""
+    low = (text or "").lower()
+    raw = tokenize(low, drop_stop=query)
+    out: list[str] = []
+    seen: set[str] = set()
+
+    def add(tok: str) -> None:
+        s = _stem(tok)
+        if s and s not in seen:
+            seen.add(s)
+            out.append(s)
+
+    for tok in _expand_phrases(low):     # multi-word phrase hits first
+        add(tok)
+    for tok in raw:
+        add(tok)
+        for syn in _SYNONYMS.get(tok, ()):    # single-token synonyms
+            add(syn)
+    return out
+
+
+def synonym_targets() -> set[str]:
+    """Every canonical term the synonym/phrase maps point at (for the sync test)."""
+    out: set[str] = set()
+    for terms in _SYNONYMS.values():
+        out.update(terms)
+    for terms in _PHRASES.values():
+        out.update(terms)
+    return out