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

gini/domain/missions/networking/least-privilege.yaml

@@ -0,0 +1,21 @@
+id: least-privilege
+layer: core
+teaches: security-groups
+spirit: a workload is protected by a default-deny security group that opens only the ports it needs —
+  least privilege by design.
+summary: Protect a workload with a security group.
+parent: security
+provides:
+- micro-segmentation
+- web-endpoint
+objectives:
+- id: has-sg
+  say: Place a security group
+  check: exists(security_group)
+- id: has-workload
+  say: Place a workload to protect
+  check: exists(web_app) or exists(database) or exists(instance)
+misconceptions:
+- Leaving a datastore open to the world instead of scoping ingress.
+peers:
+- service-chain

gini/domain/missions/networking/load-balanced-web.yaml

@@ -0,0 +1,29 @@
+id: load-balanced-web
+layer: core
+teaches: load-balancing
+spirit: incoming traffic is spread across several backend replicas via a load balancer.
+summary: Front two or more web replicas with a load balancer.
+parent: cloud/scaling
+provides:
+- load-distributor
+- public-entrypoint
+- web-endpoint
+- metrics-source
+objectives:
+- id: has-lb
+  say: Place a load balancer
+  check: exists(load_balancer)
+- id: enough-backs
+  say: Place at least two web backends
+  check: count(web_app) >= 2
+- id: fans-out
+  say: Wire the load balancer to the backends
+  check: path(load_balancer, web_app)
+- id: live-balances
+  say: 'Live: the load balancer really has 2+ live backends behind it (Run to check)'
+  kind: behavioral
+  probe: balances(load_balancer, >= 2)
+misconceptions:
+- A single backend behind the LB (nothing to balance).
+peers:
+- k8s-autoscale

gini/domain/missions/networking/observe-it.yaml

@@ -0,0 +1,24 @@
+id: observe-it
+layer: observe
+teaches: observability
+spirit: a dashboard is fed by a metrics source so the system can be watched — the dashboard must connect
+  to a metrics collector.
+summary: Wire a dashboard to a metrics source.
+parent: observability
+provides:
+- visualizer
+- dashboard-view
+- metrics-collector
+- metrics-source
+objectives:
+- id: has-metrics
+  say: Place a metrics source
+  check: exists(metrics)
+- id: has-dash
+  say: Place a dashboard
+  check: exists(dashboard)
+- id: wired
+  say: Wire the dashboard to the metrics source
+  check: path(dashboard, metrics)
+misconceptions:
+- A dashboard with no metrics source has nothing to show.

gini/domain/missions/networking/put-in-vpc.yaml

@@ -0,0 +1,30 @@
+id: put-in-vpc
+layer: core
+teaches: vpc-networking
+spirit: the workloads sit inside the VPC boundary — however the student draws the grouping.
+summary: Place a web app and a database inside a VPC.
+parent: cloud/vpc
+provides:
+- vpc-boundary
+- web-endpoint
+- relational-store
+objectives:
+- id: has-vpc
+  say: Place a VPC on the canvas
+  check: exists(vpc)
+- id: has-web
+  say: Place a web app
+  check: exists(web_app)
+- id: has-db
+  say: Place a managed database
+  check: exists(database)
+- id: web-in
+  say: The web app sits inside the VPC
+  check: contains_type(vpc, web_app)
+- id: db-in
+  say: The database sits inside the VPC
+  check: contains_type(vpc, database)
+misconceptions:
+- Leaving a workload outside the box but wired in — containment is membership.
+peers:
+- reachability-boundary

gini/domain/missions/networking/reachability-boundary.yaml

