open-interpretability 0.0.20__py3-none-any.whl

openinterp/cli_score.py

@@ -0,0 +1,446 @@
+"""``open-interpretability score``: detection, fuzzing and embedding scores for an explanation."""
+
+from __future__ import annotations
+
+import json
+import math
+import secrets
+from pathlib import Path
+
+import click
+
+from openinterp.cli import cli, recorded_model_option, with_model_options
+from openinterp.harness.explanation_scores import DEFAULT_EMBEDDING_MODEL
+
+
+def _sibling(task_path: Path, suffix: str) -> Path:
+    """``score.task.json`` -> ``score<suffix>``."""
+    return task_path.with_name(task_path.name.removesuffix(".json").removesuffix(".task") + suffix)
+
+
+def _load_submission(path: Path):
+    from openinterp.core.schemas import AuditRecord, NeuronAuditSubmission
+
+    raw = path.read_text()
+    if "submission" in json.loads(raw):
+        return AuditRecord.model_validate_json(raw).submission
+    return NeuronAuditSubmission.model_validate_json(raw)
+
+
+def _threshold(submission) -> float:
+    from openinterp.core.schemas import ReviewPolicy
+
+    if not submission.max_activation:
+        raise click.ClickException("the submission has no max_activation; rescan it first.")
+    return ReviewPolicy().activation_threshold * submission.max_activation
+
+
+@cli.command()
+@click.option(
+    "--audit-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Submission or record whose explanation to score. Required unless --task.",
+)
+@click.option(
+    "--corpus",
+    type=click.Path(exists=True, path_type=Path),
+    help="Where held-out windows come from; the scan's top examples are left out. "
+    "Use the scan's corpus, so the windows are text the proposer could have seen but didn't.",
+)
+@click.option("--seed", type=int, help="Seed for drawing windows (recorded).")
+@click.option(
+    "--judge-model",
+    default=None,
+    callback=recorded_model_option,
+    help="Judge for detection and fuzzing: a LiteLLM model string, or external/<name>. "
+    "With --task, the name recorded for whoever answered.",
+)
+@click.option(
+    "--embedding-model",
+    default=DEFAULT_EMBEDDING_MODEL,
+    show_default=True,
+    help="Hugging Face sentence encoder for the embedding score; '' to skip it.",
+)
+@click.option(
+    "--emit-task",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Draw the windows, write them here (e.g. score.task.json) with the judge's two "
+    "prompts next to them (score.detection.prompt.md, score.fuzzing.prompt.md), and exit.",
+)
+@click.option(
+    "--task",
+    "task_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="A task from --emit-task, answered in score.detection.json and score.fuzzing.json "
+    "next to it. No LLM is called.",
+)
+@click.option("--window-tokens", default=32, show_default=True, type=click.IntRange(4, 512))
+@click.option("--quantiles", default=5, show_default=True, type=click.IntRange(1, 20))
+@click.option(
+    "--per-quantile",
+    default=5,
+    show_default=True,
+    type=click.IntRange(1, 50),
+    help="Active windows per activation bin, for each of detection and fuzzing.",
+)
+@click.option("--max-windows", default=4000, show_default=True, type=click.IntRange(1))
+@click.option(
+    "--controls",
+    is_flag=True,
+    help="Also judge the same windows with no explanation and with another unit's, and "
+    "report the gaps (openinterp/score_controls.py).",
+)
+@click.option(
+    "--out",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="ExplanationScores JSON (default with --task: score.scores.json next to it).",
+)
+@with_model_options
+def score(
+    audit_file,
+    corpus,
+    seed,
+    judge_model,
+    embedding_model,
+    emit_task,
+    task_file,
+    window_tokens,
+    quantiles,
+    per_quantile,
+    max_windows,
+    controls,
+    out,
+    device,
+    dtype,
+):
+    """Score an explanation on held-out text: detection, fuzzing and embedding.
+
+    \b
+    Reported, not gated (docs/PROTOCOL.md §4), but every review records them: pass the
+    result to `open-interpretability review … --explanation-scores <file>`. In one step the
+    judge is an LLM:
+        open-interpretability score --audit-file sub.json --corpus corpus.jsonl \\
+          --judge-model M --out s.json
+    In two steps any agent can judge, without an API key:
+        open-interpretability score --audit-file sub.json --corpus corpus.jsonl \\
+          --emit-task score.task.json
+        (answer score.detection.prompt.md and score.fuzzing.prompt.md)
+        open-interpretability score --task score.task.json \\
+          --judge-model external/<model that answered>
+    """
+    from openinterp.agents.base import DEFAULT_MODEL
+    from openinterp.cli import _load_unit_runner  # looked up per call, so tests can swap it
+    from openinterp.core import costs
+
+    if task_file is not None:
+        if audit_file is not None or emit_task is not None:
+            raise click.UsageError("--task scores an emitted task; drop --audit-file/--emit-task.")
+        if not judge_model:
+            raise click.UsageError("--judge-model is required with --task: name who answered.")
+        scores = _score_answers(task_file, judge_model, embedding_model, device, dtype)
+        out = out or _sibling(task_file, ".scores.json")
+    else:
+        if audit_file is None:
+            raise click.UsageError("--audit-file is required unless --task is given.")
+        if emit_task is None and out is None:
+            raise click.UsageError("--out is required when scoring in one step.")
+        submission = _load_submission(audit_file)
+        runner = _load_unit_runner(submission.identifier, device, dtype)
+        sampling = (seed, window_tokens, quantiles, per_quantile, max_windows, controls)
+        if emit_task is not None:
+            task = _draw_task(runner, submission, corpus, *sampling)
+            _write_task(task.model_copy(update={"costs": costs.measured()}), emit_task)
+            return
+        scores = score_submission(
+            runner, submission, corpus, judge_model or DEFAULT_MODEL, embedding_model, *sampling
+        )
+        scores = scores.model_copy(update={"costs": costs.measured()})
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(scores.model_dump_json(indent=2))
+    click.echo(_summary(scores))
+    click.echo(f"Wrote {out}")
+
+
+def _score_answers(task_file: Path, judge_model: str, embedding_model, device, dtype):
+    """Step two: score an emitted task from the external judge's answers next to it."""
+    from openinterp.agents.judge import DetectionAnswer, FuzzingAnswer, ScoringTask
+    from openinterp.cli import _load_unit_runner  # looked up per call, so tests can swap it
+    from openinterp.core import costs
+
+    task = ScoringTask.model_validate_json(task_file.read_text())
+    detection = DetectionAnswer.model_validate_json(
+        _sibling(task_file, ".detection.json").read_text()
+    )
+    fuzzing = (  # no fuzzing prompt when no held-out window was active
+        FuzzingAnswer.model_validate_json(_sibling(task_file, ".fuzzing.json").read_text())
+        if task.fuzzing
+        else FuzzingAnswer(correct=[])
+    )
+    for kind in ("detection", "fuzzing") if task.fuzzing else ("detection",):
+        prompt, answer = (
+            _sibling(task_file, f".{kind}.prompt.md"),
+            _sibling(task_file, f".{kind}.json"),
+        )
+        costs.add_external("judge", judge_model, prompt, answer)
+    from openinterp.score_controls import read_answers
+
+    runner = _load_unit_runner(task.identifier, device, dtype)
+    controls = read_answers(task, task_file)
+    scores = _score_task(task, runner, detection, fuzzing, judge_model, embedding_model, controls)
+    return scores.model_copy(update={"costs": costs.merge(task.costs, costs.measured())})
+
+
+def score_submission(
+    runner,
+    submission,
+    corpus: Path | None,
+    judge_model: str,
+    embedding_model: str = DEFAULT_EMBEDDING_MODEL,
+    seed: int | None = None,
+    window_tokens: int = 32,
+    quantiles: int = 5,
+    per_quantile: int = 5,
+    max_windows: int = 4000,
+    controls: bool = False,
+):
+    """Draw held-out windows and score the explanation with an LLM judge, in one step."""
+    from openinterp.agents.judge import ExplanationJudge, FuzzingAnswer
+    from openinterp.score_controls import judge_controls
+
+    sampling = (seed, window_tokens, quantiles, per_quantile, max_windows, controls)
+    task = _draw_task(runner, submission, corpus, *sampling)
+    judge = ExplanationJudge(judge_model)
+    click.echo(f"Asking {judge.model} to judge {len(task.detection)} windows…", err=True)
+    noun = _noun(task.identifier)
+    detection = judge.detect(task.explanation, task.detection, noun)
+    fuzzing = (
+        judge.fuzz(task.explanation, task.fuzzing, noun)
+        if task.fuzzing
+        else FuzzingAnswer(correct=[])
+    )
+    judged = judge_controls(judge, task, noun)
+    return _score_task(task, runner, detection, fuzzing, judge.model, embedding_model, judged)
+
+
+def _draw_task(
+    runner, submission, corpus, seed, window_tokens, quantiles, per_quantile, cap, controls=False
+):
+    from openinterp.agents.judge import ScoringTask
+    from openinterp.cli_evidence import read_corpus
+    from openinterp.harness.explanation_scores import DECOYS
+    from openinterp.score_controls import control_tasks
+
+    texts, corpus_name, corpus_sha, _ = read_corpus(corpus)
+    seed = secrets.randbits(32) if seed is None else seed
+    threshold = _threshold(submission)
+    submission = _with_first_token_floor(runner, submission)
+    click.echo(f"Measuring held-out {window_tokens}-token windows (seed {seed})…", err=True)
+    sample = _sample(
+        runner, texts, submission, threshold, seed, window_tokens, cap, quantiles, per_quantile
+    )
+    windows = _task_windows
+    return ScoringTask(
+        identifier=submission.identifier,
+        head_profile=submission.head_profile,
+        dictionary_profile=submission.dictionary_profile,
+        superposition_profile=submission.superposition_profile,
+        first_token_floor=submission.first_token_floor,
+        explanation=submission.natural_language_explanation,
+        threshold=threshold,
+        window_tokens=window_tokens,
+        quantiles=quantiles,
+        quantile_edges=sample.quantile_edges,
+        seed=seed,
+        corpus=corpus_name,
+        corpus_sha256=corpus_sha,
+        candidate_windows=sample.candidate_windows,
+        active_windows=sample.active_windows,
+        detection=windows(sample.detection),
+        fuzzing=windows(sample.fuzzing),
+        controls=control_tasks(submission.identifier.slug, seed) if controls else [],
+        fuzzing_decoys=DECOYS,
+    )
+
+
+def _sample(
+    runner, texts, submission, threshold, seed, window_tokens, cap, quantiles, per_quantile
+):
+    """Held-out windows of the corpus, leaving out the top examples."""
+    from openinterp.core import costs
+    from openinterp.harness.explanation_scores import sample_heldout
+    from openinterp.harness.units import submission_unit
+
+    try:
+        with costs.stage("heldout_windows"):
+            return sample_heldout(
+                runner,
+                texts,
+                submission_unit(submission),
+                threshold,
+                seed=seed,
+                exclude=[e.text for e in submission.top_examples],
+                window_tokens=window_tokens,
+                max_windows=cap,
+                quantiles=quantiles,
+                per_quantile=per_quantile,
+            )
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _with_first_token_floor(runner, submission):
+    """Return ``submission`` with its first-token floor set.
+
+    A record from before protocol 0.8 has no floor, so judge it as a review does.
+    """
+    if submission.first_token_floor is not None:
+        return submission
+    from functools import partial
+
+    from openinterp.core.schemas import ReviewPolicy
+    from openinterp.harness.scan import has_first_token_floor
+    from openinterp.harness.units import submission_unit
+
+    read = partial(submission_unit(submission).strengths, runner)
+    floor = has_first_token_floor(runner, read, submission.max_activation, ReviewPolicy())
+    return submission.model_copy(update={"first_token_floor": floor})
+
+
+def _task_windows(ws):
+    from openinterp.agents.judge import TaskWindow
+
+    return [TaskWindow(text=w.text, tokens=w.tokens, highlighted=list(w.highlighted)) for w in ws]
+
+
+def _write_task(task, path: Path) -> None:
+    from openinterp.agents.judge import DetectionAnswer, ExplanationJudge, FuzzingAnswer
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(task.model_dump_json(indent=2))
+    click.echo(f"Wrote {path} ({len(task.detection)} detection, {len(task.fuzzing)} fuzzing)")
+    if not task.active_windows:
+        click.echo("No held-out window is active: detection scores false positives only.")
+    for kind, model, prompt in [
+        ("detection", DetectionAnswer, ExplanationJudge.detection_prompt),
+        ("fuzzing", FuzzingAnswer, ExplanationJudge.fuzzing_prompt),
+    ]:
+        if not getattr(task, kind):
+            continue
+        prompt_path, answer = _sibling(path, f".{kind}.prompt.md"), _sibling(path, f".{kind}.json")
+        text = prompt(task.explanation, getattr(task, kind), _noun(task.identifier))
+        prompt_path.write_text(ExplanationJudge.render_prompt(model, text, answer))
+        click.echo(f"Judge prompt: {prompt_path} (answer in {answer})")
+    if task.controls:
+        from openinterp.score_controls import write_prompts
+
+        write_prompts(task, path, _noun(task.identifier))
+        click.echo(f"Control prompts: {len(task.controls)} controls, next to {path}")
+
+
+def _score_task(task, runner, detection, fuzzing, judge_model, embedding_model, controls=()):
+    from openinterp.agents.judge import answered
+    from openinterp.core import costs
+    from openinterp.core.explanation import ExplanationScores
+    from openinterp.harness.explanation_scores import embedding_similarities, remeasure
+    from openinterp.harness.units import submission_unit
+
+    try:
+        det = answered(detection.active, len(task.detection), "detection")
+        fuz = answered(fuzzing.correct, len(task.fuzzing), "fuzzing")
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    sims = [None] * len(task.detection)
+    if embedding_model:
+        click.echo(f"Embedding the explanation and windows with {embedding_model}…", err=True)
+        with costs.stage("embedding"):
+            sims = embedding_similarities(
+                embedding_model, task.explanation, [w.text for w in task.detection]
+            )
+    scores = ExplanationScores(
+        slug=task.identifier.slug,
+        explanation=task.explanation,
+        threshold=task.threshold,
+        window_tokens=task.window_tokens,
+        quantiles=task.quantiles,
+        quantile_edges=task.quantile_edges,
+        seed=task.seed,
+        corpus=task.corpus,
+        corpus_sha256=task.corpus_sha256,
+        candidate_windows=task.candidate_windows,
+        active_windows=task.active_windows,
+        judge_model=judge_model,
+        embedding_model=embedding_model or None,
+        detection_windows=_unmeasured(task.detection, det, sims),
+        fuzzing_windows=_unmeasured(task.fuzzing, fuz, [None] * len(task.fuzzing)),
+        controls=list(controls),
+        fuzzing_decoys=task.fuzzing_decoys,
+    )
+    with costs.stage("remeasure"):
+        return remeasure(scores, runner, submission_unit(task))
+
+
+def _unmeasured(windows, answers, similarities):
+    """Judged windows awaiting their activations; ``remeasure`` fills them and the labels."""
+    from openinterp.core.explanation import ScoredWindow
+
+    return [
+        ScoredWindow(
+            text=w.text,
+            tokens=w.tokens,
+            activations=[],
+            highlighted=w.highlighted,
+            label=False,  # re-derived from a fresh measurement below
+            judged=a,
+            similarity=s,
+        )
+        for w, a, s in zip(windows, answers, similarities, strict=True)
+    ]
+
+
+def _noun(identifier) -> str:
+    return identifier.noun
+
+
+def _summary(scores) -> str:
+    def judged(s):
+        if s is None:
+            return "—"
+        return (
+            f"{s.balanced_accuracy:.2f} (TPR {_num(s.true_positive_rate)}, "
+            f"FPR {_num(s.false_positive_rate)})"
+        )
+
+    from openinterp.score_controls import gap_summary
+
+    line = (
+        f"Detection {judged(scores.detection)} · fuzzing {judged(scores.fuzzing)} · "
+        f"embedding AUROC {_num(scores.embedding_auroc)} · "
+        f"{scores.active_windows}/{scores.candidate_windows} held-out windows active"
+    )
+    rules = scores.rule_baseline
+    if rules:
+        best = ", ".join(f"{k} {v:.2f}" for k, v in sorted(rules.items()))
+        line += f"\nExplanation-free rules (upper bounds): {best}"
+    return line + ("\n" + gap_summary(scores) if scores.controls else "")
+
+
+def _num(value: float | None) -> str:
+    return "—" if value is None else f"{value:.2f}"
+
+
+def load_scores(path: Path | None, submission):
+    """The explanation scores in ``path``, checked against ``submission``, or ``None``."""
+    from openinterp.core.explanation import ExplanationScores
+
+    if path is None:
+        return None
+    scores = ExplanationScores.model_validate_json(path.read_text())
+    if scores.slug != submission.identifier.slug:
+        raise click.UsageError(f"{path} scores {scores.slug}, not {submission.identifier.slug}.")
+    if scores.explanation != submission.natural_language_explanation:
+        raise click.UsageError(
+            f"{path} scores a different explanation; re-run open-interpretability score."
+        )
+    if not math.isclose(scores.threshold, _threshold(submission), rel_tol=1e-9):
+        raise click.UsageError(f"{path} used another activation threshold; re-run it.")
+    return scores

