open-interpretability 0.0.20__py3-none-any.whl

openinterp/core/schemas.py

@@ -0,0 +1,484 @@
+"""Strict Pydantic v2 schemas for audits, hypotheses and evidence.
+
+Every model is strict (no implicit type coercion) and forbids unknown fields. So a
+record that validates here is safe to compile into the public registry. Records on disk
+are JSON. Load them with ``Model.model_validate_json``: strict mode then accepts
+ISO-8601 strings for datetimes.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import AwareDatetime, Field, model_validator
+
+from openinterp.core import evidence
+from openinterp.core.agent_names import same_agent
+from openinterp.core.attribution import InputAttribution
+from openinterp.core.causal import (  # noqa: F401  (re-exported)
+    CausalMetrics,
+    CausalPairEffect,
+    CausalTarget,
+    PatchEffect,
+)
+from openinterp.core.confounds import (  # noqa: F401  (re-exported)
+    ConfoundProfile,
+    LabelConfound,
+    LabelStat,
+    TokenStat,
+)
+from openinterp.core.contributors import CONTRIBUTOR_PATTERN
+from openinterp.core.corpora import CorpusSample, CorpusSource  # noqa: F401  (re-exported)
+from openinterp.core.costs import ExperimentCosts
+from openinterp.core.examples import (  # noqa: F401  (re-exported)
+    ActivatingExample,
+    Histogram,
+    OppositePole,
+    check_opposite_pole,
+)
+from openinterp.core.explanation import ExplanationScores
+from openinterp.core.identifiers import (  # noqa: F401  (re-exported)
+    ComponentIdentifier,
+    FeatureIdentifier,
+    HeadIdentifier,
+    NeuronIdentifier,
+    Pole,
+    SuperpositionIdentifier,
+)
+from openinterp.core.manifold import ManifoldCheck
+from openinterp.core.partners import CorrelatedNeuron  # noqa: F401  (re-exported)
+from openinterp.core.patchscope import PatchscopeReadout
+from openinterp.core.prior_art import PriorArtField
+from openinterp.core.profiles import (  # noqa: F401  (re-exported)
+    DictionaryProfile,
+    DictionarySite,
+    HeadProfile,
+    SuperpositionProfile,
+    require_unit_profile,
+)
+from openinterp.core.run_environment import RunEnvironment  # noqa: F401  (re-exported)
+from openinterp.core.specificity import WordnetSpecificity, WordStrength  # noqa: F401
+from openinterp.core.steering import SteeringSamples
+from openinterp.core.strict import StrictModel, UnitFloat
+from openinterp.core.wiring import Wiring, WiringEdge  # noqa: F401  (re-exported)
+
+VerdictStatus = Literal["VERIFIED", "REJECTED", "NEEDS_REVISION"]
+ProbeKind = Literal["hard_negative", "positive_holdout", "counterfactual", "lookahead_consistency"]
+SelectionMethod = Literal["random", "attribution", "manual"]
+
+PROTOCOL_VERSION = "0.9"
+# Probes a review asks for (PROTOCOL.md §2, step 5): 20 hard negatives, 10 holdouts.
+MAX_PROBES = 30
+# Share of max activation counted as "active" (PROTOCOL.md §1); ReviewPolicy's default.
+ACTIVATION_THRESHOLD = 0.25
+# An experiment is named by its verdict timestamp: ``%Y%m%dT%H%M%SZ``.
+EXPERIMENT_ID_PATTERN = r"^\d{8}T\d{6}Z$"
+# An experiment on a neuron pole anywhere in the registry: its pole's slug, then its id.
+SISTER_OF_PATTERN = r"^[A-Za-z0-9._-]+/L\d+/N\d+-(positive|negative)/\d{8}T\d{6}Z$"
+# ``provenance.corpus`` of a scan without ``--corpus``: the 552-token built-in sample.
+BUILTIN_CORPUS = "builtin:sample_corpus"
+# Sources of corpora that records scanned without recording one. They match by SHA-256.
+# The first is the default scan corpus's sidecar (README, "A scan corpus"). The second is
+# a table of the others.
+COMMITTED_SOURCES = ("corpus.source.json", "corpus-sources.json")
+Contributor = Annotated[
+    str,
+    Field(
+        pattern=CONTRIBUTOR_PATTERN,
+        description="The human behind this step: a public handle (e.g. a GitHub username), "
+        "never an email. None: not recorded.",
+    ),
+]
+
+
+class CounterfactualPair(StrictModel):
+    """A minimal pair predicted to change the neuron's pole activation.
+
+    A delta is ``strength(base) - strength(counterfactual)``, divided by the neuron's
+    maximum observed activation. So ``1.0`` means that the base prompt fully activates
+    the pole, and the counterfactual does not activate it at all.
+    """
+
+    base_prompt: str = Field(min_length=1)
+    counterfactual_prompt: str = Field(min_length=1)
+    expected_delta: float
+    observed_delta: float | None = None
+
+    @model_validator(mode="after")
+    def _prompts_differ(self) -> CounterfactualPair:
+        if self.base_prompt == self.counterfactual_prompt:
+            raise ValueError("base_prompt and counterfactual_prompt must differ")
+        return self
+
+
+class LookaheadProfile(StrictModel):
+    """Whether the neuron prepares specific upcoming tokens rather than reacting to past ones."""
+
+    is_lookahead: bool
+    target_upcoming_tokens: list[str] = Field(default_factory=list)
+    kl_divergence: float = Field(ge=0.0)
+
+
+class ExperimentProvenance(StrictModel):
+    """Everything needed to re-run the scan that produced a submission."""
+
+    model_revision: str | None = Field(default=None, description="Hugging Face commit hash.")
+    dtype: str
+    corpus: str = Field(min_length=1, description="Human-readable corpus description.")
+    corpus_sha256: str | None = None
+    n_snippets: int = Field(ge=0)
+    tokens_scanned: int = Field(ge=0)
+    snippet_tokens: int | None = Field(
+        default=None,
+        gt=0,
+        description="Window length when documents were scanned as overlapping windows; "
+        "None when each was scanned whole.",
+    )
+    snippet_stride: int | None = Field(
+        default=None, gt=0, description="Tokens between the starts of consecutive windows."
+    )
+    selection: SelectionMethod = Field(
+        description="How the neuron was chosen; only 'random' gives unbiased registry statistics."
+    )
+    seed: int | None = None
+    pole_forced: bool | None = Field(
+        default=None,
+        description="For a random draw: True when --pole fixed the pole, False when the seed "
+        "drew it. None for a chosen unit, and for records before issue #3205.",
+    )
+    harness_version: str
+    environment: RunEnvironment | None = None
+    corpus_source: CorpusSource | None = None
+    label_detector: str | None = Field(
+        default=None,
+        description="What fixes the scan's match labels (openinterp.sensitive.detector, "
+        "openinterp.names.DETECTOR, openinterp.toxicity.DETECTOR). None: the scan "
+        "predates those labels.",
+    )
+    corpus_sample: CorpusSample | None = Field(
+        default=None,
+        description="The sample of the corpus scanned; None when the whole corpus was "
+        "(every record before protocol 0.7).",
+    )
+    costs: ExperimentCosts | None = Field(
+        default=None,
+        description="Wall time per stage and LLM usage of the run that produced this record "
+        "(reported, never gated).",
+    )
+
+
+class VocabularyLens(StrictModel):
+    """The pole's output direction read through the logit lens and the Jacobian lens.
+
+    The Jacobian lens (Gurnee et al., 2026) first moves the direction to the final layer
+    with the context-averaged Jacobian. So it stays reliable in middle layers, where the
+    logit lens (J = I) does not. ``overlap`` is the shared fraction of the two top-k
+    lists. ``direction_cosine`` is cos(w, J·w). A low value means that later layers
+    rotate what this neuron writes by a large angle. Kurtosis of the vocabulary
+    z-scores is high when the pole promotes a small, specific token set.
+
+    The ``*_z`` lists hold each listed token's z-score over the whole vocabulary,
+    in the same order. They are scale-invariant, so the two lenses share an axis.
+    Records before they were added have ``None``.
+    """
+
+    logit_promoted: list[str]
+    logit_suppressed: list[str]
+    jacobian_promoted: list[str]
+    jacobian_suppressed: list[str]
+    logit_promoted_z: list[float] | None = None
+    logit_suppressed_z: list[float] | None = None
+    jacobian_promoted_z: list[float] | None = None
+    jacobian_suppressed_z: list[float] | None = None
+    overlap: UnitFloat
+    direction_cosine: float = Field(ge=-1.0, le=1.0)
+    logit_kurtosis: float = Field(ge=0.0)
+    jacobian_kurtosis: float = Field(ge=0.0)
+    prompts: int = Field(ge=0)
+
+
+class JointAblation(StrictModel):
+    """Next-token KL when ablating the pole, its correlated partners, or both.
+
+    ``redundancy_ratio`` = (kl_joint − kl_partners) / kl_single: how much more the pole
+    matters once its correlated partners are gone (> 1 suggests redundancy).
+    """
+
+    partners: list[int]
+    kl_single: float = Field(ge=0.0)
+    kl_partners: float = Field(ge=0.0)
+    kl_joint: float = Field(ge=0.0)
+    redundancy_ratio: float | None = None
+
+
+class ScanEvidence(StrictModel):
+    """What ``open-interpretability audit --evidence-out`` measured, for a proposer working offline.
+
+    It holds everything a submission needs except the hypothesis, so ``open-interpretability audit
+    --evidence <file> --hypothesis <file>`` can build the submission without rescanning.
+    """
+
+    identifier: ComponentIdentifier
+    top_examples: list[ActivatingExample]
+    activation_histogram: Histogram | None = None
+    first_token_floor: bool | None = None  # v0.8, see NeuronAuditSubmission
+    provenance: ExperimentProvenance | None = None
+    confounds: ConfoundProfile | None = None
+    correlated_neurons: list[CorrelatedNeuron] = Field(default_factory=list)
+    vocabulary_lens: VocabularyLens | None = None
+    input_attribution: InputAttribution | None = None
+    head_profile: HeadProfile | None = None
+    model_n_heads: int | None = Field(default=None, gt=0)
+    dictionary_profile: DictionaryProfile | None = None
+    superposition_profile: SuperpositionProfile | None = None
+    opposite_pole: OppositePole | None = None
+    manifold: ManifoldCheck | None = None  # see NeuronAuditSubmission
+
+    @model_validator(mode="after")
+    def _head_profile(self) -> ScanEvidence:
+        check_opposite_pole(self)
+        return require_unit_profile(self)
+
+
+class NeuronAuditSubmission(StrictModel):
+    """A hypothesis about one unit, frozen once submitted.
+
+    The unit is a neuron pole, an attention head (since protocol 0.6) or a dictionary
+    feature. The name predates heads and is kept for compatibility.
+    """
+
+    identifier: ComponentIdentifier
+    natural_language_explanation: str = Field(min_length=1)
+    activating_tokens: list[str]
+    counterfactuals: list[CounterfactualPair] = Field(min_length=1)
+    lookahead: LookaheadProfile
+    submitting_agent_model: str = Field(min_length=1)
+    contributor: Contributor | None = None
+    # Evidence gathered by the harness. Optional so hand-written submissions validate.
+    max_activation: float | None = Field(default=None, gt=0.0)
+    top_examples: list[ActivatingExample] = Field(default_factory=list)
+    activation_histogram: Histogram | None = None
+    first_token_floor: bool | None = Field(
+        default=None,
+        description="Protocol 0.8: the unit is active at the first position on at least half "
+        "the vocabulary, so it is not measured at a text's first token. None: not judged (a "
+        "record from before 0.8), and a review judges it.",
+    )
+    model_num_layers: int | None = Field(default=None, gt=0)
+    model_mlp_width: int | None = Field(default=None, gt=0, description="Neurons per MLP layer.")
+    provenance: ExperimentProvenance | None = None
+    correlated_neurons: list[CorrelatedNeuron] = Field(default_factory=list)
+    confounds: ConfoundProfile | None = None
+    vocabulary_lens: VocabularyLens | None = None
+    input_attribution: InputAttribution | None = None
+    head_profile: HeadProfile | None = None
+    model_n_heads: int | None = Field(default=None, gt=0, description="Heads per layer.")
+    dictionary_profile: DictionaryProfile | None = None
+    superposition_profile: SuperpositionProfile | None = None
+    patchscope: PatchscopeReadout | None = Field(
+        default=None,
+        description="The model's own description of the unit's output direction, read after "
+        "the proposer answered and shown to neither agent (reported, not gated).",
+    )
+    prior_art: PriorArtField = None
+    steering: SteeringSamples | None = Field(
+        default=None,
+        description="Neutral prompts continued with the unit clamped high, at baseline and "
+        "ablated, taken after the proposer answered and shown to neither agent (reported, "
+        "not gated).",
+    )
+    wordnet_specificity: WordnetSpecificity | None = Field(
+        default=None,
+        description="The unit on held-out words of a WordNet category against words of its "
+        "sibling categories, measured after the proposer answered and shown to neither "
+        "agent (reported, not gated).",
+    )
+    supersedes: str | None = Field(
+        default=None,
+        pattern=EXPERIMENT_ID_PATTERN,
+        description="Experiment id of the earlier experiment on the same unit that this "
+        "submission revises (reported, not gated).",
+    )
+    sister_of: str | None = Field(
+        default=None,
+        pattern=SISTER_OF_PATTERN,
+        description="A sister-neuron study: the experiment (``<pole slug>/<experiment id>``) "
+        "on a VERIFIED pole of another model whose explanation this submission tests on its "
+        "sister, unchanged (reported, not gated).",
+    )
+    opposite_pole: OppositePole | None = Field(
+        default=None,
+        description="A neuron's other pole, from the same scan: its top examples and "
+        "histogram, shown beside this pole on the neuron page (reported, not gated).",
+    )
+    wiring: Wiring | None = Field(
+        default=None,
+        description="A neuron pole's top connections by virtual weight, read after the "
+        "proposer answered and shown to neither agent (reported, not gated).",
+    )
+    manifold: ManifoldCheck | None = Field(
+        default=None,
+        description="A neuron pole and its partner poles on the activating set and on "
+        "ordered word families, and whether they trace a circle or a line (reported, not "
+        "gated).",
+    )
+
+    @model_validator(mode="after")
+    def _head_profile(self) -> NeuronAuditSubmission:
+        check_opposite_pole(self)
+        return require_unit_profile(self)
+
+
+class AdversarialTestResult(StrictModel):
+    """The outcome of one reviewer probe, measured on the model; the reviewer never sees it."""
+
+    kind: ProbeKind
+    prompt: str
+    passed: bool
+    expected_active: bool | None = None
+    activation: float | None = None
+    expected_delta: float | None = None
+    observed_delta: float | None = None
+    detail: str = ""
+    # v0.8: False for a one-token prompt to a unit with a first-token floor, which is not
+    # measured at the first token. It is recorded but counts in no metric.
+    measured: bool = True
+
+
+class ReviewPolicy(StrictModel):
+    """The decision rule a verdict was computed under; docs/PROTOCOL.md quotes its defaults."""
+
+    protocol_version: str = PROTOCOL_VERSION
+    activation_threshold: UnitFloat = ACTIVATION_THRESHOLD
+    delta_abs_tolerance: float = Field(default=0.10, ge=0.0)
+    delta_rel_tolerance: float = Field(default=0.50, ge=0.0)
+    min_hard_negatives: int = Field(default=6, ge=0)
+    min_holdouts: int = Field(default=3, ge=0)
+    min_specificity: UnitFloat = 0.80
+    min_sensitivity: UnitFloat = 0.60
+    min_counterfactual_reproduction: UnitFloat = 0.75
+    reject_below_balanced_accuracy: UnitFloat = 0.60
+    # v0.4: proposer/reviewer independence is recorded but no longer gated by default.
+    require_independent_review: bool = False
+    freeze_downstream: bool = True
+    # v0.5: causal effects are ranked against this many same-layer neurons whose strength
+    # changes as much between each minimal pair.
+    causal_null_neurons: int = Field(default=32, ge=1)
+    # v0.3: near-duplicate probes (word-set Jaccard >= this) count as one observation.
+    probe_cluster_threshold: UnitFloat = 0.5
+    # v0.3: the hypothesis must match or beat trivial token/position baselines.
+    require_confound_control: bool = True
+    joint_ablation_partners: int = Field(default=3, ge=0)
+    # Partners for joint ablation: lower-bound co-activation lift >= min_partner_lift on
+    # at least min_partner_coactive tokens, or |Spearman| >= min_partner_correlation.
+    min_partner_correlation: UnitFloat = 0.2
+    min_partner_lift: float = Field(default=2.0, ge=1.0)
+    min_partner_coactive: int = Field(default=5, ge=1)
+    # v0.8: a unit active on at least this share of its scan's tokens is default-on. It
+    # is not audited as a detector, because no hard negative of a few words can stay
+    # inactive. A unit active at the first position on this share of the vocabulary has
+    # a first-token floor.
+    max_active_share: UnitFloat = 0.5
+
+
+def scan_active_share(submission: NeuronAuditSubmission, policy: ReviewPolicy) -> float | None:
+    """Return the share of the scan's tokens that the unit is active on.
+
+    It comes from the submission's histogram. ``None`` without one.
+    """
+    histogram, scale = submission.activation_histogram, submission.max_activation
+    if histogram is None or not scale:
+        return None
+    return histogram.share_at_least(policy.activation_threshold * scale)
+
+
+class ReviewMetrics(StrictModel):
+    """The rates and gates the decision rule computes from the probes (docs/PROTOCOL.md §4)."""
+
+    specificity: UnitFloat | None  # hard negatives correctly inactive
+    sensitivity: UnitFloat | None  # positive holdouts correctly active
+    balanced_accuracy: UnitFloat
+    counterfactual_reproduction: UnitFloat | None
+    lookahead_consistent: bool
+    independent_review: bool
+    gates: dict[str, bool]
+    effective_hard_negatives: int | None = None  # clusters of near-duplicate probes
+    effective_holdouts: int | None = None
+    confound_baseline_accuracy: UnitFloat | None = None  # best trivial baseline, same probes
+    confound_baseline: str | None = None
+    # v0.8: the share of the scan's tokens at or above the "active" line (from its
+    # histogram). Also, whether the measurement left out each text's first token.
+    active_share: UnitFloat | None = None
+    first_token_floor: bool | None = None
+
+
+class VerificationVerdict(StrictModel):
+    """The reviewer's verdict on one submission, with the evidence and the policy it used."""
+
+    status: VerdictStatus
+    confidence_score: UnitFloat
+    adversarial_test_results: list[AdversarialTestResult]
+    reviewer_agent_model: str = Field(min_length=1)
+    contributor: Contributor | None = None
+    timestamp: AwareDatetime
+    causal_metrics: CausalMetrics | None = None
+    metrics: ReviewMetrics | None = None
+    policy: ReviewPolicy | None = None
+    joint_ablation: JointAblation | None = None
+    environment: RunEnvironment | None = None
+    explanation_scores: ExplanationScores | None = None
+    wiring: Wiring | None = Field(
+        default=None,
+        description="A neuron pole's top connections by attribution on the review's prompts "
+        "where it fired (reported, not gated).",
+    )
+    notes: str = ""
+
+
+class AuditRecord(StrictModel):
+    """The unit stored in the registry: a submission plus its review verdict.
+
+    Loading resolves a slim record's evidence references (:mod:`.evidence`, issue #3254).
+    """
+
+    submission: NeuronAuditSubmission
+    verdict: VerificationVerdict | None = None
+
+    @classmethod
+    def model_validate_json(cls, json_data, **kwargs) -> AuditRecord:  # noqa: D102
+        return super().model_validate_json(evidence.resolved_text(json_data), **kwargs)
+
+    @classmethod
+    def model_validate(cls, obj, **kwargs) -> AuditRecord:  # noqa: D102
+        text = evidence.resolved_dict_text(obj)
+        if text is None:
+            return super().model_validate(obj, **kwargs)
+        return super().model_validate_json(text, **kwargs)
+
+    @property
+    def is_verified(self) -> bool:
+        """True when a verdict exists and its status is VERIFIED."""
+        return self.verdict is not None and self.verdict.status == "VERIFIED"
+
+    @property
+    def scanned_on_builtin_sample(self) -> bool:
+        """Return whether the scan read only the 552-token built-in sample.
+
+        That sample is too small for a meaningful max activation, so follow-ups rescan
+        the unit instead of reusing the scan.
+        """
+        provenance = self.submission.provenance
+        return provenance is not None and provenance.corpus == BUILTIN_CORPUS
+
+    @property
+    def self_reviewed(self) -> bool:
+        """Return whether the proposer's model also reviewed the submission.
+
+        Self-review is recorded and badged, not gated (§2). It is also true when the
+        record calls the review independent but spells one model two ways (``[1m]``).
+        """
+        if self.verdict is None:
+            return False
+        if self.verdict.metrics is not None and not self.verdict.metrics.independent_review:
+            return True
+        return same_agent(self.verdict.reviewer_agent_model, self.submission.submitting_agent_model)

