open-interpretability 0.0.20__py3-none-any.whl

openinterp/core/stats.py

@@ -0,0 +1,172 @@
+"""Statistics that account for dependence between observations.
+
+Probes written by one reviewer are not independent: near-duplicates ("Many cities,
+including Paris…" / "Many cities, including Rome…") share most of their information.
+We cluster near-duplicate probes and treat each cluster as one observation, scored by
+its mean pass rate. Effective counts feed the protocol's minimum-probe gates, the
+balanced accuracy and the Beta posteriors behind significance and the registry's
+false-discovery estimate.
+"""
+
+from __future__ import annotations
+
+import random
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from functools import cache
+
+import torch
+
+_WORDS = re.compile(r"[a-z0-9']+")
+
+
+def _words(text: str) -> frozenset[str]:
+    return frozenset(_WORDS.findall(text.lower()))
+
+
+def jaccard(a: frozenset[str], b: frozenset[str]) -> float:
+    """Word-set overlap of two probes; two empty sets count as identical."""
+    union = a | b
+    return len(a & b) / len(union) if union else 1.0
+
+
+def cluster_texts(texts: Sequence[str], threshold: float) -> list[int]:
+    """Single-linkage clusters of texts whose word sets overlap by >= ``threshold``.
+
+    Returns a cluster label per text, numbered in order of first appearance.
+    """
+    parent = list(range(len(texts)))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    words = [_words(t) for t in texts]
+    for i in range(len(texts)):
+        for j in range(i + 1, len(texts)):
+            if jaccard(words[i], words[j]) >= threshold:
+                parent[find(j)] = find(i)
+    labels: dict[int, int] = {}
+    return [labels.setdefault(find(i), len(labels)) for i in range(len(texts))]
+
+
+@dataclass(frozen=True)
+class EffectiveCounts:
+    """Probe counts after near-duplicates are clustered (docs/PROTOCOL.md §4)."""
+
+    raw: int  # probes
+    clusters: int  # independent observations
+    passed: float  # sum over clusters of the cluster's pass rate
+
+    @property
+    def rate(self) -> float | None:
+        """The cluster-weighted pass rate, or ``None`` when there are no probes."""
+        return self.passed / self.clusters if self.clusters else None
+
+
+def effective_counts(
+    texts: Sequence[str], passed: Sequence[bool], threshold: float
+) -> EffectiveCounts:
+    """Cluster near-duplicate probes and count each cluster as one observation.
+
+    One reviewer writes every probe, often as variations on one theme, so probes are not
+    independent. A cluster's score is the mean pass rate of its probes (docs/PROTOCOL.md §4).
+    """
+    labels = cluster_texts(texts, threshold)
+    groups: dict[int, list[bool]] = {}
+    for label, ok in zip(labels, passed, strict=True):
+        groups.setdefault(label, []).append(ok)
+    return EffectiveCounts(
+        raw=len(texts),
+        clusters=len(groups),
+        passed=sum(sum(g) / len(g) for g in groups.values()),
+    )
+
+
+def balanced_accuracy(specificity: EffectiveCounts, sensitivity: EffectiveCounts) -> float:
+    """The mean of the rates that exist, or 0 when neither rate exists."""
+    rates = [r for r in (specificity.rate, sensitivity.rate) if r is not None]
+    return sum(rates) / len(rates) if rates else 0.0
+
+
+def p_balanced_above(
+    specificity: EffectiveCounts,
+    sensitivity: EffectiveCounts,
+    threshold: float,
+    *,
+    samples: int = 4000,
+    seed: int = 0,
+) -> float:
+    """Posterior P((spec + sens) / 2 > threshold) under Beta(1, 1) priors.
+
+    Fixed ``seed`` keeps it deterministic, so identical records always score the same.
+    Many records have the same counts, so the result is cached on them.
+    """
+    spec = (1 + specificity.passed, 1 + specificity.clusters - specificity.passed)
+    sens = (1 + sensitivity.passed, 1 + sensitivity.clusters - sensitivity.passed)
+    return _p_beta_mean_above(spec, sens, threshold, samples, seed)
+
+
+@cache
+def _p_beta_mean_above(
+    spec: tuple[float, float], sens: tuple[float, float], threshold: float, samples: int, seed: int
+) -> float:
+    """P((x + y) / 2 > threshold) for x ~ Beta(*spec) and y ~ Beta(*sens), by sampling."""
+    rng = random.Random(seed)
+    hits = sum(
+        (rng.betavariate(*spec) + rng.betavariate(*sens)) / 2 > threshold for _ in range(samples)
+    )
+    return hits / samples
+
+
+def expected_false_discoveries(p_useful: Sequence[float]) -> float:
+    """Expected number of claimed discoveries that are false: sum of (1 - P(useful))."""
+    return sum(1.0 - p for p in p_useful)
+
+
+def rank_columns(x: torch.Tensor, chunk: int = 1024) -> torch.Tensor:
+    """Ranks (0-based) down each column of ``x`` [n, c], averaging ties.
+
+    Pole strengths are mostly exact zeros, so tie handling matters. Each tied value gets
+    the mean of the ranks that it spans, as in ``scipy.stats.rankdata``.
+    """
+    n = x.shape[0]
+    out = torch.empty_like(x, dtype=torch.float32)
+    positions = torch.arange(n, dtype=torch.float32)[:, None]
+    for start in range(0, x.shape[1], chunk):
+        cols = x[:, start : start + chunk].float()
+        values, order = cols.sort(dim=0)
+        new = torch.ones_like(values, dtype=torch.bool)
+        new[1:] = values[1:] != values[:-1]
+        group = new.cumsum(0) - 1
+        pos = positions.expand_as(values)
+        sums = torch.zeros_like(values).scatter_add_(0, group, pos)
+        counts = torch.zeros_like(values).scatter_add_(0, group, torch.ones_like(values))
+        mean_rank = (sums / counts.clamp(min=1)).gather(0, group)
+        out[:, start : start + chunk] = torch.empty_like(values).scatter_(0, order, mean_rank)
+    return out
+
+
+def spearman_columns(target: torch.Tensor, others: torch.Tensor, chunk: int = 1024) -> torch.Tensor:
+    """Spearman's rho between ``target`` [n] and each column of ``others`` [n, c]."""
+    ranks_t = rank_columns(target[:, None])[:, 0]
+    t = ranks_t - ranks_t.mean()
+    tt = (t * t).sum()
+    rho = torch.zeros(others.shape[1])
+    for start in range(0, others.shape[1], chunk):
+        o = rank_columns(others[:, start : start + chunk])
+        o = o - o.mean(0)
+        denom = torch.sqrt(tt * (o * o).sum(0))
+        part = (t[:, None] * o).sum(0) / denom
+        rho[start : start + chunk] = torch.where(denom > 0, part, torch.zeros_like(part))
+    return rho.clamp(-1, 1)
+
+
+def spearman(x: torch.Tensor, y: torch.Tensor) -> float:
+    """Spearman's rho between ``x`` and ``y``; 0 with fewer than three points."""
+    if x.numel() < 3:
+        return 0.0
+    return float(spearman_columns(x.float(), y.float()[:, None])[0])

