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

gini/agent/ask.py

@@ -0,0 +1,123 @@
+"""Ask GINI orchestration (pure) — turn an Intent + retrieved knowledge into a Plan, and
+assemble the grounded context for the reasoning call.
+
+This is the routing matrix from the design, kept Qt-free so it's testable. The assistant
+(Qt side) calls `plan()` to decide what to do and `grounded_context()` to build the block
+the reasoning LLM sees; the actual building (apply_recipe), tool execution, and chat posting
+happen in the assistant.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Plan:
+    action: str                 # reason | build_recipe | execute | diagnose | clarify | chitchat | meta
+    recipe_id: str = ""         # for build_recipe, or the recipe to offer on a reason
+    offer_build: bool = False   # reason path: end by offering to build recipe_id
+    clarify: str = ""           # for clarify
+
+
+_CLARIFY = ("Could you say a bit more? For example, name an element you want explained, "
+            "or tell me what you'd like to build.")
+
+
+def plan(intent, retrieval, *, min_confidence: float = 0.45) -> Plan:
+    """Dispatch by (type x output_form x anchor). See the design's routing matrix."""
+    it = intent
+    recipe = getattr(retrieval, "recipe", None)
+    rid = recipe.id if recipe is not None else ""
+
+    if it.type == "chitchat":
+        return Plan("chitchat")
+    if it.type == "meta":
+        return Plan("meta")
+
+    # genuinely ambiguous fragment -> ask one question rather than guess
+    if it.confidence < min_confidence and not it.topics and not it.refs:
+        return Plan("clarify", clarify=_CLARIFY)
+
+    # imperative command ("add a router", "connect R1 and S1") -> tool execution
+    if it.type == "build" and it.output_form not in ("show", "guide"):
+        return Plan("execute")
+
+    if it.type == "diagnose":
+        return Plan("diagnose")
+
+    # generative "show me / construct / build" with a known pattern
+    if it.output_form in ("show", "guide") and recipe is not None:
+        if it.anchor == "concept":
+            return Plan("build_recipe", recipe_id=rid)         # empty canvas -> auto-build
+        return Plan("reason", offer_build=True, recipe_id=rid)  # populated -> offer first
+
+    # explain / how_to / tell -> reason, offering the example if we have one
+    return Plan("reason", offer_build=recipe is not None, recipe_id=rid)
+
+
+_STANCE = {
+    "strong": (
+        "GROUNDING STANCE — CLOSED WORLD: the GINI knowledge and canvas below fully cover this "
+        "question. Answer only from them; every element you name must appear in the elements "
+        "list."
+    ),
+    "thin": (
+        "GROUNDING STANCE — MOSTLY CLOSED: the KB match here is only partial. Lean on what's "
+        "provided; if a detail isn't covered, say so rather than inventing a GINI element."
+    ),
+    "empty": (
+        "GROUNDING STANCE — OPEN BUT FENCED: this question falls outside GINI's built-in "
+        "topics. You may answer from general knowledge, but do NOT claim any GINI element or "
+        "feature exists unless it's in the elements list; if GINI has no element for it, say so "
+        "plainly and point to the nearest thing GINI does have."
+    ),
+}
+
+
+def grounding_stance(retrieval, intent=None) -> str:
+    """One directive line telling the reasoner how tightly to stay on the GINI KB this turn,
+    derived from retrieval strength. The 'never invent a GINI element' rule holds in EVERY
+    tier — only the freedom to reason from general knowledge widens when the KB is thin."""
+    # no retrieval at all → default to the closed-world floor (keep the student on GINI); the
+    # open stance is only chosen when retrieval explicitly reports an empty/off-topic match.
+    strength = getattr(retrieval, "strength", "strong") if retrieval is not None else "strong"
+    return _STANCE.get(strength, _STANCE["strong"])
+
+
+def grounded_context(always_on: str, accumulator: str, retrieval, canvas_digest: str,
+                     intent, machine_card: str = "", stance: str = "") -> str:
+    """Assemble the context block the reasoning LLM sees: grounding stance + always-on index +
+    canvas + live machine (xv6) state + accumulated session knowledge + this turn's cards.
+
+    `machine_card` is the xv6 kernel state card (from domain.machine_state) when the focus is a
+    running xv6 Machine — a second 'ground truth' source alongside the canvas, so OS help is
+    grounded in this student's actual kernel run. `stance` (from `grounding_stance`) is prepended
+    so the model knows how closed-world to be for THIS question."""
+    parts = []
+    if stance:
+        parts.append(stance)
+    parts.append(always_on)
+    if canvas_digest:
+        parts.append("Current canvas (ground truth):\n" + canvas_digest)
+    if machine_card:
+        parts.append(machine_card)
+    if accumulator:
+        parts.append(accumulator)
+    rc = retrieval.as_context() if retrieval is not None else ""
+    if rc:
+        parts.append(rc)
+    return "\n\n".join(p for p in parts if p)
+
+
+def machine_card_level(text: str) -> int:
+    """How deep an xv6 state card the question warrants (progressive; keeps the small-LLM
+    budget lean). 0 = scheduling picture; 1 = + registers/stack; 2 = + memory/FS."""
+    q = (text or "").lower()
+    if any(w in q for w in ("page table", "pagetable", "satp", "virtual memory", "paging",
+                            "address space", "inode", "file system", "filesystem", "journal",
+                            "buffer cache", "disk", "block")):
+        return 2
+    if any(w in q for w in ("register", "pc", "stack", "backtrace", "trap", "trapframe",
+                            "context", "swtch", "ra ", "sp ", "program counter")):
+        return 1
+    return 0

