open-interpretability 0.0.20__py3-none-any.whl

openinterp/agreement.py

@@ -0,0 +1,63 @@
+"""Subject–verb agreement prompts: the templates, nouns and pairs (issues #3225 and #3686).
+
+``scripts/sva_circuit.py`` traces a circuit on these prompts. The ``grammatical-number``
+finder in :mod:`openinterp.superposition_finders` probes them. Each prompt ends where
+the verb comes next.
+"""
+
+from __future__ import annotations
+
+import random
+
+# Nouns whose singular and plural are one token each in Qwen2.5's tokenizer.
+NOUNS = [
+    *("author", "pilot", "surgeon", "farmer", "manager", "customer", "officer", "teacher"),
+    *("senator", "guard", "doctor", "student", "dancer", "lawyer", "writer", "painter"),
+    *("driver", "player", "worker", "singer", "judge", "nurse", "minister", "boy", "girl"),
+    *("king", "friend", "parent", "dog", "cat"),
+]
+IRREGULAR = {"child": "children", "woman": "women", "man": "men"}
+PREPOSITIONS = ("near", "behind", "beside", "with")
+VERBS = ("liked", "saw", "knew", "met")
+TEMPLATES = ("simple", "across_pp", "across_rc", "within_rc")
+
+
+def plural(noun: str) -> str:
+    """The plural of ``noun``."""
+    return IRREGULAR.get(noun, noun + "s")
+
+
+def prompt(template: str, a: str, b: str, prep: str, verb: str) -> str:
+    """The prompt. ``a`` is the head noun and ``b`` the second noun, both inflected."""
+    return {
+        "simple": f"The {a}",
+        "across_pp": f"The {a} {prep} the {b}",
+        "across_rc": f"The {a} that the {b} {verb}",
+        "within_rc": f"The {a} that the {b}",
+    }[template]
+
+
+def pairs(template: str, n: int, rng: random.Random) -> list[dict]:
+    """``n`` (clean, corrupted, sign) pairs. Half of them have a singular clean noun.
+
+    The verb agrees with the head noun, except within a relative clause, where it agrees
+    with the clause's subject. Only that noun's number differs between the two prompts.
+    The other noun's number is drawn at random, and is the same in both.
+    """
+    nouns = [*NOUNS, *IRREGULAR]
+    out = []
+    for i in range(n):
+        a, b = rng.sample(nouns, 2)
+        prep, verb = rng.choice(PREPOSITIONS), rng.choice(VERBS)
+        singular = i % 2 == 0
+        agree, other = (b, a) if template == "within_rc" else (a, b)
+        other = other if rng.random() < 0.5 else plural(other)
+        clean, corrupted = (agree, plural(agree)) if singular else (plural(agree), agree)
+
+        def text(form, other=other, prep=prep, verb=verb):
+            head, second = (other, form) if template == "within_rc" else (form, other)
+            return prompt(template, head, second, prep, verb)
+
+        out.append({"clean": text(clean), "corrupted": text(corrupted),
+                    "sign": 1.0 if singular else -1.0})  # fmt: skip
+    return out

openinterp/audit_options.py

