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
openinterp/cli_loop.py ADDED
@@ -0,0 +1,125 @@
1
+ """Run experiments back to back from the CLI, with no Claude session.
2
+
3
+ The command is ``open-interpretability loop``.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import subprocess
10
+ from pathlib import Path
11
+
12
+ import click
13
+
14
+ from openinterp.cli import cli
15
+ from openinterp.core.agent_names import EXTERNAL_PREFIX
16
+
17
+
18
+ def _api_model(_ctx, param, value: str) -> str:
19
+ """Refuse ``external/<name>``: nobody is there to answer its prompt files."""
20
+ if value.startswith(EXTERNAL_PREFIX):
21
+ raise click.BadParameter(
22
+ f"{value} needs someone to answer prompt files; use scripts/experiment-loop.sh, "
23
+ "which drives Claude Code subagents, or give a LiteLLM model.",
24
+ param=param,
25
+ )
26
+ return value
27
+
28
+
29
+ @cli.command(name="loop")
30
+ @click.option("--proposer", required=True, callback=_api_model, help="LiteLLM proposer model.")
31
+ @click.option(
32
+ "--reviewer",
33
+ required=True,
34
+ callback=_api_model,
35
+ help="LiteLLM reviewer model. A review draw of this model's own record is drawn again.",
36
+ )
37
+ @click.option(
38
+ "--max",
39
+ "max_experiments",
40
+ default=0,
41
+ show_default=True,
42
+ help="Stop after N experiments; 0 runs until stopped.",
43
+ )
44
+ @click.option(
45
+ "--epsilon",
46
+ default=0.7,
47
+ show_default=True,
48
+ type=click.FloatRange(0, 1),
49
+ help="Exploration probability, as in `open-interpretability next`.",
50
+ )
51
+ @click.option(
52
+ "--corpus",
53
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
54
+ help="Scan corpus. Default: each new scan builds a fresh `mixed` corpus.",
55
+ )
56
+ @click.option(
57
+ "--worktree",
58
+ type=click.Path(file_okay=False, path_type=Path),
59
+ help="Worktree to run in. Default: ../<repo>-loop, created if missing.",
60
+ )
61
+ @click.option(
62
+ "--one-heavy-job",
63
+ is_flag=True,
64
+ help="Queue behind a machine-wide lock before loading the model (openinterp/core/"
65
+ "heavy_lock.py). The loop keeps its model loaded, so it holds the lock until it ends.",
66
+ )
67
+ @click.option(
68
+ "--max-failures",
69
+ default=3,
70
+ show_default=True,
71
+ type=click.IntRange(1),
72
+ help="Stop after this many failed experiments in a row.",
73
+ )
74
+ def loop_command(
75
+ proposer, reviewer, max_experiments, epsilon, corpus, worktree, one_heavy_job, max_failures
76
+ ):
77
+ """Run experiments back to back: draw, claim, audit, review, post and land each one.
78
+
79
+ Each runs in a detached worktree reset to origin/main. A model loads once for the
80
+ whole loop. Logs go to logs/loop/, one per experiment, and each prints a RESULT line.
81
+ The loop honours `open-interpretability pause` and the stop file of scripts/experiment-loop.sh.
82
+ """
83
+ import time
84
+
85
+ from openinterp import runner_cache
86
+ from openinterp.experiment_loop import Loop, Options
87
+ from openinterp.planner import open_pr_claims, plan_next
88
+
89
+ repo = Path(_git("rev-parse", "--show-toplevel"))
90
+ worktree = (worktree or repo.parent / f"{repo.name}-loop").resolve()
91
+ corpus = corpus and str(corpus.resolve())
92
+ if not worktree.exists():
93
+ _git("fetch", "--quiet", "origin", "main")
94
+ _git("worktree", "add", "--detach", str(worktree), "origin/main")
95
+ if reviewer == proposer:
96
+ click.echo(
97
+ f"warning: {proposer} both proposes and reviews, so reviews are "
98
+ "self-reviewed; pass another --reviewer for independent ones.",
99
+ err=True,
100
+ )
101
+ if one_heavy_job: # every model load in this process, and every child, takes the lock
102
+ from openinterp.core.heavy_lock import ENABLE_ENV
103
+
104
+ os.environ[ENABLE_ENV] = "1"
105
+ runner_cache.keep()
106
+ os.chdir(worktree)
107
+ options = Options(proposer, reviewer, epsilon, corpus)
108
+ loop = Loop(
109
+ options,
110
+ repo / "logs" / "loop",
111
+ max_experiments,
112
+ max_failures,
113
+ plan_next,
114
+ open_pr_claims,
115
+ time.sleep,
116
+ )
117
+ raise SystemExit(loop.run())
118
+
119
+
120
+ def _git(*args: str) -> str:
121
+ """Run git in the current directory and return its stdout."""
122
+ done = subprocess.run(["git", *args], capture_output=True, text=True, check=False)
123
+ if done.returncode != 0:
124
+ raise click.ClickException(f"git {args[0]} failed: {done.stderr.strip()}")
125
+ return done.stdout.strip()
@@ -0,0 +1,28 @@
1
+ """The ``--memory`` option: load a model whole, or stream it from disk.
2
+
3
+ It is its own module so that the CLI can import it without importing torch.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import click
9
+
10
+
11
+ def _request_memory(_ctx, _param, value: str) -> str:
12
+ from openinterp.harness.memory import request
13
+
14
+ request(value)
15
+ return value
16
+
17
+
18
+ memory_option = click.option(
19
+ "--memory",
20
+ type=click.Choice(["auto", "normal", "stream"]),
21
+ default="auto",
22
+ show_default=True,
23
+ expose_value=False,
24
+ callback=_request_memory,
25
+ help="stream: keep the decoder layers on disk and read them each pass, for a model "
26
+ "larger than RAM; much slower. auto streams only when the model doesn't fit in free "
27
+ "RAM and swap. See docs/experiments.md, Memory.",
28
+ )
@@ -0,0 +1,175 @@
1
+ """Neuronpedia's explanations through the adversarial review.
2
+
3
+ The command is ``open-interpretability neuronpedia-review``.
4
+ See :mod:`openinterp.neuronpedia_review` for the rule and the comparison.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from pathlib import Path
11
+
12
+ import click
13
+
14
+ from openinterp.cli import cli, recorded_model_option, wiki_dir_option, with_model_options
15
+
16
+ N_PROBES = 20
17
+
18
+
19
+ @cli.command("neuronpedia-review")
20
+ @wiki_dir_option()
21
+ @click.option(
22
+ "--work-dir",
23
+ default="exchange/neuronpedia-review",
24
+ show_default=True,
25
+ type=click.Path(path_type=Path),
26
+ help="Submissions, reviewer prompts, probe sets and measured verdicts.",
27
+ )
28
+ @click.option(
29
+ "--reviewer-model",
30
+ default="external/claude-sonnet-5-5",
31
+ show_default=True,
32
+ callback=recorded_model_option,
33
+ help="The model that wrote the probe sets under --work-dir.",
34
+ )
35
+ @click.option(
36
+ "--out",
37
+ default="docs/analyses/neuronpedia-review",
38
+ show_default=True,
39
+ type=click.Path(path_type=Path),
40
+ help="Writes <out>.jsonl (one row per latent) and <out>.md (the comparison).",
41
+ )
42
+ @with_model_options
43
+ def neuronpedia_review(wiki_dir, work_dir, reviewer_model, out, device, dtype):
44
+ """Review Neuronpedia's explanation of each audited latent, against the agent's.
45
+
46
+ Nothing is written to the registry, and nothing is sent to Neuronpedia.
47
+
48
+ \b
49
+ Run it once to write a reviewer prompt per latent under --work-dir.
50
+ Answer each prompt with its own neuron-reviewer.
51
+ Then run it again to measure the probes and write the comparison.
52
+ """
53
+ from openinterp.neuronpedia_review import report
54
+
55
+ rows, pending, runners = [], 0, {}
56
+ for slug, record in sorted(_newest_latent_records(wiki_dir).items()):
57
+ row = _row(record, work_dir / slug, reviewer_model, runners, device)
58
+ if row is None:
59
+ continue
60
+ pending += row.neuronpedia is None
61
+ rows.append(row)
62
+ out.parent.mkdir(parents=True, exist_ok=True)
63
+ out.with_suffix(".jsonl").write_text("".join(r.model_dump_json() + "\n" for r in rows))
64
+ out.with_suffix(".md").write_text(report(rows))
65
+ click.echo(report(rows))
66
+ if pending:
67
+ click.echo(f"{pending} latents await probe sets under {work_dir}.")
68
+ click.echo(f"Wrote {out.with_suffix('.jsonl')} and {out.with_suffix('.md')}")
69
+
70
+
71
+ def _newest_latent_records(wiki_dir) -> dict:
72
+ """The newest reviewed record of each dictionary latent that Neuronpedia hosts, by slug."""
73
+ from openinterp.builder.wiki import load_archive_paths
74
+ from openinterp.crossref import latent_url
75
+
76
+ newest = {}
77
+ for _, r in load_archive_paths(wiki_dir):
78
+ ident = r.submission.identifier
79
+ if ident.kind != "dictionary_feature" or r.verdict is None or r.verdict.metrics is None:
80
+ continue
81
+ if latent_url(ident.dictionary, ident.layer, ident.feature_idx) is None:
82
+ continue
83
+ old = newest.get(ident.slug)
84
+ if old is None or r.verdict.timestamp > old.verdict.timestamp:
85
+ newest[ident.slug] = r
86
+ return newest
87
+
88
+
89
+ def _row(record, unit_dir: Path, reviewer_model: str, runners: dict, device: str):
90
+ """The latent's ReviewRow; ``None`` if Neuronpedia has no machine-written explanation."""
91
+ from openinterp.builder.wiki import experiment_id
92
+ from openinterp.crossref import latent_explanations, latent_url, machine_explanation
93
+ from openinterp.neuronpedia_review import ReviewRow, side
94
+
95
+ ident = record.submission.identifier
96
+ found = latent_explanations(ident.dictionary, ident.layer, ident.feature_idx)
97
+ if found is None:
98
+ raise click.ClickException(f"could not read Neuronpedia for {ident}; try again later")
99
+ theirs = machine_explanation(found)
100
+ if theirs is None:
101
+ return None
102
+ sub = baseline_submission(record, theirs)
103
+ verdict = _verdict(record, sub, unit_dir, reviewer_model, runners, device)
104
+ return ReviewRow(
105
+ slug=ident.slug,
106
+ experiment_id=experiment_id(record),
107
+ url=latent_url(ident.dictionary, ident.layer, ident.feature_idx),
108
+ agent_status=record.verdict.status,
109
+ agent_explanation=record.submission.natural_language_explanation,
110
+ neuronpedia_explanation=theirs.description,
111
+ explainer=theirs.explainer,
112
+ reviewer_model=verdict and reviewer_model,
113
+ agent=side(record.verdict.metrics),
114
+ neuronpedia=verdict and side(verdict.metrics),
115
+ )
116
+
117
+
118
+ def baseline_submission(record, theirs):
119
+ """A copy of the record's submission that claims only Neuronpedia's explanation.
120
+
121
+ It claims no activating tokens and a retrospective mechanism, so no claim of the
122
+ agent's reaches the reviewer. It is credited to Neuronpedia's explainer, so the review
123
+ counts as independent. It keeps the scan evidence the reviewer sees for any hypothesis.
124
+ """
125
+ from openinterp.cli import _clear_costs
126
+
127
+ sub = _clear_costs(record.submission)
128
+ return sub.model_copy(
129
+ update={
130
+ "natural_language_explanation": theirs.description,
131
+ "activating_tokens": [],
132
+ "lookahead": sub.lookahead
133
+ and sub.lookahead.model_copy(
134
+ update={"is_lookahead": False, "target_upcoming_tokens": []}
135
+ ),
136
+ "submitting_agent_model": f"neuronpedia/{theirs.explainer}",
137
+ "contributor": None,
138
+ "supersedes": None,
139
+ "sister_of": None,
140
+ "prior_art": None, # else the reviewer reads Neuronpedia's text twice
141
+ }
142
+ )
143
+
144
+
145
+ def _verdict(record, sub, unit_dir: Path, reviewer_model: str, runners: dict, device: str):
146
+ """The measured verdict of ``sub``: cached, or measured now, or ``None`` without probes.
147
+
148
+ The first time, it writes the reviewer's prompt.
149
+ """
150
+ from openinterp.agents.reviewer import ProbeSet, ReviewerAgent
151
+ from openinterp.cli import _load_unit_runner
152
+ from openinterp.cli_review import refuse_unisolated, write_review_prompt
153
+ from openinterp.core.schemas import VerificationVerdict
154
+ from openinterp.reproduce import pinned_environment
155
+
156
+ prompt, probes = unit_dir / "review.prompt.md", unit_dir / "review.probes.json"
157
+ measured = unit_dir / "verdict.json"
158
+ (unit_dir / "submission.json").parent.mkdir(parents=True, exist_ok=True)
159
+ (unit_dir / "submission.json").write_text(sub.model_dump_json(indent=2))
160
+ if measured.exists():
161
+ return VerificationVerdict.model_validate_json(measured.read_text())
162
+ if not probes.exists():
163
+ if not prompt.exists():
164
+ write_review_prompt(sub, prompt, N_PROBES, full_snippets=False)
165
+ return None
166
+ refuse_unisolated(probes)
167
+ revision, pinned = pinned_environment(record)
168
+ key = (sub.identifier.model_name, revision, pinned)
169
+ if key not in runners:
170
+ runners[key] = _load_unit_runner(sub.identifier, device, pinned, revision)
171
+ click.echo(f"Measuring the probes for {sub.identifier}…", err=True)
172
+ probe_set = ProbeSet.model_validate_json(probes.read_text()).probes
173
+ verdict = ReviewerAgent(reviewer_model).review(sub, runners[key], probes=probe_set)
174
+ measured.write_text(json.dumps(json.loads(verdict.model_dump_json()), indent=2))
175
+ return verdict
@@ -0,0 +1,45 @@
1
+ """Stop new experiments for a while.
2
+
3
+ The commands are ``open-interpretability pause`` and ``open-interpretability resume``.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import click
9
+
10
+ from openinterp.cli import cli
11
+ from openinterp.core import pause
12
+
13
+
14
+ @cli.command(name="pause")
15
+ @click.option("--reason", default="a measurement needs a quiet machine", show_default=True)
16
+ @click.option(
17
+ "--for",
18
+ "minutes",
19
+ default=pause.DEFAULT_MINUTES,
20
+ show_default=True,
21
+ type=click.FloatRange(min=0, min_open=True),
22
+ help="Minutes until the pause ends by itself.",
23
+ )
24
+ @click.option(
25
+ "--status",
26
+ is_flag=True,
27
+ help=f"Only show the pause. Exit {pause.EXIT_PAUSED} if there is one, else 0.",
28
+ )
29
+ def pause_command(reason, minutes, status):
30
+ """Stop new experiments on this machine; the ones that run go on to the end.
31
+
32
+ While the pause lasts, `open-interpretability next` draws nothing and
33
+ scripts/experiment-loop.sh waits. See docs/experiments.md.
34
+ """
35
+ if status:
36
+ current = pause.read()
37
+ click.echo(current.describe() if current else "New experiments are not paused.")
38
+ raise SystemExit(pause.EXIT_PAUSED if current else 0)
39
+ click.echo(pause.start(reason, minutes).describe())
40
+
41
+
42
+ @cli.command(name="resume")
43
+ def resume_command():
44
+ """End a pause that `open-interpretability pause` started."""
45
+ click.echo("Resumed new experiments." if pause.stop() else "New experiments were not paused.")
@@ -0,0 +1,133 @@
1
+ """The ``pole-effects`` command: each pole's estimated effect on the loss (issue #3486)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import random
7
+ from datetime import UTC, datetime
8
+ from pathlib import Path
9
+
10
+ import click
11
+
12
+ from openinterp.cli import cli, with_model_options
13
+
14
+
15
+ @cli.command(name="pole-effects")
16
+ @click.option("--model", "model_name", required=True, help="Hugging Face model ID.")
17
+ @click.option(
18
+ "--corpus",
19
+ type=click.Path(exists=True, path_type=Path),
20
+ default="corpus.jsonl",
21
+ show_default=True,
22
+ help="Text for the windows.",
23
+ )
24
+ @click.option(
25
+ "--windows",
26
+ default=64,
27
+ show_default=True,
28
+ type=click.IntRange(1),
29
+ help="Windows to fit the pole means on, and as many again to measure on.",
30
+ )
31
+ @click.option("--window-tokens", default=128, show_default=True, type=click.IntRange(8))
32
+ @click.option("--batch", default=4, show_default=True, type=click.IntRange(1))
33
+ @click.option("--seed", default=0, show_default=True, type=int)
34
+ @click.option(
35
+ "--top",
36
+ default=2000,
37
+ show_default=True,
38
+ type=click.IntRange(1),
39
+ help="Poles kept in the table, largest estimated effect first.",
40
+ )
41
+ @click.option(
42
+ "--check",
43
+ default=60,
44
+ show_default=True,
45
+ type=click.IntRange(0),
46
+ help="Poles to measure exactly, half from the top 1% and half uniform.",
47
+ )
48
+ @click.option(
49
+ "--out",
50
+ type=click.Path(dir_okay=False, path_type=Path),
51
+ help="Default: data/pole-effects/<model>.json, which the planner reads.",
52
+ )
53
+ @with_model_options
54
+ def pole_effects(
55
+ model_name, corpus, windows, window_tokens, batch, seed, top, check, out, device, dtype
56
+ ):
57
+ """Estimate each MLP pole's effect on the loss, and write the largest for the planner.
58
+
59
+ The estimate is attribution patching of single-pole mean ablation
60
+ (openinterp/pole_effects.py). --check measures some poles exactly and reports the
61
+ Spearman correlation with the estimate.
62
+ """
63
+ from openinterp import __version__
64
+ from openinterp.cli import _load_runner
65
+ from openinterp.cli_evidence import read_corpus
66
+ from openinterp.coverage import windows as draw_windows
67
+ from openinterp.planner_effects import table_path
68
+ from openinterp.pole_effects import estimate, top_poles
69
+
70
+ runner = _load_runner(model_name, device, dtype)
71
+ texts, corpus_name, corpus_sha, _ = read_corpus(corpus)
72
+ fit, test = draw_windows(runner, texts, windows, window_tokens, seed)
73
+ effects = estimate(runner, fit, test, range(runner.n_layers), batch)
74
+ table = {
75
+ "model": model_name,
76
+ "corpus": corpus_name,
77
+ "corpus_sha256": corpus_sha,
78
+ "windows": windows,
79
+ "window_tokens": window_tokens,
80
+ "seed": seed,
81
+ "dtype": dtype,
82
+ "openinterp": __version__,
83
+ "date": datetime.now(UTC).strftime("%Y-%m-%d"),
84
+ "method": "attribution patching of single-pole mean ablation",
85
+ "poles_total": sum(v.numel() for v in effects.values()),
86
+ "check": _check(runner, fit, test, effects, check, seed, batch),
87
+ "poles": top_poles(effects, top),
88
+ }
89
+ out = out or table_path(Path("."), model_name)
90
+ out.parent.mkdir(parents=True, exist_ok=True)
91
+ out.write_text(json.dumps(table, indent=1) + "\n")
92
+ rho = table["check"].get("spearman")
93
+ click.echo(
94
+ f"Wrote {len(table['poles'])} poles to {out}"
95
+ + (f"; Spearman {rho:.2f} on {check} checked poles" if rho is not None else "")
96
+ )
97
+
98
+
99
+ def _check(runner, fit, test, effects, n: int, seed: int, batch: int) -> dict:
100
+ """Measure ``n`` poles exactly, half from the estimate's top 1% and half uniform."""
101
+ import torch
102
+
103
+ from openinterp.core.stats import spearman
104
+ from openinterp.coverage import mean_loss
105
+ from openinterp.pole_effects import exact_effect, top_poles
106
+
107
+ if n == 0:
108
+ return {}
109
+ rng = random.Random(seed)
110
+ total = sum(v.numel() for v in effects.values())
111
+ head = top_poles(effects, max(n, total // 100))
112
+ sample = [(r["layer"], r["neuron"], r["pole"]) for r in rng.sample(head, n // 2)]
113
+ width = next(iter(effects.values())).numel()
114
+ layers = sorted({layer for layer, _ in effects})
115
+ sample += [
116
+ (rng.choice(layers), rng.randrange(width), rng.choice(("positive", "negative")))
117
+ for _ in range(n - n // 2)
118
+ ]
119
+ clean = mean_loss(runner, test, batch)
120
+ rows = [
121
+ {
122
+ "layer": la,
123
+ "neuron": i,
124
+ "pole": p,
125
+ "estimate": float(effects[(la, p)][i]),
126
+ "exact": exact_effect(runner, fit, test, la, i, p, clean, batch),
127
+ }
128
+ for la, i, p in sample
129
+ ]
130
+ rho = spearman(
131
+ torch.tensor([r["estimate"] for r in rows]), torch.tensor([r["exact"] for r in rows])
132
+ )
133
+ return {"poles": n, "spearman": rho, "clean_loss": clean, "rows": rows}
@@ -0,0 +1,119 @@
1
+ """``open-interpretability probe-compare``: a verified pole against linear probes for its concept.
2
+
3
+ See :mod:`openinterp.harness.probing` for the probes and :mod:`openinterp.core.probing`
4
+ for what is reported.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from pathlib import Path
10
+
11
+ import click
12
+
13
+ from openinterp.cli import cli, with_model_options
14
+
15
+
16
+ @cli.command("probe-compare")
17
+ @click.option("--record", required=True, type=click.Path(exists=True, path_type=Path))
18
+ @click.option(
19
+ "--train",
20
+ "train_path",
21
+ required=True,
22
+ type=click.Path(exists=True, path_type=Path),
23
+ help='Labelled JSON lines, {"text": ..., "spans": [[start, end], ...]}: where the '
24
+ "concept holds, marked by a rule that never sees the model.",
25
+ )
26
+ @click.option(
27
+ "--test",
28
+ "test_path",
29
+ type=click.Path(exists=True, path_type=Path),
30
+ help="The same from another source, to test on. Default: held-out documents of --train.",
31
+ )
32
+ @click.option("--concept", required=True, help="What the spans mark, as their rule states it.")
33
+ @click.option("--test-share", default=0.3, show_default=True, type=click.FloatRange(0, 1))
34
+ @click.option("--window-tokens", default=128, show_default=True, type=click.IntRange(2))
35
+ @click.option("--max-positive", default=2000, show_default=True, type=click.IntRange(1))
36
+ @click.option("--max-negative", default=8000, show_default=True, type=click.IntRange(1))
37
+ @click.option("--seed", default=0, show_default=True, type=int)
38
+ @click.option("--out", required=True, type=click.Path(path_type=Path), help="Report JSON.")
39
+ @with_model_options
40
+ def probe_compare(
41
+ record,
42
+ train_path,
43
+ test_path,
44
+ concept,
45
+ test_share,
46
+ window_tokens,
47
+ max_positive,
48
+ max_negative,
49
+ seed,
50
+ out,
51
+ device,
52
+ dtype,
53
+ ):
54
+ """Compare a neuron pole with linear probes for its concept.
55
+
56
+ The probes are logistic, mass-mean and k-sparse. They read the layer's MLP hidden
57
+ activations and the residual stream after the layer.
58
+
59
+ Reported, not gated: it shows whether the concept lives in the neuron or is only
60
+ partly carried by it.
61
+ """
62
+ from openinterp.cli import _load_runner
63
+ from openinterp.core.probing import ProbeComparison
64
+ from openinterp.core.schemas import AuditRecord
65
+ from openinterp.harness.probing import compare
66
+
67
+ sub = AuditRecord.model_validate_json(record.read_text()).submission
68
+ if sub.identifier.kind != "mlp_neuron_pole" or sub.max_activation is None:
69
+ raise click.ClickException("probe-compare needs a neuron pole with a recorded scale.")
70
+ prov = sub.provenance
71
+ runner = _load_runner(
72
+ sub.identifier.model_name, device, dtype, prov.model_revision if prov else None
73
+ )
74
+ train_wins, test_wins = _split(runner, train_path, test_path, test_share, window_tokens, seed)
75
+ try:
76
+ scores = compare(
77
+ runner,
78
+ sub,
79
+ train_wins,
80
+ test_wins,
81
+ max_positive=max_positive,
82
+ max_negative=max_negative,
83
+ seed=seed,
84
+ )
85
+ except ValueError as exc:
86
+ raise click.ClickException(str(exc)) from exc
87
+ report = ProbeComparison(
88
+ concept=concept,
89
+ labels=str(train_path) + (f" → {test_path}" if test_path else ""),
90
+ split="source" if test_path else "document",
91
+ train_source=train_path.name,
92
+ test_source=(test_path or train_path).name,
93
+ window_tokens=window_tokens,
94
+ **scores,
95
+ )
96
+ out.parent.mkdir(parents=True, exist_ok=True)
97
+ out.write_text(report.model_dump_json(indent=2) + "\n")
98
+ _echo_summary(report, out)
99
+
100
+
101
+ def _split(runner, train_path: Path, test_path, test_share: float, window_tokens: int, seed):
102
+ """(training windows, test windows): a held-out source, or a split by document."""
103
+ from openinterp.harness.probing import read_labels, split_documents, windows
104
+
105
+ train_wins = windows(runner.tokenizer, read_labels(train_path), window_tokens)
106
+ if test_path is None:
107
+ return split_documents(train_wins, test_share, seed)
108
+ return train_wins, windows(runner.tokenizer, read_labels(test_path), window_tokens)
109
+
110
+
111
+ def _echo_summary(report, out: Path) -> None:
112
+ n, dense = report.neuron, report.sites[0].logistic
113
+ click.echo(
114
+ f"{report.slug}: neuron BA {n.balanced_accuracy:.3f}"
115
+ f" (line {n.balanced_accuracy_at_line:.3f}, rank {n.rank})"
116
+ f" vs hidden probe {dense.balanced_accuracy:.3f},"
117
+ f" residual {report.sites[1].logistic.balanced_accuracy:.3f};"
118
+ f" cos {report.sites[0].logistic_cosine:+.2f}; k needed {report.neurons_needed} → {out}"
119
+ )