open-interpretability 0.0.20__py3-none-any.whl

openinterp/score_controls.py

@@ -0,0 +1,169 @@
+"""Control explanations for ``open-interpretability score --controls``.
+
+A detection or fuzzing score can be high for reasons that have nothing to do with the
+explanation. The held-out windows can have structure that a judge picks up without it,
+for example when active windows are longer or have more code. "Scoring Explanations
+Without Reading Them" (arXiv 2610.37676) reports such shortcuts. So the same windows
+are judged twice more:
+
+- ``empty``: with no explanation.
+- ``other_unit``: with the explanation of another unit of the same model, drawn with the
+  task's seed. A VERIFIED explanation is drawn when one exists, so the control is a real,
+  specific claim about a different unit.
+
+The gap between the real score and each control is the part of the score that the
+explanation earns. The controls are reported, not gated (docs/PROTOCOL.md §4).
+"""
+
+from __future__ import annotations
+
+import json
+import random
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from openinterp.core.explanation import ControlScore, ExplanationScores
+from openinterp.core.paths import DEFAULT_WIKI_DIR, experiments_dir
+
+KINDS = ("detection", "fuzzing")
+
+
+class ControlTask(BaseModel):
+    """One control explanation, as ``open-interpretability score --emit-task`` writes it."""
+
+    kind: str
+    explanation: str
+    source_slug: str | None = None
+
+
+def other_unit_explanation(slug: str, seed: int, wiki_dir: Path = DEFAULT_WIKI_DIR):
+    """Draw another unit's explanation from the same model: ``(slug, explanation)``.
+
+    Draws among VERIFIED explanations when the model has any, else among all of them.
+    Returns ``None`` when no other unit of the model has a record.
+    """
+    model_dir = experiments_dir(Path(wiki_dir)) / slug.split("/", 1)[0]
+    latest: dict[str, tuple[str, bool]] = {}
+    for path in sorted(model_dir.rglob("*.json")):  # sorted by time within a unit
+        unit = path.parent.relative_to(experiments_dir(Path(wiki_dir))).as_posix()
+        if unit == slug:
+            continue
+        record = json.loads(path.read_text())
+        verdict = record.get("verdict") or {}
+        explanation = record["submission"]["natural_language_explanation"]
+        latest[unit] = (explanation, verdict.get("status") == "VERIFIED")
+    pool = sorted(u for u, (_, ok) in latest.items() if ok) or sorted(latest)
+    if not pool:
+        return None
+    # The slug joins the seed, so units scored with one seed don't all draw the same decoy.
+    unit = random.Random(f"{seed}:{slug}").choice(pool)
+    return unit, latest[unit][0]
+
+
+def control_tasks(slug: str, seed: int, wiki_dir: Path = DEFAULT_WIKI_DIR) -> list[ControlTask]:
+    """The controls for one unit: always ``empty``, and ``other_unit`` when one exists."""
+    controls = [ControlTask(kind="empty", explanation="")]
+    other = other_unit_explanation(slug, seed, wiki_dir)
+    if other is not None:
+        controls.append(ControlTask(kind="other_unit", explanation=other[1], source_slug=other[0]))
+    return controls
+
+
+def prompt_path(task_path: Path, control: ControlTask, kind: str) -> Path:
+    """Where ``--emit-task`` writes a control's judge prompt, next to the task."""
+    return task_path.with_name(
+        task_path.name.split(".")[0] + f".control-{control.kind}.{kind}.prompt.md"
+    )
+
+
+def answer_path(task_path: Path, control: ControlTask, kind: str) -> Path:
+    """Where the judge writes its answer to a control's prompt."""
+    return task_path.with_name(
+        task_path.name.split(".")[0] + f".control-{control.kind}.{kind}.json"
+    )
+
+
+def unscored(control: ControlTask, detection: list[bool], fuzzing: list[bool]) -> ControlScore:
+    """A control with the judge's answers. ``finalize_scores`` adds its scores."""
+    return ControlScore(
+        kind=control.kind,
+        explanation=control.explanation,
+        source_slug=control.source_slug,
+        detection_judged=detection,
+        fuzzing_judged=fuzzing,
+    )
+
+
+def gap_summary(scores: ExplanationScores) -> str:
+    """One line per control: the real score minus the control's, for each kind."""
+    lines = []
+    for c in scores.controls:
+        parts = []
+        for kind in KINDS:
+            real, ctrl = getattr(scores, kind), getattr(c, kind)
+            if real is not None and ctrl is not None:
+                gap = real.balanced_accuracy - ctrl.balanced_accuracy
+                parts.append(f"{kind} {ctrl.balanced_accuracy:.2f} (gap {gap:+.2f})")
+        source = f" from {c.source_slug}" if c.source_slug else ""
+        lines.append(f"Control {c.kind}{source}: " + (", ".join(parts) or "not judged"))
+    return "\n".join(lines)
+
+
+def write_prompts(task, task_path: Path, noun: str) -> None:
+    """Write a judge prompt for each control and kind, next to the task."""
+    from openinterp.agents.judge import DetectionAnswer, ExplanationJudge, FuzzingAnswer
+
+    models = {"detection": DetectionAnswer, "fuzzing": FuzzingAnswer}
+    builders = {
+        "detection": ExplanationJudge.detection_prompt,
+        "fuzzing": ExplanationJudge.fuzzing_prompt,
+    }
+    for control in task.controls:
+        for kind in KINDS:
+            windows = getattr(task, kind)
+            if not windows:
+                continue
+            text = builders[kind](control.explanation, windows, noun)
+            answer = answer_path(task_path, control, kind)
+            rendered = ExplanationJudge.render_prompt(models[kind], text, answer)
+            prompt_path(task_path, control, kind).write_text(rendered)
+
+
+def read_answers(task, task_path: Path) -> list[ControlScore]:
+    """Read the judge's answers to each control's prompts (step two of ``--emit-task``)."""
+    from openinterp.agents.judge import DetectionAnswer, FuzzingAnswer, answered
+
+    out = []
+    for control in task.controls:
+        judged = {}
+        for kind, model, field in (
+            ("detection", DetectionAnswer, "active"),
+            ("fuzzing", FuzzingAnswer, "correct"),
+        ):
+            windows = getattr(task, kind)
+            if not windows:
+                judged[kind] = []
+                continue
+            answer = model.model_validate_json(answer_path(task_path, control, kind).read_text())
+            judged[kind] = answered(getattr(answer, field), len(windows), f"{control.kind} {kind}")
+        out.append(unscored(control, judged["detection"], judged["fuzzing"]))
+    return out
+
+
+def judge_controls(judge, task, noun: str) -> list[ControlScore]:
+    """Ask an LLM judge each control's questions (the one-step ``open-interpretability score``)."""
+    from openinterp.agents.judge import answered
+
+    out = []
+    for control in task.controls:
+        det = judge.detect(control.explanation, task.detection, noun)
+        fuz = judge.fuzz(control.explanation, task.fuzzing, noun) if task.fuzzing else None
+        out.append(
+            unscored(
+                control,
+                answered(det.active, len(task.detection), "detection"),
+                answered(fuz.correct, len(task.fuzzing), "fuzzing") if fuz else [],
+            )
+        )
+    return out