openinterp/core/specificity.py

@@ -0,0 +1,49 @@
+"""Schemas for the WordNet specificity check: a category's words against its siblings'.
+
+A "cities" unit might really be a "places" unit. To tell the two apart, the harness
+measures the unit on two lists of words. The first is words that WordNet puts under the
+claimed category (its hyponyms). The second is words from the category's siblings
+(other hyponyms of its hypernyms). Each word sits in a few fixed carrier sentences.
+Peak words of the scan are left out of both lists, so every word is held out. Reported,
+not gated (docs/PROTOCOL.md §4). Neither agent sees it.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from openinterp.core.strict import StrictModel, UnitFloat
+
+
+class WordStrength(StrictModel):
+    """One word's strength: the mean over the carriers of its peak over the word's tokens."""
+
+    word: str = Field(min_length=1)
+    strength: float = Field(ge=0.0)
+
+
+class WordnetSpecificity(StrictModel):
+    """The unit on a WordNet category's words against the words of its sibling categories.
+
+    A word is active at or above ``ACTIVATION_THRESHOLD × scale``. ``auroc`` is the
+    chance that a category word is stronger than a sibling word, ties counting half. It
+    is 1 when the unit picks out the category. It is 0.5 when the unit can't tell the
+    category from its siblings.
+    """
+
+    synset: str = Field(description="The category, e.g. 'city.n.01'.")
+    lemma: str
+    source: Literal["proposer", "peak_words"] = Field(
+        description="'proposer': the draft's wordnet_synset. 'peak_words': the proposer named "
+        "none, so the largest category of the scan's peak words."
+    )
+    sibling_synsets: list[str]
+    carriers: list[str] = Field(min_length=1, description="Templates; {} is the word.")
+    scale: float = Field(gt=0.0, description="The unit's top activation in the scan.")
+    category: list[WordStrength]
+    siblings: list[WordStrength]
+    category_active: UnitFloat
+    siblings_active: UnitFloat
+    auroc: UnitFloat