openinterp/cli_sisters.py

@@ -0,0 +1,86 @@
+"""``open-interpretability sisters``: VERIFIED neuron poles matched to other models' poles.
+
+See :mod:`openinterp.sisters`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from openinterp.cli import _load_runner, cli, wiki_dir_option
+from openinterp.sisters import DEFAULT_PATH
+
+
+@cli.command("sisters")
+@wiki_dir_option()
+@click.option(
+    "--model",
+    "model_name",
+    default=None,
+    help="Match only this model's VERIFIED poles. Default: every configured model "
+    "([tool.openinterp] models in pyproject.toml).",
+)
+@click.option(
+    "--other",
+    "others",
+    multiple=True,
+    help="Search only this model (repeatable). Default: every other configured model, "
+    "and the model's larger siblings (openinterp.sisters.SIBLINGS).",
+)
+@click.option(
+    "--corpus",
+    default=Path("corpus.jsonl"),
+    show_default=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Texts both models read; each document is one forward pass.",
+)
+@click.option(
+    "--out",
+    "path",
+    default=DEFAULT_PATH,
+    show_default=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="JSONL of sister rows, one per pole and other model.",
+)
+@click.option("-k", "k", default=5, show_default=True, help="Poles kept per pole and model.")
+@click.option("--device", default="auto", show_default=True, help="cpu, cuda, mps or auto.")
+def sisters_command(wiki_dir, model_name, others, corpus, path, k, device):
+    """Find each VERIFIED pole's best-correlated poles in other models.
+
+    Both models read --corpus. They are compared where both have read the same text
+    (token ends they share), so they may tokenize differently. Every pole of every layer
+    of the other model is correlated with each VERIFIED pole. Then each match is
+    correlated with every pole of the first model, so a row says whether the match is
+    mutual. Poles already in --out for that
+    model are skipped, so a run can resume.
+    """
+    from openinterp.builder.wiki import load_archive
+    from openinterp.evidence import read_corpus
+    from openinterp.planner import configured_models
+    from openinterp.sisters import pairs, sisters, sort_rows
+
+    todo = pairs(configured_models(wiki_dir.parent / "pyproject.toml"))
+    if model_name:
+        todo = [p for p in todo if p[0] == model_name] or pairs([model_name])
+    if others:
+        todo = [(a, b) for a in {a for a, _ in todo} or {model_name} for b in others if a != b]
+    if not todo:
+        raise click.UsageError("no model pairs to match; pass --model and --other")
+    texts, corpus_name, corpus_sha, _ = read_corpus(corpus)
+    from openinterp.core.errata import load_errata
+
+    records = load_archive(wiki_dir)
+
+    def load(name, revision):  # not cached: each stage frees its model before the next
+        return _load_runner(name, device, "float32", revision)
+
+    wrote = sisters(
+        records, load, path, texts, todo, corpus=corpus_name, corpus_sha256=corpus_sha,
+        errata=load_errata(wiki_dir), k=k, echo=click.echo,
+    )  # fmt: skip
+    for (source, other), n in wrote.items():
+        click.echo(f"Matched {n} poles of {source} against {other} → {path}")
+    if path.exists():
+        sort_rows(path)