wspx 0.1.0.dev0__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 (99) hide show
  1. wspx/__init__.py +24 -0
  2. wspx/_version.py +1 -0
  3. wspx/addressing.py +415 -0
  4. wspx/auth.py +77 -0
  5. wspx/cli/__init__.py +1 -0
  6. wspx/cli/client.py +124 -0
  7. wspx/cli/config.py +89 -0
  8. wspx/cli/connect.py +88 -0
  9. wspx/cli/main.py +848 -0
  10. wspx/cloud/__init__.py +20 -0
  11. wspx/cloud/app.py +191 -0
  12. wspx/cloud/backend.py +141 -0
  13. wspx/cloud/compose.py +85 -0
  14. wspx/cloud/deploy.py +102 -0
  15. wspx/config.py +189 -0
  16. wspx/control/__init__.py +5 -0
  17. wspx/control/app.py +488 -0
  18. wspx/control/backend.py +244 -0
  19. wspx/control/gateway_client.py +79 -0
  20. wspx/control/mcp_server.py +71 -0
  21. wspx/control/sessions.py +424 -0
  22. wspx/control/tracedb.py +183 -0
  23. wspx/control/ui/assets/index-BJFweZAn.css +1 -0
  24. wspx/control/ui/assets/index-DhUVhWIK.js +10 -0
  25. wspx/control/ui/index.html +13 -0
  26. wspx/control/views.py +180 -0
  27. wspx/diagnostics.py +146 -0
  28. wspx/driver/__init__.py +7 -0
  29. wspx/driver/loop.py +255 -0
  30. wspx/driver/messages.py +62 -0
  31. wspx/driver/providers/__init__.py +84 -0
  32. wspx/driver/providers/anthropic.py +149 -0
  33. wspx/driver/providers/compat.py +115 -0
  34. wspx/driver/providers/google.py +138 -0
  35. wspx/driver/providers/openai.py +125 -0
  36. wspx/driver/run.py +134 -0
  37. wspx/errors.py +69 -0
  38. wspx/gateway/__init__.py +8 -0
  39. wspx/gateway/app.py +626 -0
  40. wspx/gateway/ledger.py +536 -0
  41. wspx/gateway/prices.py +75 -0
  42. wspx/gateway/usage.py +284 -0
  43. wspx/handles.py +117 -0
  44. wspx/integrations/AGENTS.snippet.md +8 -0
  45. wspx/integrations/SKILL.md +52 -0
  46. wspx/integrations/__init__.py +17 -0
  47. wspx/integrations/claude-plugin/.claude-plugin/plugin.json +30 -0
  48. wspx/integrations/claude-plugin/skills/wspx/SKILL.md +52 -0
  49. wspx/integrations/codex-hooks.toml +9 -0
  50. wspx/lab/__init__.py +5 -0
  51. wspx/lab/analysis.py +485 -0
  52. wspx/lab/check.py +489 -0
  53. wspx/lab/evaluate.py +108 -0
  54. wspx/lab/export.py +275 -0
  55. wspx/lab/grep.py +754 -0
  56. wspx/lab/index.py +239 -0
  57. wspx/lab/ir/__init__.py +1 -0
  58. wspx/lab/ir/capture.py +299 -0
  59. wspx/lab/ir/graph.py +148 -0
  60. wspx/lab/ir/model_ir.py +522 -0
  61. wspx/lab/ir/semantics.py +1255 -0
  62. wspx/lab/ir/tape.py +853 -0
  63. wspx/lab/loader.py +204 -0
  64. wspx/lab/merge.py +200 -0
  65. wspx/lab/ops/__init__.py +76 -0
  66. wspx/lab/ops/builtin.py +379 -0
  67. wspx/lab/patch.py +320 -0
  68. wspx/lab/probe.py +206 -0
  69. wspx/lab/results.py +114 -0
  70. wspx/lab/sdk.py +120 -0
  71. wspx/lab/server.py +236 -0
  72. wspx/lab/session.py +1574 -0
  73. wspx/lab/tensors.py +119 -0
  74. wspx/lab/text.py +69 -0
  75. wspx/lab/tree.py +302 -0
  76. wspx/loops.py +127 -0
  77. wspx/project.py +143 -0
  78. wspx/py.typed +0 -0
  79. wspx/safety/__init__.py +15 -0
  80. wspx/safety/kill.py +47 -0
  81. wspx/safety/sweeper.py +68 -0
  82. wspx/store/__init__.py +64 -0
  83. wspx/store/objects.py +130 -0
  84. wspx/store/overlay.py +209 -0
  85. wspx/store/refs.py +150 -0
  86. wspx/testing/__init__.py +21 -0
  87. wspx/testing/api.py +155 -0
  88. wspx/testing/builtin.py +139 -0
  89. wspx/testing/runner.py +257 -0
  90. wspx/tools/__init__.py +17 -0
  91. wspx/tools/dispatch.py +129 -0
  92. wspx/tools/schemas.py +313 -0
  93. wspx/vcs/__init__.py +17 -0
  94. wspx/vcs/repo.py +431 -0
  95. wspx-0.1.0.dev0.dist-info/METADATA +278 -0
  96. wspx-0.1.0.dev0.dist-info/RECORD +99 -0
  97. wspx-0.1.0.dev0.dist-info/WHEEL +4 -0
  98. wspx-0.1.0.dev0.dist-info/entry_points.txt +10 -0
  99. wspx-0.1.0.dev0.dist-info/licenses/LICENSE +201 -0