@@ -0,0 +1,79 @@
+"""Options that ``open-interpretability audit`` and ``scan`` share, and how unit options resolve.
+
+The shared ones are the scan cache and ``--selection``.
+
+``--selection`` says how a chosen unit was selected, as its provenance records it.
+
+A ``--random`` draw records ``random`` and counts towards the registry statistics. A
+unit given by layer and index records ``manual``, unless ``--selection`` says otherwise.
+The planner's effect-weighted explore draws (issue #3486) pass ``attribution``. They are
+drawn in proportion to an attribution-patching estimate, so they must not count as random.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+scan_cache_option = click.option(
+    "--scan-cache/--no-scan-cache",
+    "use_scan_cache",
+    default=True,
+    show_default=True,
+    help="Replay a cached scan of the layer, or store this one "
+    "(see `open-interpretability scan-cache`).",
+)
+
+
+def open_scan_cache(enabled: bool):
+    """The default layer-scan cache, or ``None`` when ``enabled`` is false."""
+    from openinterp.harness.layer_cache import LayerCache
+
+    return LayerCache.default() if enabled else None
+
+
+CHOSEN = ("manual", "attribution")  # selections a unit given by layer and index may record
+
+selection_option = click.option(
+    "--selection",
+    type=click.Choice(CHOSEN),
+    help="How a unit given by layer and index was chosen (default manual). The planner's "
+    "effect-weighted draws pass attribution. Ignored with --random.",
+)
+
+
+def selection(random_pick: bool, chosen: str | None) -> str:
+    """The ``provenance.selection`` of a scan."""
+    return "random" if random_pick else chosen or "manual"
+
+
+def read_superposition(path: Path, unit: str):
+    """(unit, model, layer, profile) from a superposition's definition file."""
+    from pydantic import ValidationError
+
+    from openinterp.core.profiles import SuperpositionProfile
+
+    if unit != "neuron":
+        raise click.UsageError("--superposition is a unit of its own; don't combine it.")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    try:
+        model, layer = data.pop("model"), data.pop("layer")
+        return "superposition", model, layer, SuperpositionProfile.model_validate(data)
+    except (KeyError, ValidationError) as exc:
+        raise click.BadParameter(str(exc), param_hint="--superposition") from exc
+
+
+def resolve_unit(unit, neuron, pole, head, feature, dictionary) -> str:
+    """The unit ``--unit`` names, or the one the other options imply."""
+    if unit is None:
+        unit = "head" if head is not None else "neuron"
+        unit = "feature" if feature is not None or dictionary is not None else unit
+    if unit != "neuron" and (neuron is not None or pole is not None):
+        raise click.UsageError(f"--neuron and --pole are for neurons; a {unit} has neither.")
+    if head is not None and unit != "head":
+        raise click.UsageError("--head needs --unit head (or no --unit).")
+    if unit != "feature" and (feature is not None or dictionary is not None):
+        raise click.UsageError("--feature and --dictionary need --unit feature (or no --unit).")
+    return unit

openinterp/baseline.py

