open-interpretability 0.0.20__py3-none-any.whl

openinterp/core/errata.py

@@ -0,0 +1,244 @@
+"""Errata: harness bugs that affected signed records (``docs/PROTOCOL.md`` §5).
+
+Records cannot be rewritten. A maintainer who finds a bug that affected some of them
+appends an erratum to ``wiki/errata.jsonl``. Then they sign the file with
+``open-interpretability sign wiki/errata.jsonl``. Each line is one :class:`Erratum`. It names the
+records it covers (a list of record paths, a :class:`ErratumRule`, or both), the bug, and
+the commit that fixed it. It either lists :class:`Edit` objects for the records, or sets
+the records aside.
+
+The record files never change. The site build applies the edits to a copy of each covered
+record (:func:`apply_errata`). So pages, standings and ``registry.parquet`` read the
+corrected values. ``open-interpretability reproduce`` checks the corrected record, and skips a
+record that is set aside.
+
+``open-interpretability check`` verifies the file (:mod:`openinterp.errata_checks`). Errata have
+no page of their own. The site shows each erratum on the experiments it covers, with the old
+and new value of each edit. The standing rule (:mod:`openinterp.builder.standing`) leaves
+out the records that are set aside.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import date as Date
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import AwareDatetime, Field, JsonValue, model_validator
+
+from openinterp.core.paths import DEFAULT_WIKI_DIR
+from openinterp.core.strict import StrictModel
+
+if TYPE_CHECKING:
+    from openinterp.core.schemas import AuditRecord
+
+ERRATA_FILE = "errata.jsonl"
+"""The errata file's name in the wiki directory."""
+
+FIXED_PATHS = ("submission.identifier", "verdict.timestamp")
+"""Fields an edit can't change: they give the record's unit and id, so its place."""
+
+
+class Edit(StrictModel):
+    """One corrected field of a record: its dotted path and its new value.
+
+    The path names keys and list indices of the record's JSON, for example
+    ``verdict.status`` or ``submission.top_examples.0.max_activation``. The field must exist.
+    """
+
+    path: str = Field(pattern=r"^[a-z_]+(\.([a-z_]+|[0-9]+))*$")
+    value: JsonValue
+
+    @model_validator(mode="after")
+    def _not_fixed(self) -> Edit:
+        if any(self.path == p or self.path.startswith(p + ".") for p in FIXED_PATHS):
+            raise ValueError(f"an edit can't change {self.path}: it places the record")
+        return self
+
+
+@dataclass(frozen=True)
+class AppliedEdit:
+    """An edit as applied to one record: which erratum made it, and the value before."""
+
+    erratum: str  # the erratum's id
+    path: str
+    before: Any
+    after: Any
+
+
+class ErratumRule(StrictModel):
+    """A rule that selects records. A record matches when it matches every field given.
+
+    A field that is ``None`` matches every record. A record without a review policy has no
+    protocol version, so a rule with ``protocol_versions`` does not match it.
+    """
+
+    models: list[str] | None = Field(default=None, min_length=1, description="Model names.")
+    kinds: list[Literal["mlp_neuron_pole", "attn_head", "dictionary_feature"]] | None = Field(
+        default=None, min_length=1
+    )
+    protocol_versions: list[str] | None = Field(default=None, min_length=1)
+    harness_versions: list[str] | None = Field(default=None, min_length=1)
+    reviewed_from: AwareDatetime | None = Field(
+        default=None, description="First verdict time that matches (inclusive)."
+    )
+    reviewed_before: AwareDatetime | None = Field(
+        default=None, description="Verdict time from which records no longer match."
+    )
+
+    @model_validator(mode="after")
+    def _selects_something(self) -> ErratumRule:
+        if all(value is None for value in self.model_dump().values()):
+            raise ValueError("a rule needs at least one field; list the records instead")
+        return self
+
+    def matches(self, record: AuditRecord) -> bool:
+        """Return whether ``record`` matches every field of the rule."""
+        ident, verdict = record.submission.identifier, record.verdict
+        provenance = record.submission.provenance
+        policy = verdict.policy if verdict is not None else None
+        checks = (
+            (self.models, ident.model_name),
+            (self.kinds, ident.kind),
+            (self.protocol_versions, policy.protocol_version if policy else None),
+            (self.harness_versions, provenance.harness_version if provenance else None),
+        )
+        if any(allowed is not None and value not in allowed for allowed, value in checks):
+            return False
+        when = verdict.timestamp if verdict is not None else None
+        if self.reviewed_from is not None and (when is None or when < self.reviewed_from):
+            return False
+        return self.reviewed_before is None or (when is not None and when < self.reviewed_before)
+
+
+class Erratum(StrictModel):
+    """One harness bug and the records it affected. One line of ``wiki/errata.jsonl``."""
+
+    id: str = Field(pattern=r"^[a-z0-9][a-z0-9-]*$", description="Unique; the site's anchor.")
+    date: Date
+    title: str = Field(min_length=1, description="One line for the banner.")
+    bug: str = Field(min_length=1, description="What was wrong, and what it did to records.")
+    fixed_in: str = Field(pattern=r"^[0-9a-f]{7,40}$", description="The commit that fixed it.")
+    edits: list[Edit] = Field(default_factory=list, description="Corrections to each record.")
+    set_aside: bool = Field(default=False, description="The records count toward no status.")
+    records: list[str] = Field(
+        default_factory=list,
+        description="Covered records, as paths relative to wiki/experiments/.",
+    )
+    rule: ErratumRule | None = None
+
+    @model_validator(mode="after")
+    def _covers_something(self) -> Erratum:
+        if not self.records and self.rule is None:
+            raise ValueError("an erratum needs records, a rule, or both")
+        if bool(self.edits) == self.set_aside:
+            raise ValueError("an erratum either lists edits or sets its records aside")
+        return self
+
+    def covers(self, record: AuditRecord) -> bool:
+        """Return whether the erratum covers ``record``: it is listed or matches the rule."""
+        return record_ref(record) in self.records or (
+            self.rule is not None and self.rule.matches(record)
+        )
+
+
+def errata_path(wiki_dir: Path | str = DEFAULT_WIKI_DIR) -> Path:
+    """Where the errata file is: ``<wiki_dir>/errata.jsonl``."""
+    return Path(wiki_dir) / ERRATA_FILE
+
+
+def record_ref(record: AuditRecord) -> str:
+    """How an erratum names ``record``: its path relative to ``wiki/experiments/``."""
+    from openinterp.builder.wiki import archive_path
+    from openinterp.core.paths import experiments_dir
+
+    return archive_path(Path(), record).relative_to(experiments_dir(Path())).as_posix()
+
+
+def parse_errata(text: str) -> list[Erratum]:
+    """Parse the content of an errata file. Raises ``ValueError`` naming the bad line."""
+    errata = []
+    for number, line in enumerate(text.splitlines(), start=1):
+        try:
+            errata.append(Erratum.model_validate_json(line))
+        except ValueError as exc:
+            raise ValueError(f"line {number}: {exc}") from exc
+    return errata
+
+
+def load_errata(wiki_dir: Path | str = DEFAULT_WIKI_DIR) -> list[Erratum]:
+    """Every erratum in ``wiki_dir``, in file order; none if there is no errata file."""
+    path = errata_path(wiki_dir)
+    return parse_errata(path.read_text(encoding="utf-8")) if path.exists() else []
+
+
+def covering(errata: Sequence[Erratum], record: AuditRecord) -> list[Erratum]:
+    """The errata in ``errata`` that cover ``record``, in file order."""
+    return [erratum for erratum in errata if erratum.covers(record)]
+
+
+def apply_errata(
+    record: AuditRecord, errata: Sequence[Erratum]
+) -> tuple[AuditRecord, list[AppliedEdit]]:
+    """``record`` with the edits of ``errata`` applied in order, and what each edit changed.
+
+    Returns ``record`` itself when no erratum edits it. Raises ``ValueError`` when an edit's
+    path is not in the record, or the edited record is not valid.
+    """
+    from openinterp.core.schemas import AuditRecord
+
+    edits = [(erratum.id, edit) for erratum in errata for edit in erratum.edits]
+    if not edits:
+        return record, []
+    data = record.model_dump(mode="json")
+    applied = []
+    for erratum_id, edit in edits:
+        before = _replace(data, edit.path, edit.value)
+        applied.append(AppliedEdit(erratum_id, edit.path, before, edit.value))
+    try:
+        return AuditRecord.model_validate_json(json.dumps(data)), applied
+    except ValueError as exc:
+        raise ValueError(f"the edited record is not valid: {exc}") from exc
+
+
+def _replace(data: Any, path: str, value: Any) -> Any:
+    """Set the field at dotted ``path`` in ``data`` to ``value``; return its old value."""
+    *parents, last = path.split(".")
+    node = data
+    try:
+        for part in parents:
+            node = node[int(part)] if isinstance(node, list) else node[part]
+        key = int(last) if isinstance(node, list) else last
+        before = node[key]
+    except (KeyError, IndexError, TypeError, ValueError):
+        raise ValueError(f"the record has no field {path}") from None
+    node[key] = value
+    return before
+
+
+def corrected(record: AuditRecord, errata: Sequence[Erratum]) -> tuple[AuditRecord, bool]:
+    """``record`` with the edits of the errata that cover it, and whether one sets it aside."""
+    found = covering(errata, record)
+    return apply_errata(record, found)[0], any(erratum.set_aside for erratum in found)
+
+
+def standing_records(
+    records: Sequence[AuditRecord], errata: Sequence[Erratum]
+) -> list[AuditRecord]:
+    """The records that count toward a status, with their errata's edits applied.
+
+    This is the standing rule's first step (:mod:`openinterp.builder.standing`), for readers
+    that don't build the site's tree. A record that an erratum sets aside is left out. The
+    exception is a unit whose records are all set aside: then its status rests on them, so
+    they stay. The order of ``records`` is kept.
+    """
+    fixed = [(record, *corrected(record, errata)) for record in records]
+    counted = {r.submission.identifier.slug for r, _, aside in fixed if not aside}
+    return [
+        edited
+        for record, edited, aside in fixed
+        if not aside or record.submission.identifier.slug not in counted
+    ]

