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/gateway/usage.py ADDED
@@ -0,0 +1,284 @@
1
+ """Per-call usage and content, read from each provider's native responses.
2
+
3
+ Each provider reports token usage on every call, streamed responses included:
4
+
5
+ * Anthropic: ``message_start`` (input and cache tokens) and ``message_delta``
6
+ (cumulative output tokens) stream events; ``usage`` on plain responses.
7
+ * OpenAI Responses: the ``response.completed`` event carries the full response
8
+ with ``usage``; Chat Completions streams send it in the final chunk when
9
+ ``stream_options.include_usage`` is set.
10
+ * Gemini: ``usageMetadata`` on responses and stream chunks (the last is total).
11
+
12
+ The SDKs type these fields as optional. A call that ends without usage keeps
13
+ its full reservation rather than being guessed at.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ from dataclasses import dataclass, field
20
+ from typing import Any
21
+
22
+ from wspx.gateway.prices import Price
23
+
24
+
25
+ @dataclass
26
+ class Usage:
27
+ input: int = 0
28
+ output: int = 0
29
+ cache_read: int = 0
30
+ cache_write: int = 0
31
+ reasoning: int = 0
32
+ """Already included in ``output`` for every provider handled here."""
33
+ complete: bool = False
34
+
35
+ def cost(self, price: Price | None) -> float | None:
36
+ if price is None or not self.complete:
37
+ return None
38
+ return (
39
+ self.input * price.input
40
+ + self.output * price.output
41
+ + self.cache_read * price.read
42
+ + self.cache_write * price.write
43
+ ) / 1e6
44
+
45
+
46
+ @dataclass
47
+ class Observed:
48
+ """What the loop detector needs from one model response."""
49
+
50
+ text: str = ""
51
+ tool_calls: list[tuple[str, Any]] = field(default_factory=list)
52
+ stop_reason: str | None = None
53
+
54
+
55
+ # --------------------------------------------------------------------------- anthropic
56
+
57
+
58
+ def anthropic_json(body: dict[str, Any]) -> tuple[Usage, Observed]:
59
+ u = body.get("usage") or {}
60
+ usage = Usage(
61
+ input=int(u.get("input_tokens") or 0),
62
+ output=int(u.get("output_tokens") or 0),
63
+ cache_read=int(u.get("cache_read_input_tokens") or 0),
64
+ cache_write=int(u.get("cache_creation_input_tokens") or 0),
65
+ complete=bool(u),
66
+ )
67
+ obs = Observed(stop_reason=body.get("stop_reason"))
68
+ for block in body.get("content") or []:
69
+ if block.get("type") == "text":
70
+ obs.text += block.get("text", "")
71
+ elif block.get("type") == "tool_use":
72
+ obs.tool_calls.append((block.get("name", ""), block.get("input")))
73
+ return usage, obs
74
+
75
+
76
+ class AnthropicStream:
77
+ def __init__(self) -> None:
78
+ self.usage = Usage()
79
+ self.obs = Observed()
80
+ self._tools: dict[int, list[Any]] = {}
81
+ self._done = False
82
+
83
+ def event(self, name: str, data: dict[str, Any]) -> None:
84
+ kind = data.get("type", name)
85
+ if kind == "message_start":
86
+ u = (data.get("message") or {}).get("usage") or {}
87
+ self.usage.input = int(u.get("input_tokens") or 0)
88
+ self.usage.cache_read = int(u.get("cache_read_input_tokens") or 0)
89
+ self.usage.cache_write = int(u.get("cache_creation_input_tokens") or 0)
90
+ self.usage.output = int(u.get("output_tokens") or 0)
91
+ elif kind == "content_block_start":
92
+ block = data.get("content_block") or {}
93
+ if block.get("type") == "tool_use":
94
+ self._tools[int(data.get("index", 0))] = [block.get("name", ""), ""]
95
+ elif kind == "content_block_delta":
96
+ delta = data.get("delta") or {}
97
+ if delta.get("type") == "text_delta":
98
+ self.obs.text += delta.get("text", "")
99
+ elif (
100
+ delta.get("type") == "input_json_delta" and int(data.get("index", 0)) in self._tools
101
+ ):
102
+ self._tools[int(data.get("index", 0))][1] += delta.get("partial_json", "")
103
+ elif kind == "message_delta":
104
+ u = data.get("usage") or {}
105
+ if "output_tokens" in u:
106
+ self.usage.output = int(u["output_tokens"])
107
+ for key, attr in (
108
+ ("input_tokens", "input"),
109
+ ("cache_read_input_tokens", "cache_read"),
110
+ ("cache_creation_input_tokens", "cache_write"),
111
+ ):
112
+ if u.get(key) is not None:
113
+ setattr(self.usage, attr, int(u[key]))
114
+ self.obs.stop_reason = (data.get("delta") or {}).get("stop_reason")
115
+ elif kind == "message_stop":
116
+ self._done = True
117
+
118
+ def finish(self) -> tuple[Usage, Observed]:
119
+ self.usage.complete = self._done
120
+ for name, raw in self._tools.values():
121
+ try:
122
+ self.obs.tool_calls.append((name, json.loads(raw or "{}")))
123
+ except json.JSONDecodeError:
124
+ self.obs.tool_calls.append((name, raw))
125
+ return self.usage, self.obs
126
+
127
+
128
+ # --------------------------------------------------------------------------- openai
129
+
130
+
131
+ def openai_json(body: dict[str, Any]) -> tuple[Usage, Observed]:
132
+ u = body.get("usage") or {}
133
+ obs = Observed(stop_reason=body.get("status") or None)
134
+ if "input_tokens" in u: # Responses API: input_tokens includes cached and cache-written tokens
135
+ details = u.get("input_tokens_details") or {}
136
+ cached = int(details.get("cached_tokens") or 0)
137
+ written = int(details.get("cache_write_tokens") or 0)
138
+ usage = Usage(
139
+ input=int(u.get("input_tokens") or 0) - cached - written,
140
+ output=int(u.get("output_tokens") or 0),
141
+ cache_read=cached,
142
+ cache_write=written,
143
+ reasoning=int((u.get("output_tokens_details") or {}).get("reasoning_tokens") or 0),
144
+ complete=True,
145
+ )
146
+ for item in body.get("output") or []:
147
+ if item.get("type") == "message":
148
+ for part in item.get("content") or []:
149
+ if part.get("type") == "output_text":
150
+ obs.text += part.get("text", "")
151
+ elif item.get("type") == "function_call":
152
+ obs.tool_calls.append((item.get("name", ""), _loads(item.get("arguments"))))
153
+ return usage, obs
154
+ usage = Usage( # Chat Completions
155
+ input=int(u.get("prompt_tokens") or 0)
156
+ - int((u.get("prompt_tokens_details") or {}).get("cached_tokens") or 0),
157
+ output=int(u.get("completion_tokens") or 0),
158
+ cache_read=int((u.get("prompt_tokens_details") or {}).get("cached_tokens") or 0),
159
+ complete=bool(u),
160
+ )
161
+ for choice in body.get("choices") or []:
162
+ msg = choice.get("message") or {}
163
+ obs.text += msg.get("content") or ""
164
+ for call in msg.get("tool_calls") or []:
165
+ fn = call.get("function") or {}
166
+ obs.tool_calls.append((fn.get("name", ""), _loads(fn.get("arguments"))))
167
+ obs.stop_reason = choice.get("finish_reason")
168
+ return usage, obs
169
+
170
+
171
+ class OpenAIStream:
172
+ def __init__(self) -> None:
173
+ self.usage = Usage()
174
+ self.obs = Observed()
175
+ self._chat_tools: dict[int, list[str]] = {}
176
+
177
+ def event(self, name: str, data: dict[str, Any]) -> None:
178
+ kind = data.get("type", name)
179
+ if kind == "response.completed":
180
+ self.usage, self.obs = openai_json(data.get("response") or {})
181
+ return
182
+ if kind == "response.output_text.delta":
183
+ return # the completed event carries the full text
184
+ if "choices" in data: # chat completions chunk
185
+ for choice in data.get("choices") or []:
186
+ delta = choice.get("delta") or {}
187
+ self.obs.text += delta.get("content") or ""
188
+ for call in delta.get("tool_calls") or []:
189
+ slot = self._chat_tools.setdefault(int(call.get("index", 0)), ["", ""])
190
+ fn = call.get("function") or {}
191
+ slot[0] = fn.get("name") or slot[0]
192
+ slot[1] += fn.get("arguments") or ""
193
+ if choice.get("finish_reason"):
194
+ self.obs.stop_reason = choice["finish_reason"]
195
+ if data.get("usage"):
196
+ chat, _ = openai_json({"usage": data["usage"]})
197
+ self.usage = chat
198
+
199
+ def finish(self) -> tuple[Usage, Observed]:
200
+ for name, raw in self._chat_tools.values():
201
+ self.obs.tool_calls.append((name, _loads(raw)))
202
+ return self.usage, self.obs
203
+
204
+
205
+ # --------------------------------------------------------------------------- google
206
+
207
+
208
+ def gemini_json(body: dict[str, Any]) -> tuple[Usage, Observed]:
209
+ meta = body.get("usageMetadata") or {}
210
+ cached = int(meta.get("cachedContentTokenCount") or 0)
211
+ usage = Usage(
212
+ input=int(meta.get("promptTokenCount") or 0) - cached,
213
+ output=int(meta.get("candidatesTokenCount") or 0)
214
+ + int(meta.get("thoughtsTokenCount") or 0),
215
+ cache_read=cached,
216
+ reasoning=int(meta.get("thoughtsTokenCount") or 0),
217
+ complete=bool(meta),
218
+ )
219
+ obs = Observed()
220
+ for cand in body.get("candidates") or []:
221
+ for part in (cand.get("content") or {}).get("parts") or []:
222
+ if "text" in part and not part.get("thought"):
223
+ obs.text += part["text"]
224
+ if "functionCall" in part:
225
+ fc = part["functionCall"]
226
+ obs.tool_calls.append((fc.get("name", ""), fc.get("args")))
227
+ obs.stop_reason = cand.get("finishReason") or obs.stop_reason
228
+ return usage, obs
229
+
230
+
231
+ class GeminiStream:
232
+ def __init__(self) -> None:
233
+ self.usage = Usage()
234
+ self.obs = Observed()
235
+
236
+ def event(self, name: str, data: dict[str, Any]) -> None:
237
+ del name
238
+ usage, obs = gemini_json(data)
239
+ if usage.complete:
240
+ self.usage = usage # each chunk's metadata is cumulative
241
+ self.obs.text += obs.text
242
+ self.obs.tool_calls.extend(obs.tool_calls)
243
+ self.obs.stop_reason = obs.stop_reason or self.obs.stop_reason
244
+
245
+ def finish(self) -> tuple[Usage, Observed]:
246
+ return self.usage, self.obs
247
+
248
+
249
+ def _loads(raw: Any) -> Any:
250
+ if not isinstance(raw, str):
251
+ return raw
252
+ try:
253
+ return json.loads(raw or "{}")
254
+ except json.JSONDecodeError:
255
+ return raw
256
+
257
+
258
+ class SSEParser:
259
+ """Incremental Server-Sent Events parser over raw bytes."""
260
+
261
+ def __init__(self) -> None:
262
+ self._buf = b""
263
+
264
+ def feed(self, chunk: bytes) -> list[tuple[str, dict[str, Any]]]:
265
+ self._buf += chunk.replace(b"\r\n", b"\n")
266
+ out: list[tuple[str, dict[str, Any]]] = []
267
+ while b"\n\n" in self._buf:
268
+ raw, self._buf = self._buf.split(b"\n\n", 1)
269
+ name, data = "message", []
270
+ for line in raw.decode("utf-8", "replace").split("\n"):
271
+ if line.startswith("event:"):
272
+ name = line[6:].strip()
273
+ elif line.startswith("data:"):
274
+ data.append(line[5:].lstrip())
275
+ payload = "\n".join(data)
276
+ if not payload or payload == "[DONE]":
277
+ continue
278
+ try:
279
+ parsed = json.loads(payload)
280
+ except json.JSONDecodeError:
281
+ continue
282
+ if isinstance(parsed, dict):
283
+ out.append((name, parsed))
284
+ return out
wspx/handles.py ADDED
@@ -0,0 +1,117 @@
1
+ """The handle table: self-describing names for server-side objects (§4.3).
2
+
3
+ Agents forget what a bare ``@r1`` holds 150 turns later, or invent its meaning.
4
+ Every handle therefore carries a slug generated from what produced it and an
5
+ optional name chosen by the agent. The id is authoritative for lookup; a label
6
+ that matches neither the slug nor the name produces a warning, never a wrong
7
+ answer.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import threading
13
+ import time
14
+ from typing import Any
15
+
16
+ from pydantic import BaseModel, Field
17
+
18
+ from wspx.addressing import Handle, HandleKind, make_slug, parse_handle
19
+ from wspx.errors import HandleError
20
+
21
+
22
+ class HandleEntry(BaseModel):
23
+ kind: HandleKind
24
+ key: str
25
+ """Canonical key: ``@r1``, ``dir:loop``, ``p_8f2a91c0``, ``t_1c0d33ab``."""
26
+ slug: str
27
+ name: str | None = None
28
+ description: str = ""
29
+ size: str | None = None
30
+ created_at: float = Field(default_factory=time.time)
31
+ call_id: str | None = None
32
+ ref: str | None = None
33
+ """Where the object lives (an object id or a store path)."""
34
+ meta: dict[str, Any] = Field(default_factory=dict)
35
+
36
+ @property
37
+ def display(self) -> str:
38
+ if self.kind is HandleKind.DIRECTION:
39
+ return f"{self.key}({self.slug})" if self.slug != self.key[4:] else self.key
40
+ return f"{self.key}:{self.name or self.slug}"
41
+
42
+
43
+ class HandleTable:
44
+ """Per-session registry of live handles. Thread-safe."""
45
+
46
+ def __init__(self, entries: list[HandleEntry] | None = None) -> None:
47
+ self._lock = threading.Lock()
48
+ self._entries: dict[str, HandleEntry] = {}
49
+ self._next_result = 1
50
+ for entry in entries or []:
51
+ self._add(entry)
52
+
53
+ def _add(self, entry: HandleEntry) -> None:
54
+ self._entries[entry.key] = entry
55
+ if entry.kind is HandleKind.RESULT:
56
+ self._next_result = max(self._next_result, int(entry.key[2:]) + 1)
57
+
58
+ def register_result(self, slug_parts: tuple[object, ...], **fields: Any) -> HandleEntry:
59
+ with self._lock:
60
+ key = f"@r{self._next_result}"
61
+ entry = HandleEntry(
62
+ kind=HandleKind.RESULT, key=key, slug=make_slug(*slug_parts), **fields
63
+ )
64
+ self._add(entry)
65
+ return entry
66
+
67
+ def register(self, kind: HandleKind, key: str, slug: str, **fields: Any) -> HandleEntry:
68
+ with self._lock:
69
+ entry = HandleEntry(kind=kind, key=key, slug=slug, **fields)
70
+ self._add(entry)
71
+ return entry
72
+
73
+ def resolve(self, text: str | Handle) -> tuple[HandleEntry, list[str]]:
74
+ """Look up a handle. Returns the entry plus any label-mismatch warnings."""
75
+ handle = parse_handle(text, allow_revision=False) if isinstance(text, str) else text
76
+ with self._lock:
77
+ entry = self._entries.get(handle.key)
78
+ if entry is None:
79
+ known = ", ".join(sorted(self._entries)[:8]) or "none"
80
+ raise HandleError(f"{handle.key} does not exist (live handles: {known})")
81
+ warnings = []
82
+ if handle.label and handle.label not in (entry.slug, entry.name):
83
+ warnings.append(
84
+ f"label {handle.label!r} does not match {entry.display}; using {entry.key} "
85
+ f"({entry.description or entry.slug})"
86
+ )
87
+ return entry, warnings
88
+
89
+ def get(self, key: str) -> HandleEntry | None:
90
+ with self._lock:
91
+ return self._entries.get(key)
92
+
93
+ def entries(self) -> list[HandleEntry]:
94
+ with self._lock:
95
+ return sorted(self._entries.values(), key=lambda e: e.created_at)
96
+
97
+ def table(self, limit: int = 40) -> str:
98
+ """A compact text table for the driver's context (the workspace table)."""
99
+ rows = self.entries()[-limit:]
100
+ if not rows:
101
+ return "(no live handles)"
102
+ lines = []
103
+ for entry in rows:
104
+ size = f" · {entry.size}" if entry.size else ""
105
+ desc = f" — {entry.description}" if entry.description else ""
106
+ lines.append(f"{entry.display}{size}{desc}")
107
+ hidden = len(self._entries) - len(rows)
108
+ if hidden > 0:
109
+ lines.insert(0, f"(+{hidden} older handles; `info --handles` lists all)")
110
+ return "\n".join(lines)
111
+
112
+ def dump(self) -> list[dict[str, Any]]:
113
+ return [e.model_dump(mode="json") for e in self.entries()]
114
+
115
+ @classmethod
116
+ def load(cls, rows: list[dict[str, Any]]) -> HandleTable:
117
+ return cls([HandleEntry.model_validate(r) for r in rows])
@@ -0,0 +1,8 @@
1
+ ## wspx
2
+
3
+ This project edits model weights with wspx. Use the `wspx` MCP tools (or the
4
+ `wspx` CLI) rather than reading weights directly: `info`, then `grep` /
5
+ `contrast` / `trace` to find where a behaviour lives, `edit` to stage a change,
6
+ `check` and `test --vs base` to measure it, and `vcs commit` to record it.
7
+ Follow the fix lists that diagnostics print, and never try to read held-out
8
+ evaluation data.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: wspx
3
+ description: Edit, test and version-control model weights with wspx. Use when the task is to find, change or evaluate what a neural network's weights do (directions, neurons, heads, experts), or to commit, compare, merge or export weight edits.
4
+ ---
5
+
6
+ # Editing weights with wspx
7
+
8
+ wspx gives you, for a model's weights, what code has: grep, a compiler, tests,
9
+ git and stack traces. You never read raw numbers. Tools return addresses,
10
+ statistics and handles; heavy computation happens next to the weights.
11
+
12
+ ## Workflow
13
+
14
+ 1. **info** — see the model: blocks, layer types, residual stream, tying, coverage.
15
+ 2. **grep / contrast / trace** — find where a behaviour lives.
16
+ - `grep 'writes(" Wait") > 0.3' --in 'L*.mlp.down'` ranks the units that write a token.
17
+ - `contrast` builds a direction from two prompt sets and lists its top writers.
18
+ - `trace` shows the logit lens, top writer units and routes; `--vs` diffs two
19
+ commits; a reference input gives an attribution "stack trace".
20
+ 3. **edit** — stage an op (`project_out`, `ablate`, `scale`, `bake_steer`,
21
+ `rank_one_write`, `transplant`, …). It is checked statically and numerically
22
+ before it is staged.
23
+ 4. **check** — smoke-check what is staged: KL against the base on a canary,
24
+ perplexity and degenerate output.
25
+ 5. **test** — run suites; use `--vs base` or `--vs <commit>` for paired deltas.
26
+ 6. **vcs commit** — commits run check first. Use branches for experiments,
27
+ `vcs diff`, `vcs revert` (exact) and `vcs bisect` when something regresses.
28
+
29
+ ## Addresses and handles
30
+
31
+ - Addresses name weights: `L19.mlp.down[:, 8812]`, `L7.attn.q.h3`,
32
+ `L12.moe.e5.up`, `embed[" Wait"]`, `L*.mlp.down`, `L8-12.attn.o`. Raw
33
+ parameter names always work.
34
+ - Handles name results: `@r1:<slug>` (result sets), `dir:<name>` (directions),
35
+ `p_…` (patches), `t_…` (traces), commits and branches. Pass handles instead of
36
+ copying data, e.g. `edit project_out dir:loop L19.mlp.down cols=@r1`.
37
+ - `info --handles` lists every live handle with what it holds. Trust the id,
38
+ not your memory of what it was.
39
+
40
+ ## Rules
41
+
42
+ - Never dump weight values; ask for summaries. Raw values are capped.
43
+ - Run `check` before committing, and read the diagnostics. Every diagnostic
44
+ lists fixes: apply one rather than retrying the same edit. `W203` (sub-ULP
45
+ loss) means the change is too small for the stored dtype; `E105` means the
46
+ edit changed nothing.
47
+ - Measure behaviour with paired tests (`test --vs`), not single runs.
48
+ - Held-out suites return aggregates only. Never try to read held-out items or
49
+ outputs, or to infer them.
50
+ - If you are told something is repeating, it will not change by repeating it:
51
+ change the approach.
52
+ - Keep edits small and targeted; prefer low-rank edits on writers.
@@ -0,0 +1,17 @@
1
+ """Files shipped to external agents: the wspx skill, the Claude Code plugin and Codex templates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from importlib.resources import files
6
+
7
+
8
+ def skill_text() -> str:
9
+ """``SKILL.md`` without its front matter: the built-in driver's system prompt."""
10
+ text = files("wspx.integrations").joinpath("SKILL.md").read_text(encoding="utf-8")
11
+ if text.startswith("---"):
12
+ text = text.split("---", 2)[2]
13
+ return text.strip()
14
+
15
+
16
+ def read(name: str) -> str:
17
+ return files("wspx.integrations").joinpath(name).read_text(encoding="utf-8")
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "wspx",
3
+ "description": "Grep, edit, check, test and version-control model weights through a wspx deployment.",
4
+ "author": {"name": "Ritik Bompilwar"},
5
+ "license": "Apache-2.0",
6
+ "mcpServers": {
7
+ "wspx": {
8
+ "type": "http",
9
+ "url": "${WSPX_URL}/mcp/",
10
+ "headers": {
11
+ "Authorization": "Bearer ${WSPX_TOKEN}",
12
+ "X-Wspx-Session": "${WSPX_SESSION}"
13
+ }
14
+ }
15
+ },
16
+ "hooks": {
17
+ "PostToolUse": [
18
+ {
19
+ "matcher": "mcp__wspx__.*",
20
+ "hooks": [
21
+ {
22
+ "type": "http",
23
+ "url": "${WSPX_URL}/api/ingest/claude-code?session=${WSPX_SESSION}",
24
+ "headers": {"Authorization": "Bearer ${WSPX_TOKEN}"}
25
+ }
26
+ ]
27
+ }
28
+ ]
29
+ }
30
+ }
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: wspx
3
+ description: Edit, test and version-control model weights with wspx. Use when the task is to find, change or evaluate what a neural network's weights do (directions, neurons, heads, experts), or to commit, compare, merge or export weight edits.
4
+ ---
5
+
6
+ # Editing weights with wspx
7
+
8
+ wspx gives you, for a model's weights, what code has: grep, a compiler, tests,
9
+ git and stack traces. You never read raw numbers. Tools return addresses,
10
+ statistics and handles; heavy computation happens next to the weights.
11
+
12
+ ## Workflow
13
+
14
+ 1. **info** — see the model: blocks, layer types, residual stream, tying, coverage.
15
+ 2. **grep / contrast / trace** — find where a behaviour lives.
16
+ - `grep 'writes(" Wait") > 0.3' --in 'L*.mlp.down'` ranks the units that write a token.
17
+ - `contrast` builds a direction from two prompt sets and lists its top writers.
18
+ - `trace` shows the logit lens, top writer units and routes; `--vs` diffs two
19
+ commits; a reference input gives an attribution "stack trace".
20
+ 3. **edit** — stage an op (`project_out`, `ablate`, `scale`, `bake_steer`,
21
+ `rank_one_write`, `transplant`, …). It is checked statically and numerically
22
+ before it is staged.
23
+ 4. **check** — smoke-check what is staged: KL against the base on a canary,
24
+ perplexity and degenerate output.
25
+ 5. **test** — run suites; use `--vs base` or `--vs <commit>` for paired deltas.
26
+ 6. **vcs commit** — commits run check first. Use branches for experiments,
27
+ `vcs diff`, `vcs revert` (exact) and `vcs bisect` when something regresses.
28
+
29
+ ## Addresses and handles
30
+
31
+ - Addresses name weights: `L19.mlp.down[:, 8812]`, `L7.attn.q.h3`,
32
+ `L12.moe.e5.up`, `embed[" Wait"]`, `L*.mlp.down`, `L8-12.attn.o`. Raw
33
+ parameter names always work.
34
+ - Handles name results: `@r1:<slug>` (result sets), `dir:<name>` (directions),
35
+ `p_…` (patches), `t_…` (traces), commits and branches. Pass handles instead of
36
+ copying data, e.g. `edit project_out dir:loop L19.mlp.down cols=@r1`.
37
+ - `info --handles` lists every live handle with what it holds. Trust the id,
38
+ not your memory of what it was.
39
+
40
+ ## Rules
41
+
42
+ - Never dump weight values; ask for summaries. Raw values are capped.
43
+ - Run `check` before committing, and read the diagnostics. Every diagnostic
44
+ lists fixes: apply one rather than retrying the same edit. `W203` (sub-ULP
45
+ loss) means the change is too small for the stored dtype; `E105` means the
46
+ edit changed nothing.
47
+ - Measure behaviour with paired tests (`test --vs`), not single runs.
48
+ - Held-out suites return aggregates only. Never try to read held-out items or
49
+ outputs, or to infer them.
50
+ - If you are told something is repeating, it will not change by repeating it:
51
+ change the approach.
52
+ - Keep edits small and targeted; prefer low-rank edits on writers.
@@ -0,0 +1,9 @@
1
+
2
+ # wspx: forward Codex tool events to the wspx trace (see `wspx hook codex`)
3
+ [[hooks.post_tool_use]]
4
+ type = "command"
5
+ command = ["wspx", "hook", "codex"]
6
+
7
+ [[hooks.user_prompt_submit]]
8
+ type = "command"
9
+ command = ["wspx", "hook", "codex"]
wspx/lab/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """The lab: everything that touches weights. Runs inside the GPU sandbox.
2
+
3
+ Nothing in this package holds secrets or opens network connections. It needs
4
+ the ``lab`` extra (torch, transformers, safetensors).
5
+ """