agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/image_perturb.py

@@ -0,0 +1,241 @@
+"""Phase 9B unit 1b — pure-numpy seeded image perturbation operators (the image
+analogue of 9A's ``live/_perturb.py`` acoustic operators).
+
+ARCH-9B §2.1 / decision 9B-A1b (companion module home — substrate not loop),
+9B-A6 (PURE-NUMPY v1, ZERO new dep — settles Open Q4).
+
+MANDATORY (9B-A6): imports are **numpy + stdlib ONLY**. There is NO Pillow, no
+scipy, no cv2, no imageio, no scikit-image — verified ``pyproject.toml`` carries
+only ``numpy>=1.26.4``. Adding Pillow for the perturbation set would be a NEW
+dependency + a license-audit obligation on the public repo's Apache-2.0 posture.
+The kit's live substrate already imports numpy directly. A true-libjpeg or
+PNG-render path is a NAMED post-v1 Pillow extra, auto-skip when absent, never a
+v1 gate dependency.
+
+Operators are deterministic under a recorded seed so stressed runs replay
+byte-identically (the determinism the gate re-asserts). Each operates on a numpy
+``uint8`` raster (H x W x C) and is computed as a paired clean-vs-stressed delta
+(the ``_perturb.apply_text_perturbations`` discipline).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+import numpy as np
+
+# closed set; analogue of _perturb.py PERTURBATION_OPERATORS. All pure-numpy, all
+# deterministic-under-seed. apply_image_perturbations RAISES for any operator not
+# in this set (the _perturb.py raise-wall pattern generalized).
+V1_IMAGE_PERTURBATION_OPERATORS = ("blur", "jpeg_compress", "resolution_drop", "occlusion")
+
+
+class ImagePerturbationError(ValueError):
+    """Raised for an unknown operator or a mis-shaped raster (a contract error —
+    the _perturb.py raise-wall analogue). A ``ValueError`` subclass."""
+
+
+def _require_raster(raster: Any, *, where: str) -> np.ndarray:
+    """Type-guard the input as a numpy ``uint8`` H x W x C raster. A non-uint8 /
+    non-3D input raises ``ImagePerturbationError`` — we never silently
+    mis-shape."""
+
+    if not isinstance(raster, np.ndarray):
+        raise ImagePerturbationError(
+            f"{where} needs a numpy uint8 H x W x C raster; got {type(raster).__name__}"
+        )
+    if raster.ndim != 3:
+        raise ImagePerturbationError(
+            f"{where} needs a 3-D (H x W x C) raster; got ndim={raster.ndim}"
+        )
+    if raster.dtype != np.uint8:
+        raise ImagePerturbationError(
+            f"{where} needs a uint8 raster; got dtype={raster.dtype}"
+        )
+    return raster
+
+
+def blur(raster: np.ndarray, *, kernel_radius: int = 1, seed: int = 0) -> np.ndarray:
+    """Separable box-kernel blur as a numpy stride convolution (no scipy). A box
+    average over a ``(2*kernel_radius+1)`` window, applied separably across rows
+    then columns with edge replication. Deterministic (no rng draw); the ``seed``
+    is accepted for a uniform operator signature."""
+
+    arr = _require_raster(raster, where="blur").astype(np.float64)
+    radius = max(int(kernel_radius), 0)
+    if radius == 0:
+        return arr.astype(np.uint8)
+    width = 2 * radius + 1
+
+    def _box_axis(data: np.ndarray, axis: int) -> np.ndarray:
+        padded = np.pad(
+            data,
+            [(radius, radius) if a == axis else (0, 0) for a in range(data.ndim)],
+            mode="edge",
+        )
+        acc = np.zeros_like(data)
+        for offset in range(width):
+            sl = [slice(None)] * data.ndim
+            sl[axis] = slice(offset, offset + data.shape[axis])
+            acc = acc + padded[tuple(sl)]
+        return acc / float(width)
+
+    out = _box_axis(_box_axis(arr, 0), 1)
+    return np.clip(np.rint(out), 0, 255).astype(np.uint8)
+
+
+def jpeg_compress(raster: np.ndarray, *, quality: int = 50, seed: int = 0) -> np.ndarray:
+    """Block-DCT quantization approximation in pure numpy (8x8 DCT-II matrices +
+    a quality-keyed quant table). A true libjpeg path is the post-v1 Pillow extra
+    (auto-skip). Deterministic (no rng draw); ``seed`` accepted for a uniform
+    signature."""
+
+    arr = _require_raster(raster, where="jpeg_compress").astype(np.float64)
+    q = int(np.clip(quality, 1, 100))
+    # the standard JPEG quality -> scale heuristic.
+    if q < 50:
+        scale = 5000.0 / q
+    else:
+        scale = 200.0 - 2.0 * q
+    quant = max(1.0, scale / 16.0)  # a single flat quantization step (luma-ish)
+
+    n = 8
+    k = np.arange(n)
+    # DCT-II orthonormal basis (8x8), built deterministically.
+    basis = np.cos(np.pi * (2 * k[:, None] + 1) * k[None, :] / (2 * n))
+    basis *= np.sqrt(2.0 / n)
+    basis[0, :] = np.sqrt(1.0 / n)
+    # basis[i, x] applies the i-th cosine over sample x; forward = basis @ block.
+
+    h, w, c = arr.shape
+    pad_h = (-h) % n
+    pad_w = (-w) % n
+    padded = np.pad(arr, ((0, pad_h), (0, pad_w), (0, 0)), mode="edge")
+
+    out = np.empty_like(padded)
+    for ch in range(c):
+        plane = padded[:, :, ch] - 128.0
+        for r0 in range(0, padded.shape[0], n):
+            for c0 in range(0, padded.shape[1], n):
+                block = plane[r0:r0 + n, c0:c0 + n]
+                coeffs = basis @ block @ basis.T
+                quantized = np.round(coeffs / quant) * quant
+                restored = basis.T @ quantized @ basis
+                out[r0:r0 + n, c0:c0 + n, ch] = restored + 128.0
+
+    out = out[:h, :w, :]
+    return np.clip(np.rint(out), 0, 255).astype(np.uint8)
+
+
+def resolution_drop(raster: np.ndarray, *, scale: float = 0.5, seed: int = 0) -> np.ndarray:
+    """numpy decimate -> upsample (nearest), the band-limit analogue (the
+    ``resample_8k`` analogue from voice). Downscale by ``scale`` then nearest-
+    neighbour back to the original shape, destroying high-frequency detail.
+    Deterministic (no rng draw); ``seed`` accepted for a uniform signature."""
+
+    arr = _require_raster(raster, where="resolution_drop")
+    s = float(scale)
+    if not 0.0 < s < 1.0:
+        # scale outside (0,1) is a no-op (full resolution).
+        return arr.copy()
+    h, w, _ = arr.shape
+    small_h = max(1, int(round(h * s)))
+    small_w = max(1, int(round(w * s)))
+    # deterministic nearest-neighbour decimation.
+    row_idx = (np.arange(small_h) * (h / small_h)).astype(np.int64)
+    col_idx = (np.arange(small_w) * (w / small_w)).astype(np.int64)
+    small = arr[np.ix_(row_idx, col_idx, np.arange(arr.shape[2]))]
+    # nearest-neighbour upsample back to (h, w).
+    up_rows = (np.arange(h) * (small_h / h)).astype(np.int64)
+    up_cols = (np.arange(w) * (small_w / w)).astype(np.int64)
+    up = small[np.ix_(up_rows, up_cols, np.arange(arr.shape[2]))]
+    return up.astype(np.uint8)
+
+
+def occlusion(raster: np.ndarray, *, coverage: float = 0.2, seed: int = 0) -> np.ndarray:
+    """Seeded rectangular mask zeroing a region (``np.random.default_rng(seed)``).
+    The mask covers approximately ``coverage`` of the area; its position is keyed
+    on the seed so a re-run is byte-identical."""
+
+    arr = _require_raster(raster, where="occlusion").copy()
+    cov = float(np.clip(coverage, 0.0, 1.0))
+    if cov <= 0.0:
+        return arr
+    h, w, _ = arr.shape
+    rng = np.random.default_rng(seed)
+    side = float(np.sqrt(cov))
+    box_h = max(1, int(round(h * side)))
+    box_w = max(1, int(round(w * side)))
+    top = int(rng.integers(0, max(1, h - box_h + 1)))
+    left = int(rng.integers(0, max(1, w - box_w + 1)))
+    arr[top:top + box_h, left:left + box_w, :] = 0
+    return arr
+
+
+_OPERATOR_FNS = {
+    "blur": blur,
+    "jpeg_compress": jpeg_compress,
+    "resolution_drop": resolution_drop,
+    "occlusion": occlusion,
+}
+
+
+def perturbations_stanza(
+    applied: Sequence[Mapping[str, Any]],
+    *,
+    seed: int,
+    paired_clean_run: str | None = None,
+) -> dict[str, Any]:
+    """The applied-operator stanza (the ``_perturb.perturbations_stanza``
+    analogue): operator list, recorded seed, and the clean-twin link (deltas
+    render upstream)."""
+
+    return {
+        "operators": [dict(record) for record in applied],
+        "seed": seed,
+        "paired_clean_run": paired_clean_run,
+    }
+
+
+def apply_image_perturbations(
+    raster: np.ndarray,
+    *,
+    operators: Sequence[str],
+    seed: int = 0,
+    params: Mapping[str, Any] | None = None,
+    paired_clean_run: str | None = None,
+) -> dict[str, Any]:
+    """Walk the operator list applying each with ``seed + index`` (the
+    ``_perturb.apply_text_perturbations`` pattern). Returns
+    ``{"raster": np.ndarray, "stanza": {...}, "paired_clean_run": <ref>}``.
+
+    The stanza mirrors ``perturbations_stanza`` — the applied-operator list + the
+    ``paired_clean_run`` link. The ``WorldSpec.perturbation_profile`` field
+    (contract.py:214) carries the profile LABEL on the stressed run.
+
+    RAISES ``ImagePerturbationError`` for any operator not in
+    ``V1_IMAGE_PERTURBATION_OPERATORS`` (a contract error — the raise-wall).
+
+    DETERMINISM (the gate asserts this, unit 5): same raster + same operators +
+    same seed => byte-identical output raster. No wall-clock, no randomness
+    outside the keyed rng."""
+
+    out = _require_raster(raster, where="apply_image_perturbations").copy()
+    params = dict(params or {})
+    applied: list[dict[str, Any]] = []
+    for index, operator in enumerate(operators):
+        if operator not in V1_IMAGE_PERTURBATION_OPERATORS:
+            raise ImagePerturbationError(
+                f"unknown perturbation operator {operator!r}; "
+                f"expected one of {V1_IMAGE_PERTURBATION_OPERATORS}"
+            )
+        op_seed = seed + index
+        op_params = dict(params.get(operator) or {})
+        out = _OPERATOR_FNS[operator](out, seed=op_seed, **op_params)
+        applied.append({"operator": operator, "seed": op_seed, **op_params})
+
+    return {
+        "raster": out,
+        "stanza": perturbations_stanza(applied, seed=seed, paired_clean_run=paired_clean_run),
+        "paired_clean_run": paired_clean_run,
+    }

fi/alk/improve.py

@@ -0,0 +1,274 @@
+"""Code-level RSI — fix a framework agent's actual CODE by run→trace→diagnose→
+patch→re-run→keep-if-better-on-held-out.
+
+The general self-improvement model: the `update` ACTION is a CODE EDIT (not a
+config patch). The loop runs the framework agent's real source in sim, reads the
+trace + the (discriminating, objective-anchored) eval, asks a proposer to PATCH
+the source to fix the failure, applies the patch in an ISOLATED workdir, re-runs
+on HELD-OUT tasks, and accepts ONLY if held-out improves AND a regression split
+does not drop (no-forgetting). Reuses the proven run→eval foundation
+(run_benchmark + objective_score); the genuinely new surface is exactly two
+things — propose-a-code-edit and sandboxed re-run — both isolated here.
+
+SAFETY (the code_exec verdict-#4 line holds): a code patch is LLM-AUTHORED code
+run automatically in a loop. The patched source is written to an isolated temp
+workdir and the agent is pointed at it by ABSOLUTE path — a bad mutation NEVER
+touches the caller's real file unless the caller explicitly writes back an
+accepted patch. Each candidate run is wall-clock bounded. This is for optimizing
+a TRUSTED agent's own source; arbitrary untrusted code execution remains the
+parked code_exec concern (needs a real sandbox).
+
+OVERCLAIM GUARD: "improved" = held-out bug-class tasks pass on the DETERMINISTIC
+anchor (e.g. tool_calls / completion_without_effort) the loop never optimized
+directly, AND the regression split is not worse. A code-RSI loop is the most
+gameable thing in the kit — never accept on the metric it edited toward.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+from .tasks import run_benchmark
+
+AGENT_LEARNING_CODE_RSI_REPORT_KIND = "agent-learning.code-rsi-report.v1"
+
+# a proposer maps a diagnosis -> new full source text (or None to give up).
+PatchProposer = Callable[[Mapping[str, Any]], "str | None"]
+
+
+def _agent_for_source(source_path: Path, symbol: str) -> dict[str, Any]:
+    """A python-callable agent pointed at a source file by ABSOLUTE path (so the
+    patched copy loads, never the caller's original)."""
+    return {"type": "python", "callable": f"{source_path.resolve()}:{symbol}"}
+
+
+def _score_split(
+    source_path: Path,
+    symbol: str,
+    dataset: Mapping[str, Any],
+    split: str | None,
+    *,
+    seed: int,
+    runner: Any = None,
+) -> dict[str, Any]:
+    agent = _agent_for_source(source_path, symbol)
+    # detector-aware: a candidate that GAMES the scorer (claims completion with no
+    # tool calls on a tool-anchored objective) is FAILED — the deterministic
+    # anti-gaming anchor the objective alone misses. This is what makes the
+    # no-tool bug detectable and prevents the loop accepting a reward-hacking patch.
+    # emit_telemetry=False: the RSI loop emits ONE run (in improve_agent_code),
+    # not one per split-score across rounds (Phase 14).
+    res = run_benchmark(dataset, agent, split=split, seed=seed,
+                        evidence_class="captured_fixture", detect_reward_hacks=True,
+                        runner=runner, emit_telemetry=False)
+    return res["aggregate"], res["per_task"]
+
+
+def _failing(per_task: Sequence[Mapping[str, Any]]) -> list[dict]:
+    return [dict(r) for r in per_task if r.get("verdict") != "pass"]
+
+
+def _write_source(workdir: Path, version: int, text: str) -> Path:
+    p = workdir / f"agent_v{version}.py"
+    p.write_text(text, encoding="utf-8")
+    return p
+
+
+def improve_agent_code(
+    *,
+    source_text: str,
+    symbol: str,
+    dataset: Mapping[str, Any],
+    propose_patch: PatchProposer,
+    objective: Mapping[str, Any],
+    train_split: str = "train",
+    test_split: str = "test",
+    regression_split: str | None = "regression",
+    max_rounds: int = 3,
+    threshold: float = 0.5,
+    seed: int = 42,
+    runner: Any = None,
+    emit_telemetry: bool = True,
+    project_name: str | None = None,
+) -> dict[str, Any]:
+    """Run the code-level RSI loop on ``source_text`` (a module defining ``symbol``)
+    against ``dataset`` (needs ``train``/``test`` splits; ``regression`` optional).
+
+    Returns a report: baseline vs accepted held-out scores, the accepted patch (or
+    None), per-round attempts, and the no-forgetting (regression) result. The
+    caller decides whether to write an accepted patch back to the real file."""
+
+    splits = dataset.get("splits") or {}
+    if not splits.get(train_split) or not splits.get(test_split):
+        raise ValueError("dataset needs both train and test splits for code-RSI")
+    has_regression = bool(regression_split and splits.get(regression_split))
+
+    with tempfile.TemporaryDirectory(prefix="agent-code-rsi-") as tmp:
+        workdir = Path(tmp)
+        cur = _write_source(workdir, 0, source_text)
+
+        base_test, _ = _score_split(cur, symbol, dataset, test_split, seed=seed, runner=runner)
+        base_reg = None
+        if has_regression:
+            base_reg, _ = _score_split(cur, symbol, dataset, regression_split, seed=seed, runner=runner)
+
+        rounds: list[dict[str, Any]] = []
+        accepted_text: str | None = None
+        cur_text = source_text
+        prior_attempts: list[dict[str, Any]] = []  # fed back so the loop LEARNS
+
+        train_agg, train_per = _score_split(cur, symbol, dataset, train_split, seed=seed, runner=runner)
+        for rnd in range(max_rounds):
+            failing = _failing(train_per)
+            if not failing:
+                rounds.append({"round": rnd, "status": "no_bug_on_train", "train_pass_rate": train_agg["pass_rate"]})
+                break
+
+            diagnosis = {
+                "current_source": cur_text,
+                "symbol": symbol,
+                "objective": objective,
+                "failing_examples": [
+                    {"task_id": f.get("task_id"), "score": f.get("score"),
+                     "metric_averages": f.get("metric_averages"),
+                     "tool_calls": len(f.get("tool_calls") or []),
+                     "rewardhack": f.get("rewardhack"), "error": f.get("error")}
+                    for f in failing
+                ],
+                # the RSI signal: prior rejected patches + WHY (execution errors /
+                # no-lift), so the next proposal does not repeat the mistake.
+                "prior_attempts": prior_attempts,
+                "signal": "failing tasks; check tool use / completion-without-effort",
+            }
+            new_text = propose_patch(diagnosis)
+            if not new_text or new_text == cur_text:
+                rounds.append({"round": rnd, "status": "no_patch_proposed"})
+                break
+
+            cand = _write_source(workdir, rnd + 1, new_text)
+            cand_train, cand_train_per = _score_split(cand, symbol, dataset, train_split, seed=seed, runner=runner)
+            cand_test, _ = _score_split(cand, symbol, dataset, test_split, seed=seed, runner=runner)
+            cand_reg = None
+            if has_regression:
+                cand_reg, _ = _score_split(cand, symbol, dataset, regression_split, seed=seed, runner=runner)
+
+            held_out_lift = round(cand_test["mean_score"] - base_test["mean_score"], 6)
+            regression_ok = (not has_regression) or (cand_reg["mean_score"] >= base_reg["mean_score"] - 1e-9)
+            accept = held_out_lift > 0 and regression_ok
+            cand_errors = [r.get("error") for r in cand_train_per if r.get("error")]
+
+            rounds.append({
+                "round": rnd, "status": "accepted" if accept else "rejected",
+                "train_lift": round(cand_train["mean_score"] - train_agg["mean_score"], 6),
+                "held_out_lift": held_out_lift,
+                "regression_ok": regression_ok,
+                "held_out_baseline": base_test["mean_score"],
+                "held_out_candidate": cand_test["mean_score"],
+                "candidate_errors": cand_errors[:2],
+            })
+            if accept:
+                accepted_text = new_text
+                cur, cur_text = cand, new_text
+                base_test = cand_test
+                if has_regression:
+                    base_reg = cand_reg
+                break  # one accepted fix per call (vertical); caller can re-invoke
+            # rejected: feed this attempt (source + why it failed) back to the proposer.
+            prior_attempts.append({
+                "patch_excerpt": new_text[:500],
+                "execution_errors": cand_errors[:2],
+                "held_out_lift": held_out_lift,
+                "reason": ("crashed: " + str(cand_errors[0])) if cand_errors else "no held-out improvement",
+            })
+            cur, cur_text, train_agg, train_per = cand, new_text, cand_train, cand_train_per
+
+        report = {
+            "kind": AGENT_LEARNING_CODE_RSI_REPORT_KIND,
+            "fixed": accepted_text is not None,
+            "accepted_source": accepted_text,
+            "held_out_baseline": base_test["mean_score"] if accepted_text is None else rounds[-1]["held_out_baseline"],
+            "held_out_final": base_test["mean_score"],
+            "regression_held": (not has_regression) or all(
+                r.get("regression_ok", True) for r in rounds if r["status"] in ("accepted", "rejected")
+            ),
+            "rounds": rounds,
+        }
+        if emit_telemetry:
+            # ONE dashboard run for the whole code-RSI loop: root + per-round spans
+            # (P14). Side-channel; never alters the report.
+            from .telemetry import emit_run
+
+            lift = round(report["held_out_final"] - report["held_out_baseline"], 6)
+            summary = emit_run(
+                kind="code-rsi",
+                name=symbol,
+                metrics={
+                    "fixed": report["fixed"],
+                    "held_out_baseline": report["held_out_baseline"],
+                    "held_out_final": report["held_out_final"],
+                    "held_out_lift": lift,
+                    "regression_held": report["regression_held"],
+                },
+                verdict="pass" if report["fixed"] and lift > 0 else "fail",
+                children=[
+                    (
+                        f"round:{r['round']}",
+                        {"status": r.get("status"),
+                         "held_out_lift": r.get("held_out_lift"),
+                         "regression_ok": r.get("regression_ok")},
+                    )
+                    for r in rounds
+                ],
+                project_name=project_name,
+            )
+            report["telemetry"] = summary.as_dict()
+        return report
+
+
+def propose_patch_via_llm(model: str = "gpt-4o-mini") -> PatchProposer:
+    """Default proposer: an LLM rewrites the source to fix the diagnosed failure.
+    Conditioned on the current source + failing eval + objective; returns the new
+    full source (no co-authoring of the fix — the model derives it from the
+    trace/eval). Keyed (litellm); credential-free tests use a deterministic
+    proposer instead."""
+
+    def _propose(diagnosis: Mapping[str, Any]) -> str | None:
+        import re
+
+        import litellm
+
+        prior = diagnosis.get("prior_attempts") or []
+        prior_block = (
+            "\n\n=== YOUR PRIOR REJECTED ATTEMPTS (do NOT repeat these mistakes) ===\n"
+            + str(prior)[:800]
+            if prior else ""
+        )
+        prompt = (
+            "You are fixing a Python agent's source code. The agent runs in a "
+            "simulation. Each available tool is on `agent_input.tools` as a dict "
+            "shaped EITHER {\"name\": str, ...} OR {\"type\":\"function\",\"function\":{\"name\":str}} "
+            "— there is NO 'id' key on a tool spec, so read the name defensively "
+            "(`t.get('name') or (t.get('function') or {}).get('name')`) and generate "
+            "your own call id. The function MUST return a dict "
+            "{\"content\": str, \"tool_calls\": [{\"id\": str, \"name\": str, \"arguments\": dict}]}. "
+            "It is FAILING because it does not call the available tool (it fabricates "
+            "an answer). Rewrite the WHOLE source so it calls the first available "
+            "tool by its resolved name with empty arguments and returns that "
+            "tool_call. Keep the same function name. Code must run without KeyError. "
+            "Return ONLY the new Python source — no prose, no markdown fences."
+            + "\n\n=== CURRENT SOURCE ===\n"
+            + str(diagnosis.get("current_source", ""))
+            + "\n\n=== FAILING EVAL (sample) ===\n"
+            + str(diagnosis.get("failing_examples", []))[:600]
+            + prior_block
+        )
+        resp = litellm.completion(
+            model=model, messages=[{"role": "user", "content": prompt}], max_tokens=600,
+        )
+        text = resp.choices[0].message.content or ""
+        text = re.sub(r"^```(?:python)?\n|\n```$", "", text.strip())  # strip fences if any
+        return text or None
+
+    return _propose

fi/alk/live/__init__.py

@@ -0,0 +1,154 @@
+"""Opt-in live framework lanes (Phase 3) — facade only.
+
+Imports NOTHING framework-side: the substrate (contract/runner/transcript/
+stats/attribution/capture) is stdlib+numpy by construction, lane modules
+import frameworks lazily inside function bodies, and ``_workers/`` entry
+modules only ever run as scrubbed-env subprocesses (P3-D1). Lanes are extras
++ env-gated markers, NEVER release prerequisites: every lane entry refuses
+without its ``AGENT_LEARNING_LIVE_<LANE>=1`` flag.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+_SUBMODULES = {
+    "_attribution",
+    "_capture",
+    "_codec",
+    "_contract",
+    "_loopback",
+    "_perturb",
+    "_runner",
+    "_stats",
+    "_transcript",
+    "a2a_lane",
+    "langgraph_lane",
+    "livekit_lane",
+    "mcp_lane",
+    "pipecat_lane",
+    "voice_redteam",
+}
+
+# lane name (LANE_ENV_FLAGS / LANE_EXTRAS key) → (module, entry point)
+LANE_RUNNERS = {
+    "livekit": ("fi.alk.live.livekit_lane", "run_livekit_lane"),
+    "pipecat": ("fi.alk.live.pipecat_lane", "run_pipecat_lane"),
+    "langchain": ("fi.alk.live.langgraph_lane", "run_langgraph_lane"),
+    "mcp": ("fi.alk.live.mcp_lane", "run_mcp_lane"),
+    "a2a": ("fi.alk.live.a2a_lane", "run_a2a_lane"),
+}
+
+# public name → home module (resolved lazily so `import fi.alk.live`
+# stays trivially cheap and provably framework-free)
+_LAZY_EXPORTS = {
+    "AGENT_LEARNING_RUN_KIND": "_contract",
+    "EVIDENCE_CLASSES": "_contract",
+    "RELEASE_ADMISSIBLE_EVIDENCE_CLASSES": "_contract",
+    "FAILURE_LAYERS": "_contract",
+    "VERDICTS": "_contract",
+    "LANE_ENV_FLAGS": "_contract",
+    "LANE_EXTRAS": "_contract",
+    "LANE_BUDGET_S": "_contract",
+    "LANE_BUDGET_S_DEFAULT": "_contract",
+    "DEFAULT_REPEATS": "_contract",
+    "UNSTABLE_ICC_FLOOR": "_contract",
+    "LaneDisabledError": "_contract",
+    "LaneSpec": "_contract",
+    "LaneRun": "_contract",
+    "lane_budget_s": "_contract",
+    "require_lane_enabled": "_contract",
+    "LANE_SAFE_BASE_ENV": "_runner",
+    "LANE_BLOCKED_ENV": "_runner",
+    "LaneProcessResult": "_runner",
+    "scrubbed_lane_env": "_runner",
+    "spawn_lane_subprocess": "_runner",
+    "run_worker_once": "_runner",
+    "version_ok": "_runner",
+    "version_preflight": "_runner",
+    "TranscriptRecorder": "_transcript",
+    "read_transcript": "_transcript",
+    "redact_env_values": "_transcript",
+    "TRANSCRIPT_MAX_BYTES_ENV": "_transcript",
+    "LaneRunResult": "_stats",
+    "run_repeated": "_stats",
+    "lane_run_payload": "_stats",
+    "icc_and_within_variance": "_stats",
+    "divergence_step": "_stats",
+    "determinism_metrics": "_stats",
+    "derive_channel_evidence": "_stats",
+    "FailureAttribution": "_attribution",
+    "attribute_failure": "_attribution",
+    "CaptureRefusedError": "_capture",
+    "CAPTURE_PROVENANCE_FIELDS": "_capture",
+    "capture_to_fixture": "_capture",
+    "replay_fixture": "_capture",
+    "run_voice_escalation_campaign": "voice_redteam",
+    "compile_arc_turns": "voice_redteam",
+    "timing_fidelity": "voice_redteam",
+    "validate_authorization": "voice_redteam",
+    "VoiceAuthorizationError": "voice_redteam",
+    # Phase-12 12C rung-2: acoustic operators over the loopback PCM channel.
+    "apply_acoustic_perturbations": "_perturb",
+    "apply_reverb_blend": "_perturb",
+    "ACOUSTIC_RUNG_OPERATORS": "_perturb",
+    # Phase 9A: codec-survival facade (9A-A12, home _codec) + loopback runner
+    "score_codec_survival": "_codec",
+    "CodecUnsupportedError": "_codec",
+    "run_loopback_roundtrip": "_loopback",
+    "LoopbackFixtureMissing": "_loopback",
+}
+
+
+def run_lane(lane: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
+    """Dispatch to a lane's entry point by name (the CLI front door's hook).
+
+    The lane module is imported lazily; its entry calls
+    ``require_lane_enabled`` first, so a missing env flag refuses before any
+    framework import is attempted.
+    """
+
+    try:
+        module_name, entry_name = LANE_RUNNERS[lane]
+    except KeyError:
+        known = ", ".join(sorted(LANE_RUNNERS))
+        raise ValueError(f"unknown live lane {lane!r}; expected one of: {known}")
+    module = importlib.import_module(module_name)
+    entry = getattr(module, entry_name)
+    return entry(*args, **kwargs)
+
+
+def capture_fixture(*args: Any, **kwargs: Any) -> Any:
+    """Live→fixture demotion (see ``_capture.capture_to_fixture``)."""
+
+    from ._capture import capture_to_fixture as _capture_to_fixture
+
+    return _capture_to_fixture(*args, **kwargs)
+
+
+def __getattr__(name: str) -> Any:
+    if name in _SUBMODULES:
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    if name in _LAZY_EXPORTS:
+        module = importlib.import_module(
+            f"{__name__}.{_LAZY_EXPORTS[name]}"
+        )
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_SUBMODULES, *_LAZY_EXPORTS})
+
+
+__all__ = [
+    "LANE_RUNNERS",
+    "capture_fixture",
+    "run_lane",
+    *sorted(_LAZY_EXPORTS),
+]