open-interpretability 0.0.20__py3-none-any.whl

openinterp/concepts.py

@@ -0,0 +1,400 @@
+"""Labelled concept sets from annotated Hugging Face datasets (`open-interpretability concepts`).
+
+A concept set is JSON lines ``{"text": ..., "spans": [[start, end], ...]}``. It is the
+labelled text that ``open-interpretability probe-compare`` reads. The spans are the characters where
+the concept holds, marked by human annotators, never by the model. A concept set feeds
+sparse-probing searches. It also gives reviewers positive holdouts from a source that
+the proposer never saw. A
+``<name>.source.json`` sidecar (:class:`~openinterp.core.probing.ConceptSource`) pins
+the dataset commit, split, label and licence.
+
+Two kinds of label are read:
+
+* *word tags*: a span over each word with the tag. The tags are CoNLL-2003 entities and
+  Penn Treebank tags, and Universal Dependencies parts of speech and relations. A tag
+  matches a label
+  exactly, without its BIO prefix (``B-PER``, ``I-PER`` -> ``PER``) or without its
+  subtype (``nmod:poss`` -> ``nmod``). Sentences are joined back into documents.
+* *document classes* (language, news topic): a span over the whole text of each
+  document of the class. The sample is balanced: half the documents are of the class,
+  half are of the others.
+
+Splits are small (a few MB), so each is read whole, then sampled with a seed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+import re
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import pyarrow.parquet as pq
+
+from openinterp.core.probing import ConceptSource
+from openinterp.corpus import _license, source_path
+from openinterp.harness.annotations import Span
+
+
+@dataclass(frozen=True)
+class ConceptPreset:
+    """Where a concept preset's labels are, and how its rows become documents."""
+
+    dataset: str
+    files: str  # glob within the dataset repo, with {split} and, for treebanks, {subset}
+    split: str  # the default split: a held-out one, which is small
+    column: str  # word tags, or one class per row
+    # How rows become documents. "conll": pre-tokenised words, joined with spaces. "ud":
+    # words found in each sentence's text. "document": one per row, with one class.
+    layout: str
+    revision: str | None = None
+    subset: str | None = None  # default treebank, for "ud"
+    bio: bool = False  # tags carry B-/I- prefixes
+    text_column: str = "text"
+
+
+# Licences differ, and some forbid redistribution: check before quoting excerpts in the wiki.
+CONCEPT_PRESETS = {
+    # CoNLL-2003 English NER (PER, ORG, LOC, MISC) over Reuters news of 1996. Licence
+    # "other": the text is Reuters RCV1, for research use, so don't publish excerpts. The
+    # main branch is a loading script, so read the Hub's Parquet conversion.
+    "conll2003-ner": ConceptPreset(
+        "eriktks/conll2003",
+        "conll2003/{split}/*.parquet",
+        "validation",
+        "ner_tags",
+        "conll",
+        revision="refs/convert/parquet",
+        bio=True,
+    ),
+    # The same sentences' Penn Treebank tags (NNP, VBD, ...): a second part-of-speech
+    # source, independent of Universal Dependencies' annotators and genres.
+    "conll2003-pos": ConceptPreset(
+        "eriktks/conll2003",
+        "conll2003/{split}/*.parquet",
+        "validation",
+        "pos_tags",
+        "conll",
+        revision="refs/convert/parquet",
+    ),
+    # Universal Dependencies parts of speech (NOUN, VERB, ADP, ...) for any of its ~300
+    # treebanks; --subset picks one (en_ewt: English web text; en_gum: eight genres).
+    # Licences are per treebank (en_ewt CC BY-SA 4.0, en_gum CC BY-NC-SA 4.0).
+    "ud-upos": ConceptPreset(
+        "universal-dependencies/universal_dependencies",
+        "parquet/{subset}/{split}.parquet",
+        "dev",
+        "upos",
+        "ud",
+        subset="en_ewt",
+    ),
+    # The same treebanks' dependency relations (nsubj, obj, amod, ...), for syntax neurons.
+    "ud-deprel": ConceptPreset(
+        "universal-dependencies/universal_dependencies",
+        "parquet/{subset}/{split}.parquet",
+        "dev",
+        "deprel",
+        "ud",
+        subset="en_ewt",
+    ),
+    # Sentences and reviews in 20 languages. Their codes are ar, bg, de, el, en, es, fr,
+    # hi, it, ja, nl, pl, pt, ru, sw, th, tr, ur, vi and zh. No licence on the card; its
+    # sources include Amazon reviews and XNLI (CC BY-NC 4.0). The main branch is CSV.
+    "language-identification": ConceptPreset(
+        "papluca/language-identification",
+        "default/{split}/*.parquet",
+        "validation",
+        "labels",
+        "document",
+        revision="refs/convert/parquet",
+    ),
+    # AG News headlines and lead sentences in four topics (World, Sports, Business,
+    # Sci/Tech). Licence "unknown": academic, non-commercial use.
+    "ag_news": ConceptPreset(
+        "fancyzhx/ag_news", "data/{split}-*.parquet", "test", "label", "document"
+    ),
+}
+
+
+@dataclass(frozen=True)
+class Sentence:
+    """One annotated sentence, with a span per tagged word, and where it starts a document."""
+
+    text: str
+    spans: list[Span]  # one per tagged word
+    newdoc: bool = False
+    newpar: bool = True
+
+
+# Pre-tokenised CoNLL text: "lobster ," and "( AP )" are joined as written, "lobster,", "(AP)".
+_ATTACH_LEFT = re.compile(r"[.,;:!?%)\]}]+|n't|'(?:s|re|ve|m|ll|d)", re.IGNORECASE)
+_ATTACH_RIGHT = re.compile(r"[(\[{$]")
+
+
+def join_words(words: Sequence[str]) -> tuple[str, list[tuple[int, int]]]:
+    """Pre-tokenised words as text, with each word's characters [start, end)."""
+    text, offsets = "", []
+    for i, word in enumerate(words):
+        if i and not (_ATTACH_LEFT.fullmatch(word) or _ATTACH_RIGHT.fullmatch(words[i - 1])):
+            text += " "
+        offsets.append((len(text), len(text) + len(word)))
+        text += word
+    return text, offsets
+
+
+def locate_words(
+    text: str, words: Sequence[str], mwt: Sequence[dict] = ()
+) -> list[tuple[int, int]] | None:
+    """Return each word's characters in its sentence's ``text``.
+
+    The words of a multiword token (French "du" = "de" + "le") share its surface form's
+    characters. ``None`` if a word isn't where it should be, because that would misplace
+    every label after it.
+    """
+    fused = {}
+    for token in mwt or ():
+        first, last = token["id"].split("-")
+        fused[int(first) - 1] = (int(last) - 1, token["form"])
+    out: list[tuple[int, int]] = []
+    cursor = i = 0
+    while i < len(words):
+        last, form = fused.get(i, (i, words[i]))
+        start = text.find(form, cursor) if form else -1
+        if start < 0 or text[cursor:start].strip():
+            return None
+        cursor = start + len(form)
+        out += [(start, cursor)] * (last - i + 1)
+        i = last + 1
+    return out
+
+
+def group_sentences(sentences: Sequence[Sentence], max_chars: int) -> list[tuple[str, list[Span]]]:
+    """Join consecutive sentences into documents of at most ``max_chars``.
+
+    A new document starts at each new source document, or when the next sentence wouldn't
+    fit. Newlines separate paragraphs, and a space separates the sentences in one. A
+    sentence longer than ``max_chars`` is cut, and its spans with it.
+    """
+    docs: list[tuple[str, list[Span]]] = []
+    text, spans = "", []
+    for sent in sentences:
+        sep = "\n" if sent.newpar else " "
+        if text and (sent.newdoc or len(text) + len(sep) + len(sent.text) > max_chars):
+            docs.append((text, spans))
+            text, spans = "", []
+        shift = len(text) + len(sep) if text else 0
+        text = (text + sep if text else "") + sent.text
+        spans += [Span(s.start + shift, s.end + shift, s.label) for s in sent.spans]
+        if len(text) > max_chars:
+            text = text[:max_chars]
+            spans = [
+                Span(s.start, min(s.end, max_chars), s.label) for s in spans if s.start < max_chars
+            ]
+    if text:
+        docs.append((text, spans))
+    return docs
+
+
+def tag_matches(tag: str, label: str) -> bool:
+    """True when ``tag`` is ``label``, or ``label`` with a ``:subtype`` (``nmod:poss``)."""
+    return tag == label or tag.split(":")[0] == label
+
+
+def _tag(tag, names: list[str] | None, bio: bool) -> str | None:
+    """A word's or row's label as text, or ``None`` for none (``O``, ``_``)."""
+    if tag is None:
+        return None
+    tag = names[tag] if names is not None and isinstance(tag, int) else str(tag)
+    if tag in ("O", "_", ""):
+        return None
+    return re.sub(r"^[BI]-", "", tag) if bio else tag
+
+
+def class_names(schema, column: str) -> list[str] | None:
+    """Return the names of a Hugging Face ClassLabel column, or a sequence of them.
+
+    Parquet stores them as integers. The names are in the file's ``huggingface`` schema
+    metadata.
+    """
+    meta = (schema.metadata or {}).get(b"huggingface")
+    if meta is None:
+        return None
+    feature = json.loads(meta).get("info", {}).get("features", {}).get(column, {})
+    feature = feature.get("feature", feature)  # Sequence(ClassLabel) holds it inside
+    return feature.get("names")
+
+
+def _read_rows(fs, paths: Sequence[str], columns: Sequence[str]) -> tuple[list[dict], list | None]:
+    rows, names = [], None
+    for path in sorted(paths):
+        with fs.open(path, "rb") as fh:
+            file = pq.ParquetFile(fh)
+            names = names or class_names(file.schema_arrow, columns[-1])
+            rows += file.read(columns=list(columns)).to_pylist()
+    return rows, names
+
+
+def _documents(preset: ConceptPreset, column: str, rows, names, max_chars: int):
+    """The split's documents, each with a span per tagged word or class."""
+    if preset.layout == "document":
+        docs = []
+        for row in rows:
+            text = (row[preset.text_column] or "").strip()[:max_chars]
+            label = _tag(row[column], names, preset.bio)
+            if text:
+                docs.append((text, [Span(0, len(text), label)] if label else []))
+        return docs, 0
+    sentences, skipped = [], 0
+    for row in rows:
+        words = row["tokens"] or []
+        if preset.layout == "conll":
+            text, offsets = join_words(words)
+            newdoc, newpar = False, True
+        else:
+            text = row[preset.text_column] or ""
+            offsets = locate_words(text, words, row.get("mwt"))
+            comments = row.get("comments") or []
+            newdoc = any(c.startswith("newdoc") for c in comments)
+            newpar = newdoc or any(c.startswith("newpar") for c in comments)
+        if not words or offsets is None:
+            skipped += 1
+            continue
+        spans = [
+            Span(start, end, label)
+            for (start, end), tag in zip(offsets, row[column], strict=True)
+            if (label := _tag(tag, names, preset.bio)) is not None
+        ]
+        sentences.append(Sentence(text, spans, newdoc, newpar))
+    return group_sentences(sentences, max_chars), skipped
+
+
+@dataclass
+class LoadedSplit:
+    """One split read whole: its documents with spans, and where they came from."""
+
+    docs: list[tuple[str, list[Span]]]
+    dataset: str
+    revision: str
+    files: str
+    license: str | None
+    skipped_sentences: int
+
+    def counts(self) -> Counter:
+        """How many words (or documents) carry each label."""
+        return Counter(span.label for _, spans in self.docs for span in spans)
+
+
+def load_split(
+    name: str,
+    *,
+    split: str | None = None,
+    subset: str | None = None,
+    column: str | None = None,
+    max_chars: int = 3000,
+) -> LoadedSplit:
+    """A preset's split at a pinned commit, as labelled documents."""
+    from huggingface_hub import HfApi, HfFileSystem
+
+    preset = CONCEPT_PRESETS[name]
+    column = column or preset.column
+    api = HfApi()
+    info = api.dataset_info(preset.dataset, revision=preset.revision)
+    fs = HfFileSystem()
+    subset = subset or preset.subset
+    files = preset.files.format(split=split or preset.split, subset=subset)
+    paths = fs.glob(f"datasets/{preset.dataset}@{info.sha}/{files}")
+    if not paths:
+        raise FileNotFoundError(f"no files match {files!r} in {preset.dataset}@{info.sha}")
+    if preset.layout == "document":
+        columns = [preset.text_column, column]
+    elif preset.layout == "conll":
+        columns = ["tokens", column]
+    else:
+        columns = [preset.text_column, "tokens", "mwt", "comments", column]
+    rows, names = _read_rows(fs, paths, columns)
+    docs, skipped = _documents(preset, column, rows, names, max_chars)
+    if preset.layout == "ud":
+        # Universal Dependencies licenses each treebank separately.
+        meta = json.loads(fs.read_text(f"datasets/{preset.dataset}@{info.sha}/metadata.json"))
+        license_ = meta.get(subset, {}).get("license")
+    else:
+        license_ = _license(api, preset.dataset, info, preset.revision)
+    return LoadedSplit(
+        docs,
+        preset.dataset,
+        info.sha,
+        files,
+        ", ".join(license_) if isinstance(license_, list) else license_,
+        skipped,
+    )
+
+
+def sample_concept(
+    docs: Sequence[tuple[str, list[Span]]], label: str, documents: int, seed: int, balance: bool
+) -> list[tuple[str, list[tuple[int, int]]]]:
+    """Return up to ``documents`` documents with the spans of ``label``, in split order.
+
+    With ``balance``, half (rounded up) have a span and half don't, where there are enough.
+    """
+    marked = [[(s.start, s.end) for s in spans if tag_matches(s.label, label)] for _, spans in docs]
+    rng = random.Random(seed)
+    if balance:
+        pos = [i for i, m in enumerate(marked) if m]
+        neg = [i for i, m in enumerate(marked) if not m]
+        take_pos = min(len(pos), (documents + 1) // 2)
+        picked = rng.sample(pos, take_pos) + rng.sample(neg, min(len(neg), documents - take_pos))
+    else:
+        picked = rng.sample(range(len(docs)), min(documents, len(docs)))
+    return [(docs[i][0], marked[i]) for i in sorted(picked)]
+
+
+def build_concept(
+    name: str,
+    label: str,
+    out: Path,
+    *,
+    split: str | None = None,
+    subset: str | None = None,
+    column: str | None = None,
+    documents: int = 1000,
+    seed: int = 0,
+    max_chars: int = 3000,
+) -> ConceptSource:
+    """Write ``label``'s concept set from preset ``name`` and its source sidecar."""
+    preset = CONCEPT_PRESETS[name]
+    loaded = load_split(name, split=split, subset=subset, column=column, max_chars=max_chars)
+    counts = loaded.counts()
+    if not any(tag_matches(tag, label) for tag in counts):
+        known = ", ".join(tag for tag, _ in counts.most_common())
+        raise ValueError(f"no {label!r} labels in {name}; it has: {known}")
+    level = "document" if preset.layout == "document" else "token"
+    rows = sample_concept(loaded.docs, label, documents, seed, balance=level == "document")
+    data = "".join(
+        json.dumps({"text": text, "spans": [list(s) for s in spans]}, ensure_ascii=False) + "\n"
+        for text, spans in rows
+    ).encode()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(data)
+    source = ConceptSource(
+        preset=name,
+        dataset=loaded.dataset,
+        revision=loaded.revision,
+        files=loaded.files,
+        column=column or preset.column,
+        label=label,
+        level=level,
+        documents=len(rows),
+        positive_documents=sum(1 for _, spans in rows if spans),
+        spans=sum(len(spans) for _, spans in rows),
+        skipped_sentences=loaded.skipped_sentences,
+        seed=seed,
+        max_chars=max_chars,
+        license=loaded.license,
+        sha256=hashlib.sha256(data).hexdigest(),
+    )
+    source_path(out).write_text(source.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    return source

openinterp/core/__init__.py

@@ -0,0 +1,59 @@
+"""Schemas, identifiers and statistics that every record and command depends on."""
+
+from openinterp.core.exceptions import (
+    AgentError,
+    ArchitectureNotSupportedError,
+    OpenInterpError,
+    PatchingError,
+    RegistryError,
+    ShapeMismatchError,
+    SyncError,
+)
+from openinterp.core.schemas import (
+    ActivatingExample,
+    AdversarialTestResult,
+    AuditRecord,
+    CausalMetrics,
+    ComponentIdentifier,
+    CounterfactualPair,
+    DictionaryProfile,
+    ExperimentProvenance,
+    FeatureIdentifier,
+    HeadIdentifier,
+    HeadProfile,
+    Histogram,
+    LookaheadProfile,
+    NeuronAuditSubmission,
+    NeuronIdentifier,
+    ReviewMetrics,
+    ReviewPolicy,
+    VerificationVerdict,
+)
+
+__all__ = [
+    "ActivatingExample",
+    "AdversarialTestResult",
+    "AgentError",
+    "ArchitectureNotSupportedError",
+    "AuditRecord",
+    "CausalMetrics",
+    "ComponentIdentifier",
+    "CounterfactualPair",
+    "DictionaryProfile",
+    "ExperimentProvenance",
+    "FeatureIdentifier",
+    "HeadIdentifier",
+    "HeadProfile",
+    "Histogram",
+    "LookaheadProfile",
+    "NeuronAuditSubmission",
+    "NeuronIdentifier",
+    "OpenInterpError",
+    "PatchingError",
+    "RegistryError",
+    "ReviewMetrics",
+    "ReviewPolicy",
+    "ShapeMismatchError",
+    "SyncError",
+    "VerificationVerdict",
+]

openinterp/core/agent_names.py

@@ -0,0 +1,76 @@
+"""One name per agent model, however a record spelled it.
+
+``submitting_agent_model``, ``reviewer_agent_model`` and ``judge_model`` are free text.
+Sessions spell one model in several ways. For example:
+
+- ``external/deepseek-flash[1m]`` and ``external/deepseek-flash``.
+- ``external/gemini/gemini-3.8-flash`` and ``external/gemini-3.8-flash``.
+- ``anthropic/claude-opus-5-5 (Claude Code session)`` and ``external/claude-opus-5-5``.
+
+Records are signed, so the site build does not rewrite them. It maps each spelling to one
+name with :func:`canonical_agent`. :func:`spelling_problem` rejects new spellings at
+submission.
+"""
+
+from __future__ import annotations
+
+import re
+
+EXTERNAL_PREFIX = "external/"
+
+# Spellings that name the same model, after the generic clean-up in canonical_agent.
+# One 2026-10-26 session ran Grok Build but reported itself as Claude 3.5 Sonnet.
+ALIASES: dict[str, str] = {
+    "claude-3-5-sonnet-20241022": "grok-build-0.1",
+}
+
+# Model families whose sessions report their version inconsistently. canonical_agent maps
+# every name that starts with the key to the value. Muse Spark sessions have recorded
+# muse-spark, muse-spark-3, muse-spark-1-3-contributor and others. "-contributor" is the
+# Muse Spark pricing tier (openinterp.core.pricing.FAMILIES), not part of the model's
+# name. Every run so far was 1.3 at the Contributor tier.
+FAMILY_ALIASES: dict[str, str] = {
+    "muse-spark": "muse-spark-1.3",
+}
+
+# Shown on an agent's page when its recorded name is doubtful.
+NOTES: dict[str, str] = {
+    "grok-build-0.1": (
+        "One session on 2026-10-26 ran this model but recorded itself as "
+        "claude-3-5-sonnet-20241022; its records are signed, so the name is remapped here."
+    ),
+}
+
+
+def canonical_agent(model: str) -> str:
+    """The model's one name: ``external/deepseek-flash[1m]`` → ``deepseek-flash``.
+
+    Drops the route (``external/``, a LiteLLM provider such as ``anthropic/``), a context
+    suffix (``[1m]``), a parenthesised remark and case. Then applies :data:`FAMILY_ALIASES`
+    and :data:`ALIASES`.
+    """
+    name = re.sub(r"\s*\(.*\)\s*$", "", model.strip()).removeprefix(EXTERNAL_PREFIX)
+    name = re.sub(r"\[[^\]]*\]$", "", name.rsplit("/", 1)[-1]).strip().lower()
+    for family, canonical in FAMILY_ALIASES.items():
+        if name.startswith(family):
+            return canonical
+    return ALIASES.get(name, name) or "unknown"
+
+
+def same_agent(a: str | None, b: str | None) -> bool:
+    """True when both names are set and name one model after ``ALIASES`` and spelling fixes."""
+    return a is not None and b is not None and canonical_agent(a) == canonical_agent(b)
+
+
+def spelling_problem(model: str) -> str | None:
+    """Why ``model`` isn't a name a new record may carry, or ``None`` when it is.
+
+    An external answerer must be ``external/<name>`` with ``<name>`` already canonical. A
+    LiteLLM string is what gets called, so it already names the model and passes.
+    """
+    if not model.startswith(EXTERNAL_PREFIX):
+        return None
+    expected = EXTERNAL_PREFIX + canonical_agent(model)
+    if model != expected:
+        return f"spell it {expected} (no provider, context size, remark or version alias)"
+    return None

openinterp/core/attribution.py

@@ -0,0 +1,101 @@
+"""Schemas for input attribution: which context tokens drive a pole at its peak.
+
+Integrated gradients (Sundararajan et al., 2017) run over the input token embeddings.
+They attribute the pole's activation at each top example's peak token to every token up
+to the peak. The baseline replaces every token with one reference token. A second check
+replaces each token alone with the reference token and measures the pole again.
+Reported, not gated (docs/PROTOCOL.md §4).
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from openinterp.core.strict import StrictModel, UnitFloat
+
+
+class AttributedToken(StrictModel):
+    """One context token's contribution to the pole at the peak.
+
+    Both numbers are fractions of one gap: the pole's activation on the example minus
+    its activation on the all-baseline input. So ``attribution`` sums to about 1 over
+    the tokens, and you can compare the two numbers directly.
+    """
+
+    offset: int = Field(le=0, description="Position relative to the peak token (0 = the peak).")
+    token: str
+    attribution: float = Field(description="Integrated-gradients share of the gap.")
+    ablation_effect: float | None = Field(
+        default=None,
+        description="Drop in activation when only this token is replaced, as a share of the gap.",
+    )
+
+
+class ContextExample(StrictModel):
+    """Input attribution for one top example."""
+
+    example: int = Field(ge=0, description="Index into the scan's top examples.")
+    peak_token: str
+    tokens: int = Field(gt=0, description="Tokens attributed: the example up to its peak.")
+    steps: int = Field(gt=0, description="Integration steps used.")
+    converged: bool = Field(
+        description="completeness_error within the tolerance; only these count in the shares."
+    )
+    completeness_error: float = Field(
+        ge=0.0, description="|Σ attribution − 1|: how far the path integral is from converged."
+    )
+    top: list[AttributedToken] = Field(description="Largest |attribution| first.")
+
+
+class DistanceShare(StrictModel):
+    """Share of total |attribution| on tokens ``min_distance``..``max_distance`` back."""
+
+    min_distance: int = Field(ge=0)
+    max_distance: int | None = Field(default=None, description="None: no upper bound.")
+    share: UnitFloat
+
+    @property
+    def label(self) -> str:
+        """The distance band as the page shows it: ``0``, ``1–3`` or ``8+``."""
+        if self.max_distance is None:
+            return f"{self.min_distance}+"
+        if self.max_distance == self.min_distance:
+            return str(self.min_distance)
+        return f"{self.min_distance}–{self.max_distance}"
+
+
+class InputAttribution(StrictModel):
+    """Where in the context a pole's activation comes from, over its top examples.
+
+    ``distances`` splits each example's |attribution| by how far back each token is from
+    the peak, then averages the shares over examples. A high share at distance 0 means
+    that the pole fires on the current token. A high share far back means that it fires
+    because of earlier context.
+
+    ``ablation_agreement`` is Spearman's ρ between attribution and single-token ablation
+    effect. It uses every checked token: the peak, the tokens just before it and the most
+    attributed ones. A low value means that the linear path integral misreads this pole,
+    so trust the ablation effects.
+
+    Both use only the examples whose path integral converged. With none, they are empty.
+    """
+
+    method: str = "integrated_gradients"
+    baseline_token: str
+    tolerance: float = Field(gt=0.0, description="Largest completeness error accepted.")
+    examples: list[ContextExample]
+    distances: list[DistanceShare]
+    mean_distance: float | None = Field(
+        default=None, ge=0.0, description="|attribution|-weighted mean tokens back from the peak."
+    )
+    ablation_agreement: float | None = Field(default=None, ge=-1.0, le=1.0)
+
+    @property
+    def converged(self) -> int:
+        """How many examples converged; only these count in the shares."""
+        return sum(ex.converged for ex in self.examples)
+
+    @property
+    def current_token_share(self) -> float | None:
+        """The share at distance 0, the first band, or ``None`` with no converged example."""
+        return self.distances[0].share if self.distances else None

openinterp/core/cache_dirs.py

@@ -0,0 +1,15 @@
+"""Where the on-disk caches live."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def cache_root(env: str, name: str) -> Path | None:
+    """``$<env>``, else ``$XDG_CACHE_HOME/openinterp/<name>``; None if ``$<env>`` turns it off."""
+    value = os.environ.get(env)
+    if value is not None:
+        return None if value.lower() in ("", "0", "off", "false") else Path(value)
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "openinterp" / name