open-interpretability 0.0.20__py3-none-any.whl

openinterp/cli_submission.py

@@ -0,0 +1,217 @@
+"""The steps of ``open-interpretability audit`` after the proposer answers.
+
+The steps are counterfactuals, the Patchscope, steering, WordNet specificity and wiring
+readouts, and writing the submission.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from openinterp.cli_evidence import with_costs
+from openinterp.core.paths import DEFAULT_SUBMISSIONS_DIR
+
+
+def read_patchscope(runner, submission):
+    """Return the model's own reading of the unit's output direction.
+
+    It runs after the proposer answers, so it can't steer the hypothesis. ``None`` for a
+    head, which writes a subspace.
+    """
+    from openinterp.core import costs
+    from openinterp.harness.patchscope import patchscope, write_direction
+    from openinterp.harness.units import submission_unit
+
+    direction = write_direction(runner, submission_unit(submission))
+    if direction is None or runner.tokenizer is None:
+        return None
+    click.echo("Reading the output direction back through a Patchscope…", err=True)
+    with costs.stage("patchscope"):
+        return patchscope(runner, submission.identifier.layer, direction)
+
+
+def read_prior_art(runner, submission):
+    """Return published explanations of the unit, or of latents aligned with it.
+
+    It runs after the proposer answers, so it can't steer the hypothesis. The reviewer
+    sees it (:mod:`openinterp.prior_art`).
+    """
+    from openinterp.prior_art import enabled, find_prior_art
+
+    if enabled():
+        click.echo("Looking up prior art on Neuronpedia…", err=True)
+    return find_prior_art(submission, runner)
+
+
+def read_steering(runner, submission):
+    """Return neutral prompts continued at baseline, with the unit ablated and clamped high.
+
+    It runs after the proposer answers. ``None`` for a head, which has no "high" to clamp
+    to.
+    """
+    from openinterp.core import costs
+    from openinterp.harness.steering import steering_samples
+    from openinterp.harness.units import HeadUnit, submission_unit
+
+    unit = submission_unit(submission)
+    if isinstance(unit, HeadUnit) or not submission.max_activation or runner.tokenizer is None:
+        return None
+    click.echo("Continuing neutral prompts with the unit clamped and ablated…", err=True)
+    with costs.stage("steering"):
+        return steering_samples(runner, unit, submission.max_activation)
+
+
+def read_specificity(runner, submission, draft):
+    """Return the unit on a WordNet category's held-out words against its siblings' words.
+
+    The category is the draft's ``wordnet_synset``, or else the largest category of the
+    peak words. It runs after the proposer answers. ``None`` without WordNet, without a
+    category, or when either side has too few words.
+    """
+    from openinterp import wordnet
+    from openinterp.core import costs
+    from openinterp.harness.specificity import specificity
+    from openinterp.harness.units import submission_unit
+
+    lex = wordnet.lexicon()
+    if lex is None or not submission.max_activation or runner.tokenizer is None:
+        return None
+    peaks = wordnet.peak_words(submission.top_examples)
+    synset, source = draft.wordnet_synset, "proposer"
+    if synset is not None and not lex.has(synset):
+        click.echo(f"Skipping the WordNet check: no noun synset {synset!r}.", err=True)
+        return None
+    if synset is None:
+        groups = wordnet.categorise(peaks, lex).groups
+        if not groups:
+            return None
+        synset, source = groups[0].synset, "peak_words"
+    click.echo(f"Measuring {synset} words against its sibling categories…", err=True)
+    with costs.stage("specificity"):
+        unit = submission_unit(submission)
+        return specificity(runner, unit, lex, synset, source, submission.max_activation, peaks)
+
+
+def read_wiring(runner, submission):
+    """Return the unit's top connections by virtual weight.
+
+    It runs after the proposer answers. ``None`` on an unsupported architecture.
+    """
+    from openinterp.core import costs
+    from openinterp.core.exceptions import ArchitectureNotSupportedError
+    from openinterp.harness.units import submission_unit
+    from openinterp.harness.wiring import weight_wiring
+
+    click.echo("Reading the unit's wiring from the weights…", err=True)
+    with costs.stage("wiring"):
+        try:
+            return weight_wiring(runner, submission_unit(submission))
+        except ArchitectureNotSupportedError as exc:
+            click.echo(f"Skipping wiring: {exc}", err=True)
+            return None
+
+
+def readouts(runner, submission, draft) -> dict:
+    """The readouts taken after the proposer answers, by submission field."""
+    return {
+        "patchscope": read_patchscope(runner, submission),
+        "steering": read_steering(runner, submission),
+        "wordnet_specificity": read_specificity(runner, submission, draft),
+        "wiring": read_wiring(runner, submission),
+        "prior_art": read_prior_art(runner, submission),
+    }
+
+
+def write_submission(
+    agent,
+    draft,
+    runner,
+    evidence,
+    superseded,
+    out: Path | None,
+    contributor: str | None = None,
+    sister_file: Path | None = None,
+) -> None:
+    """Build the submission (counterfactuals, Patchscope, steering, specificity, wiring), write it.
+
+    In a sister study (``sister_file``), the explanation is the sister's, word for word.
+    """
+    from openinterp.builder.wiki import experiment_id
+    from openinterp.core import costs
+    from openinterp.sisters import sister_ref
+
+    ident = evidence.identifier
+    if superseded is not None and superseded.submission.identifier.slug != ident.slug:
+        raise click.UsageError(
+            f"--supersedes names an experiment on {superseded.submission.identifier}, "
+            f"not on {ident}."
+        )
+    sister, draft = sister_draft(sister_file, ident, draft)
+    submission = build_submission(agent, draft, runner, evidence)
+    after = readouts(runner, submission, draft)
+    # An evidence file carries the scan's costs; a one-step audit measured them here.
+    provenance = with_costs(submission.provenance, costs.measured())
+    revises = superseded and experiment_id(superseded)
+    submission = submission.model_copy(
+        update={
+            "contributor": contributor,
+            "opposite_pole": evidence.opposite_pole,
+            "provenance": provenance,
+            "supersedes": revises,
+            "sister_of": sister and sister_ref(sister),
+            **after,
+        }
+    )
+    out = out or DEFAULT_SUBMISSIONS_DIR / f"{ident.slug}.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(submission.model_dump_json(indent=2))
+    click.echo(f"Hypothesis: {submission.natural_language_explanation}")
+    if revises:
+        click.echo(f"Supersedes: {revises} ({superseded.verdict.status})")
+    if sister:
+        click.echo(f"Sister study of: {submission.sister_of}")
+    click.echo(f"Wrote {out}")
+
+
+def sister_draft(sister_file, ident, draft):
+    """Return ``(sister record, draft)``.
+
+    In a sister study, the draft has the sister's explanation, word for word. Otherwise
+    the result is ``(None, draft)``.
+    """
+    from openinterp.cli_evidence import load_sister
+
+    if sister_file is None:
+        return None, draft
+    sister = load_sister(sister_file, ident)
+    text = sister.submission.natural_language_explanation
+    return sister, draft.model_copy(update={"explanation": text})
+
+
+def build_submission(agent, draft, runner, evidence):
+    """Build the submission from the proposer's draft, timed as the counterfactuals stage."""
+    from openinterp.core import costs
+
+    with costs.stage("counterfactuals"):
+        try:
+            return agent.build_submission(
+                evidence.identifier,
+                draft,
+                runner=runner,
+                examples=evidence.top_examples,
+                histogram=evidence.activation_histogram,
+                provenance=evidence.provenance,
+                confounds=evidence.confounds,
+                correlated=evidence.correlated_neurons,
+                vocabulary_lens=evidence.vocabulary_lens,
+                input_attribution=evidence.input_attribution,
+                head_profile=evidence.head_profile,
+                dictionary_profile=evidence.dictionary_profile,
+                first_token_floor=evidence.first_token_floor,
+                superposition_profile=evidence.superposition_profile,
+                manifold=evidence.manifold,
+            )
+        except ValueError as exc:  # e.g. a one-token counterfactual prompt
+            raise click.ClickException(f"Counterfactual: {exc}") from exc