gini/agent/authoring.py

@@ -0,0 +1,72 @@
+"""Authoring loop — a teacher turns a rough intent into a releasable mission (M5).
+
+The flow: **propose** (a vague intent → a composition-by-reference the teacher can read) →
+**playtest** (assemble + validate + a dry-run report so nothing broken is released) → **to_pack**
+(the YAML the Teaching Center distributes). The teacher is sovereign: the LLM drafts, the human
+ratifies/tweaks the spec before releasing.
+
+A proposal is a *composition* (references local fragment ids) — never new foundational fragments — so
+whatever a teacher authors is gradable by construction on any install that has the referenced
+fragments (guarded by the version/existence check in `domain.composition`).
+"""
+from __future__ import annotations
+
+import yaml
+
+from ..domain import composition as _comp
+from ..domain import fragments as _frag
+from ..domain import lesson as _lesson
+
+
+def propose(intent_text: str, llm=None, *, lesson_id: str = "", genre: str | None = None) -> dict:
+    """Draft a composition spec from a rough intent (reuses the student-facing composer, but emits a
+    releasable REFERENCE spec — the core fragment ids + framing — not a one-off lesson)."""
+    from . import lesson_resolver
+    prop = lesson_resolver.compose(intent_text, llm, lesson_id=lesson_id or "authored", genre=genre)
+    if prop is None or prop.lesson is None:
+        return {}
+    les = prop.lesson
+    # reference only the CORE fragments the teacher chose; genre re-derives the enrichment on assembly
+    cores = [fid for fid in les.fragments
+             if (_frag.get(fid) is not None and _frag.get(fid).layer == _frag.CORE)]
+    spec = {"id": lesson_id or "authored", "fragments": cores or [prop.archetype_id],
+            "genre": les.genre or "expedition", "title": les.title,
+            "brief": les.brief.split("] ", 1)[-1] if les.brief.startswith("[") else les.brief}
+    if les.level is not None:
+        spec["level"] = les.level
+    return spec
+
+
+def playtest(spec: dict) -> dict:
+    """Assemble + validate a spec without releasing. Returns a report: {ok, problems, summary,
+    objectives}. This is the safety gate — a teacher sees exactly what a student would be graded on."""
+    problems = list(_comp.missing_refs(spec))
+    les = None
+    if not problems:
+        try:
+            les = _comp.from_composition(spec)
+        except _comp.CompositionError as e:
+            problems.append(str(e))
+    if les is not None:
+        problems.extend(_lesson.validate(les))
+    return {
+        "ok": not problems,
+        "problems": problems,
+        "summary": (f"{les.title} — {len(les.objectives)} objectives"
+                    f" · L{les.level} · {les.genre}") if les else "",
+        "objectives": [o.say for o in les.objectives] if les else [],
+    }
+
+
+def to_pack(spec: dict) -> str:
+    """The releasable YAML pack (a composition-by-reference the Teaching Center serves)."""
+    ordered = {k: spec[k] for k in ("id", "fragments", "genre", "level", "title", "brief",
+                                    "time_limit", "attempts", "help", "persona") if k in spec}
+    return yaml.safe_dump(ordered, sort_keys=False, allow_unicode=True, width=100)
+
+
+def ratify(spec: dict, **tweaks) -> dict:
+    """Apply a teacher's edits (title, genre, level, fragments, brief…) to a proposed spec."""
+    out = dict(spec)
+    out.update({k: v for k, v in tweaks.items() if v is not None})
+    return out