@@ -0,0 +1,254 @@
+"""The Patchscope readout as a blind proposer baseline.
+
+The command is `open-interpretability patchscope-baseline`.
+
+Does the model's own, example-free description of a unit's output direction explain the
+unit as well as the agent's hypothesis? One reading per unit is turned into an
+explanation by a rule fixed before any baseline was scored:
+
+* the ``category`` prompt, at the lowest layer read (layer 2, or the unit's own if
+  earlier), at ``BASELINE_SCALE``;
+* wrapped as ``TEMPLATE``.
+
+The baseline is then scored on the same held-out windows as the agent's explanation.
+The record stores those windows with their labels, so the two scores are paired and
+nothing is measured again. Detection and fuzzing need a judge. A pair counts only when
+the same judge model answered both. The embedding score needs none. The units looked at while
+choosing the prompts and the rule (``DEV_SLUGS``) are reported apart.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from statistics import mean
+
+from pydantic import BaseModel
+
+from openinterp.core.explanation import ExplanationScores
+from openinterp.core.patchscope import PatchscopeReading, PatchscopeReadout
+
+BASELINE_PROMPT = "category"
+BASELINE_SCALE = 2.0
+TEMPLATE = 'Fires on tokens related to "{}".'
+# Poles whose readouts were inspected while choosing the prompts, layers and scale.
+DEV_SLUGS = frozenset(
+    f"Qwen--Qwen2.5-0.5B/{unit}"
+    for unit in (
+        "L0/N788-positive",
+        "L3/N3738-negative",
+        "L5/N2106-positive",
+        "L5/N2131-negative",
+        "L5/N4579-negative",
+        "L14/N2611-positive",
+        "L17/N4749-negative",
+        "L22/N1058-negative",
+        "L22/N2686-positive",
+    )
+)
+METRICS = ("detection", "fuzzing", "embedding")
+
+
+def blind_reading(readout: PatchscopeReadout) -> PatchscopeReading | None:
+    """The one reading the baseline uses, by the fixed rule; ``None`` if it wasn't read."""
+    readings = [r for r in readout.readings if r.prompt == BASELINE_PROMPT]
+    if not readings:
+        return None
+    lowest = min(r.layer for r in readings)
+    return next((r for r in readings if r.layer == lowest and r.scale == BASELINE_SCALE), None)
+
+
+def blind_explanation(readout: PatchscopeReadout) -> str | None:
+    """The baseline explanation for ``readout``: its blind reading in ``TEMPLATE``, or ``None``."""
+    reading = blind_reading(readout)
+    return TEMPLATE.format(reading.text) if reading and reading.text else None
+
+
+def rescored(
+    scores: ExplanationScores,
+    explanation: str,
+    *,
+    judge_model: str | None = None,
+    detection: Sequence[bool] | None = None,
+    fuzzing: Sequence[bool] | None = None,
+    similarities: Sequence[float] | None = None,
+) -> ExplanationScores:
+    """Score another explanation on the windows and labels of ``scores``.
+
+    The result is what that explanation scores on the same held-out text. Answers not
+    given are left unjudged.
+    """
+    from openinterp.harness.explanation_scores import finalize_scores
+
+    def swap(windows, answers, sims=None):
+        return [
+            w.model_copy(
+                update={
+                    "judged": None if answers is None else answers[i],
+                    "similarity": None if sims is None else sims[i],
+                }
+            )
+            for i, w in enumerate(windows)
+        ]
+
+    if detection is not None and len(detection) != len(scores.detection_windows):
+        raise ValueError("one detection answer per window")
+    if fuzzing is not None and len(fuzzing) != len(scores.fuzzing_windows):
+        raise ValueError("one fuzzing answer per window")
+    return finalize_scores(
+        scores.model_copy(
+            update={
+                "explanation": explanation,
+                "judge_model": judge_model,
+                "detection_windows": swap(scores.detection_windows, detection, similarities),
+                "fuzzing_windows": swap(scores.fuzzing_windows, fuzzing),
+            }
+        )
+    )
+
+
+def metric(scores: ExplanationScores | None, name: str) -> float | None:
+    """One metric of ``scores`` (a judge's balanced accuracy, or embedding AUROC), or ``None``."""
+    if scores is None:
+        return None
+    if name == "embedding":
+        return scores.embedding_auroc
+    judged = getattr(scores, name)
+    return None if judged is None else judged.balanced_accuracy
+
+
+class BaselineRow(BaseModel):
+    """One experiment's agent explanation against the baseline, on the same windows."""
+
+    experiment_id: str
+    slug: str
+    status: str
+    selection: str | None
+    dev: bool
+    reading: str
+    agent_explanation: str
+    baseline_explanation: str | None
+    judge_model: str | None
+    baseline_judge_model: str | None = None
+    detection_answer: list[int] | None = None
+    fuzzing_answer: list[int] | None = None
+    agent: dict[str, float | None]
+    baseline: dict[str, float | None]
+
+
+def sign_test(differences: Sequence[float]) -> float | None:
+    """Two-sided exact sign test that baseline − agent is as often > 0 as < 0 (ties out)."""
+    up = sum(d > 0 for d in differences)
+    n = up + sum(d < 0 for d in differences)
+    if not n:
+        return None
+    tail = sum(math.comb(n, k) for k in range(min(up, n - up) + 1)) / 2**n
+    return min(1.0, 2 * tail)
+
+
+def summarise(rows: Sequence[BaselineRow], name: str) -> dict | None:
+    """Paired comparison on ``name`` over the rows where both explanations have a score."""
+    pairs = [(r.agent[name], r.baseline[name]) for r in rows]
+    pairs = [(a, b) for a, b in pairs if a is not None and b is not None]
+    if not pairs:
+        return None
+    diffs = [b - a for a, b in pairs]
+    return {
+        "n": len(pairs),
+        "agent": mean(a for a, _ in pairs),
+        "baseline": mean(b for _, b in pairs),
+        "difference": mean(diffs),
+        "baseline_at_least_agent": sum(d >= 0 for d in diffs) / len(diffs),
+        "sign_test_p": sign_test(diffs),
+    }
+
+
+def report(rows: Sequence[BaselineRow]) -> str:
+    """Return the comparison as a Markdown page.
+
+    The page gives the rule and the readings. It also gives every metric over held-out
+    experiments, over randomly selected and VERIFIED units, and over the dev set.
+    """
+    from collections import Counter
+
+    readings = Counter(r.reading for r in rows)
+    judged = sum(r.baseline_judge_model is not None for r in rows)
+    intro = (
+        f"Each unit's readout becomes one explanation by a rule fixed before scoring: the "
+        f"`{BASELINE_PROMPT}` prompt at the lowest layer read, at ×{BASELINE_SCALE:g} the "
+        f"replaced norm, as `{TEMPLATE.format('<reading>')}`. It is scored on the same "
+        f"held-out windows as the agent's explanation. Detection and fuzzing pair only "
+        f"experiments whose agent explanation was judged by the same model as the baseline's "
+        f"({judged} of {len(rows)}). Embedding uses the record's own encoder. The sign test "
+        f"counts experiments, and a unit with several experiments counts more than once."
+    )
+    common = ", ".join(f"{text!r} ×{n}" for text, n in readings.most_common(10))
+    after = [
+        f"{len(readings)} distinct readings over {len(rows)} experiments. The most common: "
+        f"{common}."
+    ]
+    return paired_report(
+        rows,
+        title="Patchscope readout as a blind proposer baseline",
+        generated_by="`open-interpretability patchscope-baseline`",
+        method="`openinterp/baseline.py` and docs/PROTOCOL.md §4",
+        intro=intro,
+        after=after,
+    )
+
+
+def paired_report(
+    rows: Sequence[BaselineRow],
+    *,
+    title: str,
+    generated_by: str,
+    method: str,
+    intro: str,
+    after: Sequence[str] = (),
+) -> str:
+    """Return a Markdown page: ``intro``, the paired table of every metric, then ``after``.
+
+    The table compares the agent and the baseline over held-out experiments, over
+    randomly selected and VERIFIED units, and over the dev set. Groups and metrics with
+    no pairs are left out.
+    """
+    lines = [
+        f"# {title}",
+        "",
+        f"Generated by {generated_by}. Do not edit. Method: {method}.",
+        "",
+        intro,
+        "",
+        "| Group | Metric | n | Agent | Baseline | Baseline − agent | Baseline ≥ agent "
+        "| Sign test p |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    lines += [_metric_row(label, g, name) for label, g in _groups(rows) for name in METRICS]
+    lines = [line for line in lines if line is not None]
+    if after:
+        lines += ["", *after]
+    return "\n".join(lines) + "\n"
+
+
+def _groups(rows: Sequence[BaselineRow]) -> list[tuple[str, list[BaselineRow]]]:
+    return [
+        ("Held-out experiments", [r for r in rows if not r.dev]),
+        (
+            "Held-out, randomly selected units",
+            [r for r in rows if not r.dev and r.selection == "random"],
+        ),
+        ("Held-out, VERIFIED", [r for r in rows if not r.dev and r.status == "VERIFIED"]),
+        ("Dev set (inspected while choosing the rule)", [r for r in rows if r.dev]),
+    ]
+
+
+def _metric_row(label: str, group: Sequence[BaselineRow], name: str) -> str | None:
+    """One table row comparing the agent and the baseline on ``name``; ``None`` if unpaired."""
+    s = summarise(group, name)
+    if s is None:
+        return None
+    p = "—" if s["sign_test_p"] is None else f"{s['sign_test_p']:.2g}"
+    return (
+        f"| {label} | {name} | {s['n']} | {s['agent']:.2f} | {s['baseline']:.2f} | "
+        f"{s['difference']:+.2f} | {s['baseline_at_least_agent']:.0%} | {p} |"
+    )