open-interpretability 0.0.20__py3-none-any.whl

openinterp/experiment_loop.py

@@ -0,0 +1,357 @@
+"""``open-interpretability loop``: run experiments back to back with API agents (issue #3246).
+
+Each iteration resets a detached worktree to ``origin/main`` and draws with the planner.
+It claims the draw as ``choose-next-experiment`` does, then runs the draw's steps
+(``draw_steps.steps``, the commands ``open-interpretability next --steps`` prints). Then it
+posts the result, and lands it as the ``land-experiment`` skill does.
+``open-interpretability`` commands run in this process, so a model loads once
+(``runner_cache``). git and gh run as subprocesses.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from openinterp.core.paths import DEFAULT_WIKI_DIR, draws_dir, experiments_dir, stops_dir
+from openinterp.draw_steps import REVIEW_KINDS, VERBS, draw_slug, steps
+from openinterp.planner import claim_key
+
+MERGE_PERMISSIONS = ("ADMIN", "MAINTAIN", "WRITE")
+CHECKS_TIMEOUT = 45 * 60  # seconds; the land-experiment skill gives up after 45 minutes
+OPENINTERP = ("uv", "run", "open-interpretability")
+
+
+class LoopError(Exception):
+    """One iteration failed. Its message is the reason that the loop gives."""
+
+
+@dataclass(frozen=True)
+class Options:
+    """What every iteration of a loop shares."""
+
+    proposer: str
+    reviewer: str
+    epsilon: float = 0.7
+    corpus: str | None = None  # None: each new scan builds a fresh corpus from its seed
+
+
+@dataclass(frozen=True)
+class Result:
+    """The outcome of one iteration, as the RESULT line reports it."""
+
+    slug: str | None
+    verdict: str
+    url: str | None = None
+    merged: bool = False
+
+    def line(self) -> str:
+        """``RESULT: <slug> <verdict> <PR url> <merged|open>``, or ``RESULT: none <why>``."""
+        if self.slug is None:
+            return f"RESULT: none {self.verdict}"
+        return (
+            f"RESULT: {self.slug} {self.verdict} {self.url} {'merged' if self.merged else 'open'}"
+        )
+
+
+def sh(args: list[str], check: bool = True, timeout: float | None = None) -> str:
+    """Run ``args`` in the current directory and return its stdout; echo both streams."""
+    try:
+        done = subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        raise LoopError(f"`{' '.join(args[:3])}` timed out") from exc
+    sys.stdout.write(f"$ {shlex.join(args)}\n{done.stdout}{done.stderr}")
+    if check and done.returncode != 0:
+        tail = (done.stderr or done.stdout).strip().splitlines()[-1:] or ["no output"]
+        raise LoopError(f"`{' '.join(args[:3])}` failed: {tail[0]}")
+    return done.stdout.strip()
+
+
+def openinterp(args: list[str]) -> None:
+    """Run one ``open-interpretability`` command in this process.
+
+    A non-zero exit raises LoopError.
+    """
+    from openinterp.cli import cli
+
+    sys.stdout.write(f"$ openinterp {shlex.join(args)}\n")
+    try:
+        cli.main(args=args, prog_name="open-interpretability", standalone_mode=False)
+    except SystemExit as exc:
+        if exc.code not in (0, None):
+            raise LoopError(f"`openinterp {args[0]}` exited {exc.code}") from exc
+
+
+def run_command(command: str) -> None:
+    """Run one command of a step: ``uv run openinterp …`` in-process, anything else in a shell."""
+    args = shlex.split(command)
+    if tuple(args[:3]) == OPENINTERP:
+        openinterp(args[3:])
+    else:
+        sh(args)
+
+
+def reset() -> None:
+    """Detach the current worktree at a fresh ``origin/main`` and drop old experiment branches."""
+    sh(["git", "fetch", "--quiet", "origin", "main"])
+    sh(["git", "checkout", "--quiet", "--force", "--detach", "origin/main"])
+    sh(["git", "clean", "-fdq"])
+    branches = sh(["git", "for-each-ref", "--format=%(refname:short)", "refs/heads/experiment/"])
+    for branch in branches.split():
+        sh(["git", "branch", "-D", branch])
+
+
+def proposer_of(record_path: str | None) -> str | None:
+    """The proposer model of the record at ``record_path``, if there is one."""
+    from openinterp.core.schemas import AuditRecord
+
+    if not record_path or not Path(record_path).exists():
+        return None
+    record = AuditRecord.model_validate_json(Path(record_path).read_text())
+    return record.submission.submitting_agent_model
+
+
+def draw(options: Options, plan_next, claims):
+    """Draw with the planner. A review the reviewer can't do independently is drawn again once.
+
+    ``plan_next`` and ``claims`` are passed in so that tests can replace them.
+    """
+    for _ in range(2):
+        plan = plan_next(DEFAULT_WIKI_DIR, epsilon=options.epsilon, claims=claims())
+        c = plan.choice
+        if c.kind not in REVIEW_KINDS or proposer_of(c.record) != options.reviewer:
+            return plan
+    raise LoopError(f"twice drew a review of {options.reviewer}'s own record")
+
+
+def pr_url() -> str:
+    """The URL of the pull request for the branch that is checked out."""
+    return sh(["gh", "pr", "view", "--json", "url", "-q", ".url"])
+
+
+def new_files(prefix: Path) -> list[Path]:
+    """Files under ``prefix`` that git does not track yet."""
+    out = sh(["git", "ls-files", "--others", "--exclude-standard", str(prefix)])
+    return [Path(line) for line in out.splitlines() if line]
+
+
+def verdict_of(kind: str, key: str) -> tuple[str, str]:
+    """The new record's verdict and the commit message that posts it.
+
+    A scan that stopped on its unit writes a draw or stop record and no experiment, so
+    its verdict is STOPPED.
+    """
+    from openinterp.core.schemas import AuditRecord
+
+    records = [p for p in new_files(experiments_dir(DEFAULT_WIKI_DIR)) if p.suffix == ".json"]
+    if not records:
+        if new_files(draws_dir(DEFAULT_WIKI_DIR)) or new_files(stops_dir(DEFAULT_WIKI_DIR)):
+            return "STOPPED", f"{VERBS[kind]} {key} (STOPPED)"
+        raise LoopError("the draw's steps wrote no record")
+    verdict = AuditRecord.model_validate_json(records[0].read_text()).verdict
+    accuracy = verdict.metrics.balanced_accuracy if verdict.metrics else None
+    shown = "n/a" if accuracy is None else f"{accuracy:.2f}"
+    return verdict.status, f"{VERBS[kind]} {key} ({verdict.status}, {shown})"
+
+
+def post(kind: str, key: str) -> str:
+    """Write the pages, check the registry, commit ``wiki/``, push and mark the PR ready."""
+    openinterp(["wiki"])
+    openinterp(["check", "--base-ref", "origin/main"])
+    status, message = verdict_of(kind, key)
+    sh(["git", "add", str(DEFAULT_WIKI_DIR)])
+    sh(["git", "commit", "--quiet", "-m", message])
+    sh(["git", "push", "--quiet"])
+    sh(["gh", "pr", "ready"])
+    return status
+
+
+def merge_blockers(view: dict, permission: str) -> list[str]:
+    """Why the PR described by ``view`` (``gh pr view --json``) may not be merged, if at all."""
+    files = [f["path"] for f in view.get("files", [])]
+    wiki = f"{DEFAULT_WIKI_DIR}/"
+    reasons = [f"it changes {p}, outside {wiki}" for p in files if not p.startswith(wiki)]
+    if permission not in MERGE_PERMISSIONS:
+        reasons.append(f"the token's permission is {permission or 'unknown'}")
+    if view.get("isDraft"):
+        reasons.append("it is a draft")
+    if view.get("mergeable") != "MERGEABLE":
+        reasons.append(f"GitHub says it is {view.get('mergeable', 'not mergeable')}")
+    return reasons
+
+
+def land(url: str) -> bool:
+    """Wait for the checks, then merge the PR if every merge condition holds. True if merged."""
+    import json
+
+    try:
+        sh(
+            ["gh", "pr", "checks", url, "--watch", "--fail-fast", "--interval", "30"],
+            timeout=CHECKS_TIMEOUT,
+        )
+    except LoopError as exc:
+        sh(["gh", "pr", "comment", url, "--body", f"Left open: the checks didn't pass ({exc})."])
+        return False
+    fields = "state,isDraft,mergeable,files,headRefOid"
+    view = json.loads(sh(["gh", "pr", "view", url, "--json", fields]))
+    if view.get("state") == "MERGED":  # the auto-merge workflow got there first
+        return True
+    permission = sh(["gh", "repo", "view", "--json", "viewerPermission", "-q", ".viewerPermission"])
+    if reasons := merge_blockers(view, permission):
+        sh(["gh", "pr", "comment", url, "--body", "Left open: " + "; ".join(reasons) + "."])
+        return False
+    sh(["gh", "pr", "merge", url, "--squash", "--match-head-commit", view["headRefOid"]])
+    delete_branch()
+    return True
+
+
+def delete_branch() -> None:
+    """Delete the checked-out branch on origin, so that a later draw can claim it again."""
+    branch = sh(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    sh(["git", "push", "--quiet", "origin", "--delete", branch], check=False)
+
+
+def iteration(options: Options, plan_next, claims) -> Result:
+    """Run one experiment end to end: reset, draw, claim, run, post and land."""
+    reset()
+    plan = draw(options, plan_next, claims)
+    slug = draw_slug(plan.choice)
+    if slug is None:
+        raise LoopError(f"the unit of a {plan.choice.kind} draw on {plan.choice.model} is unknown")
+    corpus = options.corpus or "corpus.jsonl"
+    claim, *work, _ = steps(
+        plan, corpus, options.proposer, options.reviewer, options.corpus is None
+    )
+    for command in claim.commands:
+        run_command(command)
+    url = pr_url()
+    try:
+        status = run_work(work, plan.choice.kind, claim_key(slug))
+    except Exception as exc:
+        sh(
+            [
+                "gh",
+                "pr",
+                "close",
+                url,
+                "--comment",
+                f"Abandoned by `open-interpretability loop`: {exc}",
+            ],
+            check=False,
+        )
+        delete_branch()
+        raise
+    return Result(slug, status, url, land(url))
+
+
+def run_work(work, kind: str, key: str) -> str:
+    """Run every step after the claim, then post. A scan that stops on its unit posts at once."""
+    from openinterp.evidence import Unauditable
+
+    try:
+        for step in work:
+            for command in step.commands:
+                run_command(command)
+    except Unauditable as exc:
+        sys.stdout.write(f"The scan stopped on the unit: {exc}\n")
+    return post(kind, key)
+
+
+BACKOFF_MINUTES = (1, 5, 15)  # waits after a provider's rate or usage limit; then stop
+_LIMIT_WORDS = ("rate limit", "ratelimit", "usage limit", "429", "overloaded", "quota")
+
+
+def is_rate_limit(exc: BaseException) -> bool:
+    """True if ``exc``, or an exception it was raised from, is a provider's rate or usage limit."""
+    seen: BaseException | None = exc
+    while seen is not None:
+        text = f"{type(seen).__name__} {seen}".lower()
+        if any(word in text for word in _LIMIT_WORDS):
+            return True
+        seen = seen.__cause__ or seen.__context__
+    return False
+
+
+def stop_file() -> Path:
+    """The kill switch that ``scripts/experiment-loop.sh`` also honours."""
+    import os
+
+    cache = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(os.environ.get("OPENINTERP_STOP_FILE") or Path(cache) / "openinterp" / "stop")
+
+
+@dataclass
+class Loop:
+    """The loop's counters, and the pieces that tests replace."""
+
+    options: Options
+    log_dir: Path
+    max_experiments: int = 0  # 0: until stopped
+    max_failures: int = 3
+    plan_next: object = None
+    claims: object = None
+    sleep: object = None
+    done: int = 0
+    failures: int = 0
+    backoffs: int = 0
+
+    def run(self) -> int:
+        """Run until the limit, the stop file or too many failures; return the exit code."""
+        while not self.max_experiments or self.done < self.max_experiments:
+            if stop_file().exists():
+                print(f"Stopping: {stop_file()} exists.")
+                return 0
+            self._wait_while_paused()
+            if (code := self._one()) is not None:
+                return code
+        return 0
+
+    def _one(self) -> int | None:
+        """Run one iteration and count it. Return an exit code when the loop must stop."""
+        import contextlib
+        from datetime import UTC, datetime
+
+        stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        log = self.log_dir / f"{stamp}.log"
+        try:
+            with (
+                open(log, "w") as out,
+                contextlib.redirect_stdout(out),
+                contextlib.redirect_stderr(out),
+            ):
+                result = iteration(self.options, self.plan_next, self.claims)
+        except Exception as exc:  # any failure of one experiment; the loop decides what next
+            return self._failed(exc, log)
+        self.done, self.failures, self.backoffs = self.done + 1, 0, 0
+        print(result.line(), flush=True)
+        return None
+
+    def _failed(self, exc: Exception, log: Path) -> int | None:
+        """Back off on a rate limit, count any other failure, and say when to stop."""
+        if is_rate_limit(exc):
+            if self.backoffs == len(BACKOFF_MINUTES):
+                print(f"RESULT: none rate limited after {self.backoffs} waits ({log})")
+                return 1
+            minutes = BACKOFF_MINUTES[self.backoffs]
+            self.backoffs += 1
+            print(f"Rate limited; waiting {minutes} min ({log})", flush=True)
+            self.sleep(minutes * 60)
+            return None
+        self.failures += 1
+        print(f"RESULT: none {exc} ({log})", flush=True)
+        return 1 if self.failures >= self.max_failures else None
+
+    def _wait_while_paused(self) -> None:
+        """Wait, a minute at a time, while ``open-interpretability pause`` is in force."""
+        from openinterp.core import pause
+
+        said = False
+        while (paused := pause.read()) is not None and not stop_file().exists():
+            if not said:
+                print(paused.describe(), flush=True)
+                said = True
+            self.sleep(60)