@@ -0,0 +1,56 @@
+id: reachability-boundary
+layer: core
+teaches: vpc-networking
+spirit: a database is reachable by the web tier but NOT from the Internet — by a private subnet, a security
+  group, or firewall placement; the mechanism is free.
+summary: Keep a database reachable from the web tier but hidden from the Internet.
+parent: cloud/vpc
+provides:
+- vpc-boundary
+- web-endpoint
+- relational-store
+# Objectives form a PROGRESSIVE LADDER (the engine orders them by tier automatically):
+#   L1 placement -> L2 connection -> L3 containment -> L4 live.
+# Independent tasks come first, so a beginner always has an obvious next move. Later tasks can be
+# satisfied incidentally by earlier ones (dropping the web app INSIDE the VPC ticks both L1 and L3).
+objectives:
+# --- L1: place the elements -------------------------------------------------
+- id: has-vpc
+  say: Place a VPC on the canvas
+  check: exists(vpc)
+- id: has-web
+  say: Place a web app
+  check: exists(web_app)
+- id: has-db
+  say: Place a managed database
+  check: exists(database)
+# --- L2: make the connection ------------------------------------------------
+- id: web-to-db
+  say: Connect the web app to the database
+  check: path(web_app, database)
+# --- L3: group them correctly (containment) ---------------------------------
+- id: web-in-vpc
+  say: The web app sits inside the VPC
+  check: contains_type(vpc, web_app)
+- id: db-in-vpc
+  say: The database sits inside the VPC
+  check: contains_type(vpc, database)
+- id: shielded
+  say: The database is not reachable from the Internet
+  # guard the negative with existence, or it passes VACUOUSLY on an empty board
+  check: exists(database) and not path(cloud, database)
+  level: 3          # isolation is an ADVANCED idea, even though its predicate reads as a connection
+# --- L4: prove it live (needs the running system) ----------------------------
+- id: live-reach
+  say: 'Live: the web app actually reaches the database (Run to check)'
+  kind: behavioral
+  probe: reach(web_app -> database) == ok
+- id: live-shield
+  say: 'Live: the database refuses the Internet (Run to check)'
+  kind: behavioral
+  probe: reach(cloud -> database) == fail
+misconceptions:
+- Thinking 'private' means unreachable by everything (still reachable inside).
+- Exposing the DB to the Internet to 'make it work'.
+peers:
+- put-in-vpc

gini/domain/missions/networking/sdn-reactive.yaml

