open-interpretability 0.0.20__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (256) hide show
  1. open_interpretability-0.0.20.dist-info/METADATA +157 -0
  2. open_interpretability-0.0.20.dist-info/RECORD +256 -0
  3. open_interpretability-0.0.20.dist-info/WHEEL +4 -0
  4. open_interpretability-0.0.20.dist-info/entry_points.txt +2 -0
  5. open_interpretability-0.0.20.dist-info/licenses/LICENSE +21 -0
  6. openinterp/__init__.py +6 -0
  7. openinterp/agents/__init__.py +25 -0
  8. openinterp/agents/base.py +229 -0
  9. openinterp/agents/judge.py +149 -0
  10. openinterp/agents/proposer.py +471 -0
  11. openinterp/agents/proposer_profiles.py +79 -0
  12. openinterp/agents/review_measurements.py +173 -0
  13. openinterp/agents/reviewer.py +498 -0
  14. openinterp/agreement.py +63 -0
  15. openinterp/audit_options.py +79 -0
  16. openinterp/baseline.py +254 -0
  17. openinterp/benchmark.py +450 -0
  18. openinterp/blends.py +239 -0
  19. openinterp/builder/__init__.py +6 -0
  20. openinterp/builder/agents.py +260 -0
  21. openinterp/builder/aligned.py +41 -0
  22. openinterp/builder/charts.py +411 -0
  23. openinterp/builder/circuit_pages.py +37 -0
  24. openinterp/builder/circuits.py +264 -0
  25. openinterp/builder/compiler.py +495 -0
  26. openinterp/builder/corpora.py +98 -0
  27. openinterp/builder/coverage.py +46 -0
  28. openinterp/builder/dashboard.py +255 -0
  29. openinterp/builder/disk_memo.py +65 -0
  30. openinterp/builder/experiment.py +105 -0
  31. openinterp/builder/heat.py +121 -0
  32. openinterp/builder/hrefs.py +71 -0
  33. openinterp/builder/learned_baseline.py +204 -0
  34. openinterp/builder/model_facts.py +138 -0
  35. openinterp/builder/neuronpedia_export.py +107 -0
  36. openinterp/builder/parallel.py +100 -0
  37. openinterp/builder/parquet_export.py +458 -0
  38. openinterp/builder/pieces.py +127 -0
  39. openinterp/builder/pii.py +211 -0
  40. openinterp/builder/registry_stats.py +144 -0
  41. openinterp/builder/research.py +109 -0
  42. openinterp/builder/sections.py +28 -0
  43. openinterp/builder/significance.py +103 -0
  44. openinterp/builder/sister_graph.py +180 -0
  45. openinterp/builder/standing.py +185 -0
  46. openinterp/builder/statuses.py +34 -0
  47. openinterp/builder/stopped.py +91 -0
  48. openinterp/builder/stops.py +30 -0
  49. openinterp/builder/superpositions.py +102 -0
  50. openinterp/builder/templates/_agent_role_cells.html +9 -0
  51. openinterp/builder/templates/_causal_chart.html +67 -0
  52. openinterp/builder/templates/_circuit.html +8 -0
  53. openinterp/builder/templates/_dashboard.html +133 -0
  54. openinterp/builder/templates/_experiment.html +500 -0
  55. openinterp/builder/templates/_macros.html +82 -0
  56. openinterp/builder/templates/_patchscope.html +33 -0
  57. openinterp/builder/templates/_prior_art.html +24 -0
  58. openinterp/builder/templates/_specificity.html +21 -0
  59. openinterp/builder/templates/_steering.html +34 -0
  60. openinterp/builder/templates/_superposition.html +62 -0
  61. openinterp/builder/templates/_vocab_chart.html +88 -0
  62. openinterp/builder/templates/_wiring.html +44 -0
  63. openinterp/builder/templates/about.html +95 -0
  64. openinterp/builder/templates/agent.html +69 -0
  65. openinterp/builder/templates/agents.html +80 -0
  66. openinterp/builder/templates/base.html +103 -0
  67. openinterp/builder/templates/circuit.html +64 -0
  68. openinterp/builder/templates/circuits.html +46 -0
  69. openinterp/builder/templates/experiment.html +21 -0
  70. openinterp/builder/templates/hub.html +16 -0
  71. openinterp/builder/templates/index.html +387 -0
  72. openinterp/builder/templates/layer.html +69 -0
  73. openinterp/builder/templates/learned-baseline.html +44 -0
  74. openinterp/builder/templates/model.html +151 -0
  75. openinterp/builder/templates/models.html +47 -0
  76. openinterp/builder/templates/neuron.html +234 -0
  77. openinterp/builder/templates/paper.html +39 -0
  78. openinterp/builder/templates/redirect.html +1 -0
  79. openinterp/builder/templates/research.html +31 -0
  80. openinterp/builder/templates/user.html +54 -0
  81. openinterp/builder/templates/users.html +39 -0
  82. openinterp/builder/templates/wiki/experiment.md +271 -0
  83. openinterp/builder/templates/wiki/index.md +32 -0
  84. openinterp/builder/templates/wiki/neuron.md +30 -0
  85. openinterp/builder/templates/wiki/stop.md +36 -0
  86. openinterp/builder/tree.py +470 -0
  87. openinterp/builder/users.py +142 -0
  88. openinterp/builder/wiki.py +427 -0
  89. openinterp/checks.py +429 -0
  90. openinterp/cli.py +494 -0
  91. openinterp/cli_baseline.py +332 -0
  92. openinterp/cli_benchmark.py +300 -0
  93. openinterp/cli_build.py +128 -0
  94. openinterp/cli_check.py +51 -0
  95. openinterp/cli_concepts.py +76 -0
  96. openinterp/cli_corpus.py +252 -0
  97. openinterp/cli_costs.py +257 -0
  98. openinterp/cli_coverage.py +76 -0
  99. openinterp/cli_crossref.py +86 -0
  100. openinterp/cli_errata.py +142 -0
  101. openinterp/cli_evidence.py +495 -0
  102. openinterp/cli_evidence_store.py +93 -0
  103. openinterp/cli_explain.py +101 -0
  104. openinterp/cli_loop.py +125 -0
  105. openinterp/cli_memory.py +28 -0
  106. openinterp/cli_neuronpedia.py +175 -0
  107. openinterp/cli_pause.py +45 -0
  108. openinterp/cli_pole_effects.py +133 -0
  109. openinterp/cli_probing.py +119 -0
  110. openinterp/cli_registry.py +348 -0
  111. openinterp/cli_reproduce.py +446 -0
  112. openinterp/cli_review.py +302 -0
  113. openinterp/cli_scan.py +223 -0
  114. openinterp/cli_score.py +446 -0
  115. openinterp/cli_sisters.py +86 -0
  116. openinterp/cli_submission.py +217 -0
  117. openinterp/cli_superpositions.py +118 -0
  118. openinterp/cli_wiring.py +54 -0
  119. openinterp/codeid.py +73 -0
  120. openinterp/concepts.py +400 -0
  121. openinterp/core/__init__.py +59 -0
  122. openinterp/core/agent_names.py +76 -0
  123. openinterp/core/attribution.py +101 -0
  124. openinterp/core/cache_dirs.py +15 -0
  125. openinterp/core/causal.py +82 -0
  126. openinterp/core/confounds.py +103 -0
  127. openinterp/core/contributors.py +26 -0
  128. openinterp/core/corpora.py +126 -0
  129. openinterp/core/costs.py +430 -0
  130. openinterp/core/draws.py +109 -0
  131. openinterp/core/errata.py +244 -0
  132. openinterp/core/evidence.py +160 -0
  133. openinterp/core/examples.py +93 -0
  134. openinterp/core/exceptions.py +29 -0
  135. openinterp/core/explanation.py +130 -0
  136. openinterp/core/fence.py +42 -0
  137. openinterp/core/heavy_lock.py +114 -0
  138. openinterp/core/identifiers.py +198 -0
  139. openinterp/core/isolation.py +149 -0
  140. openinterp/core/ledger.py +130 -0
  141. openinterp/core/licenses.py +28 -0
  142. openinterp/core/manifold.py +117 -0
  143. openinterp/core/partners.py +32 -0
  144. openinterp/core/patchscope.py +59 -0
  145. openinterp/core/paths.py +40 -0
  146. openinterp/core/pause.py +96 -0
  147. openinterp/core/pricing.py +178 -0
  148. openinterp/core/prior_art.py +44 -0
  149. openinterp/core/probing.py +146 -0
  150. openinterp/core/profiles.py +221 -0
  151. openinterp/core/project.py +28 -0
  152. openinterp/core/run_environment.py +38 -0
  153. openinterp/core/schemas.py +484 -0
  154. openinterp/core/specificity.py +49 -0
  155. openinterp/core/stats.py +172 -0
  156. openinterp/core/steering.py +49 -0
  157. openinterp/core/strict.py +19 -0
  158. openinterp/core/takedowns.py +136 -0
  159. openinterp/core/transcripts.py +130 -0
  160. openinterp/core/wiring.py +80 -0
  161. openinterp/corpus.py +476 -0
  162. openinterp/corpus_cache.py +145 -0
  163. openinterp/corpus_layouts.py +108 -0
  164. openinterp/corpus_presets.py +168 -0
  165. openinterp/corpus_rebuild.py +93 -0
  166. openinterp/coverage.py +155 -0
  167. openinterp/crossref.py +442 -0
  168. openinterp/data/__init__.py +9 -0
  169. openinterp/data/offensive_words.txt +58 -0
  170. openinterp/data/public_suffix_list.dat +15771 -0
  171. openinterp/data/sample_corpus.txt +40 -0
  172. openinterp/draw_steps.py +359 -0
  173. openinterp/errata_checks.py +129 -0
  174. openinterp/evidence.py +462 -0
  175. openinterp/evidence_branch.py +119 -0
  176. openinterp/evidence_lenses.py +75 -0
  177. openinterp/experiment_loop.py +357 -0
  178. openinterp/explain.py +252 -0
  179. openinterp/half_precision.py +79 -0
  180. openinterp/harness/__init__.py +37 -0
  181. openinterp/harness/ane/__init__.py +9 -0
  182. openinterp/harness/ane/backend.py +324 -0
  183. openinterp/harness/ane/cache.py +276 -0
  184. openinterp/harness/ane/chunks.py +163 -0
  185. openinterp/harness/ane/convert.py +116 -0
  186. openinterp/harness/ane/forward.py +258 -0
  187. openinterp/harness/ane/qualified.py +40 -0
  188. openinterp/harness/annotations.py +329 -0
  189. openinterp/harness/attribution.py +96 -0
  190. openinterp/harness/causal.py +264 -0
  191. openinterp/harness/confounds.py +184 -0
  192. openinterp/harness/covariance.py +301 -0
  193. openinterp/harness/crossref.py +195 -0
  194. openinterp/harness/cuda_devices.py +88 -0
  195. openinterp/harness/dead.py +124 -0
  196. openinterp/harness/devices.py +401 -0
  197. openinterp/harness/dictionaries.py +496 -0
  198. openinterp/harness/dreaming.py +116 -0
  199. openinterp/harness/environment.py +64 -0
  200. openinterp/harness/explanation_scores.py +371 -0
  201. openinterp/harness/features.py +276 -0
  202. openinterp/harness/first_position.py +137 -0
  203. openinterp/harness/heads.py +226 -0
  204. openinterp/harness/hooks.py +499 -0
  205. openinterp/harness/input_attribution.py +367 -0
  206. openinterp/harness/jlens.py +183 -0
  207. openinterp/harness/layer_cache.py +301 -0
  208. openinterp/harness/layer_major.py +274 -0
  209. openinterp/harness/lookahead.py +93 -0
  210. openinterp/harness/manifold.py +200 -0
  211. openinterp/harness/memory.py +471 -0
  212. openinterp/harness/moe.py +134 -0
  213. openinterp/harness/patcher.py +322 -0
  214. openinterp/harness/patchscope.py +177 -0
  215. openinterp/harness/probing.py +383 -0
  216. openinterp/harness/scan.py +462 -0
  217. openinterp/harness/scan_backend.py +201 -0
  218. openinterp/harness/sister_passes.py +463 -0
  219. openinterp/harness/sisters.py +363 -0
  220. openinterp/harness/sites.py +101 -0
  221. openinterp/harness/specificity.py +107 -0
  222. openinterp/harness/steering.py +159 -0
  223. openinterp/harness/superpositions.py +116 -0
  224. openinterp/harness/units.py +203 -0
  225. openinterp/harness/wiring.py +432 -0
  226. openinterp/harness/wiring_activations.py +285 -0
  227. openinterp/langid.py +73 -0
  228. openinterp/names.py +129 -0
  229. openinterp/neuronpedia_baseline.py +88 -0
  230. openinterp/neuronpedia_review.py +148 -0
  231. openinterp/planner.py +466 -0
  232. openinterp/planner_effects.py +89 -0
  233. openinterp/planner_heads.py +92 -0
  234. openinterp/planner_models.py +174 -0
  235. openinterp/planner_sisters.py +122 -0
  236. openinterp/planner_states.py +57 -0
  237. openinterp/planner_superpositions.py +114 -0
  238. openinterp/pole_effects.py +102 -0
  239. openinterp/prior_art.py +143 -0
  240. openinterp/reproduce.py +450 -0
  241. openinterp/revision.py +45 -0
  242. openinterp/runner_cache.py +35 -0
  243. openinterp/score_controls.py +169 -0
  244. openinterp/sensitive.py +243 -0
  245. openinterp/show.py +236 -0
  246. openinterp/signing.py +209 -0
  247. openinterp/sisters.py +476 -0
  248. openinterp/superposition_finders.py +225 -0
  249. openinterp/sync/__init__.py +5 -0
  250. openinterp/sync/r2.py +280 -0
  251. openinterp/syntax.py +399 -0
  252. openinterp/takedown_checks.py +76 -0
  253. openinterp/toxicity.py +158 -0
  254. openinterp/verdict_regression.py +79 -0
  255. openinterp/wiring_backfill.py +170 -0
  256. openinterp/wordnet.py +362 -0