openinterp/cli_superpositions.py

@@ -0,0 +1,118 @@
+"""``open-interpretability superpositions``: write and show superposition definitions.
+
+The finders write one definition per line (issue #3686). A line is what ``audit
+--superposition`` reads. :mod:`openinterp.superposition_finders` holds the finders.
+``show`` writes one definition to its own file, for a planner draw (issue #3687).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from openinterp.cli import _load_runner, cli
+
+out_option = click.option(
+    "--out",
+    "out",
+    required=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="The JSONL file to write: one definition per line.",
+)
+
+
+def _write(out: Path, definitions: list[dict]) -> None:
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("".join(json.dumps(d) + "\n" for d in definitions), encoding="utf-8")
+    click.echo(f"wrote {len(definitions)} definitions → {out}")
+
+
+@cli.group()
+def superpositions() -> None:
+    """Find superpositions: sparse directions over one layer's MLP neurons."""
+
+
+@superpositions.command("from-circuit")
+@click.option(
+    "--rows",
+    "rows_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="A circuit's rows, such as docs/analyses/sva-circuit.jsonl.",
+)
+@click.option("--model", "model", required=True, help="The model that the circuit is on.")
+@click.option("--top", default=100, show_default=True, help="The circuit's top neurons by rank.")
+@click.option("--min-members", default=2, show_default=True, help="The fewest neurons per layer.")
+@out_option
+def from_circuit_command(rows_file, model, top, min_members, out):
+    """One definition per layer with at least --min-members of the circuit's --top neurons."""
+    from openinterp.superposition_finders import definition, from_circuit
+
+    lines = rows_file.read_text(encoding="utf-8").splitlines()
+    rows = [json.loads(line) for line in lines if line.strip()]
+    source = f"{rows_file.as_posix()}, top {top} neurons by attribution (#3686)"
+    found = from_circuit(rows, top=top, min_members=min_members, source=source)
+    _write(out, [definition(model, layer, profile) for layer, profile in found])
+
+
+@superpositions.command("grammatical-number")
+@click.option("--model", "model", required=True, help="The model to probe.")
+@click.option("--layers", required=True, help="Comma-separated layers, e.g. 0,4,19.")
+@click.option("--k", default=16, show_default=True, help="Neurons per probe.")
+@click.option("--n", default=400, show_default=True, help="Agreement pairs: 2 examples each.")
+@click.option("--seed", default=0, show_default=True)
+@click.option("--device", default="auto", show_default=True, help="cpu, cuda, mps or auto.")
+@out_option
+def grammatical_number_command(model, layers, k, n, seed, device, out):
+    """One definition per layer: a sparse probe for the number of the agreeing noun."""
+    from openinterp.superposition_finders import definition, grammatical_number
+
+    try:
+        layer_list = [int(x) for x in layers.split(",") if x.strip()]
+    except ValueError as exc:
+        raise click.BadParameter(
+            "give layers as integers, e.g. 0,4,19", param_hint="--layers"
+        ) from exc
+    runner = _load_runner(model, device, "float32", None)
+    found = grammatical_number(runner, layer_list, k=k, n=n, seed=seed)
+    for layer, _, accuracy in found:
+        click.echo(f"layer {layer}: held-out accuracy {accuracy:.3f}")
+    _write(out, [definition(model, layer, profile) for layer, profile, _ in found])
+
+
+@superpositions.command("show")
+@click.argument("superposition_id")
+@click.option("--model", "model", required=True, help="The model that the superposition is on.")
+@click.option(
+    "--definitions",
+    "definitions_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="The JSONL file to search. Default: data/superpositions/<model slug>.jsonl.",
+)
+@click.option(
+    "--out",
+    "out",
+    required=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="The JSON file to write: the one definition that `audit --superposition` reads.",
+)
+def show_command(superposition_id, model, definitions_file, out):
+    """Write the definition whose id is SUPERPOSITION_ID, as one JSON object."""
+    from openinterp.planner_superpositions import (
+        default_definitions,
+        definition_identifier,
+        load_definitions,
+    )
+
+    path = definitions_file or default_definitions(model)
+    if not path.is_file():
+        raise click.ClickException(f"no definitions file at {path}")
+    for definition in load_definitions(path):
+        if definition_identifier(definition).superposition_id == superposition_id:
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(json.dumps(definition) + "\n", encoding="utf-8")
+            click.echo(f"wrote {model} superposition {superposition_id} → {out}")
+            return
+    raise click.ClickException(f"no definition in {path} has the id {superposition_id}")