@@ -0,0 +1,35 @@
+id: sdn-reactive
+layer: core
+teaches: sdn
+spirit: an OpenFlow switch has no built-in logic — it MUST be wired to a controller for traffic to flow;
+  hosts connect to the switch.
+summary: Wire an OpenVSwitch to a controller, with hosts on the switch.
+parent: sdn
+provides:
+- sdn-fabric
+- flow-control
+- service-endpoint
+objectives:
+- id: has-ovs
+  say: Place an OpenVSwitch
+  check: exists(ovs)
+- id: has-ctrl
+  say: Place a controller
+  check: exists(controller)
+- id: has-hosts
+  say: Place at least two hosts
+  check: count(host) >= 2
+- id: ovs-controlled
+  say: Wire the switch to the controller
+  check: link(ovs, controller)
+- id: hosts-on-ovs
+  say: Wire the hosts to the switch
+  check: link(host, ovs)
+- id: live-flows
+  say: 'Live: the controller actually installed flows on the switch (Run to check)'
+  kind: behavioral
+  probe: flow_installed(ovs, any)
+misconceptions:
+- Expecting an OVS to forward with no controller attached (it can't).
+peers:
+- basic-lan

gini/domain/missions/networking/send-request.yaml

@@ -0,0 +1,19 @@
+id: send-request
+layer: exercise
+teaches: request-path
+spirit: the student sends a single request through the system and follows its path end to end — proving
+  the wiring actually carries traffic.
+summary: Send a request through the system and trace its path.
+parent: traffic
+step: Add a host, send a request toward the service, and follow the path it takes.
+provides:
+- request-client
+requires:
+- traffic-sink
+objectives:
+- id: has-caller
+  say: There is a client to send a request
+  check: exists(host)
+misconceptions:
+- Assuming a drawn link works without ever sending traffic over it.
+catalog: false

gini/domain/missions/networking/serverless-api.yaml

@@ -0,0 +1,25 @@
+id: serverless-api
+layer: core
+teaches: serverless
+spirit: an API gateway fronts a function so an HTTP request to the gateway invokes it — the gateway must
+  route to the function.
+summary: Put a function behind an API gateway.
+parent: serverless
+provides:
+- serverless-fn
+- api-endpoint
+- public-entrypoint
+objectives:
+- id: has-fn
+  say: Place a function
+  check: exists(function)
+- id: has-gw
+  say: Place an API gateway
+  check: exists(api_gateway)
+- id: routed
+  say: Route the gateway to the function
+  check: path(api_gateway, function)
+misconceptions:
+- A function with no gateway — nothing can invoke it over HTTP.
+peers:
+- decouple-with-queue

gini/domain/missions/networking/service-chain.yaml

@@ -0,0 +1,33 @@
+id: service-chain
+layer: core
+teaches: sfc
+spirit: traffic passes THROUGH a network function on its way out — a firewall sits in the path between
+  the host and the Internet, by any valid wiring.
+summary: Steer a host's traffic through a firewall to the Internet.
+parent: nfv/sfc
+provides:
+- inline-nf
+- perimeter-filter
+- internet-egress
+- service-endpoint
+objectives:
+- id: has-fw
+  say: Place a firewall
+  check: exists(firewall)
+- id: has-host
+  say: Place a host
+  check: exists(host)
+- id: has-net
+  say: Place an Internet element
+  check: exists(cloud)
+- id: host-reaches-fw
+  say: The host's traffic reaches the firewall
+  check: path(host, firewall)
+- id: through-fw
+  say: Traffic to the Internet passes through the firewall (no bypass)
+  check: through(firewall, host, cloud)
+  level: 3
+misconceptions:
+- Wiring the host straight to the Internet, bypassing the function.
+peers:
+- least-privilege

gini/domain/missions/os/lottery-fix.yaml

@@ -0,0 +1,19 @@
+id: xv6-lottery-fix
+layer: core
+teaches: os-scheduling
+spirit: the shipped lottery scheduler ignores tickets (it picks uniformly at random); a correct
+  shadow makes each process's CPU share track its ticket count.
+summary: Make lottery scheduling give CPU share proportional to tickets.
+parent: os-scheduling
+objectives:
+- id: shadow-wired
+  say: Your lottery_sched shadow is running
+  kind: behavioral
+  probe: measure(shadow_active, lottery_sched) == 1
+- id: share-tracks-tickets
+  say: CPU share matches the ticket ratio
+  kind: behavioral
+  probe: measure(share_ratio, tickets) <= 0.15
+misconceptions:
+- A lottery that ignores tickets is just randomized round-robin.
+- Equal ticket counts should give equal share; unequal counts should not.

gini/domain/missions/os/priority-fix.yaml

@@ -0,0 +1,24 @@
+id: xv6-priority-fix
+layer: core
+teaches: os-scheduling
+spirit: the shipped priority scheduler starves low-priority processes (it favours the lowest pid on
+  ties and ages too weakly); a correct shadow keeps the highest-priority process served AND ages
+  waiting processes so none starves forever.
+summary: Fix the priority scheduler so high priority wins without starving anyone.
+parent: os-scheduling
+objectives:
+- id: shadow-wired
+  say: Your prio_sched shadow is running
+  kind: behavioral
+  probe: measure(shadow_active, prio_sched) == 1
+- id: high-priority-served
+  say: The highest-priority process gets its share of the CPU
+  kind: behavioral
+  probe: measure(cpu_share, highest_priority) >= 0.40
+- id: no-starvation
+  say: No runnable process is starved
+  kind: behavioral
+  probe: measure(max_wait_slices, any) <= 8
+misconceptions:
+- Strict priority with no aging starves low-priority processes forever.
+- Breaking ties by pid makes the lowest pid look higher-priority than it is.

gini/domain/missions.py

@@ -0,0 +1,111 @@
+"""Missions — the Wizard's objective layer.
+
+The Wizard is "X-ray with a goal." A student states an objective in plain words ("a
+multi-LAN IP network"); that becomes a **Mission**: the set of element types relevant to
+the goal, plus a suggested first element. The canvas then filters X-ray to on-goal
+neighbours, dims off-goal palette items, and flags off-goal drops.
+
+This module is the deterministic, offline base (keyword → relevant types). When a local
+LLM is connected the assistant refines the type set and restates the goal, but everything
+works without a model — just more coarsely.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Mission:
+    goal: str
+    types: frozenset[str]            # element type_keys that belong to this objective
+    first: str | None = None         # a good first element to drop
+
+    def allows(self, type_key: str) -> bool:
+        return type_key in self.types
+
+
+# category -> (relevant element type_keys, anchor/first element, trigger keywords)
+_CATS: tuple[tuple[str, set[str], str, tuple[str, ...]], ...] = (
+    ("net", {"router", "switch", "hub", "host", "firewall", "wap", "cloud"}, "router",
+     ("lan", "subnet", "router", "switch", "ethernet", "ip network", "ping", "route",
+      "vlan", "gateway", "multi-lan", "broadcast", "network topology", "campus")),
+    ("sdn", {"ovs", "controller", "host", "switch", "cloud"}, "controller",
+     ("sdn", "openflow", "flow table", "ovs", "openvswitch", "software-defined",
+      "software defined", "controller")),
+    ("k8s", {"k8s_cluster", "pod", "instance_group", "registry", "load_balancer",
+             "metrics", "dashboard", "load_generator"}, "k8s_cluster",
+     ("kubernetes", "k8s", "pod", "orchestrat", "deployment", "autoscal", "hpa",
+      "replica", "k3s")),
+    ("cloudnet", {"vpc", "cloud_subnet", "security_group", "gateway", "region",
+                  "instance", "web_app", "container"}, "vpc",
+     ("vpc", "security group", "isolat", "private network", "availability zone",
+      "subnet within", "tenancy")),
+    ("web", {"web_app", "instance", "container", "load_balancer", "proxy", "gateway",
+             "database", "nosql", "cache", "metrics", "dashboard", "load_generator",
+             "registry"}, "web_app",
+     ("web", "http", "microservice", "api", "backend", "frontend", "website", "web app",
+      "web service", "three-tier", "3-tier", "scal", "load balanc")),
+    ("serverless", {"function", "api_gateway", "queue", "object_store", "database"},
+     "function",
+     ("serverless", "function", "faas", "lambda", "event-driven", "pub/sub", "messaging",
+      "queue")),
+    ("data", {"database", "nosql", "cache", "object_store", "block_volume"}, "database",
+     ("database", "sql", "postgres", "mongo", "cache", "redis", "object storage",
+      "bucket", "datastore", "persist")),
+    ("obs", {"metrics", "dashboard", "tracing"}, "metrics",
+     ("monitor", "observab", "metric", "dashboard", "prometheus", "grafana", "trace",
+      "telemetry")),
+)
+
+
+def _palette_keys() -> set[str]:
+    from .devices import by_category
+    return {d.key for items in by_category().values() for d in items}
+
+
+# first-element preference when several categories match (most "anchoring" element wins)
+_ANCHOR_PRIORITY = ("k8s_cluster", "controller", "router", "vpc", "web_app", "function",
+                    "database", "metrics", "instance")
+
+
+def _hit(keyword: str, goal: str) -> bool:
+    """Match a keyword on a word boundary (a leading \\b, prefixes allowed) so 'wan' no
+    longer matches 'want' and 'route' still matches 'router'."""
+    return re.search(r"\b" + re.escape(keyword), goal) is not None
+
+
+def keyword_mission(goal: str) -> Mission:
+    """Deterministic objective → relevant element types (the offline base the LLM refines).
+    Unrecognized goals impose no constraint (every palette element is on-goal)."""
+    g = (goal or "").lower()
+    types: set[str] = set()
+    first: str | None = None
+    for _key, tset, anchor, kws in _CATS:
+        if any(_hit(kw, g) for kw in kws):
+            types |= tset
+            if first is None:
+                first = anchor
+    if not types:                                # nothing recognized -> don't constrain
+        return Mission(goal.strip(), frozenset(_palette_keys()), None)
+    return Mission(goal.strip(), frozenset(types), anchor_for(types) or first)
+
+
+def anchor_for(types) -> str | None:
+    """The best 'first element to drop' for a set of relevant types."""
+    for k in _ANCHOR_PRIORITY:
+        if k in types:
+            return k
+    return None
+
+
+def refine_types(raw: str) -> set[str]:
+    """Pull element type_keys from free LLM text (a lenient membership scan over the
+    registry's keys and labels) — used to refine a mission when a model is connected."""
+    from .devices import REGISTRY
+    low = (raw or "").lower()
+    hits: set[str] = set()
+    for key, dt in REGISTRY.items():
+        if key in low or f" {dt.label.lower()}" in f" {low}":
+            hits.add(key)
+    return hits

gini/domain/modulechain.py

@@ -0,0 +1,36 @@
+"""Parse the gRouter's LIVE inline module chain — the deployed Service Function Chain.
+
+The gRouter's data-plane pipeline is editable/inspectable over the rctl socket via `gpipe`
+(`element_query(router, "gpipe list")`). Its `list` output (gr_control.c) looks like:
+
+    base: parse -> [0:acl] -> [1:nat] -> route -> rewrite
+
+i.e. the fixed base (parse … route → rewrite) with the ordered inline NF modules in the
+middle. This module turns that into the ordered functions actually running in the router,
+so the Router Lab can show the *deployed* chain next to the *edited* one. Pure/text-only.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_MOD_RE = re.compile(r"\[(\d+):([^\]]+)\]")
+
+
+@dataclass
+class DeployedModule:
+    index: int
+    type: str          # gRouter module type: acl | nat | counter | block | lua | filter | …
+
+
+def parse_chain(text: str) -> list[DeployedModule]:
+    """The ordered inline NF modules currently deployed in the router (from `gpipe list`)."""
+    return [DeployedModule(int(i), t.strip()) for i, t in _MOD_RE.findall(text or "")]
+
+
+def chain_summary(text: str) -> str:
+    """A compact one-line view of the deployed chain, e.g. 'parse → acl → nat → route → rewrite'."""
+    mods = parse_chain(text)
+    if not mods:
+        return "parse → route → rewrite  (no service functions deployed)"
+    return "parse → " + " → ".join(m.type for m in mods) + " → route → rewrite"