gini/agent/blackboard.py

@@ -0,0 +1,114 @@
+"""The Blackboard — the shared truth cache the deterministic swarm keeps current and the Reasoning
+persona reads from (GINI_MISSIONS_AGENT_ARCHITECTURE.md §4). It holds the latest Verdict per subject
+plus the shared, curated MissionMemory. Verdicts are recomputed incrementally: an update names the
+state keys that changed, and only verifiers whose `deps()` intersect those keys re-run.
+
+Pure Python (no Qt): the substrate is unit-testable with a real Topology + lesson. The live wiring
+(bus → observers → verifiers → notifications → reasoning) sits on top in later phases.
+"""
+from __future__ import annotations
+
+from .contracts import Fact, MissionMemory, Verdict
+from .verifiers import WorldView, for_lesson
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._verifiers: dict[str, object] = {}
+
+    def add(self, verifier) -> None:
+        self._verifiers[verifier.id] = verifier
+
+    def add_all(self, verifiers) -> None:
+        for v in verifiers:
+            self.add(v)
+
+    def remove(self, verifier_id: str) -> None:
+        self._verifiers.pop(verifier_id, None)
+
+    def clear(self) -> None:
+        self._verifiers.clear()
+
+    def verifiers(self) -> list:
+        return list(self._verifiers.values())
+
+    def affected(self, changed: set[str] | None) -> list:
+        """Verifiers to re-run: all when `changed` is None, else those whose deps intersect it."""
+        if changed is None:
+            return self.verifiers()
+        return [v for v in self._verifiers.values() if set(v.deps()) & changed]
+
+
+class Blackboard:
+    def __init__(self) -> None:
+        self.registry = Registry()
+        self.memory = MissionMemory()
+        self._verdicts: dict[str, object] = {}
+        self._lesson = None
+        self._runner = None
+
+    # -- lifecycle ---------------------------------------------------------- #
+    def load_lesson(self, lesson, *, verifiers=None, runner=None) -> None:
+        """Register the tiny verifiers a mission needs and reset the truth cache. `verifiers` lets a
+        domain pack supply its own set; it defaults to the networking `for_lesson`."""
+        self.registry.clear()
+        self.registry.add_all(verifiers if verifiers is not None else for_lesson(lesson))
+        self._verdicts.clear()
+        self._lesson = lesson
+        self._runner = runner
+
+    def clear(self) -> None:
+        self.registry.clear()
+        self._verdicts.clear()
+        self._lesson = None
+        self.memory = MissionMemory()
+
+    # -- truth maintenance -------------------------------------------------- #
+    def update(self, topology, *, changed: set[str] | None = None) -> list:
+        """Re-run the affected verifiers against the current topology; refresh the cache. Returns the
+        verdicts that CHANGED (value flipped or newly appeared) — the raw material for notifications."""
+        if self._lesson is None:
+            return []
+        view = WorldView.of(topology, self._lesson, runner=self._runner)
+        flipped = []
+        for v in self.registry.affected(changed):
+            for verdict in v.check(view):
+                prev = self._verdicts.get(verdict.subject)
+                if prev is None or prev.value != verdict.value:
+                    flipped.append(verdict)
+                self._verdicts[verdict.subject] = verdict
+        return flipped
+
+    def ingest_results(self, results) -> None:
+        """Set objective verdicts directly from pre-computed ObjectiveResults (the mission already
+        evaluated them) — so the Reasoning persona is grounded without a second evaluation and even
+        when only results, not a topology, are on hand."""
+        for r in results:
+            self._verdicts[r.id] = Verdict(f"objective:{r.id}", subject=r.id, value=r.met,
+                                           evidence=Fact("status", r.status), deps=("topology",))
+
+    # -- reads -------------------------------------------------------------- #
+    def verdict(self, subject: str):
+        return self._verdicts.get(subject)
+
+    def value(self, subject: str) -> bool:
+        v = self._verdicts.get(subject)
+        return bool(v and v.value)
+
+    def verdicts(self) -> list:
+        return list(self._verdicts.values())
+
+    def unmet_objectives(self) -> list[str]:
+        return [v.subject for v in self._verdicts.values()
+                if v.verifier_id.startswith("objective:") and not v.value]
+
+    def all_objectives_met(self) -> bool:
+        objs = [v for v in self._verdicts.values() if v.verifier_id.startswith("objective:")]
+        return bool(objs) and all(v.value for v in objs)
+
+    def flags(self) -> dict:
+        """Current legality problems (for the red badges), read straight off the cache."""
+        off = self.verdict("off_task")
+        bad = self.verdict("illegal_links")
+        return {"off_task": list(off.evidence.data) if off and off.evidence and not off.value else [],
+                "illegal_links": list(bad.evidence.data) if bad and bad.evidence and not bad.value else []}