openinterp/cli_wiring.py

@@ -0,0 +1,54 @@
+"""``open-interpretability wiring-backfill``: wiring for archived records that predate it.
+
+See :mod:`openinterp.wiring_backfill`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from openinterp.cli import _load_runner, cli, wiki_dir_option
+from openinterp.wiring_backfill import DEFAULT_PATH
+
+
+@cli.command("wiring-backfill")
+@wiki_dir_option()
+@click.option(
+    "--out",
+    default=DEFAULT_PATH,
+    show_default=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="JSONL of wiring rows; rows already in it are skipped, so a run can resume.",
+)
+@click.option("--limit", type=int, help="Wire at most this many records.")
+@click.option(
+    "--device",
+    default="auto",
+    show_default=True,
+    help="cpu, cuda, mps or auto. Each record's own model revision and dtype are used.",
+)
+def wiring_backfill(wiki_dir, out, limit, device):
+    """Record the wiring of every archived experiment that has none, in --out.
+
+    Records are write-once and often signed, so they are left alone.
+    `open-interpretability build` shows a row's wiring for its record, marked as backfilled.
+    """
+    from openinterp.builder.wiki import load_archive
+    from openinterp.harness.units import attn_implementation
+    from openinterp.wiring_backfill import backfill, sort_rows
+
+    def load(record):
+        sub = record.submission
+        prov = sub.provenance
+        dtype = (prov.dtype if prov else None) or "float32"
+        revision = prov.model_revision if prov else None
+        return _load_runner(
+            sub.identifier.model_name, device, dtype, revision, attn_implementation(sub.identifier)
+        )
+
+    wrote = backfill(load_archive(wiki_dir), load, out, limit=limit, echo=click.echo)
+    if out.exists():
+        sort_rows(out)
+    click.echo(f"Wired {wrote} experiments → {out}")

openinterp/codeid.py

@@ -0,0 +1,73 @@
+"""A document's programming language, for corpora whose dataset doesn't say it.
+
+Used by ``open-interpretability corpus --detect-code``. The detector is Google's Magika, a file-type
+model that reads content only (a corpus has no file names). We compared it with go-enry
+(GitHub Linguist), a CodeBERTa language classifier and Pygments
+(``docs/analyses/code-detection.md``). The tests were labelled GitHub files, prose, prose
+followed by code, and the registry's pile-10k corpus. Magika was the most accurate, and
+it alone never labelled prose as code.
+
+A document gets a label only when Magika's confidence reaches ``MIN_CONFIDENCE`` and its
+label is a language of the github-code preset (``corpus_presets.GITHUB_CODE_LANGUAGES``).
+So prose, data files (JSON, CSV, XML) and file types outside that list stay unlabelled. The label
+is that preset's name for the language, so exact and detected labels agree. Detection is
+per document, never per window: at 200 characters Magika is right on 70% of files, and
+on whole files on 91.5%.
+
+Magika's model ships inside its package, so :func:`detector` records the package version
+and the model name.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from functools import cache
+from importlib.metadata import version
+
+# Below this the document is left unlabelled. On 1,000 labelled github-code files it keeps
+# 89% at 95.5% accuracy (0.5 keeps 98% at 92.7%). No line labelled any of 300 prose documents.
+MIN_CONFIDENCE = 0.8
+
+# Magika's labels of the github-code languages, and those languages' names there
+# (tests/test_codeid.py checks that every name in GITHUB_CODE_LANGUAGES has one label).
+MAGIKA_LABELS = {
+    "asm": "Assembly", "batch": "Batchfile", "c": "C", "cs": "C#", "cpp": "C++",
+    "cmake": "CMake", "css": "CSS", "dockerfile": "Dockerfile", "fortran": "FORTRAN",
+    "go": "GO", "html": "HTML", "haskell": "Haskell", "java": "Java",
+    "javascript": "JavaScript", "julia": "Julia", "lua": "Lua", "makefile": "Makefile",
+    "markdown": "Markdown", "php": "PHP", "perl": "Perl", "powershell": "PowerShell",
+    "python": "Python", "ruby": "Ruby", "rust": "Rust", "sql": "SQL", "scala": "Scala",
+    "shell": "Shell", "latex": "TeX", "typescript": "TypeScript", "vba": "Visual Basic",
+}  # fmt: skip
+
+
+@cache
+def _magika():
+    from magika import Magika
+
+    return Magika()
+
+
+@cache
+def detector() -> str:
+    """The detector and its settings, as a corpus's source sidecar records them."""
+    model = _magika().get_model_name()
+    return f"magika {version('magika')} (model {model}), confidence >= {MIN_CONFIDENCE}"
+
+
+def predict(text: str) -> tuple[str | None, float]:
+    """Return the github-code language that Magika gives ``text``, and its confidence.
+
+    The language is ``None`` when Magika's label is not one of those languages.
+    """
+    prediction = _magika().identify_bytes(text.encode("utf-8", "surrogatepass")).prediction
+    return MAGIKA_LABELS.get(prediction.dl.label), float(prediction.score)
+
+
+def detect(texts: Sequence[str]) -> list[str | None]:
+    """Each document's programming language, or ``None`` (see the module docstring)."""
+    out: list[str | None] = []
+    for text in texts:
+        language, p = predict(text)
+        out.append(language if p >= MIN_CONFIDENCE else None)
+    return out