openinterp/explain.py

@@ -0,0 +1,252 @@
+"""Explain one answer of a model as fully as the registry allows (issue #3250).
+
+``open-interpretability explain "<prompt>"`` attributes the logit of the model's answer to every
+MLP neuron pole. It labels the poles from the registry, and says how much of the answer is
+explained. A sparse registry is fine: the output's job is also to show how little is
+explained so far.
+
+- *Attribute.* One prompt has no corrupted twin, so the baseline is each neuron's mean
+  activation over a corpus sample. At each position, a neuron's contribution is
+  (a − mean) · ∂logit/∂a. That is first order, like ``attribution_patching``. Each
+  contribution goes to the pole that the sign of ``a`` names at that position. The
+  first token, an attention sink, is left out, as scans leave it out.
+- *Explain.* Each pole gets its newest record's status and explanation, or *stopped*
+  (a scan found it dead or default-on), or *unstudied*. Only a VERIFIED explanation is
+  shown as one.
+- *Gaps.* The share of the total |attribution| that VERIFIED poles hold.
+- *Check.* Mean-ablate single top poles, then the VERIFIED ones together, and measure
+  the change in the answer's logit.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import torch
+
+from openinterp.core.cache_dirs import cache_root
+from openinterp.harness.hooks import NeuronHookRunner
+
+MEANS_ENV = "OPENINTERP_MEANS"  # the cache of per-neuron means, or "off"
+WINDOW = 128  # tokens per window of the mean's corpus sample
+MEANS_VERSION = 2  # in the cache key: 2 leaves each window's first token out
+
+
+@dataclass
+class PoleAttribution:
+    """One pole's attribution to the answer, with what the registry says of it."""
+
+    layer: int
+    neuron: int
+    pole: str
+    attribution: float  # summed (a − mean) · grad over the positions where it is this pole
+    strength: float  # the pole's peak strength on the prompt
+    status: str = "unstudied"  # VERIFIED, NEEDS_REVISION, REJECTED, stopped, unstudied
+    explanation: str | None = None
+    max_activation: float | None = None
+    ablation_change: float | None = None  # target logit change when mean-ablated alone
+
+    @property
+    def label(self) -> str:
+        """``L3/N7+``: the pole within its model."""
+        return f"L{self.layer}/N{self.neuron}{'+' if self.pole == 'positive' else '−'}"
+
+
+@dataclass
+class Explanation:
+    """Everything ``open-interpretability explain`` reports for one prompt."""
+
+    prompt: str
+    position: int
+    token: str
+    logit: float
+    poles: list[PoleAttribution]  # the top poles, by |attribution|
+    total: float  # the sum of |attribution| over every pole of every layer
+    verified: float  # the same sum over VERIFIED poles only
+    joint: dict = field(default_factory=dict)  # the VERIFIED poles ablated together
+
+    @property
+    def verified_share(self) -> float:
+        """The share of the total |attribution| that VERIFIED poles hold."""
+        return self.verified / self.total if self.total else 0.0
+
+
+def _layer_acts(runner: NeuronHookRunner, encoded, layers) -> dict[int, torch.Tensor]:
+    _, cache = runner.run_with_cache(encoded, layers)
+    return cache
+
+
+def neuron_means(runner: NeuronHookRunner, model: str, texts: Sequence[str], tokens: int):
+    """Each layer's mean MLP activation per neuron, ``{layer: tensor[d_mlp]}``, cached.
+
+    The sample is the first ``tokens`` tokens of ``texts``, in windows of :data:`WINDOW`.
+    Each window's first token is left out, as the attribution leaves out the prompt's.
+    """
+    tag = f"{model}|{tokens}|{WINDOW}|{MEANS_VERSION}|"
+    key = hashlib.sha256(tag.encode() + "\n".join(texts).encode())
+    root = cache_root(MEANS_ENV, "means")
+    path = root / f"{key.hexdigest()[:24]}.pt" if root else None
+    if path is not None and path.exists():
+        return torch.load(path)
+    ids = [i for t in texts for i in runner.tokenizer.encode(t)][:tokens]
+    windows = [ids[i : i + WINDOW] for i in range(0, len(ids) - WINDOW + 1, WINDOW)]
+    layers = list(range(runner.n_layers))
+    sums = {la: torch.zeros(runner.mlp_width(la)) for la in layers}
+    count = 0
+    for window in windows:
+        acts = _layer_acts(runner, torch.tensor([window]), layers)
+        for la in layers:  # a window's first token is an attention sink: leave it out
+            sums[la] += acts[la][0, 1:].float().sum(0).cpu()
+        count += len(window) - 1
+    means = {la: s / max(count, 1) for la, s in sums.items()}
+    if path is not None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        torch.save(means, path)
+    return means
+
+
+def attribute(runner: NeuronHookRunner, prompt: str, means: dict, token: int, position: int):
+    """Per pole, ``{(layer, neuron, pole): (attribution, peak strength)}``, and the logit.
+
+    The metric is the logit of ``token`` at ``position``. The prompt's first token is left out.
+    """
+    layers = sorted(means)
+    captured: dict[int, torch.Tensor] = {}
+
+    def capture(layer: int):
+        def hook(act: torch.Tensor) -> None:
+            captured[layer] = act
+
+        return hook
+
+    def ensure_grad(_module, _args, output):
+        return output if output.requires_grad else output.detach().requires_grad_(True)
+
+    encoded = runner.encode(prompt)
+    handle = runner.model.get_input_embeddings().register_forward_hook(ensure_grad)
+    try:
+        with torch.enable_grad(), runner.hooks({la: capture(la) for la in layers}):
+            logit = runner.forward(encoded)[0, position, token]
+            grads = torch.autograd.grad(logit, [captured[la] for la in layers])
+    finally:
+        handle.remove()
+    out = {}
+    for la, grad in zip(layers, grads, strict=True):
+        # The first token is an attention sink, active far beyond any scan's scale whatever
+        # the prompt. The protocol leaves it out of scans, and so does this.
+        act = captured[la].detach()[0, 1:].float().cpu()
+        contribution = (act - means[la]) * grad[0, 1:].float().cpu()
+        for pole, mask in (("positive", act > 0), ("negative", act < 0)):
+            score = (contribution * mask).sum(0)
+            peak = (act.abs() * mask).amax(0)
+            for n in torch.nonzero(mask.any(0)).flatten().tolist():
+                out[(la, n, pole)] = (float(score[n]), float(peak[n]))
+    return out, float(logit.detach())
+
+
+def mean_ablation(poles: Sequence[tuple[int, int, str]], means: dict):
+    """``interventions`` that set each pole to its neuron's mean where the pole is active.
+
+    The first token keeps its value, as the attribution leaves it out.
+    """
+    by_layer: dict[int, list[tuple[int, str]]] = {}
+    for layer, neuron, pole in poles:
+        by_layer.setdefault(layer, []).append((neuron, pole))
+
+    def at(layer: int):
+        def intervene(act: torch.Tensor) -> torch.Tensor:
+            act = act.clone()
+            for neuron, pole in by_layer[layer]:
+                a = act[..., neuron]
+                active = a > 0 if pole == "positive" else a < 0
+                active[..., 0] = False  # the first token stays, as in the attribution
+                mean = means[layer][neuron].to(act.dtype)
+                act[..., neuron] = torch.where(active, mean, a)
+            return act
+
+        return intervene
+
+    return {layer: at(layer) for layer in by_layer}
+
+
+@torch.no_grad()
+def logits_with(runner: NeuronHookRunner, prompt: str, interventions, position: int):
+    """The logits at ``position`` with ``interventions`` applied."""
+    with runner.hooks(interventions):
+        return runner.forward(runner.encode(prompt))[0, position].float().cpu()
+
+
+def registry_labels(wiki_dir: Path, model: str) -> dict[str, tuple[str, str | None, float | None]]:
+    """``{pole slug: (status, explanation, max_activation)}`` for ``model``'s poles.
+
+    The status is the newest record's verdict. A pole that a scan stopped on, with no
+    record, is ``stopped``.
+    """
+    from openinterp.planner import load_states, stopped
+
+    out: dict[str, tuple[str, str | None, float | None]] = {}
+    for ident in stopped(wiki_dir):
+        if ident.model_name == model:
+            out[ident.slug] = ("stopped", None, None)
+    for slug, state in load_states(wiki_dir).items():
+        sub = state.record.submission
+        if sub.identifier.model_name == model:
+            out[slug] = (
+                state.record.verdict.status,
+                sub.natural_language_explanation,
+                sub.max_activation,
+            )
+    return out
+
+
+def explain(
+    runner: NeuronHookRunner,
+    model: str,
+    prompt: str,
+    means: dict,
+    labels: dict,
+    *,
+    token: int | None = None,
+    position: int = -1,
+    top: int = 20,
+    confirm: int = 10,
+) -> Explanation:
+    """Attribute, label, measure the VERIFIED share and check by ablation (module docstring)."""
+    from openinterp.core.identifiers import NeuronIdentifier
+
+    base = logits_with(runner, prompt, {}, position)
+    token = int(base.argmax()) if token is None else token
+    scores, logit = attribute(runner, prompt, means, token, position)
+    ranked = sorted(scores.items(), key=lambda kv: abs(kv[1][0]), reverse=True)
+    total = verified = 0.0
+    poles = []
+    for rank, ((layer, neuron, pole), (score, strength)) in enumerate(ranked):
+        slug = NeuronIdentifier(model_name=model, layer=layer, neuron_idx=neuron, pole=pole).slug
+        status, text, max_act = labels.get(slug, ("unstudied", None, None))
+        total += abs(score)
+        verified += abs(score) if status == "VERIFIED" else 0.0
+        if rank < top:
+            shown = text if status == "VERIFIED" else None
+            poles.append(
+                PoleAttribution(layer, neuron, pole, score, strength, status, shown, max_act)
+            )
+    for p in poles[:confirm]:
+        ablated = logits_with(
+            runner, prompt, mean_ablation([(p.layer, p.neuron, p.pole)], means), position
+        )
+        p.ablation_change = float(ablated[token] - base[token])
+    chosen = [(p.layer, p.neuron, p.pole) for p in poles if p.status == "VERIFIED"]
+    joint = {"poles": len(chosen)}
+    if chosen:
+        ablated = logits_with(runner, prompt, mean_ablation(chosen, means), position)
+        joint |= {
+            "logit_change": float(ablated[token] - base[token]),
+            "top_token_changed": int(ablated.argmax()) != token,
+            "new_top_token": runner.tokenizer.decode([int(ablated.argmax())]),
+        }
+    return Explanation(
+        prompt, position, runner.tokenizer.decode([token]), logit, poles, total, verified, joint
+    )