wspx/lab/analysis.py ADDED
@@ -0,0 +1,485 @@
1
+ """Show, contrast, generate and traces: the read-only tools that need the lab.
2
+
3
+ Everything heavy stays here; callers get short summaries plus arrays they
4
+ can persist for the UI.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import math
10
+ from collections.abc import Sequence
11
+ from dataclasses import dataclass, field
12
+ from typing import Any
13
+
14
+ import torch
15
+
16
+ from wspx.errors import WspxError
17
+ from wspx.lab.index import tensor_stats
18
+ from wspx.lab.ir.model_ir import ModelIR, Target
19
+ from wspx.lab.probe import Probe, writer_units
20
+ from wspx.lab.tensors import select
21
+ from wspx.lab.text import Prompt, Text
22
+
23
+ MAX_VALUES = 2048
24
+ DEFAULT_VALUES = 64
25
+ BARS = " ▏▎▍▌▋▊▉█"
26
+
27
+
28
+ # --------------------------------------------------------------------------- show
29
+
30
+
31
+ def show(
32
+ ir: ModelIR,
33
+ params: dict[str, torch.Tensor],
34
+ target: Target,
35
+ *,
36
+ text: Text | None = None,
37
+ values: int | None = None,
38
+ final_scale: torch.Tensor | None = None,
39
+ ) -> dict[str, Any]:
40
+ """Summaries before values: stats, a text histogram, the spectrum, vocab tokens, capped raw values."""
41
+ weight = params[target.param].detach()
42
+ view = select(weight, target.index)
43
+ stats = tensor_stats(view)
44
+ out: dict[str, Any] = {"address": target.address, "param": target.param, "stats": stats}
45
+ role = target.role or ir.primary_role(target.param)
46
+ if view.dim() == 1 and text is not None and role is not None:
47
+ tokens = _vocab_of_vector(ir, params, view.float(), role.kind, final_scale)
48
+ if tokens:
49
+ out["vocab"] = [(text.show(t), s) for t, s in tokens]
50
+ if values is not None:
51
+ n = max(0, min(values or DEFAULT_VALUES, MAX_VALUES))
52
+ flat = view.reshape(-1).float()
53
+ out["values"] = [round(float(v), 6) for v in flat[:n].tolist()]
54
+ out["values_total"] = flat.numel()
55
+ return out
56
+
57
+
58
+ def render_show(info: dict[str, Any]) -> str:
59
+ s = info["stats"]
60
+ lines = [
61
+ f"{info['address']} {tuple(s.shape)} {s.dtype}",
62
+ f" norm {s.norm:.4g} · mean {s.mean:.3g} · std {s.std:.3g} · absmax {s.absmax:.3g} · "
63
+ f"kurtosis {s.kurtosis:.3g} · zeros {s.zeros:.1%}"
64
+ + (f" · NaN {s.nan}" if s.nan else "")
65
+ + (f" · Inf {s.inf}" if s.inf else ""),
66
+ ]
67
+ peak = max(s.hist_counts) or 1
68
+ for i, count in enumerate(s.hist_counts):
69
+ bar = "█" * round(24 * count / peak)
70
+ lines.append(f" [{s.hist_edges[i]:+.3e}, {s.hist_edges[i + 1]:+.3e}) {bar} {count}")
71
+ if s.spectrum:
72
+ lines.append(" σ: " + " ".join(f"{v:.3g}" for v in s.spectrum[:8]))
73
+ if info.get("vocab"):
74
+ lines.append(" tokens: " + ", ".join(f"{t} {v:.2f}" for t, v in info["vocab"][:8]))
75
+ if "values" in info:
76
+ lines.append(
77
+ f" values ({len(info['values'])} of {info['values_total']}): {info['values']}"
78
+ )
79
+ return "\n".join(lines)
80
+
81
+
82
+ def _vocab_of_vector(
83
+ ir: ModelIR,
84
+ params: dict[str, torch.Tensor],
85
+ vec: torch.Tensor,
86
+ kind: str,
87
+ final_scale: torch.Tensor | None,
88
+ k: int = 8,
89
+ ) -> list[tuple[int, float]]:
90
+ writes = kind in ("writer", "embed", "pos_embed", "stem", "expert")
91
+ name = ir.semantics.unembed if writes else ir.semantics.embed
92
+ if name is None:
93
+ return []
94
+ table = params[name].detach().float()
95
+ role = next(
96
+ (r for r in ir.roles_of(name) if r.kind == ("unembed" if writes else "embed")), None
97
+ )
98
+ if role is not None and role.kind == "unembed" and role.out_dim == 1:
99
+ table = table.T
100
+ if table.shape[1] != vec.numel():
101
+ return []
102
+ if writes and final_scale is not None and final_scale.numel() == vec.numel():
103
+ vec = vec * final_scale.to(vec.device)
104
+ cos = (table @ vec) / (table.norm(dim=1) * vec.norm()).clamp_min(1e-30)
105
+ top = torch.topk(cos, k=min(k, cos.numel()))
106
+ return [(int(i), float(v)) for i, v in zip(top.indices, top.values, strict=True)]
107
+
108
+
109
+ # --------------------------------------------------------------------------- forward helpers
110
+
111
+
112
+ def forward(
113
+ model: torch.nn.Module, ir: ModelIR, ids: torch.Tensor, mask: torch.Tensor
114
+ ) -> torch.Tensor:
115
+ """Logits for a padded batch, called the way the IR was captured."""
116
+ if ir.is_lm:
117
+ out = model(input_ids=ids, attention_mask=mask, use_cache=False)
118
+ logits: torch.Tensor = getattr(out, "logits", out)
119
+ return logits
120
+ raise WspxError("this tool needs a language model; call the model directly for other classes")
121
+
122
+
123
+ def last_positions(mask: torch.Tensor) -> torch.Tensor:
124
+ """Index of each row's last real token (prompts are left-padded, so it is the last column)."""
125
+ return torch.full((mask.shape[0],), mask.shape[1] - 1, dtype=torch.long, device=mask.device)
126
+
127
+
128
+ # --------------------------------------------------------------------------- contrast
129
+
130
+
131
+ @dataclass
132
+ class Direction:
133
+ name: str
134
+ vector: torch.Tensor
135
+ layer: int
136
+ provenance: str
137
+ n_pos: int
138
+ n_neg: int
139
+ separation: float
140
+ """Mean projection gap between the two sets, in units of the pooled std."""
141
+
142
+
143
+ def contrast(
144
+ model: torch.nn.Module,
145
+ ir: ModelIR,
146
+ probe: Probe,
147
+ text: Text,
148
+ positive: Sequence[Prompt],
149
+ negative: Sequence[Prompt],
150
+ *,
151
+ name: str,
152
+ layer: int | None = None,
153
+ position: str = "last",
154
+ batch_size: int = 16,
155
+ ) -> Direction:
156
+ """Difference of means of the residual stream after ``layer`` between two prompt sets."""
157
+ if not positive or not negative:
158
+ raise WspxError("contrast needs prompts on both sides")
159
+ blocks = ir.num_blocks
160
+ if blocks == 0:
161
+ raise WspxError("contrast needs a residual stream")
162
+ layer = blocks // 2 if layer is None else layer
163
+ if not 0 <= layer < blocks:
164
+ raise WspxError(f"layer {layer} out of range (0-{blocks - 1})")
165
+ point = f"resid.L{layer}"
166
+ pos_acts = _residuals(model, ir, probe, text, positive, point, position, batch_size)
167
+ neg_acts = _residuals(model, ir, probe, text, negative, point, position, batch_size)
168
+ vector = pos_acts.mean(0) - neg_acts.mean(0)
169
+ unit = vector / vector.norm().clamp_min(1e-30)
170
+ p, n = pos_acts @ unit, neg_acts @ unit
171
+ pooled = math.sqrt((float(p.var(correction=0)) + float(n.var(correction=0))) / 2) or 1e-30
172
+ provenance = f"contrast.L{layer}-resid.n{len(positive) + len(negative)}"
173
+ return Direction(
174
+ name,
175
+ vector,
176
+ layer,
177
+ provenance,
178
+ len(positive),
179
+ len(negative),
180
+ (float(p.mean()) - float(n.mean())) / pooled,
181
+ )
182
+
183
+
184
+ def _residuals(
185
+ model: torch.nn.Module,
186
+ ir: ModelIR,
187
+ probe: Probe,
188
+ text: Text,
189
+ prompts: Sequence[Prompt],
190
+ point: str,
191
+ position: str,
192
+ batch_size: int,
193
+ ) -> torch.Tensor:
194
+ device = next(model.parameters()).device
195
+ rows = []
196
+ with torch.no_grad():
197
+ for start in range(0, len(prompts), batch_size):
198
+ ids, mask = text.batch(prompts[start : start + batch_size], device)
199
+ with probe.capture([point]) as cap:
200
+ forward(model, ir, ids, mask)
201
+ acts = cap.points[point].float()
202
+ if position == "mean":
203
+ m = mask.unsqueeze(-1).to(acts.dtype)
204
+ rows.append((acts * m).sum(1) / m.sum(1))
205
+ else:
206
+ rows.append(acts[:, -1, :])
207
+ return torch.cat(rows)
208
+
209
+
210
+ # --------------------------------------------------------------------------- generate
211
+
212
+
213
+ def generate(
214
+ model: torch.nn.Module,
215
+ text: Text,
216
+ prompts: Sequence[Prompt],
217
+ *,
218
+ max_tokens: int = 64,
219
+ temperature: float = 0.0,
220
+ top_p: float = 1.0,
221
+ seed: int = 0,
222
+ ) -> list[list[int]]:
223
+ device = next(model.parameters()).device
224
+ ids, mask = text.batch(prompts, device)
225
+ torch.manual_seed(seed)
226
+ kwargs: dict[str, Any] = {"max_new_tokens": max_tokens, "pad_token_id": text.pad_id}
227
+ if temperature > 0:
228
+ kwargs.update(do_sample=True, temperature=temperature, top_p=top_p)
229
+ else:
230
+ kwargs.update(do_sample=False)
231
+ with torch.no_grad():
232
+ out = model.generate(input_ids=ids, attention_mask=mask, **kwargs) # type: ignore[operator]
233
+ return [row[ids.shape[1] :].tolist() for row in out]
234
+
235
+
236
+ # --------------------------------------------------------------------------- traces
237
+
238
+
239
+ @dataclass
240
+ class Trace:
241
+ kind: str
242
+ summary: str
243
+ arrays: dict[str, Any] = field(default_factory=dict)
244
+ data: dict[str, Any] = field(default_factory=dict)
245
+
246
+
247
+ def _norm_and_unembed(model: torch.nn.Module, ir: ModelIR) -> tuple[Any, Any]:
248
+ sem = ir.semantics
249
+ if not sem.final_norm or sem.unembed is None:
250
+ raise WspxError("logit lens needs a final norm and an unembedding")
251
+ norm = model.get_submodule(ir.params[sem.final_norm[0]].module)
252
+ head_name = sem.unembed
253
+ head = model.get_submodule(ir.params[head_name].module) if ir.params[head_name].module else None
254
+ weight = dict(model.named_parameters())[head_name]
255
+ role = next(r for r in ir.roles if r.address == "unembed")
256
+
257
+ def unembed(h: torch.Tensor) -> torch.Tensor:
258
+ if head is not None and isinstance(head, torch.nn.Linear) and head.weight is weight:
259
+ projected: torch.Tensor = head(h)
260
+ return projected
261
+ w = weight if role.out_dim == 0 else weight.T
262
+ return h @ w.T.to(h.dtype)
263
+
264
+ return norm, unembed
265
+
266
+
267
+ def forward_trace(
268
+ model: torch.nn.Module, ir: ModelIR, probe: Probe, text: Text, prompt: Prompt, *, top: int = 5
269
+ ) -> Trace:
270
+ device = next(model.parameters()).device
271
+ ids, mask = text.batch([prompt], device)
272
+ resid_points = [f"resid.L{b.index}" for b in ir.semantics.blocks]
273
+ attn_points = [p for p in probe.points if p.startswith(("attn.", "route."))]
274
+ units = writer_units(ir)
275
+ with torch.no_grad(), probe.capture(resid_points + attn_points, units=units) as cap:
276
+ logits = forward(model, ir, ids, mask)
277
+ norm, unembed = _norm_and_unembed(model, ir)
278
+ lens_ids, lens_p, resid_norm = [], [], []
279
+ with torch.no_grad():
280
+ for point in resid_points:
281
+ h = cap.points[point]
282
+ resid_norm.append(float(h[0, -1].float().norm()))
283
+ probs = torch.softmax(unembed(norm(h[:, -1:])).float(), dim=-1)[0, -1]
284
+ topk = torch.topk(probs, k=top)
285
+ lens_ids.append(topk.indices.tolist())
286
+ lens_p.append(topk.values.tolist())
287
+ final = torch.softmax(logits[0].float(), dim=-1)
288
+ entropy = (-(final * final.clamp_min(1e-30).log()).sum(-1)).tolist()
289
+ out_ids = final.argmax(-1).tolist()
290
+ writers = _top_writers(model, ir, cap.units, top=3)
291
+ routes = {
292
+ p: [t[1][0, -1].tolist() if len(t) > 1 else t[0][0, -1].tolist()]
293
+ for p, t in cap.points.items()
294
+ if p.startswith("route.")
295
+ }
296
+ lines = [
297
+ f"forward trace · {ids.shape[1]} tokens · {len(resid_points)} blocks",
298
+ "block |h| logit lens @ last token",
299
+ ]
300
+ for i in range(len(resid_points)):
301
+ toks = ", ".join(
302
+ f"{text.show(t)} {p:.2f}" for t, p in zip(lens_ids[i][:3], lens_p[i][:3], strict=True)
303
+ )
304
+ lines.append(f"L{i:<5d} {resid_norm[i]:<8.3g} {toks}")
305
+ lines.append(
306
+ "output: "
307
+ + " ".join(
308
+ f"{text.show(t)}(H={h:.2f})" for t, h in zip(out_ids[-3:], entropy[-3:], strict=True)
309
+ )
310
+ )
311
+ if writers:
312
+ lines.append(
313
+ "top writer units @ last token: " + ", ".join(f"{a} {s:.2f}" for a, s in writers[:6])
314
+ )
315
+ if routes:
316
+ lines.append(
317
+ "routes @ last token: "
318
+ + "; ".join(f"{p[6:]} {v[0]}" for p, v in list(routes.items())[:6])
319
+ )
320
+ arrays = {
321
+ "resid_norm": resid_norm,
322
+ "lens_ids": lens_ids,
323
+ "lens_p": lens_p,
324
+ "entropy": entropy,
325
+ "output_ids": out_ids,
326
+ "input_ids": ids[0].tolist(),
327
+ }
328
+ return Trace("forward", "\n".join(lines), arrays, {"writers": writers, "routes": routes})
329
+
330
+
331
+ def _top_writers(
332
+ model: torch.nn.Module,
333
+ ir: ModelIR,
334
+ units: dict[str, torch.Tensor],
335
+ *,
336
+ top: int,
337
+ position: int = -1,
338
+ ) -> list[tuple[str, float]]:
339
+ """Units whose contribution ``a_j · ‖w_j‖`` to the residual is largest at ``position``."""
340
+ scored: list[tuple[str, float]] = []
341
+ params = dict(model.named_parameters())
342
+ for param, acts in units.items():
343
+ role = ir.primary_role(param)
344
+ if role is None or role.in_dim is None:
345
+ continue
346
+ a = acts[0, position].float() if acts.dim() == 3 else acts[position].float()
347
+ scored.extend(_unit_scores(role, a * _unit_norms(params[param], role.in_dim), top))
348
+ scored.sort(key=lambda x: -abs(x[1]))
349
+ return scored[: top * 4]
350
+
351
+
352
+ def _unit_norms(weight: torch.Tensor, in_dim: int) -> torch.Tensor:
353
+ """‖w_j‖ for each unit j of a writer: the length of what it writes per unit of activation."""
354
+ w = weight.detach().float()
355
+ return w.norm(dim=1 - in_dim) if w.dim() == 2 else torch.ones(w.shape[in_dim], device=w.device)
356
+
357
+
358
+ def _unit_scores(role: Any, score: torch.Tensor, top: int) -> list[tuple[str, float]]:
359
+ k = min(top, score.numel())
360
+ _, idx = torch.topk(score.abs(), k=k)
361
+ return [(f"{role.address}[:, {int(i)}]", float(score[int(i)])) for i in idx]
362
+
363
+
364
+ def diff_trace(
365
+ model: torch.nn.Module,
366
+ ir: ModelIR,
367
+ probe: Probe,
368
+ text: Text,
369
+ prompt: Prompt,
370
+ *,
371
+ switch: Any,
372
+ top: int = 5,
373
+ ) -> Trace:
374
+ """The same input on two weight states. ``switch`` is a context manager that swaps to the other state."""
375
+ device = next(model.parameters()).device
376
+ ids, mask = text.batch([prompt], device)
377
+ points = [f"resid.L{b.index}" for b in ir.semantics.blocks]
378
+ units = writer_units(ir)
379
+ with torch.no_grad():
380
+ with probe.capture(points, units=units) as here:
381
+ logits_here = forward(model, ir, ids, mask)
382
+ with switch, probe.capture(points, units=units) as there:
383
+ logits_there = forward(model, ir, ids, mask)
384
+ divergence = []
385
+ for p in points:
386
+ a, b = here.points[p][0, -1].float(), there.points[p][0, -1].float()
387
+ divergence.append(float((a - b).norm() / b.norm().clamp_min(1e-30)))
388
+ out_a = logits_here[0].argmax(-1).tolist()
389
+ out_b = logits_there[0].argmax(-1).tolist()
390
+ changed = [i for i, (x, y) in enumerate(zip(out_a, out_b, strict=True)) if x != y]
391
+ moved: list[tuple[str, float]] = []
392
+ params = dict(model.named_parameters())
393
+ for param in units:
394
+ role = ir.primary_role(param)
395
+ if role is None or role.in_dim is None or param not in here.units:
396
+ continue
397
+ delta = (here.units[param][0, -1] - there.units[param][0, -1]).float()
398
+ moved.extend(_unit_scores(role, delta * _unit_norms(params[param], role.in_dim), top))
399
+ moved.sort(key=lambda x: -abs(x[1]))
400
+ first = next((i for i, d in enumerate(divergence) if d > 1e-3), None)
401
+ lines = ["diff trace · relative residual change at the last token, per block"]
402
+ lines.append(" ".join(f"L{i}:{d:.3f}" for i, d in enumerate(divergence)))
403
+ lines.append(f"first divergence: {'L' + str(first) if first is not None else 'none'}")
404
+ lines.append(
405
+ f"output tokens changed at {len(changed)} of {len(out_a)} positions"
406
+ + (
407
+ f" (e.g. pos {changed[0]}: {text.show(out_b[changed[0]])} → {text.show(out_a[changed[0]])})"
408
+ if changed
409
+ else ""
410
+ )
411
+ )
412
+ if moved:
413
+ lines.append("most-moved units: " + ", ".join(f"{a} {s:+.2f}" for a, s in moved[:6]))
414
+ return Trace(
415
+ "diff",
416
+ "\n".join(lines),
417
+ {"divergence": divergence, "changed": changed},
418
+ {"moved": moved[: top * 4], "first_divergence": first},
419
+ )
420
+
421
+
422
+ def attribution_trace(
423
+ model: torch.nn.Module,
424
+ ir: ModelIR,
425
+ probe: Probe,
426
+ text: Text,
427
+ failing: Prompt,
428
+ reference: Prompt,
429
+ *,
430
+ target: int | str | None = None,
431
+ top: int = 10,
432
+ ) -> Trace:
433
+ """Score writer units by (activation difference) × (gradient) on the failing input: a stack trace."""
434
+ device = next(model.parameters()).device
435
+ units = writer_units(ir)
436
+ ids_f, mask_f = text.batch([failing], device)
437
+ ids_r, mask_r = text.batch([reference], device)
438
+ with torch.no_grad(), probe.capture([], units=units) as ref:
439
+ forward(model, ir, ids_r, mask_r)
440
+ requires = {n: p.requires_grad for n, p in model.named_parameters()}
441
+ for p in model.parameters():
442
+ p.requires_grad_(False)
443
+ try:
444
+ with torch.enable_grad(), probe.capture([], units=units, grad_units=True) as fail:
445
+ logits = _forward_with_grad(model, ir, ids_f, mask_f)
446
+ logp = torch.log_softmax(logits[0, -1].float(), dim=-1)
447
+ tid = text.token_id(target) if target is not None else int(logp.argmax())
448
+ logp[tid].backward() # type: ignore[no-untyped-call]
449
+ finally:
450
+ for n, p in model.named_parameters():
451
+ p.requires_grad_(requires[n])
452
+ scored: list[tuple[str, float]] = []
453
+ for param, acts in fail.units.items():
454
+ role = ir.primary_role(param)
455
+ grad = acts.grad
456
+ if role is None or grad is None or param not in ref.units:
457
+ continue
458
+ a_f = acts.detach()[0, -1].float()
459
+ a_r = ref.units[param][0, -1].float()
460
+ score = (a_f - a_r) * grad[0, -1].float()
461
+ scored.extend(_unit_scores(role, score, top))
462
+ scored.sort(key=lambda x: -abs(x[1]))
463
+ lines = [f"attribution · objective log p({text.show(tid)}) at the last token · (Δa × ∂/∂a)"]
464
+ lines.extend(f" {i + 1:>2}. {a:<32s} {s:+.4f}" for i, (a, s) in enumerate(scored[:top]))
465
+ return Trace(
466
+ "attribution",
467
+ "\n".join(lines),
468
+ {"scores": [s for _, s in scored[: top * 4]]},
469
+ {"ranking": scored[: top * 4], "target": tid},
470
+ )
471
+
472
+
473
+ def _forward_with_grad(
474
+ model: torch.nn.Module, ir: ModelIR, ids: torch.Tensor, mask: torch.Tensor
475
+ ) -> torch.Tensor:
476
+ """Forward pass whose unit activations carry gradients (weights stay frozen)."""
477
+ getter: Any = getattr(model, "get_input_embeddings", None)
478
+ embed: Any = getter() if callable(getter) else None
479
+ if embed is None:
480
+ raise WspxError("attribution needs a model with input embeddings")
481
+ inputs = embed(ids).detach().requires_grad_(True)
482
+ out = model(inputs_embeds=inputs, attention_mask=mask, use_cache=False)
483
+ del ir
484
+ logits: torch.Tensor = getattr(out, "logits", out)
485
+ return logits