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

gini/domain/capabilities.py

@@ -0,0 +1,177 @@
+"""The capability vocabulary — the typed interface that lets mission fragments COMPOSE.
+
+Every fragment declares what it `provides` and `requires` in these role names; assembly then joins
+fragments by matching one's provides to another's requires. Roles form a small **is-a hierarchy**
+(a role may have several super-roles), so a fragment can require a *broad* role (loose — many
+providers satisfy it) or a *specific* leaf (tight). `satisfies(provided, required)` is true when the
+required role is the provided role or any of its ancestors — i.e. providing a `web-endpoint`
+satisfies a requirement for a `traffic-sink`.
+
+Pure data + two small helpers; no Qt, no LLM. This is the vocabulary drafted in
+GINI_MISSIONS_COMPOSABLE_DESIGN.md §4 — prune here as we learn.
+"""
+from __future__ import annotations
+
+# role -> its super-roles (is-a). Roots map to (). Multiple parents are allowed (e.g. a web tier is
+# both a compute node and a traffic sink).
+PARENTS: dict[str, tuple[str, ...]] = {
+    # F1 · network fabric
+    # `network` is the recursion hinge: a slot that requires a `network` is satisfied by a LAN
+    # (l2-fabric) OR by another routed network (routed-network) — so routers nest to any depth.
+    "network": (),
+    "l2-fabric": ("network",),
+    "switched-segment": ("l2-fabric",),
+    "sdn-fabric": ("l2-fabric",),
+    "routed-network": ("network",),
+    "l3-gateway": (),
+    "router-gateway": ("l3-gateway", "routed-network"),   # a router exposes the routed network it fronts
+    "nat-gateway": ("l3-gateway",),
+    "network-boundary": (),
+    "vpc-boundary": ("network-boundary",),
+    "subnet-boundary": ("network-boundary",),
+    # F2 · edge / egress
+    "internet-egress": (),
+    "public-entrypoint": (),
+    # F3 · compute / workload
+    "compute-node": (),
+    "host-node": ("compute-node",),
+    "pod-workload": ("compute-node",),
+    "serverless-fn": ("compute-node",),
+    "orchestrated-compute": (),
+    "web-tier": ("compute-node", "traffic-sink"),
+    # F4 · traffic
+    "traffic-source": (),
+    "load-generator": ("traffic-source",),
+    "request-client": ("traffic-source",),
+    "traffic-sink": (),
+    "web-endpoint": ("traffic-sink",),
+    "api-endpoint": ("traffic-sink",),
+    "service-endpoint": ("traffic-sink",),
+    # F5 · steering / distribution
+    "load-distributor": (),
+    "inline-nf": (),
+    "flow-control": (),
+    # F6 · security / policy
+    "access-policy": (),
+    "perimeter-filter": ("access-policy",),
+    "micro-segmentation": ("access-policy",),
+    # F7 · data / state
+    "datastore": (),
+    "relational-store": ("datastore",),
+    "cache-tier": ("datastore",),
+    "object-store": ("datastore",),
+    "message-broker": (),
+    # F8 · observability
+    "metrics-source": (),
+    "metrics-collector": (),
+    "visualizer": (),
+    "dashboard-view": ("visualizer",),
+    "flow-inspector": ("visualizer",),
+    "packet-visualizer": ("visualizer",),
+    # F9 · fault / perturbation
+    "fault-injector": (),
+    "link-break": ("fault-injector",),
+    "misconfig": ("fault-injector",),
+    "overload": ("fault-injector",),
+    # F10 · operating systems (xv6 track) — standalone machine, no fabric
+    "kernel-host": (),
+    "workload-source": ("traffic-source",),      # a process/syscall stimulus (a "source" for the OS)
+    "kernel-observer": ("visualizer",),
+}
+
+# Which domain each role belongs to (for presentation + so the composer knows the track). ONE
+# namespace, tagged three ways — a role like compute-node is shared, which is what lets fragments
+# compose ACROSS domains (a cloud app on a network, an OS reached over a link).
+NETWORKING, CLOUD, OS, SHARED = "networking", "cloud", "os", "shared"
+DOMAIN: dict[str, str] = {
+    **{r: NETWORKING for r in (
+        "network", "routed-network",
+        "l2-fabric", "switched-segment", "sdn-fabric", "l3-gateway", "router-gateway", "nat-gateway",
+        "network-boundary", "vpc-boundary", "subnet-boundary", "internet-egress", "public-entrypoint",
+        "traffic-source", "load-generator", "request-client", "traffic-sink", "load-distributor",
+        "inline-nf", "flow-control", "access-policy", "perimeter-filter", "micro-segmentation",
+        "packet-visualizer", "flow-inspector", "fault-injector", "link-break", "misconfig", "overload")},
+    **{r: CLOUD for r in (
+        "compute-node", "host-node", "pod-workload", "serverless-fn", "orchestrated-compute",
+        "web-tier", "web-endpoint", "api-endpoint", "service-endpoint", "datastore",
+        "relational-store", "cache-tier", "object-store", "message-broker")},
+    **{r: SHARED for r in ("metrics-source", "metrics-collector", "visualizer", "dashboard-view")},
+    **{r: OS for r in ("kernel-host", "workload-source", "kernel-observer")},
+}
+
+# Device type → the capability roles it can PLAY. Multi-role is deliberate: it gives the composer
+# more ways to satisfy a requirement (a host is both a compute-node and, when it pings, a source).
+DEVICE_ROLES: dict[str, tuple[str, ...]] = {
+    # networking fabric / edge
+    "router": ("router-gateway",), "switch": ("switched-segment",), "hub": ("switched-segment",),
+    "firewall": ("perimeter-filter",), "wap": ("switched-segment",), "vnf": ("inline-nf",),
+    "cloud": ("internet-egress",), "ovs": ("sdn-fabric",), "controller": ("flow-control",),
+    # compute
+    "host": ("host-node",), "container": ("compute-node",), "instance": ("compute-node",),
+    "kinstance": ("compute-node",), "web_app": ("web-endpoint", "compute-node"),
+    "pod": ("pod-workload",), "k8s_cluster": ("orchestrated-compute",), "k8s_node": ("compute-node",),
+    "instance_group": ("orchestrated-compute",),
+    # cloud networking
+    "vpc": ("vpc-boundary",), "cloud_subnet": ("subnet-boundary",),
+    "security_group": ("micro-segmentation",), "gateway": ("nat-gateway",),
+    "load_balancer": ("load-distributor",), "proxy": ("load-distributor",),
+    # data / serverless / streaming
+    "database": ("relational-store",), "nosql": ("datastore",), "cache": ("cache-tier",),
+    "object_store": ("object-store",), "function": ("serverless-fn",),
+    "api_gateway": ("api-endpoint", "public-entrypoint"),
+    "queue": ("message-broker",), "stream": ("message-broker",), "messaging": ("message-broker",),
+    # observability (sinks)
+    "metrics": ("metrics-collector",), "dashboard": ("dashboard-view",), "tracing": ("visualizer",),
+    # sources / sinks (riders)
+    "ping_probe": ("request-client",), "http_probe": ("request-client",),
+    "dns_probe": ("request-client",), "traceroute_probe": ("request-client",),
+    "iperf_client": ("load-generator",), "load_generator": ("load-generator",),
+    "iperf_server": ("traffic-sink",), "iface_stats": ("metrics-source",),
+    "packet_view": ("packet-visualizer",),
+    # operating systems (xv6)
+    "xv6": ("kernel-host",), "terminal": ("kernel-observer",), "storage_volume": ("kernel-observer",),
+    "xv6_shell": ("workload-source",), "xv6_workload": ("workload-source",),
+}
+
+
+def roles_for(device_key: str) -> tuple[str, ...]:
+    """The capability roles a device type can play (may be several)."""
+    return DEVICE_ROLES.get(device_key, ())
+
+
+def domain_of(role: str) -> str:
+    return DOMAIN.get(role, SHARED)
+
+
+def is_role(name: str) -> bool:
+    return name in PARENTS
+
+
+def ancestors(role: str) -> set[str]:
+    """All super-roles of `role`, inclusive of itself (walks the is-a DAG)."""
+    seen: set[str] = set()
+    stack = [role]
+    while stack:
+        r = stack.pop()
+        if r in seen:
+            continue
+        seen.add(r)
+        stack.extend(PARENTS.get(r, ()))
+    return seen
+
+
+def satisfies(provided: str, required: str) -> bool:
+    """True when a fragment providing `provided` meets a requirement for `required` — i.e. the
+    required role is the provided role or one of its ancestors (a specific provider satisfies a
+    broad requirement)."""
+    return required in ancestors(provided)
+
+
+def any_satisfies(provided_roles, required: str) -> bool:
+    """True when any of `provided_roles` satisfies the single `required` role."""
+    return any(satisfies(p, required) for p in provided_roles)
+
+
+def unknown_roles(roles) -> list[str]:
+    """Roles not in the vocabulary (authoring safety net)."""
+    return sorted({r for r in roles if r not in PARENTS})

