open-interpretability 0.0.20__py3-none-any.whl

openinterp/cli_evidence.py

@@ -0,0 +1,495 @@
+"""``open-interpretability audit`` and its helpers: scan caching and prompt/answer files.
+
+Corpus loading and the scan itself are in :mod:`openinterp.evidence`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from openinterp.audit_options import (  # noqa: F401  (re-exported)
+    open_scan_cache,
+    read_superposition,
+    resolve_unit,
+    scan_cache_option,
+    selection_option,
+)
+from openinterp.cli import (
+    cli,
+    contributor_option,
+    recorded_model_option,
+    wiki_dir_option,
+    with_model_options,
+)
+from openinterp.corpus import DEFAULT_SAMPLE_SEED, DEFAULT_SAMPLE_TOKENS
+from openinterp.evidence import (  # noqa: F401  (re-exported)
+    ScanRequest,
+    Unauditable,
+    read_corpus,
+    scan_evidence,
+    sha256,
+)
+
+REGISTRY_CORPUS = Path("corpus.jsonl")
+
+
+def load_superseded(path: Path):
+    """The archived, reviewed record that ``audit --supersedes`` names."""
+    from openinterp.core.schemas import AuditRecord
+
+    try:
+        record = AuditRecord.model_validate_json(path.read_text())
+    except ValueError as exc:
+        raise click.BadParameter(f"not an audit record: {exc}", param_hint="--supersedes") from exc
+    if record.verdict is None:
+        raise click.BadParameter("that record has no verdict yet", param_hint="--supersedes")
+    return record
+
+
+def answer_path(prompt_path: Path, suffix: str) -> Path:
+    """``review.prompt.md`` or ``review.md`` -> ``review<suffix>``."""
+    name = prompt_path.name.removesuffix(".md").removesuffix(".prompt")
+    return prompt_path.with_name(name + suffix)
+
+
+def with_costs(provenance, *parts):
+    """``provenance`` with ``parts`` merged into its costs; unchanged if it is ``None``."""
+    from openinterp.core.costs import merge
+
+    if provenance is None:
+        return None
+    return provenance.model_copy(update={"costs": merge(provenance.costs, *parts)})
+
+
+def record_draw(exc: Unauditable, random_pick: bool, wiki_dir: Path) -> None:
+    """Keep a unit the scan stopped on, so that the registry shows the attempt.
+
+    Random-selection statistics count a random draw. A chosen unit gets a stop record and a
+    page instead, which those statistics do not read.
+    """
+    from openinterp.builder.wiki import write_stop_page
+    from openinterp.cli import _skip_wiki
+    from openinterp.core.draws import write_draw
+
+    if exc.draw is None or _skip_wiki(wiki_dir):
+        return
+    outcome = exc.draw.outcome.replace("_", "-")
+    if random_pick:
+        click.echo(f"Recorded the {outcome} draw: {write_draw(exc.draw, wiki_dir)}", err=True)
+    else:
+        click.echo(f"Recorded the {outcome} stop: {write_stop_page(exc.draw, wiki_dir)}", err=True)
+
+
+def proposer_context(evidence, wiki_dir: Path, sisters: bool, sister_file=None, superseded=None):
+    """Return what other research links to the unit, for the proposer.
+
+    That is the unit's studied sisters, and the record a revision supersedes. In a sister
+    study (``sister_file``), it is only the study's brief, because the explanation is fixed.
+    """
+    from openinterp.cli_review import sisters_text
+    from openinterp.revision import previous_attempt
+    from openinterp.sisters import sister_brief
+
+    if sister_file:
+        return sister_brief(load_sister(sister_file, evidence.identifier))
+    related = sisters_text(evidence.identifier, wiki_dir, "proposer") if sisters else ""
+    return related + (previous_attempt(superseded) if superseded else "")
+
+
+def load_sister(path: Path, unit):
+    """The record ``audit --sister-of`` names, checked against the audited ``unit``."""
+    from openinterp.sisters import load_sister_source
+
+    try:
+        return load_sister_source(path, unit)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--sister-of") from exc
+
+
+def write_evidence(evidence, path: Path, full_snippets: bool = False, related: str = "") -> None:
+    """Write ``evidence`` to ``path`` with this run's costs, and the proposer prompt beside it."""
+    from openinterp.agents.proposer import HypothesisDraft, ProposerAgent
+    from openinterp.core import costs
+
+    evidence = evidence.model_copy(
+        update={"provenance": with_costs(evidence.provenance, costs.measured())}
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(evidence.model_dump_json(indent=2))
+    prompt_path = path.with_suffix(".prompt.md")
+    answer_path = path.with_suffix(".hypothesis.json")
+    task = ProposerAgent.proposal_prompt(
+        evidence.identifier,
+        evidence.top_examples,
+        evidence.vocabulary_lens,
+        evidence.confounds,
+        evidence.correlated_neurons,
+        evidence.head_profile,
+        evidence.input_attribution,
+        evidence.dictionary_profile,
+        bool(evidence.first_token_floor),
+        full_snippets,
+        related,
+        superposition_profile=evidence.superposition_profile,
+        manifold=evidence.manifold,
+    )
+    prompt_path.write_text(ProposerAgent.render_prompt(HypothesisDraft, task, answer_path))
+    click.echo(f"Unit: {evidence.identifier}")
+    click.echo(f"Wrote {path}")
+    click.echo(f"Proposer prompt: {prompt_path} (answer in {answer_path})")
+
+
+@cli.command()
+@click.option(
+    "--model",
+    "model_name",
+    help="Hugging Face repo, e.g. Qwen/Qwen2.5-0.5B. Required unless --evidence.",
+)
+@click.option("--layer", type=int, help="Required unless --random.")
+@click.option("--neuron", type=int, help="Required unless --random or --head.")
+@click.option("--pole", type=click.Choice(["positive", "negative"]), help="Default: positive.")
+@click.option(
+    "--head",
+    type=int,
+    help="Audit this attention head of --layer instead of a neuron (implies --unit head).",
+)
+@click.option(
+    "--feature",
+    type=int,
+    help="Audit this latent of --dictionary on --layer instead of a neuron (implies --unit "
+    "feature).",
+)
+@click.option(
+    "--dictionary",
+    help="Sparse dictionary (transcoder or SAE) whose latent to audit, e.g. "
+    "gpt2-small-transcoders or gemma-scope-2b-mlp-saes; it implies --model. See "
+    "openinterp/harness/dictionaries.py.",
+)
+@click.option(
+    "--superposition",
+    "superposition_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Audit the superposition that this JSON file defines: {model, layer, members: "
+    "[{neuron_idx, weight}], method, source}. It implies --model and --layer.",
+)
+@click.option(
+    "--unit",
+    type=click.Choice(["neuron", "head", "feature"]),
+    help="What --random samples: an MLP neuron pole (default), an attention head, or a "
+    "latent of --dictionary (the learned-basis baseline).",
+)
+@click.option(
+    "--random",
+    "random_pick",
+    is_flag=True,
+    help="Sample unspecified layer/neuron/pole (or head) uniformly: the unbiased selection.",
+)
+@click.option("--seed", type=int, help="Seed for --random (recorded in provenance).")
+@click.option(
+    "--corpus",
+    type=click.Path(exists=True, path_type=Path),
+    help="Text file (one snippet per line) or .jsonl with a 'text' field. "
+    "Default: ./corpus.jsonl, the registry's scan corpus (see the README).",
+)
+@click.option(
+    "--max-tokens",
+    default=DEFAULT_SAMPLE_TOKENS,
+    show_default=True,
+    type=click.IntRange(0),
+    help="Scan a seeded sample of whole documents with at most this many tokens, so the "
+    "scan's cost and scale don't grow with the corpus (recorded in provenance). "
+    "0 scans every document.",
+)
+@click.option(
+    "--sample-seed",
+    default=DEFAULT_SAMPLE_SEED,
+    show_default=True,
+    type=int,
+    help="Seed for the --max-tokens sample. Keep the default so audits of one corpus read "
+    "the same documents.",
+)
+@click.option("--top-k", default=20, show_default=True, help="Examples shown to the proposer.")
+@click.option(
+    "--full-snippets",
+    is_flag=True,
+    help="Show the proposer whole scanned documents, without windowing or dropping "
+    "near-duplicates: the prompt before trimming, for A/B comparison.",
+)
+@click.option(
+    "--window-tokens",
+    type=click.IntRange(2),
+    help="Scan each document as overlapping windows of this many tokens (≥ 512 recommended) "
+    "instead of whole. Top examples are then windows. Default: whole documents.",
+)
+@click.option(
+    "--stride",
+    type=click.IntRange(1),
+    help="Tokens between window starts (default: half of --window-tokens). Each token counts "
+    "once, with at least --window-tokens minus --stride tokens of context.",
+)
+@scan_cache_option
+@click.option(
+    "--agent-model",
+    default=None,
+    callback=recorded_model_option,
+    help="Proposer. LiteLLM model string, or external/<name> to answer a prompt file. "
+    "With --hypothesis, the name recorded for whoever wrote it (e.g. external/claude-opus-5-5).",
+)
+@contributor_option("proposer")
+@click.option(
+    "--evidence-out",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Scan only: write the evidence to this JSON file and the proposer's prompt next to "
+    "it (<name>.prompt.md), then exit. Answer the prompt, then run with --evidence.",
+)
+@click.option(
+    "--evidence",
+    "evidence_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Evidence from --evidence-out; skips the scan. Requires --hypothesis.",
+)
+@click.option(
+    "--hypothesis",
+    "hypothesis_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="HypothesisDraft JSON answering the --evidence-out prompt. No LLM is called.",
+)
+@click.option(
+    "--sister-of",
+    "sister_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="A sister-neuron study: the archived VERIFIED record of a pole in another model "
+    "whose explanation this pole is tested on, unchanged. Give it to both steps.",
+)
+@click.option(
+    "--sisters/--no-sisters",
+    default=True,
+    show_default=True,
+    help="Show the proposer the pole's sister neurons in other models that this registry "
+    "has studied (`open-interpretability sisters`), with their explanations.",
+)
+@click.option(
+    "--supersedes",
+    "superseded_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Archived record (wiki/experiments/<slug>/<id>.json) this submission revises, e.g. a "
+    "NEEDS_REVISION one. Recorded in the submission; it must be on the same unit.",
+)
+@click.option(
+    "--out", type=click.Path(path_type=Path), help="Output JSON (default: submissions/<slug>.json)"
+)
+@wiki_dir_option(
+    "Registry root. A --random draw the scan stops on (dead or default-on) is recorded "
+    "in draws/<slug>/, as an outcome of random selection. A chosen unit is recorded in "
+    "stops/<slug>/. Pass --wiki-dir '' to skip.",
+)
+@selection_option
+@with_model_options
+def audit(  # long-function: a click command; ScanRequest takes one line per option
+    model_name,
+    layer,
+    neuron,
+    pole,
+    head,
+    feature,
+    dictionary,
+    superposition_file,
+    unit,
+    random_pick,
+    seed,
+    corpus,
+    max_tokens,
+    sample_seed,
+    top_k,
+    full_snippets,
+    window_tokens,
+    stride,
+    use_scan_cache,
+    selection,
+    agent_model,
+    contributor,
+    evidence_out,
+    evidence_file,
+    hypothesis_file,
+    sister_file,
+    sisters,
+    superseded_file,
+    out,
+    wiki_dir,
+    device,
+    dtype,
+):
+    """Scan a unit, get a hypothesis, and write a submission.
+
+    The unit is a neuron pole, an attention head, a dictionary feature or a superposition.
+
+    \b
+    In one step, the proposer is an LLM (or external/<name>, answered through exchange/).
+    In two steps, any agent can propose without an API key or a waiting process:
+        open-interpretability audit --model M --random --evidence-out ev.json
+        (answer ev.prompt.md by writing ev.hypothesis.json)
+        open-interpretability audit --evidence ev.json --hypothesis ev.hypothesis.json \\
+          --agent-model external/<model that wrote it>
+    """
+    unit = resolve_unit(unit, neuron, pole, head, feature, dictionary)
+    superposition = None
+    if superposition_file is not None:
+        unit, model_name, layer, superposition = read_superposition(superposition_file, unit)
+    if unit == "feature" and evidence_file is None:
+        model_name = check_dictionary(dictionary, model_name, window_tokens)
+    check_steps(evidence_file, hypothesis_file, evidence_out, superseded_file, agent_model)
+    check_scan(evidence_file, model_name, stride, window_tokens)
+    superseded = superseded_file and load_superseded(superseded_file)
+    if evidence_file is not None:
+        evidence, draft, runner, agent = load_answer(
+            evidence_file, hypothesis_file, agent_model, device, dtype
+        )
+    else:
+        request = ScanRequest(
+            model_name=model_name,
+            unit=unit,
+            layer=layer,
+            neuron=neuron,
+            pole=pole,
+            head=head,
+            feature=feature,
+            dictionary=dictionary,
+            superposition=superposition,
+            random_pick=random_pick,
+            seed=seed,
+            corpus=scan_corpus(corpus),
+            top_k=top_k,
+            dtype=dtype,
+            window_tokens=window_tokens,
+            stride=stride,
+            max_tokens=max_tokens,
+            sample_seed=sample_seed,
+            selection=selection,
+        )
+        runner, evidence = scan_or_record(request, use_scan_cache, wiki_dir, device)
+        related = proposer_context(evidence, wiki_dir, sisters, sister_file, superseded)
+        if evidence_out is not None:
+            write_evidence(evidence, evidence_out, full_snippets, related)
+            return
+        agent, draft = ask_proposer(agent_model, evidence, full_snippets, related)
+    from openinterp.cli_submission import write_submission
+
+    write_submission(agent, draft, runner, evidence, superseded, out, contributor, sister_file)
+
+
+def check_dictionary(dictionary, model_name, window_tokens) -> str:
+    """The model ``--dictionary`` is for, after checking it fits the scan's windows."""
+    from openinterp.harness.dictionaries import dictionary_spec
+
+    if dictionary is None:
+        raise click.UsageError("--unit feature needs --dictionary.")
+    try:
+        spec = dictionary_spec(dictionary)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--dictionary") from exc
+    if model_name not in (None, spec.model_name):
+        raise click.UsageError(f"{dictionary} is a dictionary for {spec.model_name}.")
+    limit = spec.context_tokens
+    if limit and (window_tokens is None or window_tokens > limit):
+        raise click.UsageError(
+            f"{dictionary} only fits contexts of up to {limit} tokens; "
+            f"scan with --window-tokens {limit}."
+        )
+    return spec.model_name
+
+
+def check_steps(evidence_file, hypothesis_file, evidence_out, superseded_file, agent_model):
+    """Options that go together, or apart, across the one- and two-step audits."""
+    if (evidence_file is None) != (hypothesis_file is None):
+        raise click.UsageError("--evidence and --hypothesis go together.")
+    if superseded_file is not None and evidence_out is not None:
+        raise click.UsageError(
+            "--supersedes goes on the step that writes the submission (with --hypothesis)."
+        )
+    if evidence_file is not None and evidence_out is not None:
+        raise click.UsageError("--evidence-out scans; --evidence reuses a scan. Pick one.")
+    if evidence_file is not None and not agent_model:
+        raise click.UsageError(
+            "--agent-model is required with --hypothesis: name the model that wrote it."
+        )
+
+
+def check_scan(evidence_file, model_name, stride, window_tokens) -> None:
+    """Reject scan options that do not go together, before any model loads."""
+    if stride is not None and (window_tokens is None or stride > window_tokens):
+        raise click.UsageError("--stride needs --window-tokens, and can't exceed it.")
+    if evidence_file is None and model_name is None:
+        raise click.UsageError("--model is required unless --evidence is given.")
+
+
+def scan_corpus(corpus: Path | None) -> Path:
+    """Return the corpus to scan: ``--corpus``, else the registry's ``corpus.jsonl``.
+
+    Never the built-in sample, whose ~552 tokens make a scan that says little.
+    """
+    if corpus is not None:
+        return corpus
+    if REGISTRY_CORPUS.exists():
+        click.echo(f"Scanning {REGISTRY_CORPUS} (no --corpus given).", err=True)
+        return REGISTRY_CORPUS
+    raise click.UsageError(
+        f"No --corpus given and no {REGISTRY_CORPUS} here. Build the registry's scan corpus "
+        "with `open-interpretability corpus` (see the README), copy it in, or pass --corpus."
+    )
+
+
+def load_answer(evidence_file, hypothesis_file, agent_model, device, dtype):
+    """Step two: the evidence, the external proposer's draft, the model and the agent."""
+    from openinterp.agents.proposer import HypothesisDraft, ProposerAgent
+    from openinterp.cli import _load_runner  # looked up per call, so tests can swap it
+    from openinterp.core import costs
+    from openinterp.core.schemas import ScanEvidence
+    from openinterp.harness.units import attn_implementation
+
+    evidence = ScanEvidence.model_validate_json(evidence_file.read_text())
+    draft = HypothesisDraft.model_validate_json(hypothesis_file.read_text())
+    prompt_file = evidence_file.with_suffix(".prompt.md")
+    costs.add_external("proposer", agent_model, prompt_file, hypothesis_file)
+    attn = attn_implementation(evidence.identifier)
+    runner = _load_runner(evidence.identifier.model_name, device, dtype, None, attn)
+    return evidence, draft, runner, ProposerAgent(agent_model)
+
+
+def scan_or_record(request, use_scan_cache: bool, wiki_dir: Path, device):
+    """Load the model and scan; keep a unit the scan stops on (see record_draw)."""
+    from openinterp.cli import _load_runner  # looked up per call, so tests can swap it
+
+    attn = "eager" if request.unit == "head" else None  # heads need attention patterns
+    runner = _load_runner(request.model_name, device, request.dtype, None, attn)
+    try:
+        return runner, scan_evidence(runner, request, open_scan_cache(use_scan_cache))
+    except Unauditable as exc:
+        record_draw(exc, request.random_pick, wiki_dir)
+        raise
+
+
+def ask_proposer(agent_model, evidence, full_snippets: bool, related: str = ""):
+    """Ask the LLM proposer for a hypothesis about ``evidence``'s unit."""
+    from openinterp.agents.base import DEFAULT_MODEL
+    from openinterp.agents.proposer import ProposerAgent
+
+    agent = ProposerAgent(agent_model or DEFAULT_MODEL)
+    click.echo(f"Asking {agent.model} for a hypothesis…", err=True)
+    draft = agent.propose(
+        evidence.identifier,
+        evidence.top_examples,
+        evidence.vocabulary_lens,
+        evidence.confounds,
+        evidence.correlated_neurons,
+        evidence.head_profile,
+        evidence.input_attribution,
+        evidence.dictionary_profile,
+        bool(evidence.first_token_floor),
+        full_snippets,
+        related,
+        superposition_profile=evidence.superposition_profile,
+        manifold=evidence.manifold,
+    )
+    return agent, draft

openinterp/cli_evidence_store.py

@@ -0,0 +1,93 @@
+"""``open-interpretability evidence``: move slim records' blobs to the dataset (issue #3254).
+
+``push`` runs where the experiment ran. It pushes the blobs of the records that the branch
+adds to ``evidence/<branch>``. CI runs ``upload`` (with ``HF_EVIDENCE_TOKEN``) or ``load``
+(without it), then ``verify``. :mod:`openinterp.evidence_branch` explains why the blobs
+ride on their own branch.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import click
+
+from openinterp.cli import cli, wiki_dir_option
+
+base_ref_option = click.option(
+    "--base-ref", default="origin/main", show_default=True, help="The branch the PR merges into."
+)
+ref_option = click.option(
+    "--ref", required=True, help="The evidence branch, for example FETCH_HEAD after a fetch."
+)
+
+
+def _added(wiki_dir: Path, base_ref: str) -> list[Path]:
+    from openinterp.checks import changed_records
+
+    return changed_records(wiki_dir, base_ref)
+
+
+@cli.group()
+def evidence() -> None:
+    """Carry slim records' evidence blobs to the public dataset (docs/analyses/repo-size.md)."""
+
+
+@evidence.command()
+@wiki_dir_option()
+@base_ref_option
+@click.option("--remote", default="origin", show_default=True)
+def push(wiki_dir: Path, base_ref: str, remote: str) -> None:
+    """Push the blobs of the records this branch adds to evidence/<branch>."""
+    from openinterp.evidence_branch import push as push_blobs
+    from openinterp.evidence_branch import record_refs
+
+    shas = record_refs(_added(wiki_dir, base_ref))
+    if not shas:
+        click.echo("No slim record on this branch: nothing to push.")
+        return
+    branch = subprocess.run(
+        ["git", "branch", "--show-current"], capture_output=True, text=True, check=True
+    ).stdout.strip()
+    target = push_blobs(branch, shas, remote)
+    click.echo(f"Pushed {len(shas)} evidence blobs to {remote}/{target}.")
+
+
+@evidence.command()
+@ref_option
+def load(ref: str) -> None:
+    """Copy an evidence branch's blobs into the local store, checking each hash."""
+    from openinterp.evidence_branch import load_branch
+
+    click.echo(f"Loaded {len(load_branch(ref))} evidence blobs from {ref}.")
+
+
+@evidence.command()
+@ref_option
+def upload(ref: str) -> None:
+    """Load an evidence branch's blobs, then upload them to the dataset (needs a write token)."""
+    from openinterp.core.evidence import EVIDENCE_REPO
+    from openinterp.evidence_branch import load_branch
+    from openinterp.evidence_branch import upload as upload_blobs
+
+    shas = load_branch(ref)
+    click.echo(f"Uploaded {upload_blobs(shas)} evidence blobs to {EVIDENCE_REPO}.")
+
+
+@evidence.command()
+@wiki_dir_option()
+@base_ref_option
+def verify(wiki_dir: Path, base_ref: str) -> None:
+    """Fail unless each record this branch adds has its evidence, with the right hashes."""
+    from openinterp.evidence_branch import unresolved
+
+    problems = unresolved(_added(wiki_dir, base_ref))
+    for problem in problems:
+        click.echo(problem, err=True)
+    if problems:
+        raise click.ClickException(
+            f"{len(problems)} records lack their evidence. Run `open-interpretability evidence "
+            "push` on the branch, then run the checks again."
+        )
+    click.echo("Every added record has its evidence.")

openinterp/cli_explain.py

@@ -0,0 +1,101 @@
+"""Attribute one answer of a model to its labelled neuron poles.
+
+The command is ``open-interpretability explain``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import click
+
+from openinterp.cli import _load_runner, cli, wiki_dir_option, with_model_options
+
+
+@cli.command(name="explain")
+@click.argument("prompt")
+@click.option("--model", "model_name", default="Qwen/Qwen2.5-0.5B", show_default=True)
+@click.option("--token", help="The answer token to explain. Default: the model's top token.")
+@click.option("--position", default=-1, show_default=True, help="The position to explain.")
+@click.option("--top", default=20, show_default=True, help="Poles to list.")
+@click.option(
+    "--corpus", default="corpus.jsonl", show_default=True, type=click.Path(path_type=Path)
+)
+@click.option(
+    "--mean-tokens",
+    default=20_000,
+    show_default=True,
+    help="Tokens of the corpus for each neuron's mean, the attribution's baseline (cached).",
+)
+@click.option("--json", "as_json", is_flag=True, help="Print the result as JSON.")
+@wiki_dir_option()
+@with_model_options
+def explain_command(
+    prompt, model_name, token, position, top, corpus, mean_tokens, as_json, wiki_dir, device, dtype
+):
+    """Explain the model's answer to PROMPT as fully as the registry allows.
+
+    It attributes the answer's logit to every MLP neuron pole, against each neuron's mean
+    on the corpus. It labels the top poles from the registry. It reports the share of
+    the attribution that VERIFIED poles hold, and checks it by mean-ablating them.
+    """
+    from openinterp.evidence import read_corpus
+    from openinterp.explain import explain, neuron_means, registry_labels
+
+    runner = _load_runner(model_name, device, dtype)
+    means = neuron_means(runner, model_name, read_corpus(corpus)[0], mean_tokens)
+    labels = registry_labels(Path(wiki_dir), model_name)
+    target = None
+    if token is not None:
+        ids = runner.tokenizer.encode(token, add_special_tokens=False)
+        if len(ids) != 1:
+            raise click.BadParameter(
+                f"{token!r} is {len(ids)} tokens, not one", param_hint="--token"
+            )
+        target = ids[0]
+    result = explain(
+        runner, model_name, prompt, means, labels, token=target, position=position, top=top
+    )
+    if as_json:
+        click.echo(json.dumps(asdict(result) | {"verified_share": result.verified_share}, indent=1))
+        return
+    _print(result)
+
+
+def _print(result) -> None:
+    click.echo(f"Answer at position {result.position}: {result.token!r} (logit {result.logit:.2f})")
+    click.echo(
+        f"{'pole':<14} {'attribution':>11} {'share':>6} {'ablated Δ':>9} {'peak/max':>9}  status"
+    )
+    for p in result.poles:
+        share = abs(p.attribution) / result.total if result.total else 0.0
+        ablated = f"{p.ablation_change:+.2f}" if p.ablation_change is not None else ""
+        peak = f"{p.strength / p.max_activation:.2f}" if p.max_activation else "—"
+        row = f"{p.label:<14} {p.attribution:>+11.3f} {share:>6.1%} {ablated:>9} {peak:>9}"
+        click.echo(f"{row}  {p.status}")
+        if p.explanation:
+            click.echo(f"{'':<14} {p.explanation[:110]}")
+    click.echo(
+        f"VERIFIED poles hold {result.verified_share:.1%} of the total |attribution|; "
+        f"{1 - result.verified_share:.1%} is unexplained."
+    )
+    joint = result.joint
+    if joint.get("poles"):
+        changed = (
+            f"the top token changes to {joint['new_top_token']!r}"
+            if joint["top_token_changed"]
+            else "the top token stays"
+        )
+        click.echo(
+            f"Mean-ablating the {joint['poles']} VERIFIED poles above together moves the answer's "
+            f"logit by {joint['logit_change']:+.2f}, and {changed}."
+        )
+    else:
+        click.echo("No pole above is VERIFIED, so nothing here is explained yet.")
+    click.echo(
+        "Attribution is first order and against each neuron's mean. The ablated Δ column is "
+        "the exact check: mean-ablating a pole moves the logit by about minus its attribution. "
+        "Unverified poles carry no label."
+    )