openinterp/core/evidence.py

@@ -0,0 +1,160 @@
+"""Bulky record evidence in a content-addressed store, outside the repository (issue #3254).
+
+Two fields make up about 59% of a record: ``submission.top_examples`` and
+``verdict.explanation_scores``. :func:`split` takes them out of a record's JSON. Each one
+becomes a reference, ``{"evidence_sha256": "<hash>"}``, to a blob that holds the field's
+exact JSON. :func:`resolve` puts each blob back, and refuses a blob whose hash is wrong.
+
+A record's signature covers its file's bytes, so it covers the hashes. A hash covers its
+blob. So a signed slim record still vouches for all of its evidence. Records are
+write-once, so the records that are already whole stay whole.
+
+Blobs live in a local store, ``~/.cache/openinterp/evidence/`` by default
+(``$OPENINTERP_EVIDENCE_DIR``). A blob that isn't there is fetched, read-only, from the
+public dataset :data:`EVIDENCE_REPO`. :func:`openinterp.builder.wiki.archive_record` writes
+slim records unless ``OPENINTERP_OFFLOAD_EVIDENCE=0``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+FIELDS = (("submission", "top_examples"), ("verdict", "explanation_scores"))
+"""The record fields that :func:`split` moves to the store: (parent key, field)."""
+REF_KEY = "evidence_sha256"
+EVIDENCE_REPO = "sackfield/open-interpretability-evidence"
+"""The public Hugging Face dataset that holds the blobs, by path ``<sha[:2]>/<sha>.json``."""
+DIR_ENV = "OPENINTERP_EVIDENCE_DIR"
+OFFLOAD_ENV = "OPENINTERP_OFFLOAD_EVIDENCE"  # "0" makes archive_record write whole records
+
+
+class EvidenceMissing(ValueError):
+    """A record refers to a blob that neither the local store nor the dataset holds."""
+
+
+def offload_enabled() -> bool:
+    """Whether new archived records are written slim: yes, unless the variable is ``0``.
+
+    Phase 3 of issue #3254 turned this on. CI uploads the blobs from ``evidence/<branch>``.
+    """
+    return os.environ.get(OFFLOAD_ENV, "1") != "0"
+
+
+def store_dir() -> Path:
+    """The local blob store: ``$OPENINTERP_EVIDENCE_DIR``, else ``~/.cache/openinterp/evidence``."""
+    return Path(os.environ.get(DIR_ENV) or Path.home() / ".cache" / "openinterp" / "evidence")
+
+
+def blob_name(sha: str) -> str:
+    """A blob's path in the store and in the dataset."""
+    return f"{sha[:2]}/{sha}.json"
+
+
+def canonical(value: Any) -> bytes:
+    """The bytes that a blob holds for ``value``: sorted keys, no spaces, UTF-8."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def sha256(data: bytes) -> str:
+    """The hex SHA-256 of ``data``."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def is_ref(value: Any) -> bool:
+    """Whether ``value`` is a reference that :func:`split` wrote."""
+    return isinstance(value, dict) and set(value) == {REF_KEY}
+
+
+def put(data: bytes, root: Path | None = None) -> str:
+    """Store ``data`` in the local store, and return its hash."""
+    sha = sha256(data)
+    path = (root or store_dir()) / blob_name(sha)
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(f".{os.getpid()}.tmp")
+        tmp.write_bytes(data)
+        tmp.replace(path)  # atomic: a reader sees no blob or a whole one
+    return sha
+
+
+def _fetch(sha: str) -> bytes | None:
+    """The blob from the public dataset, or ``None`` if it can't be had."""
+    try:
+        from huggingface_hub import hf_hub_download
+
+        local = hf_hub_download(EVIDENCE_REPO, blob_name(sha), repo_type="dataset")
+    except Exception:  # noqa: BLE001 - offline, no dataset yet, or no such blob
+        return None
+    return Path(local).read_bytes()
+
+
+def get(sha: str, root: Path | None = None, fetch=None) -> bytes:
+    """The blob with hash ``sha``: from the local store, else fetched and stored.
+
+    ``fetch`` defaults to the read-only fetch from :data:`EVIDENCE_REPO`. Raises
+    :class:`EvidenceMissing` when the blob can't be had or its hash is wrong.
+    """
+    path = (root or store_dir()) / blob_name(sha)
+    data = path.read_bytes() if path.exists() else (fetch or _fetch)(sha)
+    if data is None:
+        raise EvidenceMissing(
+            f"evidence blob {sha} is not in {root or store_dir()} or {EVIDENCE_REPO}"
+        )
+    if sha256(data) != sha:
+        raise EvidenceMissing(f"evidence blob {sha} has the wrong hash; the store holds a bad copy")
+    if not path.exists():
+        put(data, root)
+    return data
+
+
+def split(data: dict, root: Path | None = None) -> dict:
+    """A copy of a record's JSON with each field in :data:`FIELDS` moved to the store.
+
+    A field that is missing, ``None`` or already a reference stays as it is.
+    """
+    out = json.loads(json.dumps(data))
+    for parent, field in FIELDS:
+        node = out.get(parent)
+        if not isinstance(node, dict) or node.get(field) is None or is_ref(node[field]):
+            continue
+        node[field] = {REF_KEY: put(canonical(node[field]), root)}
+    return out
+
+
+def resolve(data: Any, root: Path | None = None, fetch=None) -> Any:
+    """``data`` with each reference in :data:`FIELDS` replaced by its blob's value.
+
+    Data with no reference comes back as it is, so whole records cost nothing.
+    """
+    if not isinstance(data, dict):
+        return data
+    refs = [
+        (parent, field)
+        for parent, field in FIELDS
+        if isinstance(data.get(parent), dict) and is_ref(data[parent].get(field))
+    ]
+    if not refs:
+        return data
+    out = dict(data)
+    for parent, field in refs:
+        sha = data[parent][field][REF_KEY]
+        out[parent] = {**out[parent], field: json.loads(get(sha, root, fetch))}
+    return out
+
+
+def resolved_text(json_data: str | bytes | bytearray) -> str | bytes | bytearray:
+    """A record's JSON text with its references resolved; whole records come back as given."""
+    text = json_data.decode() if isinstance(json_data, bytes | bytearray) else json_data
+    if REF_KEY not in text:
+        return json_data
+    return json.dumps(resolve(json.loads(text)))
+
+
+def resolved_dict_text(obj: Any) -> str | None:
+    """A record dict's JSON text with its references resolved, or ``None`` if it has none."""
+    resolved = resolve(obj)
+    return None if resolved is obj else json.dumps(resolved)

