deepparallel 0.2.0__tar.gz → 0.4.0__tar.gz

{deepparallel-0.2.0 → deepparallel-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepparallel
-Version: 0.2.0
+Version: 0.4.0
 Summary: DeepParallel - a multi-model agentic coding CLI with cross-model Guardian review, served via Crowe Logic.
 Author-email: Michael Crowe <michael@crowelogic.com>
 License: Apache-2.0
@@ -19,13 +19,27 @@ Requires-Dist: cryptography>=42.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: ruff>=0.6.0; extra == "dev"
+Provides-Extra: research
+Requires-Dist: numpy>=1.24; extra == "research"
 
 # DeepParallel
 
-A focused command-line interface for the DeepParallel model, served via Crowe Logic.
+A multi-model agentic coding CLI with cross-model Guardian review. Many models
+check the work; you ship with a second opinion. Served via Crowe Logic.
 
 ## Install
 
+    uv tool install deepparallel        # recommended
+    # or
+    pipx install deepparallel --python python3.13
+
+Then run `deepparallel` (or the short alias `dp`).
+
+Note: on systems with a broken Homebrew Python 3.14, bare `pipx install` may
+fail to find a usable interpreter - use `uv tool install` or pin `--python`.
+
+### From source
+
     uv venv
     uv pip install -p .venv -e .
 
@@ -53,6 +67,19 @@ Set the backend env vars (a `.env` file in the working directory is loaded autom
     deepparallel doctor          # diagnose config + reachability
     deepparallel run --no-tools "..."   # plain chat, no tools
     deepparallel run --yes "..."        # auto-approve tool actions
+    deepparallel review <file|--diff>   # cross-model review as a CI gate (Pro)
+    deepparallel audit <file>           # supply-chain gate: catch hallucinated deps (Pro)
+    deepparallel research conduit       # latent-relay research demo (needs [research] extra)
+
+## Supply-chain gate
+
+LLMs invent package names that don't exist — and attackers register those names
+("slopsquatting"). `deepparallel audit <file>` extracts the dependencies a file
+introduces (imports, requirements.txt, package.json) and checks each against the
+real registry (PyPI / npm), flagging any the registry has never seen. Exit 0
+clean, 2 if a likely-hallucinated package is found — so it gates a commit or PR.
+The Guardian also runs this automatically on every edit: a hallucinated import
+forces a confirmation even under `--yes`.
 
 ## Fusion (stacking models for stronger output)
 
@@ -107,7 +134,7 @@ timeboxed local subprocess.
 | `DEEPPARALLEL_API_VERSION` | Azure API version | `2024-08-01-preview` |
 | `FOUNDRY_BASE_URL` / `FOUNDRY_API_KEY` | control-plane transport | (required for foundry) |
 | `DEEPPARALLEL_TEMPERATURE` | default sampling temperature | `0.4` |
-| `DEEPPARALLEL_MAX_TOKENS` | response cap | `2048` |
+| `DEEPPARALLEL_MAX_TOKENS` | response cap (large enough to write whole files) | `8192` |
 | `DEEPPARALLEL_THINK` | surface reasoning stream | `0` (answer-only) |
 | `DEEPPARALLEL_TOOLS` | enable agent tools | `1` (on) |
 | `DEEPPARALLEL_AUTO_APPROVE` | auto-approve mutating tools | `0` (off) |

{deepparallel-0.2.0 → deepparallel-0.4.0}/README.md

@@ -1,9 +1,21 @@
 # DeepParallel
 
-A focused command-line interface for the DeepParallel model, served via Crowe Logic.
+A multi-model agentic coding CLI with cross-model Guardian review. Many models
+check the work; you ship with a second opinion. Served via Crowe Logic.
 
 ## Install
 
+    uv tool install deepparallel        # recommended
+    # or
+    pipx install deepparallel --python python3.13
+
+Then run `deepparallel` (or the short alias `dp`).
+
+Note: on systems with a broken Homebrew Python 3.14, bare `pipx install` may
+fail to find a usable interpreter - use `uv tool install` or pin `--python`.
+
+### From source
+
     uv venv
     uv pip install -p .venv -e .
 
@@ -31,6 +43,19 @@ Set the backend env vars (a `.env` file in the working directory is loaded autom
     deepparallel doctor          # diagnose config + reachability
     deepparallel run --no-tools "..."   # plain chat, no tools
     deepparallel run --yes "..."        # auto-approve tool actions
+    deepparallel review <file|--diff>   # cross-model review as a CI gate (Pro)
+    deepparallel audit <file>           # supply-chain gate: catch hallucinated deps (Pro)
+    deepparallel research conduit       # latent-relay research demo (needs [research] extra)
+
+## Supply-chain gate
+
+LLMs invent package names that don't exist — and attackers register those names
+("slopsquatting"). `deepparallel audit <file>` extracts the dependencies a file
+introduces (imports, requirements.txt, package.json) and checks each against the
+real registry (PyPI / npm), flagging any the registry has never seen. Exit 0
+clean, 2 if a likely-hallucinated package is found — so it gates a commit or PR.
+The Guardian also runs this automatically on every edit: a hallucinated import
+forces a confirmation even under `--yes`.
 
 ## Fusion (stacking models for stronger output)
 
@@ -85,7 +110,7 @@ timeboxed local subprocess.
 | `DEEPPARALLEL_API_VERSION` | Azure API version | `2024-08-01-preview` |
 | `FOUNDRY_BASE_URL` / `FOUNDRY_API_KEY` | control-plane transport | (required for foundry) |
 | `DEEPPARALLEL_TEMPERATURE` | default sampling temperature | `0.4` |
-| `DEEPPARALLEL_MAX_TOKENS` | response cap | `2048` |
+| `DEEPPARALLEL_MAX_TOKENS` | response cap (large enough to write whole files) | `8192` |
 | `DEEPPARALLEL_THINK` | surface reasoning stream | `0` (answer-only) |
 | `DEEPPARALLEL_TOOLS` | enable agent tools | `1` (on) |
 | `DEEPPARALLEL_AUTO_APPROVE` | auto-approve mutating tools | `0` (off) |

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/__init__.py

@@ -1,3 +1,3 @@
 """DeepParallel CLI package."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/agent.py

@@ -18,6 +18,17 @@ _MAX_TOOL_RESULT = 50_000
 _GATED_PATH_TOOLS = ("write_file", "edit_file")
 _EDIT_TOOLS = ("write_file", "edit_file", "ast_replace_symbol")
 
+# Shown back to the model when a tool call arrives on a response that the API
+# cut off at the token limit (finish_reason=length). The call's arguments, and
+# any file body inside them, are incomplete, so we never apply it.
+_TRUNCATION_HINT = (
+    "Your previous output was cut off by the response token limit "
+    "(finish_reason=length), so this tool call is incomplete and was NOT applied. "
+    "Write large files in smaller pieces: create the file with write_file using "
+    "the first portion, then append the rest with edit_file (or split it across "
+    "files). Do not emit an entire large file in one tool call."
+)
+
 
 def _parse_args(raw: str) -> dict:
     if not raw:
@@ -191,9 +202,30 @@ def _guardian_verdict(guardian, name: str, args: dict) -> str | None:
     return guardian_review(guardian, _guardian_review_content(name, args))
 
 
+def _supply_chain_note(name: str, args: dict) -> str | None:
+    """Best-effort: flag hallucinated/slopsquatted deps an edit introduces."""
+    content = args.get("new_source") or args.get("new_string") or args.get("content") or ""
+    path = args.get("file_path", "")
+    if not content or not path:
+        return None
+    try:
+        from deepparallel import supply_chain
+
+        result = supply_chain.audit(content, path)
+    except Exception:  # noqa: BLE001 - supply-chain check is best-effort
+        return None
+    if result["hallucinated"]:
+        return "not found on the registry (possible hallucination): " + ", ".join(
+            result["hallucinated"]
+        )
+    return None
+
+
 def _approved(name, args, interactive, auto_approve, renderer, guardian=None) -> bool:
     forced = name in _GATED_PATH_TOOLS and _outside_cwd(args)
-    if auto_approve and not forced:
+    sc_note = _supply_chain_note(name, args) if name in _EDIT_TOOLS else None
+    # A hallucinated dependency overrides auto-approve: always surface it.
+    if auto_approve and not forced and not sc_note:
         return True
     if not interactive:
         return False
@@ -202,6 +234,8 @@ def _approved(name, args, interactive, auto_approve, renderer, guardian=None) ->
         verdict = _guardian_verdict(guardian, name, args)
         if verdict:
             detail = f"{detail}\n\nGuardian: {verdict}"
+    if sc_note:
+        detail = f"{detail}\n\nSupply-chain: {sc_note}"
     return renderer.confirm(title, detail)
 
 
@@ -250,6 +284,7 @@ def run_agent(
             msg = backend.chat(messages, schemas, settings.temperature, settings.max_tokens)
             streamed = False
         tool_calls = msg.get("tool_calls")
+        truncated = bool(msg.get("_truncated"))
         if not tool_calls:
             content = msg.get("content") or ""
             messages.append({"role": "assistant", "content": content})
@@ -260,13 +295,18 @@ def run_agent(
         messages.append(
             {"role": "assistant", "content": msg.get("content"), "tool_calls": tool_calls}
         )
-        for tc in tool_calls:
+        # A length-truncated response cuts off the final tool call mid-arguments,
+        # so its file body is incomplete. Refuse it and tell the model to chunk.
+        last_idx = len(tool_calls) - 1
+        for i, tc in enumerate(tool_calls):
             name = tc["function"]["name"]
             args = _parse_args(tc["function"].get("arguments", ""))
             meta = registry.get(name)
             renderer.tool_start(name, _preview(args))
             start = time.monotonic()
-            if meta is None:
+            if truncated and i == last_idx:
+                result = json.dumps({"error": _TRUNCATION_HINT})
+            elif meta is None:
                 result = json.dumps({"error": f"unknown tool: {name}"})
             elif "__parse_error__" in args:
                 result = json.dumps({"error": "invalid JSON arguments"})

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/backend.py

@@ -56,6 +56,7 @@ def parse_sse_stream(lines: Iterator[str]):
     """
     content_parts: list[str] = []
     acc: dict[int, dict] = {}
+    finish_reason: str | None = None
     for raw in lines:
         line = raw.strip()
         if not line or not line.startswith("data:"):
@@ -70,6 +71,8 @@ def parse_sse_stream(lines: Iterator[str]):
         choices = obj.get("choices") or []
         if not choices:
             continue
+        if choices[0].get("finish_reason"):
+            finish_reason = choices[0]["finish_reason"]
         delta = choices[0].get("delta") or {}
         reasoning = delta.get("reasoning_content")
         if reasoning:
@@ -95,6 +98,7 @@ def parse_sse_stream(lines: Iterator[str]):
         "role": "assistant",
         "content": "".join(content_parts) or None,
         "tool_calls": tool_calls,
+        "_truncated": finish_reason == "length",
     }
 
 
@@ -103,6 +107,18 @@ def _host(url: str) -> str:
     return f"{p.scheme}://{p.netloc}" if p.netloc else url
 
 
+def _message_from_choice(choice: dict) -> dict:
+    """Extract the assistant message and flag output-token truncation.
+
+    `finish_reason == "length"` means the model was cut off mid-output. For a
+    tool call that carries file content, that means the arguments (and any file
+    body inside them) are incomplete and must not be applied blindly.
+    """
+    msg = dict(choice.get("message") or {})
+    msg["_truncated"] = choice.get("finish_reason") == "length"
+    return msg
+
+
 class Backend(Protocol):
     label: str
 
@@ -172,7 +188,7 @@ class AzureBackend:
         headers = {"api-key": self._api_key, "content-type": "application/json"}
         r = httpx.post(self._url, json=payload, headers=headers, timeout=_STREAM_TIMEOUT)
         r.raise_for_status()
-        return r.json()["choices"][0]["message"]
+        return _message_from_choice(r.json()["choices"][0])
 
     def stream_chat_tools(self, messages, tools, temperature, max_tokens):
         payload = {
@@ -246,7 +262,7 @@ class FoundryBackend:
         }
         r = httpx.post(self._url, json=payload, headers=headers, timeout=_STREAM_TIMEOUT)
         r.raise_for_status()
-        return r.json()["choices"][0]["message"]
+        return _message_from_choice(r.json()["choices"][0])
 
     def stream_chat_tools(self, messages, tools, temperature, max_tokens):
         payload = {

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/cli.py

@@ -43,7 +43,7 @@ from deepparallel.config import (
     missing_required,
     resolve_settings,
 )
-from deepparallel import licensing
+from deepparallel import licensing, supply_chain
 from deepparallel.fusion import (
     EscalationBackend,
     ReasonAnswerBackend,
@@ -504,6 +504,94 @@ def review(ctx: click.Context, as_diff: bool, path: str | None) -> None:
     sys.exit(verdict_exit_code(verdict))
 
 
+@main.command()
+@click.argument("path", required=True)
+@click.pass_context
+def audit(ctx: click.Context, path: str) -> None:
+    """Supply-chain gate: check a file's dependencies against the real registry.
+
+    Flags hallucinated / slopsquatted packages (names PyPI or npm has never
+    seen) in source files and manifests. Exit code: 0 clean, 2 if a likely
+    hallucinated dependency is found - so it can gate a commit or PR. Paid (Pro+).
+    """
+    ok, msg = licensing.check_feature("audit")
+    if not ok:
+        branding.error(msg)
+        sys.exit(3)
+    try:
+        content = Path(path).expanduser().read_text(encoding="utf-8")
+    except OSError as e:
+        branding.error(f"cannot read {path}: {e}")
+        sys.exit(3)
+    result = supply_chain.audit(content, path)
+    findings = result["findings"]
+    if not findings:
+        console.print(f"[{branding.DIM}]no external dependencies found in {path}[/]")
+        sys.exit(0)
+    for f in findings:
+        glyph = {"ok": branding.CHECK, "missing": branding.CROSS}.get(f["status"], "?")
+        color = {"ok": branding.GREEN_HEX, "missing": branding.RED_HEX}.get(
+            f["status"], branding.DIM
+        )
+        console.print(
+            f"  [{color}]{glyph}[/] {f['name']} [{branding.DIM}]({f['ecosystem']}) · {f['status']}[/]"
+        )
+    if result["hallucinated"]:
+        console.print(
+            f"[bold {branding.RED_HEX}]{branding.CROSS} {len(result['hallucinated'])} "
+            f"possibly hallucinated:[/] {', '.join(result['hallucinated'])}"
+        )
+        sys.exit(2)
+    console.print(f"[{branding.GREEN_HEX}]{branding.CHECK} all dependencies verified[/]")
+    sys.exit(0)
+
+
+@main.group()
+def research() -> None:
+    """Runnable demonstrators of the ideas behind DeepParallel."""
+
+
+@research.command("conduit")
+def research_conduit() -> None:
+    """Conduit: relay a thought between models as a hidden state vs. as a word.
+
+    Frozen synthetic models relay a continuous meaning down a chain of agents two
+    ways and we measure how much survives each hop. The latent channel holds the
+    meaning; the word channel (one emitted token per hop) collapses. The same
+    result on real open-weight models: crowelogic.com/research/conduit
+    """
+    try:
+        from deepparallel.research import conduit as _conduit
+    except ImportError:
+        branding.error(
+            "this demo needs numpy. Install it with: pip install 'deepparallel[research]'"
+        )
+        sys.exit(3)
+    console.print(f"[{branding.DIM}]running the latent relay (frozen synthetic models)...[/]")
+    r = _conduit.demonstrate()
+    console.print(
+        f"\n[bold]Conduit[/] · meaning retained after K relay hops "
+        f"[{branding.DIM}](cosine; 1.0 = perfect)[/]"
+    )
+    console.print(
+        f"[{branding.DIM}]  meaning = {r['meaning_dim']}-dim continuous   "
+        f"word channel = 1 token of {r['vocab']}[/]\n"
+    )
+    console.print(
+        f"  [{branding.DIM}]{'hops':>5}   {'latent relay':>13}   {'word relay':>11}   {'gain':>6}[/]"
+    )
+    for K in r["hops"]:
+        lat, wrd = r["latent"][K], r["word"][K]
+        console.print(
+            f"  {K:>5}   [{branding.GREEN_HEX}]{lat:>13.3f}[/]   "
+            f"[{branding.DIM}]{wrd:>11.3f}[/]   [{branding.AMBER_HEX}]{lat - wrd:>+6.3f}[/]"
+        )
+    console.print(
+        f"\n[{branding.DIM}]  the full hidden state relays more meaning than the single word "
+        f"the model would have said.[/]"
+    )
+
+
 @main.command(name="tools")
 def tools_cmd() -> None:
     """List the agent tools available to DeepParallel."""

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/config.py

@@ -101,7 +101,7 @@ def resolve_settings() -> Settings:
         foundry_api_key=os.environ.get("FOUNDRY_API_KEY"),
         foundry_model=os.environ.get("DEEPPARALLEL_FOUNDRY_MODEL", "DeepSeek-V3-1"),
         temperature=_float_env("DEEPPARALLEL_TEMPERATURE", 0.4),
-        max_tokens=_int_env("DEEPPARALLEL_MAX_TOKENS", 2048),
+        max_tokens=_int_env("DEEPPARALLEL_MAX_TOKENS", 8192),
         show_thinking=_bool_env("DEEPPARALLEL_THINK", False),
         tools_enabled=_bool_env("DEEPPARALLEL_TOOLS", True),
         auto_approve=_bool_env("DEEPPARALLEL_AUTO_APPROVE", False),

{deepparallel-0.2.0 → deepparallel-0.4.0}/deepparallel/licensing.py

@@ -70,6 +70,30 @@ def verify_token(token: str, pubkey_b64: str | None = None) -> dict | None:
     return payload
 
 
+def sign_token(payload: dict, private_key_b64: str) -> str:
+    """Sign a license payload into a `body.signature` token (issuer-side).
+
+    Requires the private issuance key; verify_token() checks it with the public
+    key. Used by the license-issuer (Stripe webhook) and the admin CLI.
+    """
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    priv = Ed25519PrivateKey.from_private_bytes(_b64url_decode_std(private_key_b64))
+    body = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=")
+    sig = base64.urlsafe_b64encode(priv.sign(body.encode())).decode().rstrip("=")
+    return f"{body}.{sig}"
+
+
+def _b64url_decode_std(s: str) -> bytes:
+    """Decode standard OR url-safe base64 (keys are emitted as standard b64)."""
+    s = s.strip()
+    pad = "=" * (-len(s) % 4)
+    try:
+        return base64.b64decode(s + pad)
+    except Exception:  # noqa: BLE001
+        return base64.urlsafe_b64decode(s + pad)
+
+
 def _license_file_token() -> str | None:
     path = Path(
         os.environ.get("DEEPPARALLEL_LICENSE_FILE", "~/.config/deepparallel/license")

deepparallel-0.4.0/deepparallel/research/__init__.py

@@ -0,0 +1,6 @@
+"""DeepParallel research demonstrators.
+
+Self-contained, runnable illustrations of the ideas behind DeepParallel's
+multi-model approach. These are optional and depend on numpy; install with
+`pip install deepparallel[research]`.
+"""

deepparallel-0.4.0/deepparallel/research/conduit.py

@@ -0,0 +1,156 @@
+"""Conduit: latent-state relay between frozen models (runnable demonstrator).
+
+The idea behind DeepParallel's multi-model approach, made concrete. When agents
+collaborate by writing words and reading them back, every hand-off squeezes a
+continuous thought through a single emitted token (~log2(vocab) bits). Conduit
+relays the model's hidden state directly through a tiny connector instead.
+
+This is a dependency-light demonstration of the mechanism and the information
+loss it avoids: two FROZEN synthetic transformers of different hidden sizes (so
+the connector is genuinely required) relay a continuous meaning vector down a
+chain of agents two ways, and we measure how much meaning survives each hop:
+
+    latent : h_i -> connector(W) -> next model    (continuous)
+    word   : h_i -> argmax token -> re-embed       (one discrete symbol)
+
+Needs numpy (`pip install deepparallel[research]`). The full research, including
+the same result on real open-weight models, is at crowelogic.com/research/conduit.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _gelu(x):
+    return 0.5 * x * (1.0 + np.tanh(0.7978845608 * (x + 0.044715 * x**3)))
+
+
+def _ln(x):
+    return (x - x.mean(-1, keepdims=True)) / (x.std(-1, keepdims=True) + 1e-5)
+
+
+def _softmax(x):
+    e = np.exp(x - x.max(-1, keepdims=True))
+    return e / e.sum(-1, keepdims=True)
+
+
+class _FrozenLM:
+    """A tiny frozen decoder-only transformer with its own hidden size + vocab."""
+
+    def __init__(self, vocab, d, n_layers, seed):
+        self.vocab, self.d = vocab, d
+        rng = np.random.default_rng(seed)
+        s = 1.0 / np.sqrt(d)
+        self.E = rng.standard_normal((vocab, d)) * 0.02
+        self.U = rng.standard_normal((d, vocab)) * s
+        self.layers = [
+            {
+                "Wq": rng.standard_normal((d, d)) * s,
+                "Wk": rng.standard_normal((d, d)) * s,
+                "Wv": rng.standard_normal((d, d)) * s,
+                "Wo": rng.standard_normal((d, d)) * s,
+                "W1": rng.standard_normal((d, 4 * d)) * s,
+                "W2": rng.standard_normal((4 * d, d)) * s,
+            }
+            for _ in range(n_layers)
+        ]
+
+    def _forward(self, x):
+        T = x.shape[0]
+        mask = np.triu(np.full((T, T), -1e9), k=1)
+        for p in self.layers:
+            h = _ln(x)
+            q, k, v = h @ p["Wq"], h @ p["Wk"], h @ p["Wv"]
+            att = _softmax(q @ k.T / np.sqrt(self.d) + mask)
+            x = x + (att @ v) @ p["Wo"]
+            x = x + _gelu(_ln(x) @ p["W1"]) @ p["W2"]
+        return x
+
+    def hidden_at(self, in_embed):
+        return self._forward(in_embed.reshape(1, self.d))[-1]
+
+    def next_token(self, hidden):
+        return int(np.argmax(hidden @ self.U))
+
+
+def _ridge(X, Y, lam=1e-2):
+    Xb = np.hstack([X, np.ones((X.shape[0], 1))])
+    return np.linalg.solve(Xb.T @ Xb + lam * np.eye(Xb.shape[1]), Xb.T @ Y)
+
+
+def _affine(W, x):
+    return np.hstack([x, np.ones((x.shape[0], 1))]) @ W
+
+
+class _Conduit:
+    def __init__(self, d_meaning, dims, vocab, seed=7):
+        self.dm = d_meaning
+        rng = np.random.default_rng(seed)
+        self.models = [
+            _FrozenLM(vocab, dims[0], 2, seed + 1),
+            _FrozenLM(vocab, dims[1], 2, seed + 2),
+        ]
+        self.P = [rng.standard_normal((d_meaning, m.d)) * 0.5 for m in self.models]
+        self.conn, self.readout = {}, {}
+
+    def _encode(self, mi, z):
+        return self.models[mi].hidden_at(z @ self.P[mi])
+
+    def _relay(self, z, K, path):
+        mi = 0
+        h = self._encode(mi, z)
+        for hop in range(1, K + 1):
+            mj = hop % len(self.models)
+            if path == "latent":
+                in_embed = _affine(self.conn[(mi, mj)], h.reshape(1, -1))[0]
+            else:
+                tok = self.models[mi].next_token(h)
+                in_embed = self.models[mj].E[tok]
+            h = self.models[mj].hidden_at(in_embed)
+            mi = mj
+        return h, mi
+
+    def fit(self, n_train, fit_hops, seed=0):
+        rng = np.random.default_rng(seed)
+        Z = rng.standard_normal((n_train, self.dm))
+        n = len(self.models)
+        for i in range(n):
+            Hi = np.array([self._encode(i, z) for z in Z])
+            for j in range(n):
+                self.conn[(i, j)] = _ridge(Hi, Z @ self.P[j])
+        for path in ("latent", "word"):
+            finals = {0: [], 1: []}
+            targets = {0: [], 1: []}
+            for K in fit_hops:
+                for z in Z:
+                    h, m = self._relay(z, K, path)
+                    finals[m].append(h)
+                    targets[m].append(z)
+            for m in finals:
+                if finals[m]:
+                    self.readout[(path, m)] = _ridge(np.array(finals[m]), np.array(targets[m]))
+
+    def recover(self, z, K, path):
+        h, m = self._relay(z, K, path)
+        return _affine(self.readout[(path, m)], h.reshape(1, -1))[0]
+
+
+def _cos(a, b):
+    return float(a @ b / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-9))
+
+
+def demonstrate(hops=(1, 2, 4, 6, 8)) -> dict:
+    """Run the relay both ways and return meaning retained per hop count."""
+    d_meaning, vocab = 16, 256
+    link = _Conduit(d_meaning, dims=[32, 48], vocab=vocab)
+    link.fit(n_train=800, fit_hops=hops)
+    rng = np.random.default_rng(123)
+    test = rng.standard_normal((300, d_meaning))
+    out = {"latent": {}, "word": {}, "meaning_dim": d_meaning, "vocab": vocab, "hops": list(hops)}
+    for path in ("latent", "word"):
+        for K in hops:
+            out[path][K] = round(
+                float(np.mean([_cos(z, link.recover(z, K, path)) for z in test])), 3
+            )
+    return out