openinterp/sensitive.py

@@ -0,0 +1,243 @@
+"""Find personal data and offensive words in text, for scan labels and the site.
+
+Experiments read this text unchanged. A scan labels what it finds
+(:class:`~openinterp.harness.annotations.MatchTagger`). So a record can say how much of a
+unit's activation personal data explains. Separately, the site build
+removes personal data and masks offensive examples in what it publishes
+(``openinterp/builder``).
+
+The search for personal data uses Microsoft Presidio's pattern recognisers, with rules of
+our own on top. They need no model and no network. It finds emails, phone numbers, payment
+cards, IBANs, US SSNs and ITINs, UK NHS numbers, crypto wallets and public IP addresses. It
+does NOT find names or postal addresses. Names and addresses are separate scan labels, which
+the site does not remove: :mod:`openinterp.names` and :func:`address_matches`.
+
+The search for offensive words is a short list (``openinterp/data/offensive_words.txt``),
+not a classifier. It must be fast for a site build, and needs no model. The list holds only
+words that are rarely innocent. It includes words for sexual violence, so news reports can
+match. A general profanity list flagged 12% of distinct examples, on words such as "god",
+"organ" and "stroke". This list flags 0.6%. The list is English only, and text can be
+hateful with none of these words. So a match says that a listed word is there, not that the
+text is toxic. No match does not mean that a text is safe.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import re
+from collections.abc import Iterator
+from functools import cache
+from importlib.metadata import version
+from importlib.resources import as_file, files
+from typing import Any
+
+_SUFFIX_LIST = "public_suffix_list.dat"  # publicsuffix.org, MPL 2.0
+
+# Presidio's score of a match with no context words. Below this are its weak patterns, such
+# as any nine digits for an SSN. In 1,000 sampled documents those matched only object IDs.
+MIN_SCORE = 0.4
+# Fewer digits match year ranges ("1800-1864") and plain numbers: of 30 matches in 1,000
+# sampled documents, about half. _context_phones finds shorter numbers.
+MIN_PHONE_DIGITS = 10
+# A local number has too few digits for that rule, and a region outside Presidio's has no
+# valid format. So a number of these lengths also counts when a phone word comes just before
+# it. Over 1,000 documents and 3,990 published examples, this matched 20 texts. All the
+# numbers looked real, but for one joke number.
+_CONTEXT_PHONE_DIGITS = range(7, 13)
+_PHONE_WORD_REACH = 40  # characters: "Media contact:\nA. Person, 8341 7141"
+_PHONE_WORD = re.compile(
+    r"\b(?:tel|t[ée]l[ée]phone|telefon|tel[ée]fono|phon(?:e|es|ed|ing)|ph|fax|mobile|mob|cell|call|contact"
+    r"|whatsapp)\b",
+    re.IGNORECASE,
+)
+_PHONE_DIGITS = re.compile(r"(?<![\d.,/:-])\+?\(?\d(?:[ ().-]{0,2}\d){6,11}(?![\d]|[.,/:-]\d)")
+# What such a number is not: a date range ("Call 1999-2000") or a decimal ("0.0612422").
+_NOT_A_PHONE = re.compile(r"(?:1[5-9]|20)\d\d\b|\d+\.\d+$")
+# Shapes that the phone recogniser accepts, but that are not phone numbers. Explanations hold
+# many of them. They are decimals ("0.1644-0.17004"), table rows and lists ("0.96/0.89").
+# They are also date ranges ("6/1999-2/2002"), DOIs ("1--2565"), dotted quads and counts.
+_NOT_A_PHONE_SHAPE = re.compile(
+    r"(?<![\d.])0\.\d|\s{2,}|/|--|(?<![\d.])\d{1,3}(?:\.\d{1,3}){3}(?![\d.])|(?:\b\d\s+){3}"
+)
+# RFC 2606 reserves these for examples, so an address here is nobody's. Reviewers' probes use them.
+_RESERVED_DOMAINS = {"example.com", "example.net", "example.org"}
+# A window of tokens can end inside an address, so its domain is cut or missing.
+_EMAIL_CUT = re.compile(r"(?<![\w.+%-])[\w.+%-]*\w[\w.+%-]*@[\w.-]*$")
+
+# US and UK formats only, on one line. A street's name words take no full stop, so a legal
+# citation fails ("27 Mass. App. Ct."). "St" and "Dr" before a capital are a title ("4 Did St
+# Joseph"), not a street. _COURT_NAME leaves out citations such as "2008 Supreme Court".
+_STREET_TYPE = (
+    r"(?:(?:St|Dr)\b(?![ \t]+[A-Z])|(?:Street|Avenue|Ave|Road|Rd|Boulevard|Blvd|Lane|Ln|Drive"
+    r"|Court|Ct|Way|Place|Pl|Square|Sq|Terrace|Terr|Parkway|Pkwy|Highway|Hwy|Circle|Cir"
+    r"|Crescent|Cres|Close|Gardens|Mews)\b)"
+)
+_US_STATE = (
+    r"(?:A[KLRZ]|C[AOT]|D[CE]|FL|GA|HI|I[ADLN]|K[SY]|LA|M[ADEINOST]|N[CDEHJMVY]|O[HKR]|PA|RI"
+    r"|S[CD]|T[NX]|UT|V[AT]|W[AIVY])"
+)
+_ADDRESS_PATTERNS = {
+    "street": re.compile(
+        r"(?<![\d.#,-])\b\d{1,5}[A-Za-z]?[ \t]+"
+        r"(?:(?:[NSEW]\.?|North|South|East|West)[ \t]+)?"
+        rf"(?:[A-Z][\w'’-]*[ \t]+){{1,4}}{_STREET_TYPE}\.?"
+    ),
+    "po_box": re.compile(r"\bP\.?[ \t]?O\.?[ \t]?Box[ \t]+\d+", re.IGNORECASE),
+    "us_city_zip": re.compile(rf"\b[A-Z][a-z]+,?[ \t]+{_US_STATE}[ \t]+\d{{5}}(?:-\d{{4}})?\b"),
+    "uk_postcode": re.compile(r"\b[A-Z]{1,2}\d[A-Z\d]?[ \t]\d[A-Z]{2}\b"),
+}
+_COURT_NAME = re.compile(r"\b(?:Supreme|Appeals?|Circuit|District|Superior|County)\b")
+
+# The label of each kind -> Presidio's entity. These match with no context words. Presidio's
+# others are left out. URLs, dates and UUIDs are not personal, and its medical licence
+# pattern matched a clinical trial ID.
+_PII_ENTITIES = {
+    "email": "EMAIL_ADDRESS",
+    "phone": "PHONE_NUMBER",
+    "payment_card": "CREDIT_CARD",
+    "iban": "IBAN_CODE",
+    "us_ssn": "US_SSN",
+    "us_itin": "US_ITIN",
+    "uk_nhs": "UK_NHS",
+    "crypto_wallet": "CRYPTO",
+    "ip_address": "IP_ADDRESS",
+}
+
+
+@cache
+def _domains():
+    """Read email domains against our copy of the Public Suffix List, never a live one.
+
+    The live list changes, and a scan must give the same labels again. To update the copy,
+    replace the file: :func:`detector` records its SHA-256, so records say which one they used.
+    """
+    import tldextract
+
+    with as_file(files("openinterp.data").joinpath(_SUFFIX_LIST)) as path:
+        url = path.resolve().as_uri()
+    # fallback_to_snapshot=False: fail, not silently read the list in the installed package.
+    return tldextract.TLDExtract(
+        suffix_list_urls=(url,), cache_dir=None, fallback_to_snapshot=False
+    )
+
+
+@cache
+def _recognisers() -> dict[str, Any]:
+    """Each kind's Presidio recogniser. Importing Presidio loads spaCy, so only on first use."""
+    from presidio_analyzer import predefined_recognizers as recognisers
+
+    class OfflineEmail(recognisers.EmailRecognizer):
+        def validate_result(self, pattern_text: str) -> bool:
+            domain = pattern_text.rpartition("@")[2].lower()
+            return domain not in _RESERVED_DOMAINS and _domains()(domain).suffix != ""
+
+    return {
+        "email": OfflineEmail(),
+        "phone": recognisers.PhoneRecognizer(),
+        "payment_card": recognisers.CreditCardRecognizer(),
+        "iban": recognisers.IbanRecognizer(),
+        "us_ssn": recognisers.UsSsnRecognizer(),
+        "us_itin": recognisers.UsItinRecognizer(),
+        "uk_nhs": recognisers.NhsRecognizer(),
+        "crypto_wallet": recognisers.CryptoRecognizer(),
+        "ip_address": recognisers.IpRecognizer(),
+    }
+
+
+def _is_public_ip(address: str) -> bool:
+    # "::a" is a valid address, but in text it is C++ or CSS: "std::a", ".x::after".
+    if ":" in address and sum(bool(group) for group in address.split(":")) < 3:
+        return False
+    try:
+        return ipaddress.ip_network(address, strict=False).is_global
+    except ValueError:  # the pattern also matches other dotted and colon-separated numbers
+        return False
+
+
+def _keeps(kind: str, match: str) -> bool:
+    """Our rules on top of Presidio's, from what it matched in the registry's documents."""
+    if kind == "phone":
+        enough_digits = sum(c.isdigit() for c in match) >= MIN_PHONE_DIGITS
+        return enough_digits and not _NOT_A_PHONE_SHAPE.search(match)
+    return kind != "ip_address" or _is_public_ip(match)
+
+
+def _context_phones(text: str) -> Iterator[tuple[int, int, str]]:
+    for match in _PHONE_DIGITS.finditer(text):
+        digits = sum(c.isdigit() for c in match.group())
+        if digits not in _CONTEXT_PHONE_DIGITS or _NOT_A_PHONE.match(match.group()):
+            continue
+        if _NOT_A_PHONE_SHAPE.search(match.group()):
+            continue
+        if _PHONE_WORD.search(text, max(0, match.start() - _PHONE_WORD_REACH), match.start()):
+            yield (*match.span(), "phone")
+
+
+def _cut_email(text: str) -> Iterator[tuple[int, int, str]]:
+    cut = _EMAIL_CUT.search(text)
+    if cut and cut.group().rpartition("@")[2].rstrip(".").lower() not in _RESERVED_DOMAINS:
+        yield (*cut.span(), "email")
+
+
+def may_match(text: str) -> bool:
+    """Return False for a text too short for any match: most record strings are single tokens."""
+    return "@" in text or text.count(":") >= 2 or sum(map(str.isdigit, text)) >= 4
+
+
+@cache
+def pii_matches(text: str) -> tuple[tuple[int, int, str], ...]:
+    """Return ``(start, end, kind)`` of each match in ``text``, sorted; matches can overlap.
+
+    Many pages show the same text, so the result is cached.
+    """
+    if not may_match(text):
+        return ()
+    found = {*_cut_email(text), *_context_phones(text)}
+    for kind, recogniser in _recognisers().items():
+        for match in recogniser.analyze(text, [_PII_ENTITIES[kind]], None):
+            if match.score >= MIN_SCORE and _keeps(kind, text[match.start : match.end]):
+                found.add((match.start, match.end, kind))
+    return tuple(sorted(found))  # a set, because the phone recogniser repeats a number per region
+
+
+def address_matches(text: str) -> tuple[tuple[int, int, str], ...]:
+    """Return ``(start, end, kind)`` of each postal address part in ``text``, sorted.
+
+    These are a scan label only. The site does not remove them. The patterns cannot tell a
+    home from a business, and most matches are organisations.
+    """
+    found = (
+        (*match.span(), kind)
+        for kind, pattern in _ADDRESS_PATTERNS.items()
+        for match in pattern.finditer(text)
+        if kind != "street" or not _COURT_NAME.search(match.group())
+    )
+    return tuple(sorted(found))
+
+
+def _data(name: str) -> str:
+    return files("openinterp.data").joinpath(name).read_text(encoding="utf-8")
+
+
+@cache
+def _offensive_pattern() -> re.Pattern[str]:
+    alternatives = "|".join(re.escape(word) for word in _data("offensive_words.txt").split())
+    return re.compile(rf"\b(?:{alternatives})\b", re.IGNORECASE)
+
+
+@cache
+def is_offensive(text: str) -> bool:
+    """Return whether ``text`` holds a listed word; many pages show the same example."""
+    return _offensive_pattern().search(text) is not None
+
+
+def detector() -> str:
+    """Name the package versions and the suffix list that fix what a search finds."""
+    names = ("presidio-analyzer", "phonenumbers", "tldextract")
+    packages = ", ".join(f"{p} {version(p)}" for p in names)
+    return f"openinterp.sensitive ({packages}; suffix list {_sha12(_data(_SUFFIX_LIST))})"
+
+
+def _sha12(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()[:12]

openinterp/show.py

@@ -0,0 +1,236 @@
+"""Compact summaries of records, submissions, scan evidence and a unit's history.
+
+``open-interpretability show`` prints these, so agents need not open a big file to learn a little.
+A record can be 300 KB, an ``ev.json`` 500 KB and an experiment page 25 KB. An agent
+often needs only a verdict, the failed gates and probes, or what a scan found. The files
+stay the source of truth, and this only reads them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from openinterp.core.schemas import (
+    ACTIVATION_THRESHOLD,
+    AuditRecord,
+    NeuronAuditSubmission,
+    ScanEvidence,
+)
+
+PROMPT_CHARS = 160  # probes and examples are cut to this unless full=True
+TOP_EXAMPLES = 5
+CONTEXT_TOKENS = 8  # tokens shown before an example's peak
+
+
+def show(path: Path, full: bool = False) -> str:
+    """Summarise ``path``: a record, submission or evidence JSON, or a unit's directory.
+
+    For a directory, it lists every experiment on the unit, oldest first, with each
+    page's Discussion.
+    """
+    if path.is_dir():
+        return show_unit(path, full)
+    text = path.read_text(encoding="utf-8")
+    data = json.loads(text)  # to tell the kinds apart; strict models validate the text
+    if "submission" in data:
+        return show_record(AuditRecord.model_validate_json(text), path, full)
+    if "natural_language_explanation" in data:
+        return show_submission(NeuronAuditSubmission.model_validate_json(text), full)
+    if "top_examples" in data:
+        return show_evidence(ScanEvidence.model_validate_json(text), full)
+    raise ValueError(f"{path} is not a record, submission or scan evidence")
+
+
+def show_unit(unit_dir: Path, full: bool = False) -> str:
+    """Every experiment on the unit in ``unit_dir``, oldest first, with each page's Discussion."""
+    records = sorted(
+        (
+            (AuditRecord.model_validate_json(p.read_text(encoding="utf-8")), p)
+            for p in unit_dir.glob("*.json")
+        ),
+        key=lambda rp: rp[0].verdict.timestamp if rp[0].verdict else 0,
+    )
+    if not records:
+        raise ValueError(f"no experiment records in {unit_dir}")
+    parts = [f"{len(records)} experiment(s) in {unit_dir}, oldest first"]
+    parts += [show_record(record, path, full) for record, path in records]
+    return "\n\n".join(parts)
+
+
+def show_record(record: AuditRecord, path: Path | None = None, full: bool = False) -> str:
+    """A record's verdict, failed gates and probes, scores and hypothesis."""
+    sub, verdict = record.submission, record.verdict
+    name = f"{sub.identifier.slug}" + (f" · {path.stem}" if path else "")
+    if verdict is None:
+        return f"{name} · not reviewed\n{show_submission(sub, full)}"
+    status = f"{verdict.status} {verdict.confidence_score:.2f}"
+    protocol = verdict.policy.protocol_version if verdict.policy else "< 0.2"
+    lines = [
+        f"== {name} · {status} (protocol {protocol})"
+        + (" · self-reviewed" if record.self_reviewed else "")
+    ]
+    lines.append(
+        f"Proposer {sub.submitting_agent_model} · reviewer {verdict.reviewer_agent_model}"
+        + _selection(sub)
+        + (f" · supersedes {sub.supersedes}" if sub.supersedes else "")
+    )
+    lines += _hypothesis(sub)
+    lines += _metrics(verdict)
+    lines += _failed_probes(record, full)
+    if verdict.notes:
+        lines.append(f"Notes: {_clip(verdict.notes, full, 400)}")
+    if path is not None and (discussion := _discussion(path.with_suffix(".md"))):
+        lines.append(f"Discussion: {_clip(discussion, full, 1200)}")
+    return "\n".join(lines)
+
+
+def _metrics(verdict) -> list[str]:
+    """Failed gates, the review's rates, and the scores recorded beside them."""
+    lines, m = [], verdict.metrics
+    if m is not None:
+        failed = [g for g, ok in m.gates.items() if not ok]
+        lines.append("Failed gates: " + (", ".join(failed) if failed else "none"))
+        rates = [
+            ("specificity", m.specificity),
+            ("sensitivity", m.sensitivity),
+            ("balanced accuracy", m.balanced_accuracy),
+            ("counterfactuals", m.counterfactual_reproduction),
+        ]
+        line = " · ".join(f"{k} {v:.2f}" for k, v in rates if v is not None)
+        if m.confound_baseline_accuracy is not None:
+            line += f" · best baseline ({m.confound_baseline}) {m.confound_baseline_accuracy:.2f}"
+        lines.append(line)
+    if (s := verdict.explanation_scores) is not None:
+        scores = [("detection", s.detection), ("fuzzing", s.fuzzing)]
+        lines.append(
+            "Explanation scores: "
+            + " · ".join(f"{k} {v.balanced_accuracy:.2f}" for k, v in scores if v is not None)
+        )
+    if (c := verdict.causal_metrics) is not None:
+        lines.append(
+            f"Causal: sufficiency {c.sufficiency_score:.2f} · necessity {c.necessity_score:.2f}"
+        )
+    return lines
+
+
+def show_submission(sub: NeuronAuditSubmission, full: bool = False) -> str:
+    """A submission's unit, proposer, selection and hypothesis."""
+    lines = [
+        f"== {sub.identifier.slug} · submission by {sub.submitting_agent_model}{_selection(sub)}"
+    ]
+    lines += _hypothesis(sub)
+    lines.append(f"Counterfactuals: {len(sub.counterfactuals)}")
+    return "\n".join(lines)
+
+
+def show_evidence(ev: ScanEvidence, full: bool = False) -> str:
+    """What a scan found: its corpus, peak and top examples."""
+    lines = [f"== {ev.identifier.slug} · scan evidence"]
+    if (p := ev.provenance) is not None:
+        window = f", {p.snippet_tokens}-token windows" if p.snippet_tokens else ""
+        lines.append(
+            f"Corpus {p.corpus}: {p.n_snippets} snippets, {p.tokens_scanned:,} tokens{window}"
+            + (f" · selection {p.selection} (seed {p.seed})" if p.seed is not None else "")
+        )
+    top = ev.top_examples[0].max_activation if ev.top_examples else 0.0
+    line = f"Max activation {top:.3f}"
+    if ev.activation_histogram is not None and top > 0:
+        share = ev.activation_histogram.share_at_least(ACTIVATION_THRESHOLD * top)
+        line += f" · ≥ {ACTIVATION_THRESHOLD:g}×max on at least {share:.1%} of tokens"
+    if ev.first_token_floor:
+        line += " · first-token floor"
+    lines.append(line)
+    shown = ev.top_examples if full else ev.top_examples[:TOP_EXAMPLES]
+    lines.append(
+        f"Top examples ({len(shown)} of {len(ev.top_examples)}), peak token in [brackets]:"
+    )
+    lines += [f"  {ex.max_activation:7.3f}  {_peak(ex, full)}" for ex in shown]
+    if (lens := ev.vocabulary_lens) is not None:
+        lines.append(f"Logit lens promotes: {_tokens(lens.logit_promoted)}")
+        lines.append(f"Logit lens suppresses: {_tokens(lens.logit_suppressed)}")
+    if ev.correlated_neurons:
+        sign = {"positive": "+", "negative": "−"}
+        lines.append(
+            "Co-activating poles: "
+            + ", ".join(
+                f"N{n.neuron_idx}{sign[n.pole]} (lift ≥ {n.coactivation_lift_lower:.1f})"
+                for n in ev.correlated_neurons[:5]
+            )
+        )
+    if (op := ev.opposite_pole) is not None and op.top_examples:
+        ex = op.top_examples[0]
+        lines.append(f"Opposite pole ({op.pole}) peak {ex.max_activation:.3f}: {_peak(ex, full)}")
+    return "\n".join(lines)
+
+
+def _selection(sub) -> str:
+    p = sub.provenance
+    if p is None:
+        return ""
+    return f" · selection {p.selection}" + (f" (seed {p.seed})" if p.seed is not None else "")
+
+
+def _hypothesis(sub) -> list[str]:
+    return [
+        f"Hypothesis: {sub.natural_language_explanation}",
+        f"Tokens: {_tokens(sub.activating_tokens)} · mechanism "
+        + ("lookahead" if sub.lookahead.is_lookahead else "retrospective")
+        + (f" · max activation {sub.max_activation:.3f}" if sub.max_activation else ""),
+    ]
+
+
+def _failed_probes(record: AuditRecord, full: bool) -> list[str]:
+    verdict = record.verdict
+    results = verdict.adversarial_test_results
+    failed = [r for r in results if r.measured and not r.passed]
+    if not results:
+        return []
+    line = f"Failed probes: {len(failed)} of {len(results)}"
+    peak = record.submission.max_activation
+    if verdict.policy is not None and peak:
+        line += f" (active line {verdict.policy.activation_threshold * peak:.3f})"
+    lines = [line + (":" if failed else "")]
+    for r in failed:
+        if r.kind == "counterfactual":
+            got = f"Δ {_num(r.observed_delta)} vs expected {_num(r.expected_delta)}"
+        else:
+            expected = "active" if r.expected_active else "inactive"
+            got = f"{_num(r.activation)}, expected {expected}"
+        lines.append(f"  ✗ {r.kind.replace('_', ' ')}: {got}: {_clip(r.prompt, full)}")
+    return lines
+
+
+def _discussion(page: Path) -> str:
+    """The page's Discussion section without the template comment, or ''."""
+    if not page.exists():
+        return ""
+    text = page.read_text(encoding="utf-8").split("\n## Discussion", 1)
+    if len(text) < 2:
+        return ""
+    body = re.sub(r"<!--.*?-->", "", text[1], flags=re.S)
+    return " ".join(body.split())
+
+
+def _peak(ex, full: bool) -> str:
+    i = ex.max_token_index
+    start = 0 if full else max(0, i - CONTEXT_TOKENS)
+    end = len(ex.tokens) if full else i + 3
+    before, peak, after = ex.tokens[start:i], ex.tokens[i : i + 1], ex.tokens[i + 1 : end]
+    text = "".join(before) + "[" + "".join(peak) + "]" + "".join(after)
+    return ("…" if start else "") + text.replace("\n", "⏎")
+
+
+def _tokens(tokens: list[str], n: int = 10) -> str:
+    shown = ", ".join(repr(t) for t in tokens[:n])
+    return shown + (f" (+{len(tokens) - n})" if len(tokens) > n else "")
+
+
+def _num(x: float | None) -> str:
+    return "n/a" if x is None else f"{x:.3f}"
+
+
+def _clip(text: str, full: bool, chars: int = PROMPT_CHARS) -> str:
+    text = " ".join(text.split())
+    return text if full or len(text) <= chars else text[: chars - 1] + "…"