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

fi/alk/bench/_grader.py

@@ -0,0 +1,286 @@
+"""Command/artifact-graded coding lane — the hardened coding tier.
+
+This resolves the in-process forge/oracle-read weakness of the ``check_*`` lane by
+changing the *model*, not bolting on isolation. A task gives the candidate a
+working directory + a way to RUN it; a **held-out grader** runs AFTERWARD and
+emits the verdict via its **exit code + a reward file in a grader-controlled
+path** — never parsed from candidate-shared stdout.
+
+Why this is robust (the two vulns from the PR review, structurally closed):
+
+* **No verdict forgery** — the verdict is the grader's exit code (and an optional
+  ``reward.json`` the grader writes), not anything the candidate prints.
+* **No oracle read** — the grader files (held-out expected values / tests) are
+  written ONLY after the candidate command has finished and its processes are
+  killed. The candidate never co-runs with the grader, so it cannot read the
+  expected values; and in the Docker lane the grader files are owned by a
+  different user the candidate uid cannot read.
+
+It also gives **multi-language for free**: the candidate ``build`` command and the
+``grader`` command are arbitrary shell, so the same lane grades Python, bash,
+Node, compiled languages, etc.
+
+Two sandboxes share one flow (temporal separation candidate→grader):
+  * ``subprocess`` — candidate + grader run as host subprocesses in *separate*
+    temp dirs; the grader dir path is given only to the grader. Credential-free,
+    Docker-free; used by the release gate on trusted shipped tasks.
+  * ``docker`` — a per-task, network-off, capped, ephemeral container; candidate
+    runs as an unprivileged uid, grader files land in a root-owned dir the
+    candidate cannot read. The hardened lane for untrusted agent output.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Any, Mapping
+
+from ._codeexec import _empty_result, _tail
+
+GRADING_COMMAND = "command"  # suite/task grading mode discriminator
+_DEFAULT_TIMEOUT_S = 20.0
+_REWARD_FILE = "reward.json"
+
+
+def _files(value: Any) -> dict[str, str]:
+    """Coerce a {path: content} mapping to str->str (defensive)."""
+
+    if not isinstance(value, Mapping):
+        return {}
+    return {str(k): str(v) for k, v in value.items()}
+
+
+def _write_tree(root: Path, files: Mapping[str, str]) -> None:
+    for rel, content in files.items():
+        dest = root / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+
+
+def _result_from_grader(
+    rc: int | None, reward: Mapping[str, Any] | None, raw: dict[str, Any]
+) -> dict[str, Any]:
+    """Build the unified Result from the grader's exit code + optional reward.json.
+
+    Verdict authority: the grader's exit code (0 = pass). If the grader also wrote
+    a ``reward.json`` with a numeric ``score`` in [0,1], that becomes the scalar;
+    otherwise the scalar is 1.0/0.0 from the exit code. Sub-check booleans, if the
+    grader reports a ``checks`` map, flow into ``pass_fail``.
+    """
+
+    passed = rc == 0
+    scalar: float
+    pass_fail: dict[str, bool] = {}
+    explanation = f"grader exit {rc}"
+    if isinstance(reward, Mapping):
+        score = reward.get("score")
+        if isinstance(score, (int, float)) and not isinstance(score, bool):
+            scalar = round(float(score), 6)
+        else:
+            scalar = 1.0 if passed else 0.0
+        checks = reward.get("checks")
+        if isinstance(checks, Mapping):
+            pass_fail = {str(k): bool(v) for k, v in checks.items()}
+        if reward.get("explanation"):
+            explanation = str(reward["explanation"])
+    else:
+        scalar = 1.0 if passed else 0.0
+    if not pass_fail:
+        pass_fail = {"grader": passed}
+    return {
+        "result": {
+            "scalar": scalar,
+            "components": {"grader_exit_ok": 1.0 if passed else 0.0},
+            "pass_fail": pass_fail,
+            "explanation": explanation,
+        },
+        "raw": raw,
+    }
+
+
+def run_command_graded(
+    task: Mapping[str, Any],
+    candidate_files: Mapping[str, str],
+    *,
+    sandbox: str = "subprocess",
+    timeout_s: float = _DEFAULT_TIMEOUT_S,
+) -> dict[str, Any]:
+    """Grade ``candidate_files`` for a command-graded ``task``.
+
+    Returns ``{"result", "raw"}``. Never raises for infra problems (missing Docker,
+    grader crash) — those surface as a failing/infra Result, tagged
+    ``raw["infra_error"]`` when the lane could not run at all.
+    """
+
+    if sandbox == "docker":
+        from ._docker import docker_available
+
+        if not docker_available():
+            return _empty_result(
+                "docker unavailable (no daemon / not installed)",
+                {"sandbox": "docker", "grading": GRADING_COMMAND, "infra_error": True},
+            )
+        return _run_docker_graded(task, candidate_files, timeout_s=timeout_s)
+    if sandbox != "subprocess":
+        return _empty_result(
+            f"unknown sandbox {sandbox!r}; expected 'subprocess' or 'docker'",
+            {"sandbox": sandbox, "grading": GRADING_COMMAND, "infra_error": True},
+        )
+    return _run_subprocess_graded(task, candidate_files, timeout_s=timeout_s)
+
+
+def _run_subprocess_graded(
+    task: Mapping[str, Any], candidate_files: Mapping[str, str], *, timeout_s: float
+) -> dict[str, Any]:
+    build = task.get("build")
+    grader_cmd = str(task.get("grader_cmd") or "")
+    if not grader_cmd:
+        return _empty_result("task has no grader_cmd", {"sandbox": "subprocess", "infra_error": True})
+
+    raw: dict[str, Any] = {"sandbox": "subprocess", "grading": GRADING_COMMAND, "timed_out": False}
+    with tempfile.TemporaryDirectory(prefix="bench-work-") as work_s, \
+            tempfile.TemporaryDirectory(prefix="bench-grader-") as grader_s:
+        work = Path(work_s)
+        grader = Path(grader_s)
+        _write_tree(work, {**_files(task.get("files")), **dict(candidate_files)})
+
+        # PHASE 1 — candidate runs with NO grader present (temporal hold-out).
+        if build:
+            try:
+                proc = subprocess.run(
+                    ["sh", "-c", str(build)], cwd=str(work), capture_output=True,
+                    text=True, timeout=timeout_s,
+                )
+                raw["build_exit"] = proc.returncode
+                raw["build_stdout_tail"] = _tail(proc.stdout)
+            except subprocess.TimeoutExpired:
+                raw["timed_out"] = True
+                return _empty_result(f"candidate build timed out after {timeout_s}s", raw)
+
+        # PHASE 2 — grader written AFTER, in a dir the candidate phase never knew.
+        _write_tree(grader, _files(task.get("grader_files")))
+        # The subprocess lane is the trusted/gate tier (not a security boundary —
+        # the Docker lane is), so the grader gets a usable PATH to resolve
+        # interpreters; GRADER_DIR points it at its held-out files.
+        env = {
+            "PATH": os.environ.get("PATH", "/usr/bin:/bin:/usr/local/bin"),
+            "GRADER_DIR": str(grader),
+            "HOME": os.environ.get("HOME", str(work)),
+        }
+        try:
+            gproc = subprocess.run(
+                ["sh", "-c", grader_cmd], cwd=str(work), capture_output=True,
+                text=True, timeout=timeout_s, env=env,
+            )
+        except subprocess.TimeoutExpired:
+            raw["timed_out"] = True
+            return _empty_result(f"grader timed out after {timeout_s}s", raw)
+        raw["grader_exit"] = gproc.returncode
+        raw["grader_stdout_tail"] = _tail(gproc.stdout)
+        raw["grader_stderr_tail"] = _tail(gproc.stderr)
+
+        reward = _read_reward(grader / _REWARD_FILE)
+        return _result_from_grader(gproc.returncode, reward, raw)
+
+
+def _read_reward(path: Path) -> dict[str, Any] | None:
+    try:
+        if path.exists():
+            return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return None
+
+
+# ---- Docker command-graded lane (hardened, opt-in) ----
+
+_DOCKER_IMAGE = "python:3.11-slim"
+
+
+def _docker(*args: str, timeout: float = 30.0) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["docker", *args], capture_output=True, text=True, timeout=timeout
+    )
+
+
+def _run_docker_graded(
+    task: Mapping[str, Any], candidate_files: Mapping[str, str], *, timeout_s: float
+) -> dict[str, Any]:
+    build = task.get("build")
+    grader_cmd = str(task.get("grader_cmd") or "")
+    image = str(task.get("image") or _DOCKER_IMAGE)
+    if not grader_cmd:
+        return _empty_result("task has no grader_cmd", {"sandbox": "docker", "infra_error": True})
+
+    name = f"agent-learn-grade-{uuid.uuid4().hex[:12]}"
+    raw: dict[str, Any] = {
+        "sandbox": "docker", "grading": GRADING_COMMAND, "image": image,
+        "network": "none", "container": name, "timed_out": False,
+    }
+    with tempfile.TemporaryDirectory(prefix="bench-docker-") as host_s:
+        host = Path(host_s)
+        work_host = host / "work"
+        grader_host = host / "grader"
+        _write_tree(work_host, {**_files(task.get("files")), **dict(candidate_files)})
+        _write_tree(grader_host, _files(task.get("grader_files")))
+
+        started = _docker(
+            "run", "-d", "--rm", "--name", name, "--network", "none",
+            "--memory", "512m", "--cpus", "1.0", "--pids-limit", "256",
+            "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
+            image, "sleep", str(int(timeout_s * 2 + 60)),
+        )
+        if started.returncode != 0:
+            raw["infra_error"] = True
+            return _empty_result(
+                f"docker run failed: {_tail(started.stderr, 300)}", raw
+            )
+        try:
+            # candidate user + dirs; /work candidate-writable, /grader root-only.
+            _docker("exec", name, "sh", "-c",
+                    "id cand 2>/dev/null || useradd -M -s /usr/sbin/nologin cand; "
+                    "mkdir -p /work /grader")
+            _docker("cp", f"{work_host}/.", f"{name}:/work")
+            _docker("exec", name, "sh", "-c", "chown -R cand:cand /work && chmod 700 /grader")
+
+            # PHASE 1 — candidate runs as `cand`, no grader files present yet.
+            if build:
+                try:
+                    b = _docker("exec", "-u", "cand", "-w", "/work", name,
+                                "sh", "-c", str(build), timeout=timeout_s + 15)
+                    raw["build_exit"] = b.returncode
+                    raw["build_stdout_tail"] = _tail(b.stdout)
+                except subprocess.TimeoutExpired:
+                    raw["timed_out"] = True
+                    return _empty_result(f"candidate build timed out after {timeout_s}s", raw)
+
+            # kill any lingering candidate processes before grading.
+            _docker("exec", name, "sh", "-c", "pkill -u cand 2>/dev/null || true")
+
+            # PHASE 2 — inject grader (root-owned, unreadable to cand), run as root.
+            _docker("cp", f"{grader_host}/.", f"{name}:/grader")
+            _docker("exec", name, "sh", "-c", "chown -R root:root /grader && chmod -R go-rwx /grader")
+            try:
+                g = _docker("exec", "-w", "/work", name, "sh", "-c",
+                            f"export GRADER_DIR=/grader; {grader_cmd}", timeout=timeout_s + 15)
+            except subprocess.TimeoutExpired:
+                raw["timed_out"] = True
+                return _empty_result(f"grader timed out after {timeout_s}s", raw)
+            raw["grader_exit"] = g.returncode
+            raw["grader_stdout_tail"] = _tail(g.stdout)
+            raw["grader_stderr_tail"] = _tail(g.stderr)
+
+            cat = _docker("exec", name, "sh", "-c", "cat /grader/reward.json 2>/dev/null || true")
+            reward: dict[str, Any] | None = None
+            if cat.stdout.strip():
+                try:
+                    reward = json.loads(cat.stdout)
+                except json.JSONDecodeError:
+                    reward = None
+            return _result_from_grader(g.returncode, reward, raw)
+        finally:
+            _docker("rm", "-f", name)

fi/alk/bench/_pull.py

@@ -0,0 +1,212 @@
+"""Pull / RL control mode — the AGENT drives a live environment via reset/step.
+
+The push lane has the harness drive the agent; artifact-in scores a submitted
+artifact. **Pull** inverts control: the agent is a policy ``obs -> action`` that
+steps an environment until done, and the score is the environment's reward. This
+is the Gym/OpenEnv shape, run live (not replayed).
+
+Deep-contract + simulated: the environments here are deterministic, in-process,
+credential-free simulators (so the lane is fully gate-verifiable). A *live*
+external env server (an HTTP step/reset endpoint) is the same contract with a
+network transport and is deferred to owner infra — it plugs in as another
+``Environment`` without changing the driver or the unified Result.
+
+An environment implements:
+  * ``reset(spec) -> (state, obs)``
+  * ``step(state, action) -> (state, obs, reward, done, info)``
+  * ``optimal_action(obs) -> action``  — a reference policy (proves solvability)
+  * ``actions`` — the discrete action set
+
+A policy is a callable ``obs -> action`` or a spec dict: ``{"type": "reference"}``
+(the env's optimal policy) or ``{"type": "noop"}`` (always the first action).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Protocol
+
+
+class Environment(Protocol):
+    actions: tuple[str, ...]
+
+    def reset(self, spec: Mapping[str, Any]) -> tuple[dict, dict]: ...
+    def step(self, state: dict, action: str) -> tuple[dict, dict, float, bool, dict]: ...
+    def optimal_action(self, obs: Mapping[str, Any]) -> str: ...
+
+
+class ReachTargetEnv:
+    """1-D navigation: move toward ``target`` from ``start`` within ``max_steps``.
+
+    obs = {pos, target, remaining}. Reward 1.0 the step the agent lands on target
+    (then done); 0.0 otherwise. Deterministic + trivially verifiable; the optimal
+    policy is "step toward target".
+    """
+
+    actions: tuple[str, ...] = ("left", "right", "stay")
+
+    def reset(self, spec: Mapping[str, Any]) -> tuple[dict, dict]:
+        state = {
+            "pos": int(spec.get("start", 0)),
+            "target": int(spec.get("target", 5)),
+            "steps": 0,
+            "max_steps": int(spec.get("max_steps", 20)),
+        }
+        return state, self._obs(state)
+
+    def step(self, state: dict, action: str) -> tuple[dict, dict, float, bool, dict]:
+        state = dict(state)
+        state["pos"] += {"left": -1, "right": 1, "stay": 0}.get(action, 0)
+        state["steps"] += 1
+        reached = state["pos"] == state["target"]
+        done = reached or state["steps"] >= state["max_steps"]
+        reward = 1.0 if reached else 0.0
+        return state, self._obs(state), reward, done, {"reached": reached}
+
+    def optimal_action(self, obs: Mapping[str, Any]) -> str:
+        if obs["pos"] < obs["target"]:
+            return "right"
+        if obs["pos"] > obs["target"]:
+            return "left"
+        return "stay"
+
+    @staticmethod
+    def _obs(state: Mapping[str, Any]) -> dict:
+        return {
+            "pos": state["pos"],
+            "target": state["target"],
+            "remaining": state["max_steps"] - state["steps"],
+        }
+
+
+class GuessNumberEnv:
+    """Binary-search style: guess ``secret`` in [low, high] with higher/lower hints.
+
+    obs = {low, high, last, hint, remaining}. Reward 1.0 on the correct guess.
+    Optimal policy = guess the midpoint. Action = the integer guess (as str).
+    """
+
+    actions: tuple[str, ...] = ()  # any int in range; reference uses midpoint
+
+    def reset(self, spec: Mapping[str, Any]) -> tuple[dict, dict]:
+        low, high = int(spec.get("low", 1)), int(spec.get("high", 100))
+        state = {
+            "low": low, "high": high, "secret": int(spec.get("secret", (low + high) // 3)),
+            "last": None, "hint": "go", "steps": 0,
+            "max_steps": int(spec.get("max_steps", 12)),
+        }
+        return state, self._obs(state)
+
+    def step(self, state: dict, action: str) -> tuple[dict, dict, float, bool, dict]:
+        state = dict(state)
+        try:
+            guess = int(action)
+        except (TypeError, ValueError):
+            guess = state["low"]
+        state["steps"] += 1
+        state["last"] = guess
+        if guess == state["secret"]:
+            state["hint"] = "correct"
+            return state, self._obs(state), 1.0, True, {"reached": True}
+        if guess < state["secret"]:
+            state["low"] = guess + 1
+            state["hint"] = "higher"
+        else:
+            state["high"] = guess - 1
+            state["hint"] = "lower"
+        done = state["steps"] >= state["max_steps"]
+        return state, self._obs(state), 0.0, done, {"reached": False}
+
+    def optimal_action(self, obs: Mapping[str, Any]) -> str:
+        return str((int(obs["low"]) + int(obs["high"])) // 2)
+
+    @staticmethod
+    def _obs(state: Mapping[str, Any]) -> dict:
+        return {
+            "low": state["low"], "high": state["high"], "last": state["last"],
+            "hint": state["hint"], "remaining": state["max_steps"] - state["steps"],
+        }
+
+
+ENVIRONMENTS: dict[str, Callable[[], Environment]] = {
+    "reach_target": lambda: ReachTargetEnv(),
+    "guess_number": lambda: GuessNumberEnv(),
+}
+
+
+class PullError(ValueError):
+    """Raised for an unknown env kind or malformed pull task."""
+
+
+def resolve_policy(agent: Any, env: Environment) -> Callable[[Mapping[str, Any]], str]:
+    """Resolve a policy from a callable or a spec dict (``reference`` / ``noop``)."""
+
+    if callable(agent):
+        return agent
+    spec = agent if isinstance(agent, Mapping) else {}
+    kind = str(spec.get("type", "reference"))
+    if kind == "reference":
+        return env.optimal_action
+    if kind == "noop":
+        first = env.actions[0] if env.actions else "0"
+        return lambda _obs: first
+    raise PullError(f"unknown pull policy {kind!r}; expected callable / reference / noop")
+
+
+def run_pull(task: Mapping[str, Any], agent: Any) -> dict[str, Any]:
+    """Run one agent-driven episode over a simulated environment.
+
+    Returns ``{"result", "raw"}`` (unified Result). The scalar is the cumulative
+    reward; ``pass_fail`` records goal-reached; ``raw`` records the trajectory
+    length + terminal info.
+    """
+
+    env_spec = task.get("env") or {}
+    kind = str(env_spec.get("kind") or "")
+    if kind not in ENVIRONMENTS:
+        return {
+            "result": {"scalar": 0.0, "components": {}, "pass_fail": {},
+                       "explanation": f"unknown env kind {kind!r}"},
+            "raw": {"control": "pull", "infra_error": True, "env_kind": kind},
+        }
+    env = ENVIRONMENTS[kind]()
+    try:
+        policy = resolve_policy(agent, env)
+    except PullError as exc:
+        return {
+            "result": {"scalar": 0.0, "components": {}, "pass_fail": {},
+                       "explanation": str(exc)},
+            "raw": {"control": "pull", "infra_error": True},
+        }
+
+    state, obs = env.reset(env_spec.get("spec") or {})
+    total = 0.0
+    reached = False
+    steps = 0
+    hard_cap = int((env_spec.get("spec") or {}).get("max_steps", 50)) + 5
+    while steps < hard_cap:
+        try:
+            action = policy(obs)
+        except Exception as exc:  # a misbehaving policy fails the episode, not the lane
+            return {
+                "result": {"scalar": round(total, 6), "components": {"reward": total},
+                           "pass_fail": {"goal_reached": False},
+                           "explanation": f"policy raised: {exc}"},
+                "raw": {"control": "pull", "env_kind": kind, "steps": steps, "policy_error": True},
+            }
+        state, obs, reward, done, info = env.step(state, str(action))
+        total += float(reward)
+        steps += 1
+        if info.get("reached"):
+            reached = True
+        if done:
+            break
+
+    return {
+        "result": {
+            "scalar": round(total, 6),
+            "components": {"reward": round(total, 6), "steps": float(steps)},
+            "pass_fail": {"goal_reached": reached},
+            "explanation": f"{'reached' if reached else 'did not reach'} goal in {steps} steps",
+        },
+        "raw": {"control": "pull", "env_kind": kind, "steps": steps, "reached": reached},
+    }

fi/alk/bench/_voice.py

@@ -0,0 +1,147 @@
+"""Voice modality — deterministic voice-episode verifier (deep contract + simulated).
+
+Voice is the modality that stress-tests the harness: the environment is an active
+caller and the verifier is *temporal*, not an exit code. This module scores a
+voice **episode transcript** (interleaved caller + agent turns with millisecond
+timing) on the dimensions a real voice benchmark cares about:
+
+  * **latency** — the agent answers within the budget after the caller stops;
+  * **turn-taking** — no harmful overlap (both speaking at once) outside a
+    legitimate barge-in;
+  * **barge-in handling** — when the caller interrupts mid-agent-turn, the agent
+    yields promptly;
+  * **task content** — the agent's words cover the required content.
+
+This is the **simulated / deep-contract** tier: it scores a transcript produced
+by a deterministic simulated caller, so it is fully credential-free and
+gate-verifiable. The same verifier consumes a transcript captured from a *live*
+audio/SIP/WebRTC call + ASR — that live capture (and real WER) is deferred to
+owner infra; it plugs in here unchanged by producing the same transcript shape.
+
+A transcript is a list of turns::
+
+    {"speaker": "caller"|"agent", "start_ms": int, "end_ms": int,
+     "text": str, "interrupt": bool (optional, caller turns only)}
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+_DEFAULT_MAX_LATENCY_MS = 1200
+_BARGE_IN_YIELD_MS = 600  # the agent must stop within this of a barge-in to "yield"
+_PASS_FLOOR = 0.75        # each sub-score must meet this for a pass
+
+
+def _norm_turns(dialogue: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    turns = []
+    for t in dialogue:
+        turns.append({
+            "speaker": str(t.get("speaker")),
+            "start_ms": int(t.get("start_ms", 0)),
+            "end_ms": int(t.get("end_ms", 0)),
+            "text": str(t.get("text") or ""),
+            "interrupt": bool(t.get("interrupt", False)),
+        })
+    return turns
+
+
+def _latency_score(turns: list[dict[str, Any]], max_latency_ms: int) -> float:
+    gaps_ok, gaps = 0, 0
+    for i, t in enumerate(turns):
+        if t["speaker"] != "agent":
+            continue
+        prev = next((turns[j] for j in range(i - 1, -1, -1)
+                     if turns[j]["speaker"] == "caller"), None)
+        if prev is None:
+            continue
+        gap = t["start_ms"] - prev["end_ms"]
+        gaps += 1
+        if 0 <= gap <= max_latency_ms:
+            gaps_ok += 1
+    return gaps_ok / gaps if gaps else 1.0
+
+
+def _overlap_and_bargein(turns: list[dict[str, Any]]) -> tuple[float, float]:
+    """Turn-taking (no harmful overlap) + barge-in handling scores."""
+
+    agent_turns = [t for t in turns if t["speaker"] == "agent"]
+    harmful, considered = 0, 0
+    bargein_handled, bargein_total = 0, 0
+    callers = [t for t in turns if t["speaker"] == "caller"]
+    for a in agent_turns:
+        considered += 1
+        overlapping_callers = [
+            c for c in callers
+            if c["start_ms"] < a["end_ms"] and c["end_ms"] > a["start_ms"]
+        ]
+        legit_bargein = False
+        for c in overlapping_callers:
+            if c["interrupt"]:
+                bargein_total += 1
+                legit_bargein = True
+                # the agent must yield: its turn ends within the window after the
+                # interrupt begins.
+                if a["end_ms"] - c["start_ms"] <= _BARGE_IN_YIELD_MS:
+                    bargein_handled += 1
+        if overlapping_callers and not legit_bargein:
+            harmful += 1  # both speaking at once with no barge-in to excuse it
+    turn_taking = 1.0 - (harmful / considered) if considered else 1.0
+    bargein = bargein_handled / bargein_total if bargein_total else 1.0
+    return turn_taking, bargein
+
+
+def _content_score(turns: list[dict[str, Any]], required: Sequence[str]) -> float:
+    if not required:
+        return 1.0
+    agent_text = " ".join(t["text"] for t in turns if t["speaker"] == "agent").lower()
+    hit = sum(1 for kw in required if str(kw).lower() in agent_text)
+    return hit / len(required)
+
+
+def score_voice_episode(
+    dialogue: Sequence[Mapping[str, Any]],
+    *,
+    budgets: Mapping[str, Any] | None = None,
+    required_content: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Score a voice episode transcript; return ``{"result", "raw"}`` (unified Result).
+
+    The scalar is the mean of the four sub-scores; the verdict (in pass_fail) is a
+    pass only if EVERY sub-score meets the floor — a single bad dimension (e.g. the
+    agent talks over the caller) fails the episode.
+    """
+
+    budgets = budgets or {}
+    required_content = required_content or []
+    if not dialogue:
+        return {
+            "result": {"scalar": 0.0, "components": {}, "pass_fail": {"voice": False},
+                       "explanation": "empty transcript"},
+            "raw": {"modality": "voice"},
+        }
+    turns = _norm_turns(dialogue)
+    max_latency = int(budgets.get("max_latency_ms", _DEFAULT_MAX_LATENCY_MS))
+    latency = _latency_score(turns, max_latency)
+    turn_taking, bargein = _overlap_and_bargein(turns)
+    content = _content_score(turns, required_content)
+    sub = {
+        "latency": round(latency, 6),
+        "turn_taking": round(turn_taking, 6),
+        "barge_in": round(bargein, 6),
+        "content": round(content, 6),
+    }
+    scalar = round(sum(sub.values()) / len(sub), 6)
+    floors_met = all(v >= _PASS_FLOOR for v in sub.values())
+    return {
+        "result": {
+            "scalar": scalar,
+            "components": sub,
+            "pass_fail": {"voice": floors_met, **{f"{k}_floor": (v >= _PASS_FLOOR)
+                                                  for k, v in sub.items()}},
+            "explanation": ("all voice dimensions met the floor" if floors_met
+                            else "a voice dimension fell below the floor"),
+        },
+        "raw": {"modality": "voice", "turns": len(turns), "max_latency_ms": max_latency,
+                "floors_met": floors_met},
+    }