openinterp/core/examples.py

@@ -0,0 +1,93 @@
+"""What a scan shows of a unit.
+
+A scan shows a unit's top-activating examples and the histogram of its strengths. For a
+neuron, it shows the same for the other pole.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field, model_validator
+
+from openinterp.core.identifiers import Pole
+from openinterp.core.strict import StrictModel, UnitFloat
+
+
+class Histogram(StrictModel):
+    """Counts of strengths in bins; ``bin_edges`` has one more entry than ``counts``."""
+
+    bin_edges: list[float] = Field(min_length=2)
+    counts: list[int]
+
+    @model_validator(mode="after")
+    def _shape(self) -> Histogram:
+        if len(self.counts) != len(self.bin_edges) - 1:
+            raise ValueError("counts must have exactly len(bin_edges) - 1 entries")
+        return self
+
+    def share_at_least(self, line: float) -> float:
+        """Return the share of values at or above ``line``.
+
+        Only bins wholly above ``line`` count, so the result is a lower bound, within one
+        bin of the exact share.
+        """
+        total = sum(self.counts)
+        above = sum(n for lo, n in zip(self.bin_edges, self.counts, strict=False) if lo >= line)
+        return above / total if total else 0.0
+
+
+class ActivatingExample(StrictModel):
+    """A text snippet with per-token strengths (non-negative magnitudes).
+
+    For an attention head, ``attends_to`` lists the tokens the peak token attends to
+    most, strongest first, with their attention weights in ``attention_weights``.
+    ``peak_labels`` gives the peak token's label in each of the scan's label sets. A
+    document label, such as language, is the label of the token's document. It is
+    ``None`` when the scan had no label sets, or the peak token has no label in any.
+    """
+
+    text: str
+    tokens: list[str]
+    activations: list[float]
+    max_activation: float = Field(ge=0.0)
+    max_token_index: int = Field(ge=0)
+    attends_to: list[int] = Field(default_factory=list)
+    attention_weights: list[UnitFloat] = Field(default_factory=list)
+    peak_labels: dict[str, str] | None = None
+
+    @model_validator(mode="after")
+    def _aligned(self) -> ActivatingExample:
+        if len(self.tokens) != len(self.activations):
+            raise ValueError("tokens and activations must be the same length")
+        if self.tokens and self.max_token_index >= len(self.tokens):
+            raise ValueError("max_token_index out of range")
+        if len(self.attends_to) != len(self.attention_weights):
+            raise ValueError("attends_to and attention_weights must be the same length")
+        if any(not 0 <= i <= self.max_token_index for i in self.attends_to):
+            raise ValueError("attends_to must index tokens up to the peak (attention is causal)")
+        return self
+
+
+class OppositePole(StrictModel):
+    """A neuron's other pole, read from the same scan as the audited pole.
+
+    The neuron's page shows it beside the audited pole. It is reported, not gated, and
+    neither agent sees it.
+    """
+
+    pole: Pole
+    top_examples: list[ActivatingExample]
+    activation_histogram: Histogram | None = None
+
+
+def check_opposite_pole(model) -> None:
+    """Reject an ``opposite_pole`` that the unit cannot have.
+
+    Only a neuron pole has an opposite pole, and it must not be the audited pole.
+    """
+    if model.opposite_pole is None:
+        return
+    pole = model.identifier.pole
+    if pole is None:
+        raise ValueError("opposite_pole is only for neuron poles")
+    if model.opposite_pole.pole == pole:
+        raise ValueError("opposite_pole must be the pole the identifier does not name")

openinterp/core/exceptions.py

@@ -0,0 +1,29 @@
+"""Exception hierarchy for openinterp."""
+
+
+class OpenInterpError(Exception):
+    """Base class for all openinterp errors."""
+
+
+class ArchitectureNotSupportedError(OpenInterpError):
+    """The hook runner could not locate MLP layers on the given model."""
+
+
+class PatchingError(OpenInterpError):
+    """An activation patching run could not be performed as requested."""
+
+
+class ShapeMismatchError(PatchingError):
+    """Source and target activations have incompatible shapes."""
+
+
+class AgentError(OpenInterpError):
+    """An LLM agent failed to produce a valid structured response."""
+
+
+class RegistryError(OpenInterpError):
+    """An audit record on disk is missing or malformed."""
+
+
+class SyncError(OpenInterpError):
+    """Deploying the static site to object storage failed."""

openinterp/core/explanation.py

@@ -0,0 +1,130 @@
+"""Schemas for scoring an explanation on held-out text (detection, fuzzing, embedding).
+
+These follow Delphi (Paulo et al., 2025). A judge sees only the explanation.
+
+- *detection*: the judge picks out the held-out windows that activate the pole.
+- *fuzzing*: the judge says whether the marked tokens in a window activate the pole.
+- *embedding*: an embedding model ranks windows by similarity to the explanation.
+
+The scores are reported, not gated (docs/PROTOCOL.md §4).
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from openinterp.core.costs import ExperimentCosts
+from openinterp.core.strict import StrictModel, UnitFloat
+
+
+class ScoredWindow(StrictModel):
+    """A held-out window as the judge saw it, measured on its own (like a probe)."""
+
+    text: str
+    tokens: list[str]
+    activations: list[float]
+    quantile: int | None = Field(
+        default=None,
+        ge=0,
+        description="Activation bin of the window's peak among active held-out windows "
+        "(0 = weakest); None when the window is inactive.",
+    )
+    highlighted: list[int] = Field(
+        default_factory=list, description="Fuzzing: indices of the tokens marked for the judge."
+    )
+    label: bool = Field(
+        description="What a perfect judge answers: the window is active (detection), or its "
+        "marked tokens are exactly its active tokens (fuzzing)."
+    )
+    judged: bool | None = Field(default=None, description="The judge's answer.")
+    similarity: float | None = Field(
+        default=None, description="Embedding: cosine between the explanation and the window."
+    )
+
+
+class JudgeScore(StrictModel):
+    """How well the judge's answers match the labels.
+
+    ``recall_by_quantile[q]`` is the share of positive windows in activation bin ``q``
+    that the judge got right. It is ``None`` when the bin had no positive windows. It
+    shows the weak activations, which the top activations can otherwise hide.
+    """
+
+    balanced_accuracy: UnitFloat
+    true_positive_rate: UnitFloat | None
+    false_positive_rate: UnitFloat | None
+    recall_by_quantile: list[UnitFloat | None]
+
+
+class ControlScore(StrictModel):
+    """The judge's scores for a control explanation, on the same windows as the real one.
+
+    A control shows how much of a score comes from the windows and not from the
+    explanation. ``empty`` gives the judge no explanation. ``other_unit`` gives it the
+    explanation of another unit of the same model. A real explanation should score well
+    above both.
+    """
+
+    kind: str = Field(description="'empty' or 'other_unit'.")
+    explanation: str = Field(description="What the judge saw; '' for the empty control.")
+    source_slug: str | None = Field(
+        default=None, description="other_unit: the unit whose explanation this is."
+    )
+    detection_judged: list[bool] = Field(default_factory=list)
+    fuzzing_judged: list[bool] = Field(default_factory=list)
+    detection: JudgeScore | None = None
+    fuzzing: JudgeScore | None = None
+
+
+class ExplanationScores(StrictModel):
+    """Delphi-style scores of ``explanation`` on windows the proposer never saw.
+
+    Windows are cut from corpus snippets outside the scan's top examples and measured on
+    their own, exactly as the judge reads them. Active windows (peak ≥ ``threshold``) are
+    drawn evenly from ``quantiles`` bins of their peak strength, split at
+    ``quantile_edges``, and matched with as many inactive ones.
+    """
+
+    slug: str = Field(description="The unit scored: its identifier's slug.")
+    explanation: str = Field(min_length=1)
+    threshold: float = Field(gt=0.0, description="Pole strength counted as active.")
+    window_tokens: int = Field(gt=0)
+    quantiles: int = Field(gt=0)
+    quantile_edges: list[float]
+    seed: int
+    corpus: str
+    corpus_sha256: str | None = None
+    candidate_windows: int = Field(ge=0, description="Held-out windows measured.")
+    active_windows: int = Field(ge=0, description="Of those, windows reaching the threshold.")
+    judge_model: str | None = None
+    embedding_model: str | None = None
+    detection: JudgeScore | None = None
+    fuzzing: JudgeScore | None = None
+    embedding_auroc: UnitFloat | None = Field(
+        default=None,
+        description="AUROC of the embedding similarity for active vs inactive detection windows.",
+    )
+    detection_windows: list[ScoredWindow] = Field(default_factory=list)
+    fuzzing_windows: list[ScoredWindow] = Field(default_factory=list)
+    fuzzing_decoys: str | None = Field(
+        default=None,
+        description="How fuzzing decoys were marked: 'matched-shape' (the real marks' count "
+        "and spacing, moved) since issue #3505. None for older scores, whose decoys were "
+        "random tokens that explanation-free rules could tell apart.",
+    )
+    rule_baseline: dict[str, float] = Field(
+        default_factory=dict,
+        description="Balanced accuracy of explanation-free rules on these windows, best cut "
+        "chosen on them, so an upper bound: detection_length, fuzzing_contiguous, "
+        "fuzzing_count. A score means something only above these.",
+    )
+    controls: list[ControlScore] = Field(
+        default_factory=list,
+        description="The same windows judged with control explanations "
+        "(open-interpretability score --controls). Each control's answers are scored against "
+        "these windows' labels.",
+    )
+    costs: ExperimentCosts | None = Field(
+        default=None,
+        description="What scoring cost; a review moves it into the record's provenance.",
+    )