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/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.
|