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/signing.py ADDED
@@ -0,0 +1,209 @@
1
+ """Maintainer signatures on experiment records (`open-interpretability sign`).
2
+
3
+ A trusted signer can vouch for a record with their SSH key, so CI need not reproduce
4
+ it. The signature is a separate file, ``<id>.json.sig``, next to the write-once record.
5
+ ``ssh-keygen -Y sign`` makes it in the ``openinterp-record`` namespace. It covers the
6
+ record's exact bytes, so editing the record invalidates it.
7
+
8
+ Signers are listed in ``.github/allowed_signers`` (OpenSSH format, one per line:
9
+ ``<principal> namespaces="openinterp-record" <key type> <public key>``). CI reads that
10
+ file from the pull request's *base* branch, so a pull request can't add its own key.
11
+
12
+ Each key can have a validity window (``valid-after="YYYYMMDDZ"``, ``valid-before=...``).
13
+ A signature is checked at the time it landed on ``main`` (:func:`landing_times`), not at
14
+ the time of the check. So a key revoked with ``valid-before`` set to the start of its
15
+ exposure still vouches for what landed before that time. A signature that a listed key
16
+ made, but that landed outside the key's window, raises :class:`SignatureOutsideWindow`.
17
+ Then the record must be reproduced (``SECURITY.md``).
18
+
19
+ A signature doesn't change the verdict: the record still went through the review
20
+ protocol. It only says the signer vouches that the record is what it claims to be.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import os
26
+ import re
27
+ import subprocess
28
+ import tempfile
29
+ from datetime import UTC, datetime
30
+ from pathlib import Path
31
+
32
+ NAMESPACE = "openinterp-record"
33
+ ALLOWED_SIGNERS = Path(".github/allowed_signers")
34
+ DEFAULT_KEY = Path("~/.ssh/openinterp_signing")
35
+
36
+
37
+ def signing_key() -> Path:
38
+ """The signing key: ``$OPENINTERP_SIGNING_KEY``, else ``~/.ssh/openinterp_signing``."""
39
+ return Path(os.environ.get("OPENINTERP_SIGNING_KEY") or DEFAULT_KEY).expanduser()
40
+
41
+
42
+ class SignatureError(Exception):
43
+ """A signature exists but does not verify against the allowed signers."""
44
+
45
+
46
+ class SignatureOutsideWindow(SignatureError):
47
+ """A listed key made the signature, but the check time is outside the key's window.
48
+
49
+ The key is revoked or expired (``valid-before``), or not yet valid (``valid-after``).
50
+ The signature then vouches for nothing, and the record must be reproduced.
51
+ """
52
+
53
+ def __init__(self, principal: str, at: datetime | None):
54
+ self.principal = principal
55
+ when = "now" if at is None else f"at {at:%Y-%m-%d %H:%M:%S} UTC"
56
+ super().__init__(
57
+ f"signed by {principal}, but that key is not valid {when} (outside its "
58
+ "valid-after/valid-before window in the allowed signers)"
59
+ )
60
+
61
+
62
+ def signature_path(record_path: Path) -> Path:
63
+ """Where the signature of ``record_path`` goes: the same name plus ``.sig``."""
64
+ return record_path.with_name(record_path.name + ".sig")
65
+
66
+
67
+ def sign_record(record_path: Path, key: Path) -> Path:
68
+ """Sign ``record_path`` with the private SSH ``key``; returns the signature's path."""
69
+ sig = signature_path(record_path)
70
+ sig.unlink(missing_ok=True) # ssh-keygen refuses to overwrite
71
+ _ssh_keygen("-Y", "sign", "-f", str(key), "-n", NAMESPACE, str(record_path))
72
+ return sig
73
+
74
+
75
+ def auto_sign(record_path: Path, allowed_signers: Path = ALLOWED_SIGNERS) -> str | None:
76
+ """Sign a newly archived record if this machine holds a trusted signing key.
77
+
78
+ Returns the signer's principal. Returns ``None`` when signing is off
79
+ (``OPENINTERP_AUTO_SIGN=0``), when there is no key, or when the key isn't in
80
+ ``allowed_signers``. An untrusted signature would only make CI fail.
81
+ """
82
+ if os.environ.get("OPENINTERP_AUTO_SIGN", "1").lower() in {"0", "false", "no"}:
83
+ return None
84
+ key = signing_key()
85
+ public = key.with_name(key.name + ".pub")
86
+ if not key.exists() or not public.exists() or not allowed_signers.exists():
87
+ return None
88
+ signers = allowed_signers.read_text(encoding="utf-8")
89
+ if public.read_text(encoding="utf-8").split()[1] not in signers.split():
90
+ return None
91
+ sign_record(record_path, key)
92
+ try:
93
+ return verify_record(record_path, signers)
94
+ except SignatureError:
95
+ signature_path(record_path).unlink() # e.g. an expired key: CI would not trust it
96
+ raise
97
+
98
+
99
+ def verify_record(
100
+ record_path: Path, allowed_signers: str, at: datetime | None = None
101
+ ) -> str | None:
102
+ """The principal who signed ``record_path``, or ``None`` if it has no signature.
103
+
104
+ ``allowed_signers`` is the *content* of an allowed-signers file. ``at`` is the time to
105
+ check each key's validity window at (default: now). Raises
106
+ :class:`SignatureOutsideWindow` if a listed key made the signature but is not valid
107
+ at ``at``. Raises :class:`SignatureError` if a signature exists but no allowed signer
108
+ made it over these exact bytes.
109
+ """
110
+ sig = signature_path(record_path)
111
+ if not sig.exists():
112
+ return None
113
+ principal, _ = _signed_by(record_path, allowed_signers, at)
114
+ if principal:
115
+ return principal
116
+ principal, listed = _signed_by(record_path, without_windows(allowed_signers), None)
117
+ if principal:
118
+ raise SignatureOutsideWindow(principal, at)
119
+ raise SignatureError(
120
+ f"{sig.name} is not a valid signature of this record by an allowed signer"
121
+ + ("" if listed else " (its key is not in the allowed signers)")
122
+ )
123
+
124
+
125
+ def without_windows(allowed_signers: str) -> str:
126
+ """``allowed_signers`` with every ``valid-after`` and ``valid-before`` option removed."""
127
+ window = re.compile(r'\bvalid-(?:after|before)=(?:"[^"]*"|[^,\s]*),?')
128
+ lines = (window.sub("", line) for line in allowed_signers.splitlines())
129
+ return "\n".join(re.sub(r",(?=\s)", "", line) for line in lines) + "\n"
130
+
131
+
132
+ def _signed_by(record_path: Path, allowed_signers: str, at: datetime | None):
133
+ """(principal who signed at ``at`` or ``None``, whether any listed key matched)."""
134
+ sig = signature_path(record_path)
135
+ when = [] if at is None else [f"-Overify-time={at.astimezone(UTC):%Y%m%d%H%M%S}Z"]
136
+ with tempfile.NamedTemporaryFile("w", suffix=".allowed_signers", delete=False) as fh:
137
+ fh.write(allowed_signers)
138
+ signers = fh.name
139
+ try:
140
+ found = _ssh_keygen(
141
+ "-Y", "find-principals", "-s", str(sig), "-f", signers, *when, check=False
142
+ )
143
+ principals = found.stdout.split()
144
+ for principal in principals:
145
+ with record_path.open("rb") as data:
146
+ result = subprocess.run(
147
+ ["ssh-keygen", "-Y", "verify", "-f", signers, "-I", principal,
148
+ "-n", NAMESPACE, "-s", str(sig), *when],
149
+ stdin=data, capture_output=True, text=True,
150
+ ) # fmt: skip
151
+ if result.returncode == 0:
152
+ return principal, True
153
+ finally:
154
+ Path(signers).unlink(missing_ok=True)
155
+ return None, bool(principals)
156
+
157
+
158
+ def landing_times(ref: str = "HEAD") -> dict[Path, datetime]:
159
+ """When each record's signature landed on ``ref``, by resolved path of the record.
160
+
161
+ It also covers the errata file (``wiki/errata.jsonl``), which is signed the same way.
162
+
163
+ Each time is a committer date. It comes from the newest commit on ``ref``'s first-parent
164
+ history that added or changed the record or its ``.sig`` file. On ``main`` that is the merge
165
+ time GitHub sets, which a pull request's author can't choose. A record not on ``ref``
166
+ (e.g. one a pull request adds) is absent. It is checked at the current time. In a
167
+ shallow clone the history is incomplete, so this returns nothing.
168
+ """
169
+
170
+ def git(*args: str) -> str:
171
+ return subprocess.run(["git", *args], capture_output=True, text=True).stdout.strip()
172
+
173
+ root = git("rev-parse", "--show-toplevel")
174
+ if not root or git("rev-parse", "--is-shallow-repository") != "false":
175
+ return {}
176
+ log = git(
177
+ "-C", root, "log", "--first-parent", "--diff-filter=AM", "--name-only",
178
+ "--format=@%ct", ref, "--", "wiki",
179
+ ) # fmt: skip
180
+ times: dict[Path, datetime] = {}
181
+ when = None
182
+ for line in log.splitlines():
183
+ if line.startswith("@"):
184
+ when = datetime.fromtimestamp(int(line[1:]), UTC)
185
+ elif line.endswith((".json", ".json.sig", ".jsonl", ".jsonl.sig")) and when is not None:
186
+ record = (Path(root) / line.removesuffix(".sig")).resolve()
187
+ times.setdefault(record, when) # the log is newest first
188
+ return times
189
+
190
+
191
+ def allowed_signers_text(path: Path = ALLOWED_SIGNERS, base_ref: str | None = None) -> str:
192
+ """The allowed-signers file's content: from ``base_ref`` if given, else from disk.
193
+
194
+ CI gives the pull request's base branch, so a pull request can't trust its own key. A
195
+ missing file gives an empty string, which trusts no key.
196
+ """
197
+ if base_ref:
198
+ shown = subprocess.run(
199
+ ["git", "show", f"{base_ref}:{path.as_posix()}"], capture_output=True, text=True
200
+ )
201
+ return shown.stdout if shown.returncode == 0 else ""
202
+ return path.read_text(encoding="utf-8") if path.exists() else ""
203
+
204
+
205
+ def _ssh_keygen(*args: str, check: bool = True) -> subprocess.CompletedProcess:
206
+ result = subprocess.run(["ssh-keygen", *args], capture_output=True, text=True)
207
+ if check and result.returncode != 0:
208
+ raise SignatureError(f"ssh-keygen {args[1]} failed: {result.stderr.strip()}")
209
+ return result
openinterp/sisters.py ADDED
@@ -0,0 +1,476 @@
1
+ """Sister neurons across models (`open-interpretability sisters`).
2
+
3
+ This takes every VERIFIED neuron pole of a model. It finds the poles of another model
4
+ whose activity over the corpus correlates best with it. Each match has its own best
5
+ partner back in the first model, and a rotated-basis reference
6
+ (:mod:`openinterp.harness.sisters`). The models may tokenize differently. So they are
7
+ compared where both have read the same text. Rows go to
8
+ ``docs/analyses/sister-neurons.jsonl``, one per pole and other model.
9
+
10
+ A *sister* is a mutual best match above the rotated reference: a candidate for the same
11
+ feature in both models. Whether the two do represent the same concept is a further
12
+ experiment: the pole's explanation tested on its sister. A row is observational evidence
13
+ for that. Reported, not gated.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from collections import Counter, defaultdict
19
+ from collections.abc import Callable, Sequence
20
+ from pathlib import Path
21
+
22
+ from openinterp.core.fence import fence
23
+ from openinterp.core.identifiers import model_slug
24
+ from openinterp.core.schemas import AuditRecord, Pole
25
+ from openinterp.core.strict import StrictModel
26
+
27
+ DEFAULT_PATH = Path("docs/analyses/sister-neurons.jsonl")
28
+
29
+ # Models searched for a model's sisters, besides the registry's other models. Each is a
30
+ # larger sibling of the same family, which the registry doesn't audit.
31
+ SIBLINGS = {"Qwen/Qwen2.5-0.5B": ("Qwen/Qwen2.5-1.5B",)}
32
+
33
+
34
+ class SisterMatch(StrictModel):
35
+ """A pole of the other model, and how its activity correlates with the source pole's.
36
+
37
+ ``back`` is its best partner among all of the source model's poles.
38
+ """
39
+
40
+ layer: int
41
+ neuron_idx: int
42
+ pole: Pole
43
+ pearson: float
44
+ back_slug: str
45
+ back_pearson: float
46
+
47
+ def slug(self, other: str) -> str:
48
+ """This pole's slug in model ``other``."""
49
+ return f"{model_slug(other)}/L{self.layer}/N{self.neuron_idx}-{self.pole}"
50
+
51
+
52
+ class SisterRow(StrictModel):
53
+ """One VERIFIED pole against one other model.
54
+
55
+ ``matches`` are its best-correlated poles there, strongest first. ``rotated`` is the
56
+ best correlation that it reaches with a unit of a random rotation of the first
57
+ match's layer. ``tokens`` positions were paired. They are the share ``coverage`` of
58
+ the source model's positions, with each text's first token left out.
59
+ ``layers`` and ``other_layers`` are the two models' depths, so a pole's relative depth
60
+ is known for a model the registry has no page for.
61
+ """
62
+
63
+ slug: str
64
+ other: str
65
+ model_revision: str | None
66
+ other_revision: str | None
67
+ corpus: str
68
+ corpus_sha256: str
69
+ tokens: int
70
+ coverage: float
71
+ matches: list[SisterMatch]
72
+ rotated: float
73
+ layers: int | None = None
74
+ other_layers: int | None = None
75
+
76
+ @property
77
+ def top(self) -> SisterMatch | None:
78
+ """The best match, or ``None`` when there are no matches."""
79
+ return self.matches[0] if self.matches else None
80
+
81
+ @property
82
+ def mutual(self) -> bool:
83
+ """The best match's own best partner is this pole."""
84
+ return self.top is not None and self.top.back_slug == self.slug
85
+
86
+ @property
87
+ def sister(self) -> SisterMatch | None:
88
+ """The best match, if it is mutual and beats the rotated reference."""
89
+ top = self.top
90
+ return top if self.mutual and top.pearson > self.rotated else None
91
+
92
+
93
+ def load_rows(path: Path | None = DEFAULT_PATH) -> dict[str, list[SisterRow]]:
94
+ """The rows in ``path`` by pole slug; empty if it doesn't exist."""
95
+ out: dict[str, list[SisterRow]] = defaultdict(list)
96
+ if path is None or not Path(path).exists():
97
+ return out
98
+ for line in Path(path).read_text().splitlines():
99
+ if line.strip():
100
+ row = SisterRow.model_validate_json(line)
101
+ out[row.slug].append(row)
102
+ return out
103
+
104
+
105
+ def sort_rows(path: Path) -> None:
106
+ """Rewrite ``path`` in a stable order, so reruns that append don't churn the diff."""
107
+ rows = sorted(
108
+ (r for rows in load_rows(path).values() for r in rows), key=lambda r: (r.slug, r.other)
109
+ )
110
+ path.write_text("".join(r.model_dump_json() + "\n" for r in rows))
111
+
112
+
113
+ def verified_poles(records: Sequence[AuditRecord], errata: Sequence, model_name: str):
114
+ """Return ``{slug: (identifier, revision)}`` for each VERIFIED pole of ``model_name``.
115
+
116
+ Standing uses the site's rule, with ``errata`` applied. The revision is the model
117
+ revision that the pole's records pin most often.
118
+ """
119
+ from openinterp.builder.tree import build_tree
120
+
121
+ revisions: dict[str, Counter] = defaultdict(Counter)
122
+ for r in records:
123
+ ident = r.submission.identifier
124
+ if ident.kind == "mlp_neuron_pole" and ident.model_name == model_name:
125
+ prov = r.submission.provenance
126
+ revisions[ident.slug][prov.model_revision if prov else None] += 1
127
+ out = {}
128
+ for model in build_tree(records, errata):
129
+ if model.name != model_name:
130
+ continue
131
+ for layer in model.layers:
132
+ for node in layer.units:
133
+ for standing in node.standings.values():
134
+ if node.is_neuron and standing.verified:
135
+ ident = standing.lead.record.submission.identifier
136
+ out[ident.slug] = (ident, revisions[ident.slug])
137
+ return out
138
+
139
+
140
+ def _pinned(revisions) -> str | None:
141
+ pinned = [(n, r) for r, n in revisions.items() if r is not None]
142
+ return max(pinned)[1] if pinned else None
143
+
144
+
145
+ def pairs(models: Sequence[str]) -> list[tuple[str, str]]:
146
+ """Every ordered pair of ``models``, and each with its :data:`SIBLINGS`."""
147
+ out = [(a, b) for a in models for b in models if a != b]
148
+ out += [(a, b) for a in models for b in SIBLINGS.get(a, ()) if b not in models]
149
+ return sorted(out)
150
+
151
+
152
+ def sisters(
153
+ records: Sequence[AuditRecord],
154
+ load_runner: Callable[[str, str | None], object],
155
+ out: Path,
156
+ texts: Sequence[str],
157
+ todo: Sequence[tuple[str, str]],
158
+ *,
159
+ corpus: str,
160
+ corpus_sha256: str,
161
+ errata: Sequence,
162
+ k: int = 5,
163
+ echo: Callable[[str], None] = print,
164
+ ) -> dict[tuple[str, str], int]:
165
+ """Append a row to ``out`` for each VERIFIED pole without one yet, for each pair.
166
+
167
+ ``todo`` holds (model, other) pairs. The rows of a pair are for ``other``. One search
168
+ covers every pair (:mod:`openinterp.harness.sister_passes`), and ``load_runner`` is
169
+ called once per model and stage. ``errata`` decide which poles stand VERIFIED, as on
170
+ the site. Returns how many rows each pair got.
171
+ """
172
+ from openinterp.harness.sister_passes import Job, search
173
+
174
+ done = {(r.slug, r.other) for rows in load_rows(out).values() for r in rows}
175
+ jobs, slugs = [], {}
176
+ for model_name, other in todo:
177
+ verified = verified_poles(records, errata, model_name)
178
+ poles = {s: v for s, v in verified.items() if (s, other) not in done}
179
+ if not poles:
180
+ continue
181
+ revision = _pinned(sum((revisions for _, revisions in poles.values()), Counter()))
182
+ units = {(i.layer, i.neuron_idx, i.pole): slug for slug, (i, _) in poles.items()}
183
+ echo(f"{len(units)} VERIFIED poles of {model_name} against {other}")
184
+ jobs.append(Job((model_name, revision), (other, None), list(units), other_name=other))
185
+ slugs[id(jobs[-1])] = units
186
+ if jobs:
187
+ search(
188
+ jobs, load_runner, texts, k=k, progress=lambda stage, n: echo(f"{stage}: {n} positions")
189
+ )
190
+ out.parent.mkdir(parents=True, exist_ok=True)
191
+ wrote = {pair: 0 for pair in todo}
192
+ with out.open("a") as f:
193
+ for job in jobs:
194
+ common = _common(job, corpus, corpus_sha256)
195
+ prefix = model_slug(job.source[0])
196
+ for unit, slug in sorted(slugs[id(job)].items(), key=lambda u: u[1]):
197
+ f.write(_row(slug, prefix, job.found[unit], common).model_dump_json() + "\n")
198
+ wrote[(job.source[0], job.other[0])] = len(job.units)
199
+ return wrote
200
+
201
+
202
+ def _common(job, corpus: str, corpus_sha256: str) -> dict:
203
+ """The fields that every row of one pair shares."""
204
+ return {
205
+ "other": job.other[0],
206
+ "model_revision": job.source_revision or job.source[1],
207
+ "other_revision": job.other_revision or job.other[1],
208
+ "corpus": corpus,
209
+ "corpus_sha256": corpus_sha256,
210
+ "tokens": job.tokens,
211
+ "coverage": round(job.tokens / max(job.readable, 1), 4),
212
+ "layers": job.source_layers,
213
+ "other_layers": job.other_layers,
214
+ }
215
+
216
+
217
+ def _row(slug: str, prefix: str, found, common: dict) -> SisterRow:
218
+ """Make a :class:`SisterRow` from one pole's result of ``find_sisters``.
219
+
220
+ ``find_sisters`` is :func:`~openinterp.harness.sisters.find_sisters`. ``prefix`` is
221
+ the source model's slug.
222
+ """
223
+ matches = [
224
+ SisterMatch(
225
+ layer=m.layer,
226
+ neuron_idx=m.neuron_idx,
227
+ pole=m.pole,
228
+ pearson=round(m.pearson, 4),
229
+ back_slug=f"{prefix}/L{b.layer}/N{b.neuron_idx}-{b.pole}",
230
+ back_pearson=round(b.pearson, 4),
231
+ )
232
+ for m, b in zip(found.matches, found.back, strict=True)
233
+ ]
234
+ return SisterRow(slug=slug, matches=matches, rotated=round(found.rotated, 4), **common)
235
+
236
+
237
+ def by_match_slug(rows: dict[str, list[SisterRow]]) -> dict[str, list[SisterRow]]:
238
+ """The rows naming each pole as a match, so the matched pole's page can link back."""
239
+ out: dict[str, list[SisterRow]] = defaultdict(list)
240
+ for rs in rows.values():
241
+ for row in rs:
242
+ for m in row.matches:
243
+ out[m.slug(row.other)].append(row)
244
+ return out
245
+
246
+
247
+ def pole_href(slug: str) -> str:
248
+ """A pole slug's neuron page: ``M/L3/N7-positive`` → ``models/M/L3/N7.html``."""
249
+ from openinterp.builder.tree import neuron_href
250
+
251
+ model, layer, unit = slug.split("/")
252
+ return neuron_href(model, int(layer[1:]), int(unit[1:].split("-")[0]))
253
+
254
+
255
+ def sister_view(
256
+ model_slug_: str, neuron, rows: dict, named_by: dict, studied: set, tests: dict | None = None
257
+ ) -> list[dict]:
258
+ """Return each pole's matches for a neuron page.
259
+
260
+ ``matches`` are its best-correlated poles in other models. ``named_by`` are the poles
261
+ of other models that name it as one of theirs (from :func:`by_match_slug`). Each
262
+ links to its page where the registry has one. Each also carries the verdict of a
263
+ sister study between the two (``tests``, from :func:`sister_tests`), if any.
264
+ """
265
+ tests = tests or {}
266
+ if not neuron.is_neuron:
267
+ return []
268
+ poles = []
269
+ for pole in neuron.sides:
270
+ slug = f"{model_slug_}/L{neuron.layer}/N{neuron.idx}-{pole}"
271
+ out = []
272
+ for row in rows.get(slug, []):
273
+ matches = []
274
+ for m in row.matches:
275
+ href = pole_href(m.slug(row.other))
276
+ matches.append(
277
+ {
278
+ "m": m,
279
+ "href": href if href in studied else None,
280
+ "mutual": m.back_slug == slug,
281
+ "tested": tests.get((m.slug(row.other), slug)),
282
+ }
283
+ )
284
+ out.append({"row": row, "matches": matches, "sister": row.sister})
285
+ back = []
286
+ for row in named_by.get(slug, []):
287
+ m = next(m for m in row.matches if m.slug(row.other) == slug)
288
+ href = pole_href(row.slug)
289
+ tested = tests.get((slug, row.slug))
290
+ back.append(
291
+ {"row": row, "m": m, "href": href if href in studied else None, "tested": tested}
292
+ )
293
+ if out or back:
294
+ poles.append({"pole": pole, "rows": out, "named_by": back})
295
+ return poles
296
+
297
+
298
+ def pole_findings(records: Sequence[AuditRecord], errata: Sequence) -> dict[str, tuple[str, str]]:
299
+ """Return ``{slug: (status, explanation)}`` for every studied neuron pole.
300
+
301
+ That is its standing, with ``errata`` applied, and the explanation of the experiment
302
+ that the standing rests on.
303
+ """
304
+ from openinterp.builder.tree import build_tree
305
+
306
+ out = {}
307
+ for model in build_tree(records, errata):
308
+ for layer in model.layers:
309
+ for node in layer.units:
310
+ if not node.is_neuron:
311
+ continue
312
+ for standing in node.standings.values():
313
+ sub = standing.lead.record.submission
314
+ out[sub.identifier.slug] = (standing.status, sub.natural_language_explanation)
315
+ return out
316
+
317
+
318
+ # A linked pole that isn't a sister reaches an agent's prompt only from this correlation:
319
+ # weaker links mostly join unrelated features (r ≈ 0.1 between a preposition pole and a
320
+ # body-region pole), and would mislead more than help.
321
+ MIN_PROMPT_PEARSON = 0.5
322
+
323
+
324
+ def _linked(slug: str, rows: dict, named_by: dict) -> list[tuple[str, float, bool]]:
325
+ """Return ``(other pole's slug, r, sister)`` for each pole linked to ``slug``.
326
+
327
+ Only links strong enough to show an agent are included. That is a sister either way,
328
+ or a match with r of at least :data:`MIN_PROMPT_PEARSON`.
329
+ """
330
+ out = []
331
+ for row in rows.get(slug, []):
332
+ for m in row.matches:
333
+ sister = row.sister is m
334
+ if sister or m.pearson >= MIN_PROMPT_PEARSON:
335
+ out.append((m.slug(row.other), m.pearson, sister))
336
+ for row in named_by.get(slug, []):
337
+ m = next(m for m in row.matches if m.slug(row.other) == slug)
338
+ sister = row.sister is m
339
+ if sister or m.pearson >= MIN_PROMPT_PEARSON:
340
+ out.append((row.slug, m.pearson, sister))
341
+ return out
342
+
343
+
344
+ INTRO = (
345
+ "Neurons in other models whose activity over the corpus correlates with this pole's "
346
+ "(`open-interpretability sisters`: r is the Pearson correlation of the two poles' "
347
+ "strengths where both models have read the same text; a sister is a mutual best match, "
348
+ "each the other's best partner, above what a random rotation of the layer reaches), "
349
+ "and what this registry's experiments concluded about them. A correlated neuron may "
350
+ "encode a related feature rather than the same one."
351
+ )
352
+ ADVICE = {
353
+ "proposer": "Treat them as leads: ground the hypothesis in this pole's own evidence above.",
354
+ "reviewer": "Where the hypothesis and a correlated neuron's explanation differ, write "
355
+ "probes that tell them apart; where they agree, the shared account may still be too "
356
+ "broad or too narrow.",
357
+ }
358
+
359
+
360
+ def format_sisters(slug: str, rows: dict, findings: dict, role: str, exclude=()) -> str:
361
+ """Return the prompt section on ``slug``'s studied sister neurons for ``role``.
362
+
363
+ ``role`` is proposer or reviewer. The sisters are strongest first. ``exclude`` is
364
+ left out: it is the pole that a sister study tests, whose explanation is the
365
+ hypothesis. Returns "" if none is left.
366
+ """
367
+ best: dict[str, tuple[float, bool]] = {}
368
+ for other, r, sister in _linked(slug, rows, by_match_slug(rows)):
369
+ if other in exclude:
370
+ continue
371
+ if other in findings and (other not in best or r > best[other][0]):
372
+ best[other] = (r, sister)
373
+ lines = []
374
+ for other, (r, sister) in sorted(best.items(), key=lambda kv: -kv[1][0]):
375
+ status, explanation = findings[other]
376
+ tag = f"r {r:+.2f}{', sister' if sister else ''}; {status}"
377
+ lines.append(f"- {other} ({tag}): {explanation}")
378
+ if not lines:
379
+ return ""
380
+ return f"{INTRO} {ADVICE[role]}\n" + fence("\n".join(lines)) + "\n"
381
+
382
+
383
+ def sister_context(
384
+ identifier, wiki_dir: Path, role: str, path: Path = DEFAULT_PATH, exclude=()
385
+ ) -> str:
386
+ """Return :func:`format_sisters` for the unit that ``identifier`` names.
387
+
388
+ It reads the rows in ``path``, and in ``wiki_dir`` only the records of the poles
389
+ linked to the unit. Reading the whole archive took 2.4 GB and 30 s for 2,189 records.
390
+ Returns "" for a unit that isn't a neuron pole.
391
+ """
392
+ rows = load_rows(path)
393
+ if identifier.kind != "mlp_neuron_pole" or not rows or not Path(wiki_dir).exists():
394
+ return ""
395
+ linked = {other for other, _, _ in _linked(identifier.slug, rows, by_match_slug(rows))}
396
+ from openinterp.core.errata import load_errata
397
+
398
+ findings = pole_findings(_records_of(wiki_dir, linked), load_errata(wiki_dir))
399
+ return format_sisters(identifier.slug, rows, findings, role, exclude)
400
+
401
+
402
+ def _records_of(wiki_dir: Path, slugs) -> list[AuditRecord]:
403
+ """The archived records of the poles named by ``slugs``; a slug is its folder."""
404
+ from openinterp.core.paths import experiments_dir
405
+
406
+ root = experiments_dir(wiki_dir)
407
+ return [
408
+ AuditRecord.model_validate_json(p.read_text(encoding="utf-8"))
409
+ for slug in sorted(slugs)
410
+ for p in sorted((root / slug).glob("*.json"))
411
+ ]
412
+
413
+
414
+ def load_sister_source(path: Path, unit) -> AuditRecord:
415
+ """Return the archived record that ``audit --sister-of`` names, after checks.
416
+
417
+ It must be a VERIFIED experiment on a neuron pole of a model other than ``unit``'s.
418
+ Raises ValueError otherwise.
419
+ """
420
+ record = AuditRecord.model_validate_json(Path(path).read_text())
421
+ ident = record.submission.identifier
422
+ if record.verdict is None or record.verdict.status != "VERIFIED":
423
+ raise ValueError(f"{path} is not a VERIFIED experiment")
424
+ if ident.kind != "mlp_neuron_pole" or unit.kind != "mlp_neuron_pole":
425
+ raise ValueError("sister studies are between neuron poles")
426
+ if ident.model_name == unit.model_name:
427
+ raise ValueError(f"{ident} is in {unit.model_name} too; a sister is in another model")
428
+ return record
429
+
430
+
431
+ def sister_ref(record: AuditRecord) -> str:
432
+ """``<pole slug>/<experiment id>``: what a submission's ``sister_of`` names."""
433
+ from openinterp.builder.wiki import experiment_id
434
+
435
+ return f"{record.submission.identifier.slug}/{experiment_id(record)}"
436
+
437
+
438
+ def sister_brief(source: AuditRecord) -> str:
439
+ """The proposer's brief for a sister study: the explanation under test is fixed."""
440
+ ident = source.submission.identifier
441
+ return (
442
+ f"This is a sister-neuron study. The hypothesis under test is fixed: the explanation "
443
+ f"VERIFIED for {ident}, a pole whose activity correlates with "
444
+ f"this one's (`open-interpretability sisters`). It is recorded as this submission's "
445
+ f"explanation word for word, whatever you write, so the review tests whether it "
446
+ f"carries over:\n\n"
447
+ f"> {source.submission.natural_language_explanation}\n\n"
448
+ f"Write `explanation` as exactly that text. Choose the activating tokens, mechanism and "
449
+ f"counterfactuals that this explanation predicts for this pole, using the evidence "
450
+ f"above; where the evidence disagrees with it, keep to the explanation anyway.\n"
451
+ )
452
+
453
+
454
+ def sister_source_href(ref: str) -> str:
455
+ """The page of the experiment a ``sister_of`` names."""
456
+ from openinterp.builder.hrefs import experiment_href
457
+
458
+ slug, experiment = ref.rsplit("/", 1)
459
+ return experiment_href(slug, experiment)
460
+
461
+
462
+ def sister_tests(experiments) -> dict[tuple[str, str], str]:
463
+ """Return ``{(sister's slug, source pole's slug): status}`` for each sister study.
464
+
465
+ The status is the newest verdict. The keys are the pole that the study tested, and
466
+ the pole whose explanation it tested.
467
+ """
468
+ newest: dict[tuple[str, str], object] = {}
469
+ for e in experiments:
470
+ ref = e.record.submission.sister_of
471
+ if ref:
472
+ key = (e.record.submission.identifier.slug, ref.rsplit("/", 1)[0])
473
+ old = newest.get(key)
474
+ if old is None or e.record.verdict.timestamp > old.record.verdict.timestamp:
475
+ newest[key] = e
476
+ return {key: e.record.verdict.status for key, e in newest.items()}