openinterp/half_precision.py

@@ -0,0 +1,79 @@
+"""Reproducing records made in a 16-bit dtype (bfloat16 or float16), issue #2995.
+
+16-bit rounding moves a number by a few percent from one device to another. So a 16-bit
+record is reproduced in float32, and compared within ``reproduce.HALF_TOLERANCE``
+(``docs/analyses/half-precision-reproduce.md``). A pass/fail can then flip where rounding
+moves a number across its threshold. These helpers check that the record's own results
+follow from its own numbers, and its decision from its results.
+"""
+
+from __future__ import annotations
+
+HALF = frozenset({"bfloat16", "float16"})
+ROUNDING = 1e-6  # records round activations and deltas to 6 decimals
+
+
+def reproduction_dtype(dtype: str) -> str:
+    """The dtype to reproduce a record in: float32 for a 16-bit record, else its own."""
+    return "float32" if dtype in HALF else dtype
+
+
+def recorded_pass(result, policy, scale: float) -> bool | None:
+    """What the decision rule gives for ``result``'s own recorded number, or None.
+
+    A probe passes when its activation is at or above the threshold exactly when it is
+    expected to be active. A counterfactual passes when its Δ agrees with the expected Δ.
+    Other kinds (lookahead) have no single number, so they get None. Records round
+    numbers to 6 decimals, so a number within that rounding of its boundary gets None too.
+    """
+    from openinterp.agents.review_measurements import _delta_agrees
+
+    if not result.measured or scale <= 0:
+        return None
+    if result.kind in {"hard_negative", "positive_holdout"}:
+        if result.activation is None:
+            return False
+
+        def rule(x):
+            return (x >= policy.activation_threshold * scale) == result.expected_active
+
+        number = result.activation
+    elif result.kind == "counterfactual":
+        if result.observed_delta is None or result.expected_delta is None:
+            return False
+
+        def rule(x):
+            return _delta_agrees(result.expected_delta, x, policy)
+
+        number = result.observed_delta
+    else:
+        return None
+    low, high = rule(number - ROUNDING), rule(number + ROUNDING)
+    return low if low == high else None
+
+
+def rederived(verdict):
+    """``verdict`` with its metrics and status computed again from its own recorded results."""
+    from openinterp.agents.reviewer import decide, review_metrics
+
+    m = verdict.metrics
+    baseline = (
+        (m.confound_baseline, m.confound_baseline_accuracy)
+        if m.confound_baseline is not None
+        else None
+    )
+    metrics = review_metrics(
+        verdict.adversarial_test_results,
+        verdict.policy,
+        independent=m.independent_review,
+        baseline=baseline,
+        active_share=m.active_share,
+        first_token_floor=m.first_token_floor,
+    )
+    return verdict.model_copy(
+        update={
+            "metrics": metrics,
+            "status": decide(metrics, verdict.policy),
+            "confidence_score": metrics.balanced_accuracy,
+        }
+    )