gini/agent/contracts.py

@@ -0,0 +1,142 @@
+"""Multi-agent message contracts — the domain-neutral types the mission agents pass on the bus /
+blackboard. Pinning these down first is the whole point: a multi-agent system with sloppy message
+types is the real maintenance nightmare. See GINI_MISSIONS_AGENT_ARCHITECTURE.md §7.
+
+Two families:
+  • truth & change (deterministic agents): Observation, Fact, Verdict, Notification;
+  • meaning (LLM personas): Intent, Claim, Move; plus the shared, curated MissionMemory.
+
+Everything here is a plain dataclass (no Qt, no LLM) so the whole substrate is unit-testable. The
+`Verifier`/`Observer` protocols are the domain-pack seam: a domain implements tiny verifiers and
+observers; the framework never looks inside them.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+# ---- truth & change ------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class Fact:
+    """A checkable datum — a counterexample, disconnected components, a value, a status. NEVER prose;
+    turning a Fact into meaning is always the Reasoning persona's job."""
+    kind: str
+    data: Any = None
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """The result of ONE tiny verifier for ONE subject: a boolean + the fact that evidences it."""
+    verifier_id: str
+    subject: str                 # what was checked (an objective id, a device id, "off_task" …)
+    value: bool
+    evidence: Fact | None = None
+    deps: tuple[str, ...] = ()   # state keys this verdict depends on (for incremental re-check)
+
+
+@dataclass(frozen=True)
+class Observation:
+    """A sensed datum from the running world (a snapshot or a discrete event)."""
+    source: str
+    data: Any = None
+    event: str = ""              # "" for a snapshot; else a discrete event name (panic, run_done…)
+    ts: float = field(default_factory=time.time)
+
+
+@dataclass(frozen=True)
+class Notification:
+    """A salient CHANGE, routed to wake the Reasoning persona. Salience is rules-only (0..1)."""
+    change: str                  # e.g. "objective_met", "off_task_added", "run_complete", "question"
+    subjects: tuple[str, ...] = ()
+    salience: float = 1.0
+    data: Any = None
+    ts: float = field(default_factory=time.time)
+
+
+# ---- meaning -------------------------------------------------------------- #
+
+# Intent kinds the Understanding persona classifies a student input into
+CONCEPT, ENTITY, OBJECTIVE, NEXT_STEP, OFF_TASK, META = (
+    "concept", "entity", "objective", "next_step", "off_task", "meta")
+
+
+@dataclass(frozen=True)
+class Intent:
+    """A student input, understood: what they mean and what it references."""
+    kind: str = META
+    text: str = ""
+    refs: tuple[str, ...] = ()          # resolved world-entity ids
+    objective_ref: str = ""
+
+
+@dataclass(frozen=True)
+class Claim:
+    """A single factual assertion inside a Move — re-checkable against the oracle, so the model may
+    reason freely while nothing false ships."""
+    predicate: str               # a verifier subject or a structural predicate to re-evaluate
+    expected: bool = True
+
+
+@dataclass(frozen=True)
+class Move:
+    """The Reasoning persona's output for a turn."""
+    kind: str = "say"            # say | hint | advance | flag | answer | quiet
+    text: str = ""
+    refs: tuple[str, ...] = ()
+    claims: tuple[Claim, ...] = ()
+
+
+@dataclass
+class MissionMemory:
+    """The Reasoning persona's curated, SHARED working memory (read-only to other personas). Compact
+    and structured — not a raw transcript — so a small model stays sharp over a long mission."""
+    arc: str = ""                       # where the mission is, in a line
+    tried: list[str] = field(default_factory=list)     # what the student has attempted
+    facts: list[str] = field(default_factory=list)     # established facts worth carrying
+    threads: list[str] = field(default_factory=list)   # open questions / loose ends
+
+    def note_tried(self, s: str) -> None:
+        if s and s not in self.tried:
+            self.tried.append(s)
+
+    def note_fact(self, s: str) -> None:
+        if s and s not in self.facts:
+            self.facts.append(s)
+
+    def digest(self, *, max_items: int = 6) -> str:
+        """A compact slice for a persona prompt (bounded — small models drown in clutter)."""
+        parts = []
+        if self.arc:
+            parts.append(f"Where we are: {self.arc}")
+        if self.tried:
+            parts.append("Tried: " + "; ".join(self.tried[-max_items:]))
+        if self.facts:
+            parts.append("Known: " + "; ".join(self.facts[-max_items:]))
+        if self.threads:
+            parts.append("Open: " + "; ".join(self.threads[-max_items:]))
+        return "\n".join(parts)
+
+
+# ---- the domain-pack seam ------------------------------------------------- #
+
+
+@runtime_checkable
+class Verifier(Protocol):
+    """A tiny, single-aspect, deterministic checker. Produces Verdicts for a WorldView; declares the
+    state keys it depends on so the blackboard only re-runs it when relevant state changes."""
+    id: str
+
+    def deps(self) -> tuple[str, ...]: ...
+
+    def check(self, view) -> list[Verdict]: ...
+
+
+@runtime_checkable
+class Observer(Protocol):
+    """Senses the running world into Observations (a snapshot or discrete events)."""
+    id: str
+
+    def observe(self, world) -> list[Observation]: ...