openinterp/core/steering.py

@@ -0,0 +1,49 @@
+"""Schemas for steering samples: what the model writes with a unit clamped high or ablated.
+
+The harness continues each neutral prompt greedily in three ways: at baseline, with the
+unit ablated, and with the unit clamped at every position. The clamp uses several
+multiples of the unit's own top activation. You can then read the continuations side
+by side (Turner et al., 2023; Goodfire, "Neural Networks Are Already Clean", 2026).
+Reported, not gated (docs/PROTOCOL.md §4). Neither the proposer nor the reviewer sees
+them.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field, model_validator
+
+from openinterp.core.strict import StrictModel
+
+
+class SteeringSample(StrictModel):
+    """One prompt's greedy continuations under each intervention."""
+
+    prompt: str = Field(min_length=1)
+    baseline: str = Field(description="The continuation with no intervention.")
+    ablated: str = Field(description="The same with the unit ablated at every position.")
+    clamped: list[str] = Field(
+        description="The same with the unit clamped at every position, one per `multiples`."
+    )
+
+
+class SteeringSamples(StrictModel):
+    """Every prompt's continuations, with the unit clamped high or ablated."""
+
+    clamp_unit: float = Field(
+        gt=0.0,
+        description="The strength one multiple stands for: the unit's top activation in the "
+        "scan (`max_activation`). A neuron pole is clamped to that signed value.",
+    )
+    multiples: list[float] = Field(min_length=1)
+    max_new_tokens: int = Field(gt=0)
+    samples: list[SteeringSample]
+
+    @model_validator(mode="after")
+    def _one_text_per_multiple(self) -> SteeringSamples:
+        for s in self.samples:
+            if len(s.clamped) != len(self.multiples):
+                raise ValueError(
+                    f"{s.prompt!r} has {len(s.clamped)} clamped texts for "
+                    f"{len(self.multiples)} multiples"
+                )
+        return self

