open-interpretability 0.0.20__py3-none-any.whl

openinterp/reproduce.py

@@ -0,0 +1,450 @@
+"""Reproduce an experiment record from its JSON before it merges.
+
+The command is `open-interpretability reproduce`.
+
+`open-interpretability check` only validates a record's shape. This runs again every
+measurement that the verdict rests on. It uses the model revision and dtype that the record pins:
+
+1. The scan evidence: each top example's per-token strengths. Also the scale
+   (``max_activation``) that every "active" threshold is a fraction of.
+2. Each counterfactual pair's observed Δ.
+3. The review itself, with the record's stored probes and its own ``ReviewPolicy`` (no
+   LLM calls). That is every probe's activation and pass/fail, every gate and the status.
+
+Given the scan's corpus, it also draws the record's corpus sample again (protocol 0.7),
+from its seed and token budget. It checks that the sample hashes the same and holds
+every top example.
+
+Numbers must agree within ``atol × scale + rtol × |recorded|``. Anything the decision
+rule reads (pass/fail, gates, status) must agree exactly. Causal metrics, joint
+ablation and explanation scores are reported but not gated, so a difference there is
+only a warning. Explanation scores are re-derived from re-measured windows and the
+judge's stored answers; the judge and embedding model are not re-run.
+
+A record made in a 16-bit dtype (bfloat16 or float16) is reproduced in float32. Its
+numbers are compared within :data:`HALF_TOLERANCE`, because 16-bit rounding moves a
+number by a few percent from one device to another (issue #2995). float32 is also about
+10 times faster than bfloat16 on a CPU. ``half_precision.py`` has the other rules.
+
+A record judged under another protocol version can't be reproduced by this harness:
+its decision rule was different. Re-evaluate it instead (`open-interpretability reevaluate`). A
+library upgrade can still shift its activations. So ``measurements_only`` compares its
+scan evidence and counterfactuals, and leaves out the review.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import date
+from functools import partial
+from pathlib import Path
+
+from openinterp.core.schemas import PROTOCOL_VERSION, AuditRecord, RunEnvironment
+from openinterp.half_precision import HALF, recorded_pass, rederived, reproduction_dtype
+from openinterp.harness.environment import run_environment
+from openinterp.harness.hooks import NeuronHookRunner
+from openinterp.harness.layer_major import map_layer_major, prompt_tokens
+
+
+@dataclass(frozen=True)
+class Tolerance:
+    """Allowed |reproduced − recorded| = atol × scale + rtol × |recorded|.
+
+    The defaults absorb float32 differences between devices and library versions
+    (records round activations to 5–6 decimals) but not an edited number.
+    """
+
+    atol: float = 1e-3  # fraction of the neuron's max activation
+    rtol: float = 1e-2
+
+    def close(self, recorded: float | None, reproduced: float | None, scale: float) -> bool:
+        """True when ``reproduced`` is within tolerance of ``recorded``, or both are ``None``."""
+        if recorded is None or reproduced is None:
+            return recorded is None and reproduced is None
+        return abs(reproduced - recorded) <= self.atol * scale + self.rtol * abs(recorded)
+
+    def for_dtype(self, dtype: str) -> Tolerance:
+        """This tolerance, widened to :data:`HALF_TOLERANCE` for a record in a 16-bit dtype."""
+        if dtype not in HALF:
+            return self
+        return Tolerance(
+            atol=max(self.atol, HALF_TOLERANCE.atol), rtol=max(self.rtol, HALF_TOLERANCE.rtol)
+        )
+
+
+DEFAULT_TOLERANCE = Tolerance()
+# Set from cross-device re-measurements (docs/analyses/half-precision-reproduce.md).
+# At a peak it allows 7%, so a 10% edit of a peak still fails.
+HALF_TOLERANCE = Tolerance(atol=0.05, rtol=0.02)
+# Tokens of one top example that a 16-bit record may have outside HALF_TOLERANCE. Deep
+# layers on unusual text can move a few tokens by up to 22% of the peak; 3 was the most.
+HALF_STRAY_TOKENS = 4
+
+
+@dataclass
+class ReproductionReport:
+    """The result of reproducing one record: the mismatches, the warnings and what was compared."""
+
+    path: Path | None
+    record: AuditRecord
+    mismatches: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    compared: int = 0
+
+    @property
+    def ok(self) -> bool:
+        """True when nothing that the decision rule reads differed."""
+        return not self.mismatches
+
+    def fail(self, message: str) -> None:
+        """Record a mismatch."""
+        self.mismatches.append(message)
+
+
+def pinned_environment(record: AuditRecord) -> tuple[str | None, str]:
+    """(model revision, dtype) to load the model with, from the record's own pins."""
+    env = record.verdict.environment if record.verdict else None
+    prov = record.submission.provenance
+    revision = (env and env.model_revision) or (prov and prov.model_revision)
+    dtype = (env and env.dtype) or (prov and prov.dtype) or "float32"
+    return revision, dtype
+
+
+def check_protocol(record: AuditRecord) -> str | None:
+    """Why this harness can't reproduce ``record``'s verdict, or ``None`` if it can."""
+    if record.verdict is None:
+        return "record has no verdict"
+    policy = record.verdict.policy
+    version = policy.protocol_version if policy else "< 0.2"
+    if version != PROTOCOL_VERSION:
+        return (
+            f"judged under protocol {version}, but this harness implements "
+            f"{PROTOCOL_VERSION}; reproduce it with that openinterp version, or re-evaluate it"
+        )
+    return None
+
+
+def rotating_sample(paths: Sequence[Path], size: int, day: date) -> list[Path]:
+    """Return the ``size`` records of ``paths`` that ``day`` selects.
+
+    The order comes from a hash of each path, so one day's records are spread over models
+    and layers. A new record doesn't move the others in the order. Consecutive days take
+    consecutive windows, so a registry of N records is covered in N / ``size`` days.
+    """
+    order = sorted(paths, key=lambda p: hashlib.sha256(Path(p).as_posix().encode()).hexdigest())
+    if size >= len(order):
+        return order
+    start = day.toordinal() * size % len(order)
+    return (order + order)[start : start + size]
+
+
+def reproduce_record(
+    record: AuditRecord,
+    runner: NeuronHookRunner,
+    tolerance: Tolerance = DEFAULT_TOLERANCE,
+    path: Path | None = None,
+    corpus: tuple[list[str], str] | None = None,
+    *,
+    measurements_only: bool = False,
+) -> ReproductionReport:
+    """Reproduce ``record`` with ``runner``.
+
+    ``corpus`` is (documents, SHA-256 of the corpus file), to draw the scan's sample from.
+    With ``measurements_only``, a record from another protocol version gets its scan
+    evidence and counterfactuals compared, and a warning that the review was left out.
+    """
+    report = ReproductionReport(path=path, record=record)
+    reason = check_protocol(record)
+    if reason and (record.verdict is None or not measurements_only):
+        report.fail(reason)
+        return report
+    from openinterp.harness.units import submission_unit
+
+    sub, verdict = record.submission, record.verdict
+    unit = submission_unit(sub)
+    half = pinned_environment(record)[1] in HALF
+    tolerance = tolerance.for_dtype(pinned_environment(record)[1])
+    _compare_environment(record, run_environment(runner), report)
+
+    scale = sub.max_activation or 0.0
+    _check_scale(sub, unit, runner, scale, report)
+
+    # 1. Scan evidence.
+    if corpus is not None:
+        _check_sample(sub.provenance, sub.top_examples, runner, *corpus, report)
+    stray = HALF_STRAY_TOKENS if half else 0
+    _check_examples(sub.top_examples, unit, runner, tolerance, scale, report, stray)
+
+    # 2. Counterfactuals as submitted.
+    _check_counterfactuals(sub, unit, runner, tolerance, scale, report)
+    if reason:
+        report.warnings.append(f"measurements only, because the record was {reason}")
+        return report
+
+    # 3. The review, under the record's own policy and reviewer.
+    _compare_verdicts(verdict, _review_again(record, runner), tolerance, scale, report, half=half)
+
+    # 4. Explanation scores (reported, not gated): re-measure the windows, keep the answers.
+    if verdict.explanation_scores is not None:
+        _compare_explanation_scores(
+            verdict.explanation_scores, runner, unit, tolerance, scale, report
+        )
+    return report
+
+
+def _review_again(record: AuditRecord, runner):
+    """The record's probes and pairs measured again, under its own policy and reviewer."""
+    from openinterp.agents.reviewer import evaluate_submission, probes_from_verdict
+
+    verdict = record.verdict
+    return evaluate_submission(
+        record.submission,
+        runner,
+        probes_from_verdict(verdict),
+        verdict.reviewer_agent_model,
+        verdict.policy,
+        wire=False,  # reported, not gated: nothing to compare
+    )
+
+
+def _check_scale(sub, unit, runner, scale: float, report) -> None:
+    """``max_activation`` is the top example's peak, and the first-token floor reproduces."""
+    peak = max((e.max_activation for e in sub.top_examples), default=None)
+    if peak is not None and not math.isclose(scale, peak, rel_tol=1e-9, abs_tol=1e-12):
+        report.fail(f"max_activation {scale} is not the top example's peak {peak}")
+    if sub.first_token_floor is not None:  # judged against the scan's scale (protocol 0.8)
+        from functools import partial
+
+        from openinterp.core.schemas import ReviewPolicy
+        from openinterp.harness.scan import has_first_token_floor
+
+        read = partial(unit.strengths, runner)
+        if has_first_token_floor(runner, read, scale, ReviewPolicy()) != sub.first_token_floor:
+            report.fail(f"first_token_floor {sub.first_token_floor} does not reproduce")
+
+
+def _check_counterfactuals(sub, unit, runner, tolerance: Tolerance, scale: float, report):
+    from openinterp.agents.proposer import observed_delta
+
+    pairs = [(n, p) for n, p in enumerate(sub.counterfactuals, 1) if p.observed_delta is not None]
+    if not scale:
+        return
+    texts = [t for _, p in pairs for t in (p.base_prompt, p.counterfactual_prompt)]
+    deltas = map_layer_major(
+        runner, lambda item: observed_delta(runner, unit, item[1], scale), pairs,
+        tokens=prompt_tokens(runner, texts), logits=False,
+    )  # fmt: skip
+    for (n, pair), delta in zip(pairs, deltas, strict=True):
+        report.compared += 1
+        if not tolerance.close(pair.observed_delta, delta, 1.0):
+            report.fail(
+                f"counterfactual {n}: observed_delta recorded {pair.observed_delta}, "
+                f"reproduced {delta}"
+            )
+
+
+def _check_examples(
+    examples, unit, runner, tolerance: Tolerance, scale: float, report, stray: int = 0
+) -> None:
+    """Each top example's tokens and activations, measured layer-major when streamed.
+
+    Up to ``stray`` tokens of each example may differ beyond ``tolerance``, as a warning.
+    """
+    texts = [ex.text for ex in examples]
+    measured = map_layer_major(
+        runner, partial(unit.strengths, runner), texts,
+        tokens=prompt_tokens(runner, texts), logits=False,
+    )  # fmt: skip
+    for n, (ex, strengths) in enumerate(zip(examples, measured, strict=True), 1):
+        _check_example(n, ex, unit, runner, tolerance, scale, report, strengths, stray)
+
+
+def _check_example(
+    n: int, ex, unit, runner, tolerance: Tolerance, scale: float, report, strengths, stray=0
+) -> None:
+    """Top example ``n``'s tokens and per-token activations (``strengths``), and its peak."""
+    tokens = runner.encode(ex.text)["input_ids"][0].tolist()
+    words = [runner.tokenizer.decode([i]) for i in tokens] if runner.tokenizer else None
+    if words is not None and words != ex.tokens:
+        report.fail(f"top example {n}: tokens differ from the record")
+        return
+    values = strengths[0].tolist()
+    report.compared += len(values)
+    bad = [
+        i
+        for i, (a, b) in enumerate(zip(ex.activations, values, strict=False))
+        if not tolerance.close(a, b, scale)
+    ]
+    if bad and len(bad) <= stray and len(values) == len(ex.activations):
+        report.warnings.append(
+            f"top example {n}: {len(bad)} token(s) differ beyond the 16-bit tolerance, "
+            f"e.g. token {bad[0]} (recorded {ex.activations[bad[0]]}, "
+            f"reproduced {round(values[bad[0]], 6)})"
+        )
+        bad = []
+    if len(values) != len(ex.activations) or bad:
+        where = f"token {bad[0]}" if bad else "length"
+        report.fail(
+            f"top example {n}: activations differ at {where} "
+            f"(recorded {ex.activations[bad[0]] if bad else len(ex.activations)}, "
+            f"reproduced {round(values[bad[0]], 6) if bad else len(values)})"
+        )
+    measured = values[int(unit.skip_first) :]
+    if not tolerance.close(ex.max_activation, max(measured, default=0.0), scale):
+        report.fail(f"top example {n}: max_activation differs")
+
+
+def _check_sample(prov, examples, runner, texts, corpus_sha, report) -> None:
+    """Re-draw the record's corpus sample: the same documents, holding every top example."""
+    from openinterp.corpus import sample_tokens
+
+    sample = prov and prov.corpus_sample
+    if sample is None:
+        return
+    if corpus_sha != prov.corpus_sha256:
+        report.warnings.append("the corpus given is not the scan's; its sample was not checked")
+        return
+    drawn, redrawn = sample_tokens(runner.tokenizer, texts, sample.max_tokens, sample.seed)
+    if redrawn != sample:
+        report.fail(f"corpus sample recorded {sample}, re-drawn {redrawn}")
+        return
+    for n, ex in enumerate(examples, 1):
+        if not any(ex.text in doc for doc in drawn):
+            report.fail(f"top example {n} is not in the corpus sample")
+
+
+def _compare_explanation_scores(
+    old, runner, unit, tolerance: Tolerance, scale: float, report
+) -> None:
+    from openinterp.harness.explanation_scores import remeasure
+
+    new = remeasure(old, runner, unit)
+    for kind in ("detection", "fuzzing"):
+        pairs = zip(getattr(old, f"{kind}_windows"), getattr(new, f"{kind}_windows"), strict=True)
+        for n, (a, b) in enumerate(pairs, 1):
+            report.compared += 1
+            same = len(a.activations) == len(b.activations) and all(
+                tolerance.close(x, y, scale)
+                for x, y in zip(a.activations, b.activations, strict=True)
+            )
+            if not same or a.label != b.label:
+                report.warnings.append(
+                    f"explanation scores: {kind} window {n} re-measures differently "
+                    f"(label {a.label} -> {b.label})"
+                )
+    for name in ("detection", "fuzzing", "embedding_auroc"):
+        if getattr(old, name) != getattr(new, name):
+            report.warnings.append(f"explanation scores: {name} differs (recorded, not gated)")
+
+
+def _compare_environment(record: AuditRecord, now: RunEnvironment, report) -> None:
+    revision, dtype = pinned_environment(record)
+    if revision and now.model_revision and revision != now.model_revision:
+        report.fail(f"model revision {now.model_revision} is not the pinned {revision}")
+    if dtype not in {"auto", now.dtype} and reproduction_dtype(dtype) != now.dtype:
+        report.fail(f"loaded {now.dtype} weights; the record pins {dtype}")
+    elif dtype in HALF and now.dtype != dtype:
+        report.warnings.append(
+            f"reproduced in {now.dtype}; the record pins {dtype}, so its numbers are compared "
+            "within the 16-bit tolerance"
+        )
+    then = record.verdict.environment
+    if then is None:
+        report.warnings.append("record predates environment pinning; device and versions unknown")
+        return
+    names = ("device", "device_name", "torch_version", "transformers_version")
+    for name in (*names, "experts_implementation"):
+        if name == "device_name" and then.device_name is None:  # recorded before 0.0.19
+            continue
+        if getattr(then, name) != getattr(now, name):
+            report.warnings.append(
+                f"{name}: recorded {getattr(then, name)}, now {getattr(now, name)}"
+            )
+
+
+def _compare_verdicts(
+    old, new, tolerance: Tolerance, scale: float, report, *, half: bool = False
+) -> None:
+    """Each test's numbers and result, then the decision.
+
+    For a 16-bit record (``half``), a result may flip where 16-bit rounding moves a number
+    across its threshold. The flip is only a warning when the numbers agree within
+    ``tolerance`` and the recorded result follows from the recorded number. The recorded
+    decision must then follow exactly from the recorded results.
+    """
+    if len(old.adversarial_test_results) != len(new.adversarial_test_results):
+        report.fail("the record's test results don't match the probes and pairs it stores")
+        return
+    flips = 0
+    for n, (a, b) in enumerate(
+        zip(old.adversarial_test_results, new.adversarial_test_results, strict=True), 1
+    ):
+        flips += _compare_result(n, a, b, old.policy, tolerance, scale, report, half)
+
+    if flips and old.metrics is None:
+        report.fail("a result flipped, and the record has no metrics to re-derive")
+    elif flips:
+        _compare_decision(old, rederived(old), report)
+        if (old.metrics and old.metrics.gates) != new.metrics.gates or old.status != new.status:
+            report.warnings.append(
+                f"reproduced decision {new.status} with gates {new.metrics.gates}; the "
+                "recorded decision follows from the recorded results"
+            )
+    else:
+        _compare_decision(old, new, report)
+
+
+def _compare_result(n, a, b, policy, tolerance, scale: float, report, half: bool) -> int:
+    """Compare recorded test ``a`` with reproduced test ``b``. Return 1 for a 16-bit flip."""
+    label = f"test {n} ({a.kind}: {a.prompt[:40]!r})"
+    if (a.kind, a.prompt) != (b.kind, b.prompt):
+        report.fail(f"{label}: does not match the stored probe")
+        return 0
+    report.compared += 1
+    close = tolerance.close(a.activation, b.activation, scale)
+    if not close:
+        report.fail(f"{label}: activation recorded {a.activation}, reproduced {b.activation}")
+    if not tolerance.close(a.observed_delta, b.observed_delta, 1.0):
+        close = False
+        report.fail(f"{label}: Δ recorded {a.observed_delta}, reproduced {b.observed_delta}")
+    follows = recorded_pass(a, policy, scale)
+    if half and follows not in {None, a.passed}:
+        report.fail(f"{label}: recorded passed={a.passed} does not follow from its number")
+    elif a.passed != b.passed:
+        if half and close and follows is not None:
+            report.warnings.append(
+                f"{label}: passed={a.passed} recorded, {b.passed} reproduced, at its "
+                "threshold within 16-bit rounding"
+            )
+            return 1
+        report.fail(f"{label}: recorded passed={a.passed}, reproduced passed={b.passed}")
+    return 0
+
+
+def _compare_decision(old, new, report) -> None:
+    """Gates, balanced accuracy and status must match; causal metrics only warn."""
+    if old.metrics is None or old.metrics.gates != new.metrics.gates:
+        report.fail(
+            f"gates recorded {old.metrics.gates if old.metrics else None}, "
+            f"reproduced {new.metrics.gates}"
+        )
+    if not math.isclose(old.confidence_score, new.confidence_score, abs_tol=1e-6):
+        report.fail(
+            f"balanced accuracy recorded {old.confidence_score}, reproduced {new.confidence_score}"
+        )
+    if old.status != new.status:
+        report.fail(f"status recorded {old.status}, reproduced {new.status}")
+
+    oc, nc = old.causal_metrics, new.causal_metrics
+    if (oc is None) != (nc is None) or (
+        oc
+        and nc
+        and (
+            abs(oc.sufficiency_score - nc.sufficiency_score) > 0.1
+            or abs(oc.necessity_score - nc.necessity_score) > 0.1
+        )
+    ):
+        report.warnings.append("causal metrics differ (recorded, not gated)")