gini/agent/domains.py

@@ -0,0 +1,91 @@
+"""Domain packs — the seam that makes the mission engine domain-agnostic (GINI_MISSIONS_AGENT_
+ARCHITECTURE.md §8). The framework (blackboard, notifier, personas, reasoning) is blind to the domain;
+a DomainPack supplies the domain-specific pieces behind one interface: the tiny Verifiers, the Observers,
+the capability Vocabulary, the objective PredicateSet, the KB, the palette, and the fragments.
+
+Networking is the first pack — it just wraps the modules we already have, so nothing is duplicated.
+Cloud and xv6/OS become future packs implementing the same protocol; the reasoner discovers a pack's
+tools by enumerating its verifiers/observers, which is the proof the reasoning is domain-neutral.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .contracts import Observation
+
+
+@runtime_checkable
+class DomainPack(Protocol):
+    name: str
+
+    def verifiers(self, lesson) -> list: ...       # tiny verifiers for this lesson
+    def observers(self) -> list: ...               # world sensors
+    def vocabulary(self): ...                       # capability roles module (is-a hierarchy)
+    def predicates(self) -> set: ...                # objective predicate names
+    def fragments(self) -> list: ...                # composable content
+    def palette(self) -> dict: ...                  # buildable/observable elements
+    def knowledge(self): ...                        # KB module (retrieval)
+
+
+class TopologyObserver:
+    """Senses the networking world (the drawn topology) as a snapshot Observation."""
+    id = "topology"
+
+    def observe(self, world) -> list[Observation]:
+        data = world.to_dict() if hasattr(world, "to_dict") else world
+        return [Observation(source="topology", data=data)]
+
+
+class NetworkingPack:
+    """The first domain pack — a thin adapter over the existing networking modules."""
+    name = "networking"
+
+    def verifiers(self, lesson) -> list:
+        from . import verifiers as _v
+        return _v.for_lesson(lesson)
+
+    def observers(self) -> list:
+        return [TopologyObserver()]
+
+    def vocabulary(self):
+        from ..domain import capabilities
+        return capabilities
+
+    def predicates(self) -> set:
+        from ..domain.objectives import _PREDICATES
+        return set(_PREDICATES)
+
+    def fragments(self) -> list:
+        from ..domain import fragments
+        return fragments.all_fragments()
+
+    def palette(self) -> dict:
+        from ..domain.devices import REGISTRY
+        return dict(REGISTRY)
+
+    def knowledge(self):
+        from . import kb
+        return kb
+
+
+# -- registry --------------------------------------------------------------- #
+_PACKS: dict[str, DomainPack] = {}
+
+
+def register(pack: DomainPack) -> None:
+    _PACKS[pack.name] = pack
+
+
+def get(name: str) -> DomainPack | None:
+    return _PACKS.get(name)
+
+
+def names() -> list[str]:
+    return list(_PACKS)
+
+
+register(NetworkingPack())
+
+# the OS pack — same protocol, drops xv6/OS onto the domain-neutral engine.
+from .xv6_pack import Xv6Pack   # noqa: E402  (import here to avoid a cycle at module top)
+register(Xv6Pack())

gini/agent/embed.py

@@ -0,0 +1,123 @@
+"""L2 semantic recall — embeddings over the (small, fixed) GINI knowledge base.
+
+The KB is ~75 short documents (concept notes + recipes + element descriptions), so semantic
+search is a cosine over a precomputed matrix, not a vector-database problem:
+
+  • POPULATE (offline, shipped):  `scripts/build_kb_index.py` embeds every `kb_documents()`
+    entry once and writes `data/kb_index.json` (model tag + KB hash + id→vector). A test
+    asserts the hash matches the live KB, so an edited note without a rebuild fails CI.
+  • QUERY (online, reused infra):  `OllamaEmbeddings` embeds the student's query via the SAME
+    Ollama server GINI already uses for the LLM (`/api/embed`) — no new Python dependency —
+    then cosines against the shipped vectors.
+
+`NullEmbeddings` is the graceful fallback when no index/embed-model is available, so GINI
+still runs offline (it simply drops to L0+L1). Callers use the `EmbeddingIndex` protocol and
+never care which is active.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from pathlib import Path
+from typing import Protocol
+
+from ..domain import concepts as _concepts
+from ..domain import recipes as _recipes
+from ..domain.devices import all_devices
+
+_INDEX_PATH = Path(__file__).resolve().parent.parent / "data" / "kb_index.json"
+
+
+# -- the shared document set (builder + validation) ------------------------- #
+def kb_documents() -> list[tuple[str, str]]:
+    """(doc_id, text) for every embeddable KB card. Stable IDs `concept:<key>` /
+    `recipe:<id>` / `element:<key>` so recall can map a vector back to its object."""
+    docs: list[tuple[str, str]] = []
+    for c in _concepts.CONCEPTS:
+        docs.append((f"concept:{c.key}",
+                     f"{c.title}. {' '.join(c.keywords)}. {c.body}"))
+    for r in _recipes.RECIPES:
+        docs.append((f"recipe:{r.id}",
+                     f"{r.name}. {r.summary} {r.teaches} {' '.join(r.intent)}"))
+    for d in all_devices():
+        docs.append((f"element:{d.key}", f"{d.label}: {d.description}"))
+    return docs
+
+
+def kb_hash() -> str:
+    """A stable hash of the KB text — the index records it so we can detect drift."""
+    h = hashlib.sha256()
+    for doc_id, text in kb_documents():
+        h.update(doc_id.encode()); h.update(b"\x00"); h.update(text.encode()); h.update(b"\x01")
+    return h.hexdigest()
+
+
+# -- cosine helpers --------------------------------------------------------- #
+def _cosine(a: list[float], b: list[float]) -> float:
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+# -- the protocol + implementations ----------------------------------------- #
+class EmbeddingIndex(Protocol):
+    def available(self) -> bool: ...
+    def query(self, text: str, k: int = 4) -> list[tuple[str, float]]: ...
+
+
+class NullEmbeddings:
+    """The offline fallback — never matches, so recall degrades to L0+L1."""
+
+    def available(self) -> bool:
+        return False
+
+    def query(self, text: str, k: int = 4) -> list[tuple[str, float]]:
+        return []
+
+
+def load_index(path: Path = _INDEX_PATH) -> dict | None:
+    try:
+        return json.loads(Path(path).read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+class OllamaEmbeddings:
+    """Semantic recall backed by the precomputed index + an Ollama `/api/embed` query call.
+
+    `backend` is any object exposing `embed(texts) -> list[vector]` (the OllamaBackend). The
+    index is loaded once; if it's missing or the KB has drifted, `available()` is False and we
+    fall back cleanly. `min_score` gates weak cosine matches out."""
+
+    def __init__(self, backend, *, index: dict | None = None, index_path: Path = _INDEX_PATH,
+                 min_score: float = 0.55, check_hash: bool = True) -> None:
+        self.backend = backend
+        self.min_score = min_score
+        self._index = index if index is not None else load_index(index_path)
+        self._ok = bool(self._index) and bool(self._index.get("vectors"))
+        if self._ok and check_hash:
+            # a mismatched hash means the notes changed without a rebuild — don't trust it
+            if self._index.get("kb_hash") not in (None, kb_hash()):
+                self._ok = False
+
+    def available(self) -> bool:
+        return self._ok and self.backend is not None
+
+    def query(self, text: str, k: int = 4) -> list[tuple[str, float]]:
+        if not self.available():
+            return []
+        try:
+            vecs = self.backend.embed([text])
+            qv = vecs[0] if vecs else None
+        except Exception:
+            return []
+        if not qv:
+            return []
+        scored = [(doc_id, _cosine(qv, vec)) for doc_id, vec in self._index["vectors"].items()]
+        scored = [(d, s) for d, s in scored if s >= self.min_score]
+        scored.sort(key=lambda p: -p[1])
+        return scored[:k]