openinterp/core/strict.py

@@ -0,0 +1,19 @@
+"""Base types shared by the schema modules."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field
+
+UnitFloat = Annotated[float, Field(ge=0.0, le=1.0)]
+
+
+class StrictModel(BaseModel):
+    """The base of every schema.
+
+    Strict types and ``extra="forbid"`` reject a record that does not match its schema.
+    ``frozen`` stops code from changing a model after validation, because records are signed.
+    """
+
+    model_config = ConfigDict(strict=True, extra="forbid", frozen=True)

openinterp/core/takedowns.py

@@ -0,0 +1,136 @@
+"""Takedowns: passages that the project stops publishing on request (``SECURITY.md``).
+
+A takedown is one line of ``wiki/takedowns.jsonl``. It names a passage by the hashes of
+its *shingles*: each run of :data:`SHINGLE_WORDS` consecutive words, lowercased. The file
+never holds the text, because that would publish the text again. One passage can appear
+in many records and fields, and the hashes find it in each one.
+
+The build removes the text that the shingles cover from everything it publishes
+(:mod:`openinterp.builder.pii`). An experiment page may change outside its Discussion
+section only by that removal (:func:`redact`). The record files and their signatures
+don't change. So a takedown hides the text without breaking reproduction.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Iterable, Sequence
+from datetime import date as Date
+from pathlib import Path
+
+from pydantic import Field, ValidationError
+
+from openinterp.core.paths import DEFAULT_WIKI_DIR
+from openinterp.core.strict import StrictModel
+
+SHINGLE_WORDS = 8  # a run this long is rare enough to name one passage
+WORD = re.compile(r"\w+")
+HASH_CHARS = 16  # a 64-bit prefix of SHA-256
+
+Span = tuple[int, int]
+
+
+class Takedown(StrictModel):
+    """One request to stop publishing a passage."""
+
+    id: str = Field(min_length=1, pattern=r"^[a-z0-9-]+$")
+    date: Date
+    reason: str = Field(
+        min_length=1, description="Why, in a few words. It must not hold personal data."
+    )
+    shingles: list[str] = Field(
+        min_length=1, description="The hash of each shingle of the passage (shingle_hashes)."
+    )
+
+
+def takedowns_path(wiki_dir: Path | str = DEFAULT_WIKI_DIR) -> Path:
+    """The takedown file of ``wiki_dir``."""
+    return Path(wiki_dir) / "takedowns.jsonl"
+
+
+def parse_takedowns(text: str) -> list[Takedown]:
+    """Every takedown in ``text``, in order. Raises ``ValueError`` naming a bad line."""
+    out = []
+    for number, line in enumerate(text.splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            out.append(Takedown.model_validate_json(line))
+        except ValidationError as exc:
+            raise ValueError(f"line {number}: {exc.errors()[0]['msg']}") from exc
+    return out
+
+
+def load_takedowns(wiki_dir: Path | str = DEFAULT_WIKI_DIR) -> list[Takedown]:
+    """Every takedown of ``wiki_dir``; none if there is no takedown file."""
+    path = takedowns_path(wiki_dir)
+    return parse_takedowns(path.read_text(encoding="utf-8")) if path.exists() else []
+
+
+def _shingles(text: str) -> Iterable[tuple[str, Span]]:
+    """Each shingle of ``text``: its hash, and the characters from its first to last word."""
+    words = list(WORD.finditer(text))
+    for i in range(len(words) - SHINGLE_WORDS + 1):
+        run = words[i : i + SHINGLE_WORDS]
+        key = " ".join(w.group().lower() for w in run)
+        digest = hashlib.sha256(key.encode()).hexdigest()[:HASH_CHARS]
+        yield digest, (run[0].start(), run[-1].end())
+
+
+def shingle_hashes(passage: str) -> list[str]:
+    """The hashes that name ``passage``, in order and without repeats.
+
+    Raises ``ValueError`` for a passage shorter than one shingle.
+    """
+    hashes = list(dict.fromkeys(h for h, _ in _shingles(passage)))
+    if not hashes:
+        raise ValueError(f"a passage needs at least {SHINGLE_WORDS} words")
+    return hashes
+
+
+def all_hashes(takedowns: Sequence[Takedown]) -> frozenset[str]:
+    """Every shingle hash of ``takedowns``."""
+    return frozenset(h for t in takedowns for h in t.shingles)
+
+
+def covered(text: str, hashes: frozenset[str]) -> tuple[Span, ...]:
+    """The spans of ``text`` that the shingles in ``hashes`` cover, sorted and merged."""
+    if not hashes:
+        return ()
+    merged: list[Span] = []
+    for digest, (start, end) in _shingles(text):
+        if digest not in hashes:
+            continue
+        if merged and start <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+        else:
+            merged.append((start, end))
+    return tuple(merged)
+
+
+def redact(text: str, hashes: frozenset[str], marker: str) -> str:
+    """``text`` with ``marker`` in place of each span that ``hashes`` cover."""
+    for start, end in reversed(covered(text, hashes)):
+        text = text[:start] + marker + text[end:]
+    return text
+
+
+_active: frozenset[str] = frozenset()
+
+
+def activate(takedowns: Sequence[Takedown]) -> None:
+    """Make the build remove what ``takedowns`` name (:func:`active_hashes`)."""
+    global _active
+    _active = all_hashes(takedowns)
+
+
+def active_hashes() -> frozenset[str]:
+    """The shingle hashes that the build removes. :func:`activate` sets them."""
+    return _active
+
+
+def to_line(takedown: Takedown) -> str:
+    """``takedown`` as one line of the takedown file, with its keys in a fixed order."""
+    return json.dumps(takedown.model_dump(mode="json")) + "\n"

openinterp/core/transcripts.py

@@ -0,0 +1,130 @@
+"""Token usage of a Claude Code subagent, read from its transcript.
+
+Claude Code keeps each subagent's transcript at
+``~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl``, one JSON line per
+message part. Every part of one API response repeats that response's ``usage``. The
+last part carries the final output count. So we count each response once, from its
+last line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+from openinterp.core.costs import ExternalUsage, RequestUsage
+
+
+def _time(value) -> datetime | None:
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (AttributeError, ValueError):
+        return None
+
+
+def claude_dir() -> Path:
+    """Claude Code's config directory: ``$CLAUDE_CONFIG_DIR``, else ``~/.claude``."""
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+
+
+def find_transcript(agent: str) -> Path:
+    """Return the transcript file of ``agent``.
+
+    ``agent`` is a transcript path, or the agent ID that Claude Code reports when a
+    subagent finishes (``a1b2c3…``, with or without the ``agent-`` prefix).
+    """
+    path = Path(agent).expanduser()
+    if path.suffix == ".jsonl" and path.is_file():
+        return path
+    name = f"agent-{agent.removeprefix('agent-')}.jsonl"
+    found = sorted(
+        claude_dir().glob(f"projects/*/*/subagents/{name}"), key=lambda p: p.stat().st_mtime
+    )
+    if not found:
+        raise FileNotFoundError(f"No Claude Code transcript {name} under {claude_dir()}.")
+    return found[-1]  # the newest, if a resumed session copied it
+
+
+def usage_from_transcript(path: Path) -> ExternalUsage:
+    """Tokens per API request in a Claude Code transcript, for ``open-interpretability usage``.
+
+    Claude Code writes one line per content block, so a request can have many lines. The
+    last line of each request holds its final usage.
+    """
+    last: dict[str, tuple] = {}  # API response id → (time, its last line's message)
+    for line in path.read_text().splitlines():
+        try:
+            entry = json.loads(line)
+        except ValueError:
+            continue  # a line cut off by a crash
+        message = entry.get("message") if entry.get("type") == "assistant" else None
+        if not isinstance(message, dict) or not message.get("usage"):
+            continue
+        if message.get("model", "").startswith("<"):  # e.g. "<synthetic>" error stubs
+            continue
+        at = _time(entry.get("timestamp"))
+        last[message.get("id") or entry.get("uuid")] = (at, message)
+
+    requests, models = [], {}
+    for at, message in last.values():
+        u = message["usage"]
+        write_1h = (u.get("cache_creation") or {}).get("ephemeral_1h_input_tokens") or 0
+        requests.append(
+            RequestUsage(
+                at=at,
+                input_tokens=u.get("input_tokens") or 0,
+                cache_read_tokens=u.get("cache_read_input_tokens") or 0,
+                cache_write_5m_tokens=max(
+                    (u.get("cache_creation_input_tokens") or 0) - write_1h, 0
+                ),
+                cache_write_1h_tokens=write_1h,
+                output_tokens=u.get("output_tokens") or 0,
+            )
+        )
+        model = message.get("model") or "unknown"
+        models[model] = models.get(model, 0) + 1
+    return ExternalUsage.of(
+        requests,
+        model=",".join(sorted(models, key=lambda m: -models[m])) or None,
+        source=f"claude-code:{path.stem}",
+    )
+
+
+def forbidden_reads(path: Path) -> tuple[list[str], list[str]]:
+    """Blocked paths that the reviewer in transcript ``path`` read, and tried to read.
+
+    The check is :func:`openinterp.core.isolation.forbidden`, for each tool call in the
+    transcript. The first list has the calls that completed. The second list has the
+    calls that failed, e.g. because the reviewer's hook denied them, so no content was
+    read. Each list is in transcript order, without duplicates.
+    """
+    from openinterp.core.isolation import TOOLS, forbidden
+
+    calls: dict[str, tuple[str, bool]] = {}  # tool_use id → (blocked path, completed)
+    for line in path.read_text().splitlines():
+        try:
+            entry = json.loads(line)
+        except ValueError:
+            continue
+        content = (entry.get("message") or {}).get("content")
+        if not isinstance(content, list):
+            continue
+        cwd = entry.get("cwd") or "."
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_use" and block.get("name") in TOOLS:
+                hit = forbidden(block["name"], block.get("input") or {}, cwd, cwd)
+                if hit is not None:
+                    calls[block.get("id")] = (hit, True)
+            elif (
+                block.get("type") == "tool_result"
+                and block.get("tool_use_id") in calls
+                and block.get("is_error")
+            ):
+                calls[block["tool_use_id"]] = (calls[block["tool_use_id"]][0], False)
+    read = [hit for hit, completed in calls.values() if completed]
+    tried = [hit for hit, completed in calls.values() if not completed]
+    return list(dict.fromkeys(read)), list(dict.fromkeys(tried))

openinterp/core/wiring.py

@@ -0,0 +1,80 @@
+"""A neuron pole's strongest upstream and downstream connections (reported, not gated)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from openinterp.core.strict import StrictModel
+
+WiringMethod = Literal["weights", "activations"]
+
+
+class WiringEdge(StrictModel):
+    """One connection between the audited pole and another unit of the same model.
+
+    ``kind`` and ``layer``/``index`` name the other unit: a neuron (either pole) or an
+    attention head. What ``weight`` measures depends on :attr:`Wiring.method`.
+    ``channels`` splits a weights reading by the read that it goes through. The reads
+    are ``in``, or ``gate`` and ``up`` for a gated MLP, or ``q``, ``k`` and ``v`` for a
+    head downstream. ``weight`` is then the channel of largest magnitude.
+    """
+
+    kind: Literal["mlp_neuron", "attn_head"]
+    layer: int = Field(ge=0)
+    index: int = Field(ge=0)
+    weight: float
+    channels: dict[str, float] = Field(default_factory=dict)
+
+
+class Wiring(StrictModel):
+    """A unit's top connections, from its weights or from activations.
+
+    How each kind of unit reads and writes:
+
+    - A neuron pole reads its MLP input (``gate``/``up``, or ``in``). It writes ``w_out``,
+      negated for the negative pole.
+    - A dictionary feature reads with its encoder row and writes its decoder row.
+    - A head reads through ``q``, ``k`` and ``v``, and writes the subspace ``W_O``.
+
+    Upstream units write before the unit reads. A head's own layer's MLP runs after the
+    head, so it reads the head downstream.
+
+    *weights* (virtual weights, Elhage et al., 2021). The norms before each read are
+    folded in as their gain, and centring for LayerNorm. Their per-token scale is
+    ignored. So weights rank units, but have no absolute meaning. Each number is how much
+    one unit's read picks up of the other unit's write:
+
+    - When a vector reads a vector: ``w · r̂``. ``+`` means that a positive activation
+      raises the read. Upstream, the unit's own reads are unit-normalised.
+    - Otherwise, a norm (≥ 0). For a matrix read, it is the norm of ``R·w``. For an
+      upstream head's OV circuit, it is the norm of ``R·W_O·W_V``. Downstream, it is the
+      norm of ``W_Q/K/V·w``.
+
+    *activations* (attribution patching, Syed et al., 2023). Each number is averaged over
+    the peaks of the review's prompts where the unit fired:
+
+    - Upstream: ``Σ_s write_s · ∂strength/∂x_s``. This is the first-order change in
+      strength when the earlier unit's direct write is removed from the input. ``+``
+      means that the earlier unit excites the unit.
+    - Downstream neurons: the exact change in a later neuron's signed activation at the
+      peak. The unit's write is removed from that neuron's input only.
+    - Downstream heads: ``|W_O Δz|``, how far a later head's write at the peak moves. The
+      harness removes the unit's write from one input of the head at a time (``q``,
+      ``k`` or ``v``). It removes the write at every position at once.
+    """
+
+    method: WiringMethod
+    upstream_neurons: list[WiringEdge]
+    upstream_heads: list[WiringEdge] | None = Field(
+        default=None, description="None when the architecture's attention isn't supported."
+    )
+    downstream_neurons: list[WiringEdge]
+    downstream_heads: list[WiringEdge] | None = Field(
+        default=None,
+        description="None when not measured (activations before downstream heads were).",
+    )
+    prompts: int = Field(
+        default=0, ge=0, description="Activations only: prompts whose peaks were averaged."
+    )