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.
- wspx/__init__.py +24 -0
- wspx/_version.py +1 -0
- wspx/addressing.py +415 -0
- wspx/auth.py +77 -0
- wspx/cli/__init__.py +1 -0
- wspx/cli/client.py +124 -0
- wspx/cli/config.py +89 -0
- wspx/cli/connect.py +88 -0
- wspx/cli/main.py +848 -0
- wspx/cloud/__init__.py +20 -0
- wspx/cloud/app.py +191 -0
- wspx/cloud/backend.py +141 -0
- wspx/cloud/compose.py +85 -0
- wspx/cloud/deploy.py +102 -0
- wspx/config.py +189 -0
- wspx/control/__init__.py +5 -0
- wspx/control/app.py +488 -0
- wspx/control/backend.py +244 -0
- wspx/control/gateway_client.py +79 -0
- wspx/control/mcp_server.py +71 -0
- wspx/control/sessions.py +424 -0
- wspx/control/tracedb.py +183 -0
- wspx/control/ui/assets/index-BJFweZAn.css +1 -0
- wspx/control/ui/assets/index-DhUVhWIK.js +10 -0
- wspx/control/ui/index.html +13 -0
- wspx/control/views.py +180 -0
- wspx/diagnostics.py +146 -0
- wspx/driver/__init__.py +7 -0
- wspx/driver/loop.py +255 -0
- wspx/driver/messages.py +62 -0
- wspx/driver/providers/__init__.py +84 -0
- wspx/driver/providers/anthropic.py +149 -0
- wspx/driver/providers/compat.py +115 -0
- wspx/driver/providers/google.py +138 -0
- wspx/driver/providers/openai.py +125 -0
- wspx/driver/run.py +134 -0
- wspx/errors.py +69 -0
- wspx/gateway/__init__.py +8 -0
- wspx/gateway/app.py +626 -0
- wspx/gateway/ledger.py +536 -0
- wspx/gateway/prices.py +75 -0
- wspx/gateway/usage.py +284 -0
- wspx/handles.py +117 -0
- wspx/integrations/AGENTS.snippet.md +8 -0
- wspx/integrations/SKILL.md +52 -0
- wspx/integrations/__init__.py +17 -0
- wspx/integrations/claude-plugin/.claude-plugin/plugin.json +30 -0
- wspx/integrations/claude-plugin/skills/wspx/SKILL.md +52 -0
- wspx/integrations/codex-hooks.toml +9 -0
- wspx/lab/__init__.py +5 -0
- wspx/lab/analysis.py +485 -0
- wspx/lab/check.py +489 -0
- wspx/lab/evaluate.py +108 -0
- wspx/lab/export.py +275 -0
- wspx/lab/grep.py +754 -0
- wspx/lab/index.py +239 -0
- wspx/lab/ir/__init__.py +1 -0
- wspx/lab/ir/capture.py +299 -0
- wspx/lab/ir/graph.py +148 -0
- wspx/lab/ir/model_ir.py +522 -0
- wspx/lab/ir/semantics.py +1255 -0
- wspx/lab/ir/tape.py +853 -0
- wspx/lab/loader.py +204 -0
- wspx/lab/merge.py +200 -0
- wspx/lab/ops/__init__.py +76 -0
- wspx/lab/ops/builtin.py +379 -0
- wspx/lab/patch.py +320 -0
- wspx/lab/probe.py +206 -0
- wspx/lab/results.py +114 -0
- wspx/lab/sdk.py +120 -0
- wspx/lab/server.py +236 -0
- wspx/lab/session.py +1574 -0
- wspx/lab/tensors.py +119 -0
- wspx/lab/text.py +69 -0
- wspx/lab/tree.py +302 -0
- wspx/loops.py +127 -0
- wspx/project.py +143 -0
- wspx/py.typed +0 -0
- wspx/safety/__init__.py +15 -0
- wspx/safety/kill.py +47 -0
- wspx/safety/sweeper.py +68 -0
- wspx/store/__init__.py +64 -0
- wspx/store/objects.py +130 -0
- wspx/store/overlay.py +209 -0
- wspx/store/refs.py +150 -0
- wspx/testing/__init__.py +21 -0
- wspx/testing/api.py +155 -0
- wspx/testing/builtin.py +139 -0
- wspx/testing/runner.py +257 -0
- wspx/tools/__init__.py +17 -0
- wspx/tools/dispatch.py +129 -0
- wspx/tools/schemas.py +313 -0
- wspx/vcs/__init__.py +17 -0
- wspx/vcs/repo.py +431 -0
- wspx-0.1.0.dev0.dist-info/METADATA +278 -0
- wspx-0.1.0.dev0.dist-info/RECORD +99 -0
- wspx-0.1.0.dev0.dist-info/WHEEL +4 -0
- wspx-0.1.0.dev0.dist-info/entry_points.txt +10 -0
- 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
|