@@ -0,0 +1,332 @@
1
+ """The Patchscope readout as a blind proposer baseline.
2
+
3
+ The command is ``open-interpretability patchscope-baseline``.
4
+ See :mod:`openinterp.baseline` for the rule and the comparison.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from pathlib import Path
10
+
11
+ import click
12
+
13
+ from openinterp.cli import cli, recorded_model_option, wiki_dir_option, with_model_options
14
+
15
+
16
+ @cli.command("patchscope-baseline")
17
+ @wiki_dir_option()
18
+ @click.option(
19
+ "--work-dir",
20
+ default="exchange/patchscope-baseline",
21
+ show_default=True,
22
+ type=click.Path(path_type=Path),
23
+ help="Readouts, judge prompts and their answers.",
24
+ )
25
+ @click.option(
26
+ "--judge-model",
27
+ default="external/claude-haiku-5-5",
28
+ show_default=True,
29
+ callback=recorded_model_option,
30
+ help="Write judge prompts for the experiments this judge scored, and record their "
31
+ "answers as its own: the pair is only fair with the same judge.",
32
+ )
33
+ @click.option(
34
+ "--out",
35
+ default="docs/analyses/patchscope-baseline",
36
+ show_default=True,
37
+ type=click.Path(path_type=Path),
38
+ help="Writes <out>.jsonl (one row per experiment) and <out>.md (the comparison).",
39
+ )
40
+ @with_model_options
41
+ def patchscope_baseline(wiki_dir, work_dir, judge_model, out, device, dtype):
42
+ """Score each unit's Patchscope readout as an explanation, against the agent's.
43
+
44
+ A fixed rule turns the readout into an explanation. It is scored on the held-out
45
+ windows that the agent's explanation was scored on.
46
+
47
+ \b
48
+ Run it once to read every unit and write judge prompts under --work-dir.
49
+ Answer each prompt with its own explanation-judge.
50
+ Then run it again to score the answers.
51
+ Each run writes what can be compared so far. The embedding score uses the encoder the
52
+ record's own scores used, so it needs no judge.
53
+ """
54
+ from openinterp.builder.wiki import load_archive_paths
55
+
56
+ records = [
57
+ r
58
+ for _, r in load_archive_paths(wiki_dir)
59
+ if r.verdict
60
+ and r.verdict.explanation_scores
61
+ and r.submission.identifier.kind != "attn_head"
62
+ ]
63
+ click.echo(f"{len(records)} experiments have explanation scores.", err=True)
64
+ readouts = _readouts(records, work_dir / "readouts", device, dtype)
65
+ rows, pending = [], 0
66
+ for record in records:
67
+ row, waiting = _baseline_row(record, readouts, work_dir, judge_model)
68
+ rows.append(row)
69
+ pending += waiting
70
+ _write_report(rows, out, pending, work_dir)
71
+
72
+
73
+ def _baseline_row(record, readouts: dict, work_dir: Path, judge_model: str):
74
+ """(the record's BaselineRow, whether it still awaits judge answers)."""
75
+ from openinterp.baseline import DEV_SLUGS, blind_explanation, blind_reading
76
+
77
+ readout = readouts[record.submission.identifier.slug]
78
+ reading = (blind_reading(readout) or readout.readings[0]).text
79
+ return paired_row(
80
+ record,
81
+ blind_explanation(readout),
82
+ reading,
83
+ work_dir,
84
+ judge_model,
85
+ dev=record.submission.identifier.slug in DEV_SLUGS,
86
+ )
87
+
88
+
89
+ def paired_row(
90
+ record, explanation: str | None, reading: str, work_dir: Path, judge_model: str, *, dev: bool
91
+ ):
92
+ """Score ``explanation`` on the record's held-out windows, paired with the agent's.
93
+
94
+ Return (the record's BaselineRow, whether it still awaits judge answers). It writes
95
+ the judge task under ``work_dir`` the first time. Detection and fuzzing are scored
96
+ only when ``judge_model`` judged the agent's explanation too.
97
+ """
98
+ from openinterp.baseline import METRICS, BaselineRow, metric, rescored
99
+ from openinterp.builder.wiki import experiment_id
100
+ from openinterp.harness.explanation_scores import embedding_similarities
101
+
102
+ scores = record.verdict.explanation_scores
103
+ eid, slug = experiment_id(record), record.submission.identifier.slug
104
+ row = _row_fields(record, reading, explanation, dev)
105
+ agent = row["agent"]
106
+ if explanation is None:
107
+ return BaselineRow(**row), False
108
+ sims = None
109
+ if scores.embedding_model and agent["embedding"] is not None:
110
+ texts = [w.text for w in scores.detection_windows]
111
+ sims = embedding_similarities(scores.embedding_model, explanation, texts)
112
+ detection = fuzzing = None
113
+ waiting = False
114
+ if scores.judge_model == judge_model:
115
+ task_path = work_dir / "judge" / slug / f"{eid}.task.json"
116
+ judged = _judged(record, explanation, task_path)
117
+ if judged is None:
118
+ waiting = True
119
+ else:
120
+ detection, fuzzing, answers = judged
121
+ row |= {"baseline_judge_model": judge_model, **answers}
122
+ judge = row.get("baseline_judge_model")
123
+ judged = {"detection": detection, "fuzzing": fuzzing, "similarities": sims}
124
+ base = rescored(scores, explanation, judge_model=judge, **judged)
125
+ row["baseline"] = {name: metric(base, name) for name in METRICS}
126
+ return BaselineRow(**row), waiting
127
+
128
+
129
+ def _row_fields(record, reading: str, explanation: str | None, dev: bool) -> dict:
130
+ """The row before the baseline is scored: the agent's metrics and the reading."""
131
+ from openinterp.baseline import METRICS, metric
132
+ from openinterp.builder.wiki import experiment_id
133
+
134
+ sub, scores = record.submission, record.verdict.explanation_scores
135
+ return dict(
136
+ experiment_id=experiment_id(record),
137
+ slug=sub.identifier.slug,
138
+ status=record.verdict.status,
139
+ selection=sub.provenance.selection if sub.provenance else None,
140
+ dev=dev,
141
+ reading=reading,
142
+ agent_explanation=scores.explanation,
143
+ baseline_explanation=explanation,
144
+ judge_model=scores.judge_model,
145
+ agent={name: metric(scores, name) for name in METRICS},
146
+ baseline=dict.fromkeys(METRICS),
147
+ )
148
+
149
+
150
+ def _judged(record, explanation: str, task_path: Path):
151
+ """Return (detection, fuzzing, the raw answers) from the answers next to ``task_path``.
152
+
153
+ Returns ``None`` while the answers are missing. It first writes the task if the task
154
+ isn't there yet.
155
+ """
156
+ from openinterp.agents.judge import DetectionAnswer, FuzzingAnswer, answered
157
+ from openinterp.cli_score import _sibling, _write_task
158
+
159
+ scores = record.verdict.explanation_scores
160
+ det_path = _sibling(task_path, ".detection.json")
161
+ fuz_path = _sibling(task_path, ".fuzzing.json")
162
+ need_fuzzing = bool(scores.fuzzing_windows) # no prompt without fuzzing windows
163
+ if not det_path.exists() or not (fuz_path.exists() or not need_fuzzing):
164
+ if not task_path.exists():
165
+ _write_task(_task(record, explanation), task_path)
166
+ return None
167
+ det = _answer(DetectionAnswer, det_path).active
168
+ detection = answered(det, len(scores.detection_windows), "detection")
169
+ fuz = fuzzing = None
170
+ if need_fuzzing:
171
+ fuz = _answer(FuzzingAnswer, fuz_path).correct
172
+ fuzzing = answered(fuz, len(scores.fuzzing_windows), "fuzzing")
173
+ return detection, fuzzing, {"detection_answer": det, "fuzzing_answer": fuz}
174
+
175
+
176
+ def _write_report(rows, out: Path, pending: int, work_dir: Path, report=None) -> None:
177
+ from openinterp.baseline import report as patchscope_report
178
+
179
+ out.parent.mkdir(parents=True, exist_ok=True)
180
+ jsonl = out.with_suffix(".jsonl")
181
+ jsonl.write_text("".join(r.model_dump_json() + "\n" for r in rows))
182
+ table = (report or patchscope_report)(rows)
183
+ out.with_suffix(".md").write_text(table)
184
+ click.echo(table)
185
+ if pending:
186
+ click.echo(f"{pending} experiments await judge answers under {work_dir / 'judge'}.")
187
+ click.echo(f"Wrote {jsonl} and {out.with_suffix('.md')}")
188
+
189
+
190
+ def _answer(model, path: Path):
191
+ try:
192
+ return model.model_validate_json(path.read_text())
193
+ except ValueError as exc:
194
+ raise click.ClickException(f"{path} is not a valid answer; judge it again: {exc}") from exc
195
+
196
+
197
+ def _readouts(records, directory: Path, device: str, dtype: str) -> dict:
198
+ """Each unit's readout, read once under its record's pinned revision and cached."""
199
+ from openinterp.cli import _load_unit_runner
200
+ from openinterp.core.patchscope import PatchscopeReadout
201
+ from openinterp.harness.patchscope import patchscope, write_direction
202
+ from openinterp.harness.units import submission_unit
203
+ from openinterp.reproduce import pinned_environment
204
+
205
+ runners, readouts = {}, {}
206
+ for record in records:
207
+ sub = record.submission
208
+ slug = sub.identifier.slug
209
+ path = directory / f"{slug}.json"
210
+ if slug in readouts:
211
+ continue
212
+ if sub.patchscope is not None:
213
+ readouts[slug] = sub.patchscope
214
+ continue
215
+ if path.exists():
216
+ readouts[slug] = PatchscopeReadout.model_validate_json(path.read_text())
217
+ continue
218
+ revision, pinned = pinned_environment(record)
219
+ key = (sub.identifier.model_name, revision, pinned)
220
+ if key not in runners:
221
+ runners[key] = _load_unit_runner(sub.identifier, device, pinned, revision)
222
+ runner = runners[key]
223
+ click.echo(f"Reading {sub.identifier} through a Patchscope…", err=True)
224
+ readout = patchscope(
225
+ runner, sub.identifier.layer, write_direction(runner, submission_unit(sub))
226
+ )
227
+ path.parent.mkdir(parents=True, exist_ok=True)
228
+ path.write_text(readout.model_dump_json(indent=2))
229
+ readouts[slug] = readout
230
+ return readouts
231
+
232
+
233
+ def _task(record, explanation: str):
234
+ """A judge task on the record's own held-out windows, with ``explanation`` instead."""
235
+ from openinterp.agents.judge import ScoringTask, TaskWindow
236
+
237
+ sub, scores = record.submission, record.verdict.explanation_scores
238
+
239
+ def windows(ws):
240
+ return [TaskWindow(text=w.text, tokens=w.tokens, highlighted=w.highlighted) for w in ws]
241
+
242
+ return ScoringTask(
243
+ identifier=sub.identifier,
244
+ head_profile=sub.head_profile,
245
+ dictionary_profile=sub.dictionary_profile,
246
+ superposition_profile=sub.superposition_profile,
247
+ explanation=explanation,
248
+ threshold=scores.threshold,
249
+ window_tokens=scores.window_tokens,
250
+ quantiles=scores.quantiles,
251
+ quantile_edges=scores.quantile_edges,
252
+ seed=scores.seed,
253
+ corpus=scores.corpus,
254
+ corpus_sha256=scores.corpus_sha256,
255
+ candidate_windows=scores.candidate_windows,
256
+ active_windows=scores.active_windows,
257
+ detection=windows(scores.detection_windows),
258
+ fuzzing=windows(scores.fuzzing_windows),
259
+ )
260
+
261
+
262
+ @cli.command("neuronpedia-baseline")
263
+ @wiki_dir_option()
264
+ @click.option(
265
+ "--work-dir",
266
+ default="exchange/neuronpedia-baseline",
267
+ show_default=True,
268
+ type=click.Path(path_type=Path),
269
+ help="Judge prompts and their answers.",
270
+ )
271
+ @click.option(
272
+ "--judge-model",
273
+ default="external/claude-haiku-5-5",
274
+ show_default=True,
275
+ callback=recorded_model_option,
276
+ help="Write judge prompts for the experiments this judge scored, and record their "
277
+ "answers as its own: the pair is only fair with the same judge.",
278
+ )
279
+ @click.option(
280
+ "--out",
281
+ default="docs/analyses/neuronpedia-baseline",
282
+ show_default=True,
283
+ type=click.Path(path_type=Path),
284
+ help="Writes <out>.jsonl (one row per experiment) and <out>.md (the comparison).",
285
+ )
286
+ def neuronpedia_baseline(wiki_dir, work_dir, judge_model, out):
287
+ """Score Neuronpedia's explanation of each audited latent, against the agent's.
288
+
289
+ Only dictionary latents that Neuronpedia hosts are compared. Each takes the latent's
290
+ first machine-written explanation, word for word. It is scored on the held-out
291
+ windows that the agent's explanation was scored on. Explanations are read from Neuronpedia's
292
+ public API once and cached; nothing is sent to it.
293
+
294
+ \b
295
+ Run it once to write judge prompts under --work-dir.
296
+ Answer each prompt with its own explanation-judge.
297
+ Then run it again to score the answers.
298
+ """
299
+ from openinterp.builder.wiki import load_archive_paths
300
+ from openinterp.crossref import latent_explanations, latent_url, machine_explanation
301
+ from openinterp.neuronpedia_baseline import reading, report
302
+
303
+ records = []
304
+ for _, r in load_archive_paths(wiki_dir):
305
+ ident = r.submission.identifier
306
+ if not (r.verdict and r.verdict.explanation_scores):
307
+ continue
308
+ if ident.kind == "dictionary_feature" and latent_url(
309
+ ident.dictionary, ident.layer, ident.feature_idx
310
+ ):
311
+ records.append(r)
312
+ click.echo(f"{len(records)} experiments on latents Neuronpedia hosts.", err=True)
313
+ rows, pending, links = [], 0, {}
314
+ for record in records:
315
+ ident = record.submission.identifier
316
+ links[ident.slug] = latent_url(ident.dictionary, ident.layer, ident.feature_idx)
317
+ found = latent_explanations(ident.dictionary, ident.layer, ident.feature_idx)
318
+ if found is None:
319
+ raise click.ClickException(f"could not read {links[ident.slug]}; try again later")
320
+ theirs = machine_explanation(found)
321
+ explanation = theirs and theirs.description
322
+ row, waiting = paired_row(
323
+ record,
324
+ explanation,
325
+ reading(theirs and theirs.explainer),
326
+ work_dir,
327
+ judge_model,
328
+ dev=False,
329
+ )
330
+ rows.append(row)
331
+ pending += waiting
332
+ _write_report(rows, out, pending, work_dir, report=lambda rs: report(rs, links))
@@ -0,0 +1,300 @@
1
+ """``open-interpretability benchmark``: freeze, measure, seal and score the explainer benchmark.
2
+
3
+ See docs/benchmark.md. :mod:`openinterp.benchmark` holds the logic that needs no model.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ from pathlib import Path
10
+
11
+ import click
12
+
13
+ from openinterp.cli import cli, recorded_model_option, wiki_option, with_model_options
14
+ from openinterp.core.agent_names import EXTERNAL_PREFIX
15
+
16
+ PRIVATE_SUFFIX = ".private.jsonl" # .gitignore keeps these files out of the repository
17
+
18
+ bench_option = click.option(
19
+ "--bench",
20
+ "bench_dir",
21
+ required=True,
22
+ type=click.Path(exists=True, file_okay=False, path_type=Path),
23
+ help="A frozen version, e.g. benchmark/v1.",
24
+ )
25
+
26
+
27
+ @cli.group()
28
+ def benchmark() -> None:
29
+ """The public benchmark for explanation tools (docs/benchmark.md)."""
30
+
31
+
32
+ @benchmark.command()
33
+ @wiki_option
34
+ @click.option("--version", "version", required=True, help="Version name, e.g. v1. Salts the split.")
35
+ @click.option("--out", "out_root", default=Path("benchmark"), show_default=True, type=Path)
36
+ @click.option("--force", is_flag=True, help="Replace an existing, unpublished version.")
37
+ def freeze(wiki_dir, version, out_root, force):
38
+ """Build a version from the registry's records: units, split and dev probes."""
39
+ from openinterp import benchmark as bench
40
+ from openinterp.builder.wiki import load_archive
41
+
42
+ out_dir = out_root / version
43
+ if (out_dir / bench.MANIFEST).exists() and not force:
44
+ raise click.ClickException(f"{out_dir} exists; versions are frozen (use a new version)")
45
+ frozen = bench.freeze(load_archive(wiki_dir), version)
46
+ bench.write(frozen, out_dir)
47
+ m = frozen.manifest
48
+ click.echo(
49
+ f"Wrote {out_dir}: {m['units']['dev']} dev units ({m['dev_probes']} probes), "
50
+ f"{m['units']['test']} test units awaiting fresh probes"
51
+ )
52
+
53
+
54
+ @benchmark.command()
55
+ @bench_option
56
+ @wiki_option
57
+ @click.option("--unit", "slug", required=True, help="A test unit's slug.")
58
+ @click.option(
59
+ "--probes",
60
+ "probes_file",
61
+ required=True,
62
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
63
+ help="ProbeSet JSON, e.g. a reviewer's answer to `open-interpretability review --emit-prompt`.",
64
+ )
65
+ @click.option(
66
+ "--labels",
67
+ "labels_path",
68
+ required=True,
69
+ type=Path,
70
+ help=f"The private labels file (name ending {PRIVATE_SUFFIX}). Rows are appended.",
71
+ )
72
+ @with_model_options
73
+ def measure(bench_dir, wiki_dir, slug, probes_file, labels_path, device, dtype, **_):
74
+ """Measure fresh probes for one test unit, and append their labels to a private file."""
75
+ from openinterp import benchmark as bench
76
+ from openinterp.agents.review_measurements import measure_probes, settle_first_token_floor
77
+ from openinterp.agents.reviewer import ProbeSet
78
+ from openinterp.cli import _load_unit_runner
79
+ from openinterp.core.paths import experiments_dir
80
+ from openinterp.core.schemas import AuditRecord, ReviewPolicy
81
+
82
+ if not labels_path.name.endswith(PRIVATE_SUFFIX):
83
+ raise click.ClickException(f"--labels must end with {PRIVATE_SUFFIX}, which git ignores")
84
+ unit = bench.read_units(bench_dir).get(slug)
85
+ if unit is None or unit.split != "test":
86
+ raise click.ClickException(f"{slug} is not a test unit of {bench_dir}")
87
+ path = experiments_dir(wiki_dir) / slug / f"{unit.records[-1]}.json"
88
+ record = AuditRecord.model_validate_json(path.read_text(encoding="utf-8"))
89
+ probes = ProbeSet.model_validate_json(probes_file.read_text()).probes
90
+ runner = _load_unit_runner(record.submission.identifier, device, dtype, unit.model_revision)
91
+ policy = record.verdict.policy or ReviewPolicy()
92
+ _, measured_unit, scale = settle_first_token_floor(record.submission, runner, policy)
93
+ threshold = policy.activation_threshold * scale
94
+ results, _, _ = measure_probes(runner, measured_unit, probes, scale, threshold)
95
+ rows = [
96
+ {"unit": slug, "text": r.prompt, "active": r.passed == r.expected_active, "kind": r.kind}
97
+ for r in results
98
+ if r.measured
99
+ ]
100
+ labels_path.parent.mkdir(parents=True, exist_ok=True)
101
+ with labels_path.open("a", encoding="utf-8") as f:
102
+ f.writelines(json.dumps(r, sort_keys=True, ensure_ascii=False) + "\n" for r in rows)
103
+ active = sum(r["active"] for r in rows)
104
+ click.echo(f"{slug}: appended {len(rows)} probes ({active} active) to {labels_path}")
105
+
106
+
107
+ @benchmark.command()
108
+ @bench_option
109
+ @click.option(
110
+ "--labels", "labels_path", required=True, type=click.Path(exists=True, path_type=Path)
111
+ )
112
+ def seal(bench_dir, labels_path):
113
+ """Sort the private test labels and publish their SHA-256 in the manifest."""
114
+ from openinterp import benchmark as bench
115
+
116
+ try:
117
+ manifest = bench.seal(bench_dir, labels_path)
118
+ except ValueError as exc:
119
+ raise click.ClickException(str(exc)) from exc
120
+ click.echo(f"Sealed {manifest['test_probes']} test probes: {manifest['test_labels_sha256']}")
121
+
122
+
123
+ @benchmark.command()
124
+ @bench_option
125
+ @click.option("--split", type=click.Choice(["dev", "test"]), default="dev", show_default=True)
126
+ @click.option(
127
+ "--explanations",
128
+ required=True,
129
+ help="JSONL of {unit, explanation}, or `registry` for the registry's own explanations.",
130
+ )
131
+ @click.option(
132
+ "--labels",
133
+ "labels_path",
134
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
135
+ help="The private test labels; must match the manifest's hash.",
136
+ )
137
+ @click.option(
138
+ "--judge-model",
139
+ required=True,
140
+ callback=recorded_model_option,
141
+ help="LiteLLM model string, or external/<name> to answer prompt files.",
142
+ )
143
+ @click.option(
144
+ "--out",
145
+ "out_path",
146
+ required=True,
147
+ type=Path,
148
+ help="Per-unit results (JSONL). Units already in it are not judged again. "
149
+ "The summary goes next to it as <name>.summary.json.",
150
+ )
151
+ @click.option("--limit", type=int, help="Score only the first N units, for a cheap trial.")
152
+ @click.option(
153
+ "--order",
154
+ type=click.Choice(["slug", "shuffled"]),
155
+ default="slug",
156
+ show_default=True,
157
+ help="The order --limit takes units in. `shuffled` is fixed by the version, so the first "
158
+ "N units are a random sample of the split. `slug` resumes results files from before it.",
159
+ )
160
+ @click.option(
161
+ "--prompts-dir",
162
+ type=click.Path(file_okay=False, path_type=Path),
163
+ help="With an external/<name> judge: write the prompt of every unit without an answer "
164
+ "to this directory at once, and score the units whose answers are there. Run the "
165
+ "command again when the answers are written.",
166
+ )
167
+ def score(
168
+ bench_dir, split, explanations, labels_path, judge_model, out_path, limit, order, prompts_dir
169
+ ):
170
+ """Apply each explanation to its unit's probes with a judge, and score the labels.
171
+
172
+ With ``--prompts-dir``, many judges answer at once, one prompt file each. The summary
173
+ is written only when every explained unit has an answer.
174
+ """
175
+ from openinterp import benchmark as bench
176
+
177
+ if prompts_dir and not judge_model.startswith(EXTERNAL_PREFIX):
178
+ raise click.UsageError(f"--prompts-dir needs an {EXTERNAL_PREFIX}<name> judge model")
179
+ try:
180
+ probes = bench.load_labels(bench_dir, split, labels_path)
181
+ except ValueError as exc:
182
+ raise click.ClickException(str(exc)) from exc
183
+ units = [u for u in bench.read_units(bench_dir).values() if u.split == split]
184
+ split_units = len(units)
185
+ version = bench.read_manifest(bench_dir)["version"]
186
+ units = bench.ordered(units, order, version)[:limit]
187
+ probes = {u.unit: probes[u.unit] for u in units}
188
+ explained = _explanations(bench_dir, split, explanations)
189
+ done = {r["unit"]: r for r in bench.read_jsonl(out_path)} if out_path.exists() else {}
190
+ judge = _file_judge(prompts_dir) if prompts_dir else _judge(judge_model)
191
+
192
+ out_path.parent.mkdir(parents=True, exist_ok=True)
193
+ with out_path.open("a", encoding="utf-8") as f:
194
+
195
+ def write(row):
196
+ f.write(json.dumps(row, sort_keys=True) + "\n")
197
+ f.flush()
198
+ click.echo(f"{row['unit']}: {row['balanced_accuracy']:.3f}", err=True)
199
+
200
+ rows = bench.score(probes, explained, judge, done=done, on_row=write)
201
+ pending = len({u.unit for u in units} & set(explained)) - len(rows)
202
+ if pending:
203
+ click.echo(
204
+ f"{pending} unit(s) wait for a judge's answer, one prompt each in {prompts_dir}. "
205
+ "Run this command again when they are answered."
206
+ )
207
+ return
208
+ meta = {"split": split, "explanations": explanations, "judge_model": judge_model}
209
+ meta |= {"limit": limit, "order": order}
210
+ _write_summary(bench_dir, out_path, rows, units, meta, split_units)
211
+
212
+
213
+ def _write_summary(
214
+ bench_dir: Path, out_path: Path, rows, units, meta: dict, split_units: int
215
+ ) -> None:
216
+ """Write ``<out>.summary.json`` next to ``out_path``, and print the split's score.
217
+
218
+ A run of part of a split is a random sample of it only in shuffled order.
219
+ """
220
+ from openinterp import benchmark as bench
221
+
222
+ version = bench.read_manifest(bench_dir)["version"]
223
+ summary = {"benchmark": version, **meta, **bench.summarize(rows, units, 0, split_units)}
224
+ part = len(units) < split_units
225
+ summary["random_sample"] = not part or meta["order"] == "shuffled"
226
+ summary_path = out_path.with_name(out_path.name.removesuffix(".jsonl") + ".summary.json")
227
+ summary_path.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n")
228
+ click.echo(
229
+ f"{meta['split']}: mean balanced accuracy {summary['mean_balanced_accuracy']} over "
230
+ f"{summary['units']} units ({summary['explained']} explained), 95% CI {summary['ci95']}"
231
+ )
232
+ if part:
233
+ sample = "a random sample" if summary["random_sample"] else "not a random sample"
234
+ click.echo(f"These are {len(units)} of the split's {split_units} units: {sample} of it.")
235
+ flagged = summary["listed_nearly_all"]
236
+ if flagged:
237
+ click.echo(
238
+ f"Warning: the judge listed at least {bench.LISTED_ALL_SHARE:.0%} of the texts for "
239
+ f"{len(flagged)} unit(s): {', '.join(flagged)}. An explanation that tells the judge "
240
+ "to list every text looks like this, so read those explanations (#3303)."
241
+ )
242
+
243
+
244
+ def _explanations(bench_dir: Path, split: str, source: str) -> dict[str, str]:
245
+ from openinterp import benchmark as bench
246
+
247
+ files = {"dev": bench.DEV_EXPLANATIONS, "test": bench.TEST_EXPLANATIONS}
248
+ rows = bench.read_jsonl(bench_dir / files[split] if source == "registry" else Path(source))
249
+ return {r["unit"]: r["explanation"] for r in rows}
250
+
251
+
252
+ def _judge(model: str):
253
+ """``judge(unit, explanation, texts)``: which texts the explanation says make it fire."""
254
+ from openinterp.agents.judge import ExplanationJudge, TaskWindow, answered
255
+
256
+ agent = ExplanationJudge(model)
257
+
258
+ def judge(unit: str, explanation: str, texts: list[str]) -> list[bool]:
259
+ windows = [TaskWindow(text=t, tokens=[t]) for t in texts]
260
+ answer = agent.detect(explanation, windows)
261
+ return answered(answer.active, len(texts), "detection")
262
+
263
+ return judge
264
+
265
+
266
+ def _file_judge(directory: Path):
267
+ """A judge that reads each unit's answer from ``directory``, or asks for it there.
268
+
269
+ A unit's prompt is ``<unit>.prompt.md``, with ``--`` for each ``/`` of the slug. It is
270
+ the prompt that an ``external/<name>`` judge writes, and it names the answer file,
271
+ ``<unit>.json``. The judge returns ``None`` until that answer exists. A bad answer is
272
+ moved to ``<unit>.rejected.json`` with the reason in ``<unit>.error.txt``. Then the
273
+ unit waits for a new answer.
274
+ """
275
+ from pydantic import ValidationError
276
+
277
+ from openinterp.agents.judge import DetectionAnswer, ExplanationJudge, TaskWindow, answered
278
+
279
+ directory.mkdir(parents=True, exist_ok=True)
280
+
281
+ def judge(unit: str, explanation: str, texts: list[str]) -> list[bool] | None:
282
+ name = unit.replace("/", "--")
283
+ answer_path, error_path = directory / f"{name}.json", directory / f"{name}.error.txt"
284
+ if answer_path.exists():
285
+ try:
286
+ answer = DetectionAnswer.model_validate_json(answer_path.read_text())
287
+ result = answered(answer.active, len(texts), "detection")
288
+ except (ValidationError, ValueError) as exc:
289
+ error_path.write_text(f"{exc}\n", encoding="utf-8")
290
+ answer_path.replace(directory / f"{name}.rejected.json")
291
+ else:
292
+ error_path.unlink(missing_ok=True)
293
+ return result
294
+ windows = [TaskWindow(text=t, tokens=[t]) for t in texts]
295
+ prompt = ExplanationJudge.detection_prompt(explanation, windows)
296
+ text = ExplanationJudge.render_prompt(DetectionAnswer, prompt, answer_path)
297
+ (directory / f"{name}.prompt.md").write_text(text, encoding="utf-8")
298
+ return None
299
+
300
+ return judge