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/ir/tape.py ADDED
@@ -0,0 +1,853 @@
1
+ """The tape: records every executed ATen op of a forward pass (§5.1.1 step 4).
2
+
3
+ The tape is a ``TorchDispatchMode``. It sees the real ops the model runs, which
4
+ module ran each one and which parameter storages each one read, so it works
5
+ whenever the model can run at all, whatever its code looks like.
6
+
7
+ Beyond the op list it tracks three things the semantics pass needs:
8
+
9
+ * **Parameter layout.** For every matmul-like op it records which parameter
10
+ dim was contracted against the activation and which became output features,
11
+ following views and transposes by stride, so ``nn.Linear`` and GPT-2's
12
+ transposed ``Conv1D`` are both understood without names.
13
+ * **Feature provenance.** The output of every parameter projection gets a
14
+ *shadow*: a tensor of the same shape holding each element's output-feature
15
+ index. Data-movement ops (views, splits, slices, cat, index) are replayed on
16
+ the shadow, and pointwise ops carry it through, so wherever it stops the tape
17
+ knows exactly which features of which projection arrived. That is how fused
18
+ ``qkv`` and ``gate_up`` splits are read from data flow.
19
+ * **Forced routing.** At a ``topk`` whose input comes from a parameter
20
+ projection through pointwise ops only (a router), the selected indices are
21
+ replaced by a round-robin assignment so every expert receives tokens.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import weakref
27
+ from collections.abc import Callable, Iterator
28
+ from contextlib import contextmanager
29
+ from dataclasses import dataclass
30
+ from typing import Any
31
+
32
+ import torch
33
+ from torch.utils._python_dispatch import TorchDispatchMode
34
+ from torch.utils._pytree import tree_flatten, tree_unflatten
35
+
36
+ from wspx.lab.ir.graph import INPUT, Node, OpGraph, ParamUse, Value, compress_indices
37
+
38
+ aten = torch.ops.aten
39
+
40
+ MATMUL_OPS = frozenset({"mm", "addmm", "bmm", "baddbmm", "matmul", "linear", "_grouped_mm"})
41
+ CONV_OPS = frozenset({"convolution", "_convolution", "conv1d", "conv2d", "conv3d"})
42
+ INDEX_OPS = frozenset({"index", "index_select", "_unsafe_index", "gather", "select", "slice"})
43
+ COPY_OPS = frozenset({"_to_copy", "to", "clone", "contiguous", "detach", "alias", "lift_fresh"})
44
+ MOVEMENT_OPS = frozenset(
45
+ {
46
+ "cat",
47
+ "stack",
48
+ "index",
49
+ "_unsafe_index",
50
+ "index_select",
51
+ "gather",
52
+ "repeat",
53
+ "repeat_interleave",
54
+ "flip",
55
+ "roll",
56
+ "_unsafe_view",
57
+ "expand_copy",
58
+ "permute_copy",
59
+ "transpose_copy",
60
+ "view_copy",
61
+ "split_with_sizes_copy",
62
+ "unbind_copy",
63
+ "narrow_copy",
64
+ }
65
+ | COPY_OPS
66
+ )
67
+ ACTIVATION_OPS = frozenset(
68
+ {
69
+ "silu",
70
+ "gelu",
71
+ "relu",
72
+ "sigmoid",
73
+ "tanh",
74
+ "softplus",
75
+ "elu",
76
+ "leaky_relu",
77
+ "hardtanh",
78
+ "hardswish",
79
+ "mish",
80
+ "glu",
81
+ "relu6",
82
+ "hardsigmoid",
83
+ "selu",
84
+ "celu",
85
+ "_prelu_kernel",
86
+ "prelu",
87
+ }
88
+ )
89
+ SOFTMAX_OPS = frozenset({"_softmax", "softmax", "_log_softmax", "log_softmax", "_safe_softmax"})
90
+ WRITE_OPS = frozenset(
91
+ {"copy", "index_put", "index_copy", "masked_scatter", "scatter", "fill", "zero"}
92
+ )
93
+ """In-place ops that overwrite (part of) their first argument rather than combine with it."""
94
+
95
+
96
+ def short_name(func: Any) -> str:
97
+ """``aten.mm.default`` → ``mm``; strips trailing ``_`` of in-place variants."""
98
+ name = str(getattr(func, "__name__", func)).split(".")[0]
99
+ return name[:-1] if name.endswith("_") and not name.startswith("_") else name
100
+
101
+
102
+ def is_pointwise(func: Any) -> bool:
103
+ return torch.Tag.pointwise in getattr(func, "tags", ())
104
+
105
+
106
+ def is_view(func: Any) -> bool:
107
+ return bool(getattr(func, "is_view", False))
108
+
109
+
110
+ @dataclass(slots=True)
111
+ class _ParamRef:
112
+ name: str
113
+ dim_map: tuple[int | None, ...]
114
+ rows: list[int] | None
115
+
116
+
117
+ @dataclass(slots=True)
118
+ class _Derived:
119
+ """A value computed only from parameters (a cast, ``1 + w``, an expert slice)."""
120
+
121
+ sources: tuple[str, ...]
122
+ dim_map: tuple[int | None, ...] | None
123
+ rows: list[int] | None
124
+
125
+
126
+ READER_SHIFT = 32
127
+ """Shadow values encode ``(projection node << 32) | feature`` so mixed sources stay exact."""
128
+
129
+
130
+ @dataclass(slots=True)
131
+ class _Shadow:
132
+ tensor: torch.Tensor
133
+
134
+
135
+ class Tape(TorchDispatchMode): # type: ignore[no-untyped-call]
136
+ """Record one forward pass into an :class:`OpGraph`.
137
+
138
+ Use :meth:`recording` rather than entering the mode directly: it installs the
139
+ module hooks that attribute each op to the module that ran it.
140
+ """
141
+
142
+ def __init__(
143
+ self,
144
+ model: torch.nn.Module,
145
+ phase: str,
146
+ *,
147
+ force_routing: bool = False,
148
+ route_offset: int = 0,
149
+ track_features: bool = True,
150
+ ) -> None:
151
+ super().__init__() # type: ignore[no-untyped-call]
152
+ self.graph = OpGraph(phase)
153
+ self.graphs: dict[str, OpGraph] = {phase: self.graph}
154
+ self.active = True
155
+ """When false, ops run untouched (generation glue between forward calls)."""
156
+ self.force_routing = force_routing
157
+ self.route_offset = route_offset
158
+ self.track_features = track_features
159
+ self.routers: dict[int, dict[str, int]] = {}
160
+ """topk node idx → ``{"router": node idx, "experts": n, "k": k, "slots": tokens × k}``."""
161
+ self.rows_read: dict[str, set[int]] = {}
162
+ """Leading-dim rows read per parameter, for reads that select rows (expert weights)."""
163
+ self.full_read: set[str] = set()
164
+ """Parameters read whole at least once."""
165
+
166
+ self._params: dict[int, list[tuple[str, torch.Tensor]]] = {}
167
+ for name, param in model.named_parameters():
168
+ ptr = param.untyped_storage().data_ptr()
169
+ self._params.setdefault(ptr, []).append((name, param))
170
+ self._buffers: dict[int, str] = {}
171
+ for name, buf in model.named_buffers():
172
+ if buf.device.type != "meta":
173
+ self._buffers.setdefault(buf.untyped_storage().data_ptr(), name)
174
+
175
+ self._vid_of: dict[int, int] = {}
176
+ self._ref_of: dict[int, weakref.ref[torch.Tensor]] = {}
177
+ self._derived: dict[int, _Derived] = {}
178
+ self._shadow: dict[int, _Shadow] = {}
179
+ self._param_dep: set[int] = set()
180
+ """Values computed (transitively) from some parameter."""
181
+ self._next_vid = 0
182
+ self._stack: list[str] = []
183
+ self._model = model
184
+
185
+ # ------------------------------------------------------------------ public
186
+
187
+ @contextmanager
188
+ def recording(self) -> Iterator[Tape]:
189
+ names = {id(m): n for n, m in self._model.named_modules(remove_duplicate=False)}
190
+ handles = []
191
+
192
+ def pre(module: torch.nn.Module, _args: Any) -> None:
193
+ self._stack.append(names.get(id(module), type(module).__name__))
194
+
195
+ def post(_module: torch.nn.Module, _args: Any, _out: Any) -> None:
196
+ if self._stack:
197
+ self._stack.pop()
198
+
199
+ for module in self._model.modules():
200
+ handles.append(module.register_forward_pre_hook(pre))
201
+ handles.append(module.register_forward_hook(post, always_call=True))
202
+ try:
203
+ with self:
204
+ yield self
205
+ finally:
206
+ for handle in handles:
207
+ handle.remove()
208
+ self._stack.clear()
209
+
210
+ def start_phase(self, phase: str) -> None:
211
+ """Record subsequent ops into a fresh graph; tensors from earlier phases become inputs."""
212
+ self.graph = OpGraph(phase)
213
+ self.graphs[phase] = self.graph
214
+ self._vid_of.clear()
215
+ self._ref_of.clear()
216
+ self._derived.clear()
217
+ self._shadow.clear()
218
+ self._param_dep.clear()
219
+
220
+ def mark_outputs(self, output: Any) -> None:
221
+ for tensor in _iter_tensors(output):
222
+ vid = self._lookup_vid(tensor)
223
+ if vid is not None and vid not in self.graph.outputs:
224
+ self.graph.outputs.append(vid)
225
+
226
+ def release(self) -> None:
227
+ """Drop tensor references once recording is finished."""
228
+ self._shadow.clear()
229
+ self._vid_of.clear()
230
+ self._ref_of.clear()
231
+
232
+ # ------------------------------------------------------------------ values
233
+
234
+ def _lookup_vid(self, tensor: torch.Tensor) -> int | None:
235
+ key = id(tensor)
236
+ ref = self._ref_of.get(key)
237
+ if ref is None or ref() is not tensor:
238
+ return None
239
+ return self._vid_of[key]
240
+
241
+ def _bind(self, tensor: torch.Tensor, producer: int) -> int:
242
+ vid = self._next_vid
243
+ self._next_vid += 1
244
+ key = id(tensor)
245
+ self._vid_of[key] = vid
246
+ self._ref_of[key] = weakref.ref(tensor, self._forget(key, vid))
247
+ self.graph.values[vid] = Value(vid, tuple(tensor.shape), str(tensor.dtype), producer)
248
+ return vid
249
+
250
+ def _forget(self, key: int, vid: int) -> Callable[[Any], None]:
251
+ def cleanup(_ref: Any) -> None:
252
+ if self._vid_of.get(key) == vid:
253
+ self._vid_of.pop(key, None)
254
+ self._ref_of.pop(key, None)
255
+ self._shadow.pop(vid, None)
256
+
257
+ return cleanup
258
+
259
+ def _param_of(self, tensor: torch.Tensor) -> _ParamRef | None:
260
+ try:
261
+ ptr = tensor.untyped_storage().data_ptr()
262
+ except (RuntimeError, NotImplementedError):
263
+ return None
264
+ candidates = self._params.get(ptr)
265
+ if not candidates:
266
+ return None
267
+ name, param = candidates[0]
268
+ if len(candidates) > 1:
269
+ off = tensor.storage_offset()
270
+ for cand_name, cand in candidates:
271
+ span = cand.storage_offset() + max(cand.numel(), 1)
272
+ if cand.storage_offset() <= off < span:
273
+ name, param = cand_name, cand
274
+ break
275
+ return _ParamRef(name, _stride_map(tensor, param), _rows_of_view(tensor, param))
276
+
277
+ # ------------------------------------------------------------------ dispatch
278
+
279
+ def __torch_dispatch__(
280
+ self,
281
+ func: Any,
282
+ types: Any,
283
+ args: tuple[Any, ...] = (),
284
+ kwargs: dict[str, Any] | None = None,
285
+ ) -> Any:
286
+ kwargs = kwargs or {}
287
+ if not self.active:
288
+ return func(*args, **kwargs)
289
+ name = short_name(func)
290
+ leaves, spec = tree_flatten((args, kwargs))
291
+ positions = [i for i, leaf in enumerate(leaves) if isinstance(leaf, torch.Tensor)]
292
+
293
+ arg_vids: list[int] = []
294
+ param_uses: list[ParamUse] = []
295
+ param_refs: dict[int, list[_ParamRef]] = {}
296
+ buffers: list[str] = []
297
+ new_inputs: list[tuple[int, torch.Tensor]] = []
298
+ for pos, leaf_idx in enumerate(positions):
299
+ tensor = leaves[leaf_idx]
300
+ ref = self._param_of(tensor)
301
+ if ref is not None:
302
+ arg_vids.append(-1)
303
+ param_refs[pos] = [ref]
304
+ param_uses.append(ParamUse(ref.name, pos, ref.rows))
305
+ continue
306
+ vid = self._lookup_vid(tensor)
307
+ if vid is not None and vid in self._derived:
308
+ derived = self._derived[vid]
309
+ arg_vids.append(-1)
310
+ refs = [
311
+ _ParamRef(src, derived.dim_map or (), derived.rows) for src in derived.sources
312
+ ]
313
+ param_refs[pos] = refs
314
+ param_uses.extend(ParamUse(r.name, pos, r.rows) for r in refs)
315
+ continue
316
+ if vid is None:
317
+ try:
318
+ buf = self._buffers.get(tensor.untyped_storage().data_ptr())
319
+ except (RuntimeError, NotImplementedError):
320
+ buf = None
321
+ if buf is not None:
322
+ arg_vids.append(-1)
323
+ buffers.append(buf)
324
+ continue
325
+ new_inputs.append((pos, tensor))
326
+ arg_vids.append(-2) # placeholder, bound below
327
+ continue
328
+ arg_vids.append(vid)
329
+
330
+ for pos, tensor in new_inputs:
331
+ vid = self._bind(tensor, INPUT)
332
+ self.graph.inputs.append(vid)
333
+ arg_vids[pos] = vid
334
+
335
+ # An in-place op on a view also changes the view's base: remember both.
336
+ packet = str(func).split(".")
337
+ inplace = len(packet) > 1 and packet[1].endswith("_") and not packet[1].startswith("__")
338
+ dst = leaves[positions[0]] if inplace and positions else None
339
+ base = dst._base if dst is not None and dst._base is not None else None
340
+ base_old = self._lookup_vid(base) if base is not None else None
341
+ dst_old = arg_vids[0] if inplace and arg_vids else None
342
+
343
+ out = func(*args, **kwargs)
344
+
345
+ node_idx = len(self.graph.nodes)
346
+ meta: dict[str, Any] = {}
347
+ if buffers:
348
+ meta["buffers"] = buffers
349
+ if name == "topk" and self.force_routing:
350
+ out = self._maybe_force_route(node_idx, arg_vids, args, kwargs, out, meta)
351
+
352
+ out_leaves, out_spec = tree_flatten(out)
353
+ out_tensors = [t for t in out_leaves if isinstance(t, torch.Tensor)]
354
+ input_tensors = [leaves[i] for i in positions]
355
+ activation_in = [v for v in arg_vids if v >= 0]
356
+
357
+ # Ops that only re-view a parameter produce no value; later reads are
358
+ # recognised by storage, so the node itself carries no information.
359
+ if (
360
+ out_tensors
361
+ and all(self._param_of(t) is not None for t in out_tensors)
362
+ and not activation_in
363
+ ):
364
+ return out
365
+
366
+ data_is_param = bool(param_refs.get(0)) and name in INDEX_OPS
367
+ param_only = bool(param_uses) and (not activation_in or data_is_param)
368
+
369
+ node = Node(
370
+ node_idx,
371
+ str(func),
372
+ self._stack[-1] if self._stack else "",
373
+ arg_vids,
374
+ param_uses,
375
+ [],
376
+ meta,
377
+ )
378
+ self._contraction_dims(name, node, param_refs, input_tensors)
379
+ if name == "_grouped_mm":
380
+ self._grouped_rows(node, leaves, positions)
381
+
382
+ out_vids: list[int] = []
383
+ for tensor in out_tensors:
384
+ if self._param_of(tensor) is not None:
385
+ out_vids.append(-1)
386
+ continue
387
+ vid = self._bind(tensor, node_idx)
388
+ out_vids.append(vid)
389
+ if param_only:
390
+ self._derived[vid] = self._derive(name, param_refs, input_tensors, tensor, arg_vids)
391
+ node.outs = out_vids
392
+ if base is not None and base_old is not None:
393
+ node.meta["writes_base"] = self._bind(base, node_idx)
394
+ out_vids = [*out_vids, node.meta["writes_base"]]
395
+ if node.params or any(v in self._param_dep for v in activation_in):
396
+ self._param_dep.update(v for v in out_vids if v >= 0)
397
+ for use in node.params:
398
+ if use.rows is not None:
399
+ self.rows_read.setdefault(use.name, set()).update(use.rows)
400
+ else:
401
+ self.full_read.add(use.name)
402
+ self.graph.nodes.append(node)
403
+
404
+ if self.track_features and not param_only:
405
+ if inplace and name in WRITE_OPS and dst is not None:
406
+ self._write_shadow(
407
+ func,
408
+ name,
409
+ node,
410
+ leaves,
411
+ spec,
412
+ positions,
413
+ dst,
414
+ base,
415
+ base_old if base is not None else dst_old,
416
+ )
417
+ else:
418
+ self._propagate_shadows(func, name, node, leaves, spec, positions, out_tensors)
419
+ del out_spec
420
+ return out
421
+
422
+ # ------------------------------------------------------------------ layout
423
+
424
+ def _contraction_dims(
425
+ self,
426
+ name: str,
427
+ node: Node,
428
+ refs: dict[int, list[_ParamRef]],
429
+ inputs: list[torch.Tensor],
430
+ ) -> None:
431
+ """Fill ``in_dim``/``out_dim`` on parameter uses of matmul-like ops."""
432
+ operand: dict[int, tuple[int, int]] = {}
433
+ if name == "mm":
434
+ operand = {0: (1, 0), 1: (0, 1)} # position → (in axis, out axis) of that operand
435
+ elif name in ("addmm",):
436
+ operand = {1: (1, 0), 2: (0, 1)}
437
+ elif name in ("bmm",):
438
+ operand = {0: (2, 1), 1: (1, 2)}
439
+ elif name == "baddbmm":
440
+ operand = {1: (2, 1), 2: (1, 2)}
441
+ elif name == "linear":
442
+ operand = {1: (1, 0)}
443
+ elif name == "_grouped_mm":
444
+ operand = {1: (1, 2)}
445
+ elif name in CONV_OPS:
446
+ operand = {1: (1, 0)}
447
+ elif name == "embedding":
448
+ operand = {0: (0, 1)}
449
+ elif name == "matmul" and len(inputs) >= 2:
450
+ nd = inputs[1].dim()
451
+ operand = {1: (nd - 2, nd - 1)} if nd >= 2 else {}
452
+ for use in node.params:
453
+ axes = operand.get(use.arg)
454
+ if axes is None:
455
+ continue
456
+ ref = next((r for r in refs.get(use.arg, []) if r.name == use.name), None)
457
+ if ref is None or not ref.dim_map:
458
+ continue
459
+ in_ax, out_ax = axes
460
+ if in_ax < len(ref.dim_map):
461
+ use.in_dim = ref.dim_map[in_ax]
462
+ if out_ax < len(ref.dim_map):
463
+ use.out_dim = ref.dim_map[out_ax]
464
+ if name == "embedding":
465
+ use.rows = None
466
+
467
+ def _grouped_rows(self, node: Node, leaves: list[Any], positions: list[int]) -> None:
468
+ offs = None
469
+ for leaf in leaves:
470
+ if (
471
+ isinstance(leaf, torch.Tensor)
472
+ and leaf.dtype in (torch.int32, torch.int64)
473
+ and leaf.dim() == 1
474
+ ):
475
+ offs = leaf
476
+ if offs is None:
477
+ return
478
+ ends = offs.tolist()
479
+ sizes = [e - s for s, e in zip([0, *ends[:-1]], ends, strict=True)]
480
+ rows = [i for i, size in enumerate(sizes) if size > 0]
481
+ for use in node.params:
482
+ if use.arg == 1:
483
+ use.rows = rows
484
+
485
+ def _derive(
486
+ self,
487
+ name: str,
488
+ refs: dict[int, list[_ParamRef]],
489
+ inputs: list[torch.Tensor],
490
+ out: torch.Tensor,
491
+ arg_vids: list[int],
492
+ ) -> _Derived:
493
+ sources = tuple(dict.fromkeys(r.name for rs in refs.values() for r in rs))
494
+ first = refs.get(0, [None])[0]
495
+ dim_map: tuple[int | None, ...] | None = None
496
+ rows = first.rows if first is not None else None
497
+ if first is not None and first.dim_map:
498
+ if name in COPY_OPS:
499
+ dim_map = first.dim_map
500
+ elif name in ("index", "_unsafe_index", "index_select"):
501
+ index_vals = [
502
+ t
503
+ for pos, t in enumerate(inputs)
504
+ if pos > 0 and t.dtype in (torch.int32, torch.int64)
505
+ ]
506
+ if index_vals:
507
+ rows = sorted({int(i) for i in index_vals[0].flatten().tolist()})
508
+ dim_map = (None, *first.dim_map[1:])
509
+ elif is_view_like(name) and inputs:
510
+ local = _stride_map(out, inputs[0])
511
+ dim_map = tuple(
512
+ first.dim_map[d] if d is not None and d < len(first.dim_map) else None
513
+ for d in local
514
+ )
515
+ del arg_vids
516
+ return _Derived(sources, dim_map, rows)
517
+
518
+ # ------------------------------------------------------------------ routing
519
+
520
+ def _maybe_force_route(
521
+ self,
522
+ node_idx: int,
523
+ arg_vids: list[int],
524
+ args: tuple[Any, ...],
525
+ kwargs: dict[str, Any],
526
+ out: Any,
527
+ meta: dict[str, Any],
528
+ ) -> Any:
529
+ if not arg_vids or arg_vids[0] < 0:
530
+ return out
531
+ router = self._router_of(arg_vids[0])
532
+ if router is None:
533
+ return out
534
+ scores: torch.Tensor = args[0]
535
+ k = int(args[1]) if len(args) > 1 else int(kwargs["k"])
536
+ dim = int(args[2]) if len(args) > 2 else int(kwargs.get("dim", -1))
537
+ dim = dim % scores.dim()
538
+ n = scores.shape[dim]
539
+ moved = scores.movedim(dim, -1)
540
+ rows = moved.reshape(-1, n).shape[0]
541
+ base = torch.arange(rows * k, device=scores.device).reshape(rows, k) + self.route_offset
542
+ idx = (base % n).reshape(*moved.shape[:-1], k).movedim(-1, dim).contiguous()
543
+ values = torch.gather(scores, dim, idx)
544
+ meta["forced_routing"] = {"router": router, "experts": n, "k": k}
545
+ self.routers[node_idx] = {"router": router, "experts": n, "k": k, "slots": rows * k}
546
+ return (values, idx)
547
+
548
+ def _router_of(self, vid: int) -> int | None:
549
+ """Walk back through pointwise/softmax/movement ops to a parameter projection."""
550
+ for _ in range(32):
551
+ node = self.graph.producer(vid)
552
+ if node is None:
553
+ return None
554
+ name = node.short_op
555
+ if node.params and (name in MATMUL_OPS or name in CONV_OPS):
556
+ return node.idx
557
+ floating = [
558
+ v
559
+ for _, v in node.activation_args
560
+ if self.graph.values[v].dtype.startswith("torch.float")
561
+ or self.graph.values[v].dtype.startswith("torch.bfloat")
562
+ ]
563
+ passthrough = (
564
+ name in SOFTMAX_OPS
565
+ or name in MOVEMENT_OPS
566
+ or is_view_like(name)
567
+ or _pointwise_name(node.op)
568
+ )
569
+ if not passthrough or not floating:
570
+ return None
571
+ vid = floating[0]
572
+ return None
573
+
574
+ # ------------------------------------------------------------------ features
575
+
576
+ def _propagate_shadows(
577
+ self,
578
+ func: Any,
579
+ name: str,
580
+ node: Node,
581
+ leaves: list[Any],
582
+ spec: Any,
583
+ positions: list[int],
584
+ outs: list[torch.Tensor],
585
+ ) -> None:
586
+ shadowed = [
587
+ (pos, vid, self._shadow[vid])
588
+ for pos, vid in node.activation_args
589
+ if vid in self._shadow
590
+ ]
591
+
592
+ if node.params and (name in MATMUL_OPS or name in CONV_OPS) and outs:
593
+ out = outs[0]
594
+ fdim = 1 if name in CONV_OPS else out.dim() - 1
595
+ if out.dim() > 0 and node.outs and node.outs[0] >= 0:
596
+ size = out.shape[fdim]
597
+ shape = [1] * out.dim()
598
+ shape[fdim] = size
599
+ codes = torch.arange(size, device=out.device) + (node.idx << READER_SHIFT)
600
+ shadow = codes.view(shape).expand(out.shape).contiguous()
601
+ self._shadow[node.outs[0]] = _Shadow(shadow)
602
+ if shadowed:
603
+ self._record_features(node, shadowed)
604
+ return
605
+ if not shadowed:
606
+ return
607
+
608
+ pointwise = is_pointwise(func)
609
+ if name in ACTIVATION_OPS or (pointwise and len(shadowed) > 1):
610
+ self._record_features(node, shadowed)
611
+ if pointwise:
612
+ # Mixing in another full-shape, parameter-derived activation without a
613
+ # shadow (the residual in ``x + f(x)``) means the output is no longer pure
614
+ # projection features. Broadcast factors (norm scales, routing weights) and
615
+ # constants (rotary tables, masks) keep features where they are.
616
+ shadowed_vids = {vid for _, vid, _ in shadowed}
617
+ out_shape = tuple(outs[0].shape) if outs else ()
618
+ for _, vid in node.activation_args:
619
+ if (
620
+ vid not in shadowed_vids
621
+ and vid in self._param_dep
622
+ and self.graph.values[vid].shape == out_shape
623
+ ):
624
+ return
625
+ for vid, out in zip(node.outs, outs, strict=False):
626
+ if vid < 0:
627
+ continue
628
+ for _, _, sh in shadowed:
629
+ try:
630
+ self._shadow[vid] = _Shadow(sh.tensor.expand(out.shape))
631
+ break
632
+ except RuntimeError:
633
+ continue
634
+ return
635
+ if name in MOVEMENT_OPS or is_view(func) or is_view_like(name):
636
+ if name in COPY_OPS or name in ("lift_fresh",):
637
+ if node.outs and node.outs[0] >= 0:
638
+ self._shadow[node.outs[0]] = shadowed[0][2]
639
+ return
640
+ replayed = self._replay(func, leaves, spec, positions, node, outs)
641
+ if replayed is not None:
642
+ for vid, replay in zip(node.outs, replayed, strict=False):
643
+ if vid >= 0 and replay is not None:
644
+ self._shadow[vid] = _Shadow(replay)
645
+ return
646
+ self._record_features(node, shadowed)
647
+
648
+ def _replay(
649
+ self,
650
+ func: Any,
651
+ leaves: list[Any],
652
+ spec: Any,
653
+ positions: list[int],
654
+ node: Node,
655
+ outs: list[torch.Tensor],
656
+ ) -> list[torch.Tensor | None] | None:
657
+ new_leaves = list(leaves)
658
+ for pos, leaf_idx in enumerate(positions):
659
+ tensor = leaves[leaf_idx]
660
+ if not (tensor.is_floating_point() or tensor.is_complex()):
661
+ continue # indices and masks keep their values
662
+ vid = node.args[pos]
663
+ if vid >= 0 and vid in self._shadow:
664
+ new_leaves[leaf_idx] = self._shadow[vid].tensor
665
+ else:
666
+ new_leaves[leaf_idx] = torch.full(
667
+ tensor.shape, -1, dtype=torch.long, device=tensor.device
668
+ )
669
+ args, kwargs = tree_unflatten(new_leaves, spec)
670
+ kwargs = {k: v for k, v in kwargs.items() if k not in ("dtype", "memory_format")}
671
+ try:
672
+ result = func(*args, **kwargs)
673
+ except RuntimeError:
674
+ # Shadows can differ from the real tensor in layout (a pointwise op may
675
+ # hand on an expanded view). Views are defined on logical shape, so the
676
+ # same op on contiguous shadows gives the same answer.
677
+ leaves2 = [
678
+ t.contiguous() if isinstance(t, torch.Tensor) and t.dtype == torch.long else t
679
+ for t in new_leaves
680
+ ]
681
+ args, kwargs = tree_unflatten(leaves2, spec)
682
+ kwargs = {k: v for k, v in kwargs.items() if k not in ("dtype", "memory_format")}
683
+ try:
684
+ result = func(*args, **kwargs)
685
+ except (RuntimeError, TypeError, NotImplementedError, IndexError):
686
+ return None
687
+ except (TypeError, NotImplementedError, IndexError):
688
+ return None
689
+ flat = [t for t in tree_flatten(result)[0] if isinstance(t, torch.Tensor)]
690
+ if len(flat) != len(outs):
691
+ return None
692
+ return [s if s.shape == o.shape else None for s, o in zip(flat, outs, strict=True)]
693
+
694
+ def _write_shadow(
695
+ self,
696
+ func: Any,
697
+ name: str,
698
+ node: Node,
699
+ leaves: list[Any],
700
+ spec: Any,
701
+ positions: list[int],
702
+ dst: torch.Tensor,
703
+ base: torch.Tensor | None,
704
+ old_vid: int | None,
705
+ ) -> None:
706
+ """Replay an in-place write on the target's shadow, laid out exactly like the target."""
707
+ target = base if base is not None else dst
708
+ sources = [v for p, v in node.activation_args if p > 0 and v in self._shadow]
709
+ existing = self._shadow.get(old_vid) if old_vid is not None else None
710
+ if existing is None and not sources:
711
+ return
712
+ shadow = existing.tensor if existing is not None else None
713
+ if shadow is None or shadow.shape != target.shape or shadow.stride() != target.stride():
714
+ fresh = torch.empty_strided(
715
+ target.shape, target.stride(), dtype=torch.long, device=target.device
716
+ ).fill_(-1)
717
+ if shadow is not None:
718
+ fresh.copy_(shadow)
719
+ shadow = fresh
720
+ if base is not None:
721
+ offset = dst.storage_offset() - target.storage_offset() + shadow.storage_offset()
722
+ region = shadow.as_strided(dst.shape, dst.stride(), offset)
723
+ else:
724
+ region = shadow
725
+ if name in ("fill", "zero"):
726
+ region.fill_(-1)
727
+ else:
728
+ new_leaves = list(leaves)
729
+ new_leaves[positions[0]] = region
730
+ for pos, leaf_idx in enumerate(positions[1:], start=1):
731
+ tensor = leaves[leaf_idx]
732
+ if not tensor.is_floating_point():
733
+ continue
734
+ vid = node.args[pos]
735
+ new_leaves[leaf_idx] = (
736
+ self._shadow[vid].tensor
737
+ if vid >= 0 and vid in self._shadow
738
+ else torch.full(tensor.shape, -1, dtype=torch.long, device=tensor.device)
739
+ )
740
+ args, kwargs = tree_unflatten(new_leaves, spec)
741
+ kwargs = {k: v for k, v in kwargs.items() if k not in ("dtype", "memory_format")}
742
+ try:
743
+ func(*args, **kwargs)
744
+ except (RuntimeError, TypeError, NotImplementedError, IndexError):
745
+ return
746
+ if base is not None:
747
+ self._shadow[node.meta["writes_base"]] = _Shadow(shadow)
748
+ if node.outs and node.outs[0] >= 0:
749
+ self._shadow[node.outs[0]] = _Shadow(region)
750
+ elif node.outs and node.outs[0] >= 0:
751
+ self._shadow[node.outs[0]] = _Shadow(shadow)
752
+
753
+ def _record_features(self, node: Node, shadowed: list[tuple[int, int, _Shadow]]) -> None:
754
+ """Store, per argument, ``[[projection node, feature runs], …]``."""
755
+ feats = node.meta.setdefault("features", {})
756
+ mask = (1 << READER_SHIFT) - 1
757
+ for pos, _, sh in shadowed:
758
+ values = torch.unique(sh.tensor)
759
+ values = values[values >= 0].tolist()
760
+ by_reader: dict[int, list[int]] = {}
761
+ for v in values:
762
+ by_reader.setdefault(int(v) >> READER_SHIFT, []).append(int(v) & mask)
763
+ feats[str(pos)] = [
764
+ [r, compress_indices(sorted(f))] for r, f in sorted(by_reader.items())
765
+ ]
766
+
767
+
768
+ # ---------------------------------------------------------------------- helpers
769
+
770
+ _VIEW_LIKE = frozenset(
771
+ {
772
+ "view",
773
+ "_unsafe_view",
774
+ "reshape",
775
+ "transpose",
776
+ "permute",
777
+ "t",
778
+ "unsqueeze",
779
+ "squeeze",
780
+ "expand",
781
+ "slice",
782
+ "select",
783
+ "split",
784
+ "split_with_sizes",
785
+ "chunk",
786
+ "unbind",
787
+ "narrow",
788
+ "as_strided",
789
+ "movedim",
790
+ "unflatten",
791
+ "flatten",
792
+ "diagonal",
793
+ "unfold",
794
+ "view_as",
795
+ "alias",
796
+ }
797
+ )
798
+
799
+
800
+ def is_view_like(name: str) -> bool:
801
+ return name in _VIEW_LIKE
802
+
803
+
804
+ def _pointwise_name(op: str) -> bool:
805
+ try:
806
+ packet, _, overload = op.removeprefix("aten.").partition(".")
807
+ func = getattr(getattr(aten, packet), overload or "default")
808
+ except AttributeError:
809
+ return False
810
+ return is_pointwise(func)
811
+
812
+
813
+ def _stride_map(view: torch.Tensor, base: torch.Tensor) -> tuple[int | None, ...]:
814
+ """Map each dim of ``view`` to the dim of ``base`` it walks along, by stride."""
815
+ used: set[int] = set()
816
+ out: list[int | None] = []
817
+ for size, stride in zip(view.shape, view.stride(), strict=True):
818
+ match = None
819
+ if size > 1:
820
+ for j, (bsize, bstride) in enumerate(zip(base.shape, base.stride(), strict=True)):
821
+ if j not in used and bstride == stride and bsize >= size and bsize > 1:
822
+ match = j
823
+ break
824
+ if match is not None:
825
+ used.add(match)
826
+ out.append(match)
827
+ return tuple(out)
828
+
829
+
830
+ def _rows_of_view(view: torch.Tensor, param: torch.Tensor) -> list[int] | None:
831
+ if view.numel() == param.numel() or param.dim() < 2 or param.stride(0) <= 0:
832
+ return None
833
+ first = int((view.storage_offset() - param.storage_offset()) // param.stride(0))
834
+ if view.dim() == param.dim() - 1 and tuple(view.shape) == tuple(param.shape[1:]):
835
+ return [first]
836
+ if (
837
+ view.dim() == param.dim()
838
+ and view.stride(0) == param.stride(0)
839
+ and tuple(view.shape[1:]) == tuple(param.shape[1:])
840
+ ):
841
+ return list(range(first, first + view.shape[0]))
842
+ return None
843
+
844
+
845
+ def _iter_tensors(obj: Any) -> Iterator[torch.Tensor]:
846
+ if isinstance(obj, torch.Tensor):
847
+ yield obj
848
+ elif isinstance(obj, dict):
849
+ for value in obj.values():
850
+ yield from _iter_tensors(value)
851
+ elif isinstance(obj, list | tuple):
852
+ for value in obj:
853
+ yield from _iter_tensors(value)