openinterp/revision.py

@@ -0,0 +1,45 @@
+"""What a revision's proposer sees of the record that it supersedes (issue #3246).
+
+``open-interpretability audit --supersedes <record>`` revises an earlier hypothesis about the same
+unit. Without this, the proposer wrote its new hypothesis from the scan alone and could
+repeat the old mistake. The brief gives the old hypothesis, its verdict, the gates it
+failed and the probes it got wrong. The proposer may see the measurements: only the
+reviewer must not.
+"""
+
+from __future__ import annotations
+
+from openinterp.core.fence import fence
+
+MAX_WRONG = 12  # wrong probes listed, so a long probe set doesn't flood the prompt
+PROBES = ("hard_negative", "positive_holdout")
+
+
+def previous_attempt(record) -> str:
+    """Return the brief on ``record`` for the proposer of the hypothesis that supersedes it."""
+    verdict = record.verdict
+    gates = verdict.metrics.gates if verdict.metrics else {}
+    failed = [gate for gate, ok in gates.items() if not ok]
+    wrong = [
+        r
+        for r in verdict.adversarial_test_results
+        if r.kind in PROBES and r.measured and not r.passed
+    ]
+    lines = [
+        "This hypothesis revises an earlier one about this unit. Fix what failed, and "
+        "keep what the earlier review confirmed.",
+        f"Earlier hypothesis:\n{fence(record.submission.natural_language_explanation)}",
+        f"Its verdict: {verdict.status}. Failed gates: {', '.join(failed) or 'none'}.",
+    ]
+    if wrong:
+        lines.append(f"Probes it got wrong ({min(len(wrong), MAX_WRONG)} of {len(wrong)}):")
+        lines += [_probe_line(r) for r in wrong[:MAX_WRONG]]
+    return "\n".join(lines) + "\n"
+
+
+def _probe_line(result) -> str:
+    """One wrong probe: what the hypothesis predicted, and what was measured."""
+    predicted = "active" if result.expected_active else "inactive"
+    measured = "n/a" if result.activation is None else f"{result.activation:.2f}"
+    kind = result.kind.replace("_", " ")
+    return f"- {kind}, predicted {predicted}, activation {measured}: {result.prompt!r}"

openinterp/runner_cache.py

@@ -0,0 +1,35 @@
+"""Keep loaded models across commands that run in one process (``open-interpretability loop``).
+
+Each ``open-interpretability`` command loads its model afresh, which is right for one command
+per process. ``open-interpretability loop`` runs many commands in one process, so it turns this
+cache on. Then each experiment on a model after the first skips the load. The cache is off by
+default.
+"""
+
+from __future__ import annotations
+
+import functools
+
+_runners: dict[tuple, object] | None = None  # None: the cache is off
+
+
+def keep() -> None:
+    """Turn the cache on for the rest of this process."""
+    global _runners
+    if _runners is None:
+        _runners = {}
+
+
+def cached(load):
+    """Wrap ``load`` so that, while the cache is on, equal arguments return one runner."""
+
+    @functools.wraps(load)
+    def wrapper(*args, **kwargs):
+        if _runners is None:
+            return load(*args, **kwargs)
+        key = (args, tuple(sorted(kwargs.items())))
+        if key not in _runners:
+            _runners[key] = load(*args, **kwargs)
+        return _runners[key]
+
+    return wrapper