gini/domain/catalog.py

@@ -0,0 +1,85 @@
+"""The Game Catalog — an ADAPTER over the foundational fragments (now YAML packs under `missions/`).
+
+Historically this module held the archetypes as Python literals. Those foundational templates now live
+as data (YAML) and are loaded by `fragments`; this module presents the pickable/standalone fragments as
+`Archetype`s so the older call sites (lesson.from_archetype, lesson_resolver, the mission picker) keep
+working unchanged. Content moved to data; the API is stable.
+
+`ObjectiveTemplate` is re-exported from `fragments` for back-compat. Objectives use the same type-based,
+name-agnostic predicates (`exists`, `count`, `link`, `path`, `through`, `contains_type`).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from . import fragments as _frag
+from .fragments import ObjectiveTemplate  # noqa: F401  (re-export for back-compat)
+from .objectives import Objective
+
+
+@dataclass(frozen=True)
+class Archetype:
+    id: str
+    teaches: str
+    spirit: str
+    summary: str
+    params: tuple[str, ...] = ()
+    objectives: tuple[ObjectiveTemplate, ...] = ()
+    misconceptions: tuple[str, ...] = ()
+    complete_when: str = "all"
+    difficulty: dict = field(default_factory=dict)
+    stage: dict = field(default_factory=dict)
+
+
+# Type-based objectives need no name bindings, so archetypes launch with no params.
+DEMO_PARAMS: dict[str, dict] = {}
+
+
+def _arch_of(frag) -> Archetype:
+    return Archetype(id=frag.id, teaches=frag.teaches, spirit=frag.spirit, summary=frag.summary,
+                     params=(), objectives=tuple(frag.objectives),
+                     misconceptions=tuple(frag.misconceptions), complete_when=frag.complete_when,
+                     stage=dict(frag.stage))
+
+
+def get(archetype_id: str) -> Archetype | None:
+    frag = _frag.get(archetype_id)
+    return _arch_of(frag) if (frag is not None and frag.catalog) else None
+
+
+def all_archetypes() -> list[Archetype]:
+    """The standalone, pickable missions (fragments flagged `catalog`), preserving fragment order."""
+    return [_arch_of(f) for f in _frag.all_fragments() if f.catalog]
+
+
+def demo_params(archetype_id: str) -> dict:
+    return dict(DEMO_PARAMS.get(archetype_id, {}))
+
+
+# -- instantiation ---------------------------------------------------------- #
+_PLACEHOLDER = re.compile(r"\{(\w+)\}")
+
+
+def _bind(text: str, params: dict) -> str:
+    """Replace {ref} placeholders with concrete names (a no-op for type-based checks)."""
+    return _PLACEHOLDER.sub(lambda m: str(params.get(m.group(1), m.group(0))), text)
+
+
+def instantiate(archetype: Archetype, params: dict) -> list[Objective]:
+    from .objectives import by_level
+    out: list[Objective] = []
+    for t in archetype.objectives:
+        out.append(Objective(id=t.id, say=t.say, kind=t.kind,
+                             check=_bind(t.check, params) if t.check else "",
+                             probe=_bind(t.probe, params) if t.probe else "",
+                             level=t.level))
+    return by_level(out)         # progressive ladder: place → connect → group → prove live
+
+
+def unbound_refs(archetype: Archetype, params: dict) -> list[str]:
+    refs: set[str] = set()
+    for t in archetype.objectives:
+        refs.update(_PLACEHOLDER.findall(t.check))
+        refs.update(_PLACEHOLDER.findall(t.probe))
+    return sorted(r for r in refs if r not in params)

gini/domain/certify.py

@@ -0,0 +1,201 @@
+"""Fragment certification — the client-side quality gate before a block goes to the Teaching Center.
+
+Certification has two organs, matching the generate⇄verify spine:
+
+  * **the compiler (deterministic, HARD gate)** — proves ground truth: the fragment validates, and
+    (once a live runner is wired) that a reference solution grades to complete. The AI never decides
+    correctness — a hallucinated "looks fine" on a broken block would poison every mission composed
+    from it.
+  * **the AI certifier (advisory, SOFT gate)** — reviews *composability*: the issues the composer
+    will hit when it recombines this block. Its strongest form is a **dry-run of the composition
+    engine** — actually attempt to compose the fragment against the library and report what fit,
+    what's orphaned, and what it can feed. The reasoning here is deterministic today (contract
+    matching via `assembly`); an LLM advisor can layer richer judgement on top later.
+
+`certify()` returns a report of tiered issues. `blocked` (any BLOCK issue) means "not certified".
+WARN issues are soft — the teacher may upload over them, but they travel with the fragment so the
+composer knows the risk.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from . import capabilities as _caps
+from . import fragment_yaml as _fy
+from . import fragments as _frag
+
+BLOCK, WARN, INFO = "block", "warn", "info"
+
+
+@dataclass
+class Issue:
+    level: str          # BLOCK | WARN | INFO
+    code: str
+    message: str
+
+
+@dataclass
+class CertReport:
+    fragment_id: str
+    issues: list[Issue] = field(default_factory=list)
+    composes_into: list[str] = field(default_factory=list)   # fragments this one can feed (forward)
+    unmet_requires: list[str] = field(default_factory=list)   # requires nothing in the library gives
+
+    def add(self, level: str, code: str, message: str) -> None:
+        self.issues.append(Issue(level, code, message))
+
+    @property
+    def blocked(self) -> bool:
+        return any(i.level == BLOCK for i in self.issues)
+
+    @property
+    def certified(self) -> bool:
+        return not self.blocked
+
+    def of(self, level: str) -> list[Issue]:
+        return [i for i in self.issues if i.level == level]
+
+
+@dataclass
+class RuntimeGrade:
+    """The outcome of grading the fragment's AUTHORING BOARD (the reference solution) on a live
+    stack. The caller runs `objectives.evaluate_all` with the fragment's sources auto-started, then
+    hands the summary here. `available=False` means the stack wasn't running, so nothing was proven.
+    """
+    available: bool = False
+    unmet: list = field(default_factory=list)     # objective ids that graded UNMET (a real failure)
+    pending: list = field(default_factory=list)   # behavioral ids the runner couldn't witness
+
+    @property
+    def all_met(self) -> bool:
+        return self.available and not self.unmet and not self.pending
+
+
+_COUNT_RE = re.compile(r"^\s*count\(\s*(\w+)\s*\)\s*>=\s*(\d+)")
+_PROBE_ENDS_RE = re.compile(r"(?:reach|ping|http)\(\s*(\w+)\s*->\s*(\w+)")
+_MEASURE_RE = re.compile(r"measure\(\s*(\w+)\s*,")
+
+
+def _multi_types(objectives) -> set[str]:
+    """Types the fragment asks for MORE THAN ONE of — the ones a type-based probe can be ambiguous
+    about in a merged board."""
+    out = set()
+    for o in objectives:
+        m = _COUNT_RE.match(o.get("check") or "")
+        if m and int(m.group(2)) >= 2:
+            out.add(m.group(1))
+    return out
+
+
+def _probe_types(objectives) -> set[str]:
+    out = set()
+    for o in objectives:
+        p = o.get("probe") or ""
+        m = _PROBE_ENDS_RE.search(p)
+        if m:
+            out.update((m.group(1), m.group(2)))
+        m = _MEASURE_RE.search(p)
+        if m:
+            out.add(m.group(1))
+    return out
+
+
+def _dry_run_compose(frag, rep: CertReport, library) -> None:
+    """A deterministic dry-run of the composition engine: can the fragment's requirements be met by
+    the library (backward), and what can consume what it provides (forward)? This is exactly the
+    contract-matching the assembler does when it chains fragments."""
+    lib = library if library is not None else _frag.all_fragments()
+    others = [f for f in lib if f.id != frag.id]
+
+    for req in frag.requires:                        # backward: who can satisfy what I need?
+        if any(_caps.any_satisfies(f.provides, req) for f in others):
+            continue
+        rep.unmet_requires.append(req)
+        rep.add(WARN, "orphan-requires",
+                f"Nothing in the library provides '{req}', so I can only ever use this block to "
+                f"START a chain, never in the middle.")
+
+    for f in others:                                 # forward: who can consume what I provide?
+        if any(_caps.any_satisfies(frag.provides, r) for r in f.requires):
+            rep.composes_into.append(f.id)
+    if frag.provides and rep.composes_into:
+        rep.add(INFO, "composes-into",
+                f"Composes into: {', '.join(sorted(set(rep.composes_into)))}.")
+
+
+def certify(frag_dict: dict, *, library=None, runtime: "RuntimeGrade | None" = None) -> CertReport:
+    """Certify an authored fragment dict. `runtime` is the result of grading the fragment's authoring
+    board on a live stack (None = not graded). A fragment with live/output checks is only certified
+    once that grade is clean — the HARD compiler gate; pure-structural fragments need no runtime."""
+    rep = CertReport(fragment_id=frag_dict.get("id", ""))
+
+    # -- compiler: gradable (BLOCK) ---------------------------------------- #
+    problems = _fy.validate(_fy.fragment_from_dict(frag_dict))
+    for p in problems:
+        rep.add(BLOCK, "invalid", p)
+    if rep.blocked:
+        return rep                                   # a broken block: don't reason further
+
+    frag = _fy.fragment_from_dict(frag_dict)
+    objectives = frag_dict.get("objectives", [])
+    has_output = any((o.get("probe") or "").startswith("measure(") for o in objectives)
+    has_live = any((o.get("probe") or "").startswith(("reach", "ping", "http")) for o in objectives)
+    has_behavioral = has_output or has_live
+
+    # -- compiler: winnable / runtime-sound (HARD gate) -------------------- #
+    # The authoring board IS the reference solution: grade it live and it must pass. Behavioral /
+    # output checks need a running stack (with the Sources driving traffic); pure-structural doesn't.
+    if not has_behavioral:
+        rep.add(INFO, "structural-only",
+                "Structural fragment — no live checks, so no runtime playtest is needed.")
+    elif runtime is None or not runtime.available:
+        rep.add(BLOCK, "runtime-required",
+                "Run the topology and Certify to prove the live/output checks — required before "
+                "upload (its Sources drive traffic while the board is graded).")
+    elif runtime.unmet:
+        rep.add(BLOCK, "not-winnable",
+                f"The reference board doesn't satisfy: {', '.join(runtime.unmet)} — is it winnable?")
+    elif runtime.pending:
+        rep.add(BLOCK, "runtime-incomplete",
+                f"Couldn't witness: {', '.join(runtime.pending)} — is the whole stack running?")
+    else:
+        rep.add(INFO, "runtime-ok",
+                "Playtested live: the reference solution grades to complete.")
+
+    # -- AI certifier: composability review (WARN, soft gate) -------------- #
+    if not (frag_dict.get("spirit") or "").strip():
+        rep.add(WARN, "no-spirit",
+                "No spirit/intent — the composer can't generate variants or negotiate level without "
+                "a sentence on what success means.")
+    if not has_output and not has_live:
+        rep.add(WARN, "no-output",
+                "No live/output check — this grades only the picture, not that the system works. "
+                "Attach a Sink and add an output check.")
+    if not frag.forks:
+        rep.add(WARN, "no-difficulty",
+                "No difficulty knob — the composer can't offer an easier/harder variant. Add input "
+                "presets or a fork.")
+    multi, probed = _multi_types(objectives), _probe_types(objectives)
+    for tk in sorted(multi & probed):
+        # not actually ambiguous — type-based grading reads this as "SOME <tk>" by default (add
+        # ', all' if you mean EVERY one). Just a hint so the author picks the intended quantifier.
+        rep.add(INFO, "quantifier",
+                f"You have ≥2 '{tk}' and a check on '{tk}' — it grades as \"some {tk}\"; add ', all' "
+                f"to the probe if you mean every one.")
+    if len(objectives) > 8:
+        rep.add(WARN, "too-big",
+                f"{len(objectives)} objectives — big blocks recombine poorly; consider splitting "
+                f"into single-idea fragments.")
+
+    # -- AI certifier: dry-run the composition engine (WARN/INFO) ---------- #
+    _dry_run_compose(frag, rep, library)
+    return rep
+
+
+def runtime_from_results(results, *, available: bool = True) -> RuntimeGrade:
+    """Summarise an `objectives.evaluate_all` result list into a RuntimeGrade for `certify()`."""
+    from . import objectives as _obj
+    unmet = [r.id for r in results if r.status == _obj.UNMET]
+    pending = [r.id for r in results if r.status == _obj.PENDING]
+    return RuntimeGrade(available=available, unmet=unmet, pending=pending)