@withgateway/sdk 0.2.4 → 0.2.5

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 (46) hide show
  1. package/dist/cli.js +1798 -1713
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +2412 -2327
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +47 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +43 -27
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/index.d.mts +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.js +390 -287
  12. package/dist/index.js.map +1 -1
  13. package/dist/index.mjs +375 -271
  14. package/dist/index.mjs.map +1 -1
  15. package/dist/traces/index.js +36 -20
  16. package/dist/traces/index.js.map +1 -1
  17. package/dist/traces/index.mjs +32 -16
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +2 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +2 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +26 -22
  24. package/dist/worlds/index.d.ts +26 -22
  25. package/dist/worlds/index.js +307 -203
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +297 -193
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +2 -1
  30. package/runtime/gatewaysdk/environment/_bundle.py +14 -24
  31. package/runtime/gatewaysdk/environment/schema/api.py +37 -18
  32. package/runtime/gatewaysdk/environment/schema/data.py +21 -19
  33. package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
  34. package/runtime/gatewaysdk/environment/schema/host.py +156 -546
  35. package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
  36. package/runtime/gatewaysdk/environment/schema/local.py +32 -126
  37. package/runtime/gatewaysdk/environment/schema/platform.py +14 -22
  38. package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
  39. package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
  40. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  41. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +6 -4
  42. package/runtime/gatewaysdk/environment/schema/tools_world.py +75 -23
  43. package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
  44. package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
  45. package/runtime/gatewaysdk/environment/world.py +391 -0
  46. package/skills/hooks-getting-started/SKILL.md +6 -4
@@ -0,0 +1,391 @@
1
+ """What a tree on disk IS, decided once.
2
+
3
+ ``World.from_tree`` is the one Python detector: the local runtime
4
+ (``_bundle.detect_kind``), the data commands (``data.world_kind``), the hub
5
+ client (``harbor_adapter.detect_env_kind``), the benchmark runner
6
+ (``engines/hub_bundle.detect_env_kind``), the platform bridge
7
+ (``platform.world_root``) and the World Host (``host.world_tree``) all read
8
+ their answer from here. The TypeScript twin is
9
+ ``packages/shared/src/world/`` (``WorldTree`` + ``World.fromTree``); the
10
+ corpus under ``conformance/worlds/`` pins both to the same answers.
11
+
12
+ Stdlib only: the benchmark runner vendors this subpackage without the SDK's
13
+ dependencies.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import os
19
+ import re
20
+ import tomllib
21
+ from collections.abc import Iterator
22
+ from dataclasses import dataclass
23
+ from functools import cached_property
24
+ from pathlib import Path
25
+ from typing import ClassVar
26
+
27
+ # ── Markers (twin of packages/shared/src/world/markers.ts) ──────────────────
28
+
29
+ WORLD_MANIFEST = "gateway-env.toml"
30
+ API_BUNDLE_MANIFEST = "gateway-api-world.toml"
31
+ BUNDLED_WORLD_PREFIX = "server/world/"
32
+ CONNECTOR_SPEC = "connector.toml"
33
+ PYPROJECT = "pyproject.toml"
34
+ WORLD_SCHEMA_MARKERS = ("schema/world.json", "schema/runtime.json", "schema/lock.json")
35
+ WORLD_ROOT_MARKERS = (CONNECTOR_SPEC, *WORLD_SCHEMA_MARKERS)
36
+ SCHEMA_MANIFEST_KIND = "schema"
37
+ SCHEMA_MANIFEST_KINDS = frozenset({SCHEMA_MANIFEST_KIND, "mock-tools"})
38
+
39
+ KIND_MOCK_TOOLS = "mock-tools"
40
+ KIND_API = "api"
41
+ KIND_HARBOR = "harbor"
42
+ KIND_VERIFIERS = "verifiers"
43
+ KIND_VERIFIERS_V1 = "verifiers-v1"
44
+
45
+ _SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
46
+ _HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
47
+
48
+ # The `verifiers.v1` namespace first shipped in verifiers 0.2.0, so a v1
49
+ # package declares verifiers>=0.2 (or ~=0.2 / ==0.2.* / >=1 / ==1.*) in
50
+ # pyproject — minor >= 2 on the 0.x line or any major >= 1, never 0.0/0.1 —
51
+ # and/or imports the namespace or subclasses Taskset alongside the v1
52
+ # packaging convention of an ``__all__`` export (any library may name a class
53
+ # Taskset). A bare unversioned dependency or a pre-0.2 pin is v0.
54
+ _V1_DEP = re.compile(
55
+ r"""["']verifiers\s*(?:\[[^\]]*\])?\s*(?:>=|~=|==|>)\s*""" r"""(?:0\.(?:[2-9]\d*|[1-9]\d+)|[1-9]\d*)"""
56
+ )
57
+ _V1_IMPORT = re.compile(
58
+ r"^\s*(?:from\s+verifiers\.v1\s+import\b|from\s+verifiers\s+import\s+v1\b|import\s+verifiers\.v1\b)",
59
+ re.MULTILINE,
60
+ )
61
+ _V1_TASKSET = re.compile(r"class\s+\w+\s*\(\s*(?:(?:vf|v1|verifiers(?:\.v1)?)\.)?Taskset\s*[,)]")
62
+
63
+
64
+ def _present(path: Path) -> bool:
65
+ """A file exists — or a symlink to one is dangling: a broken authority
66
+ must fail loudly downstream, never quietly downgrade the tree."""
67
+ return path.is_file() or path.is_symlink()
68
+
69
+
70
+ def _skipped_dir(name: str) -> bool:
71
+ return name.startswith(".") or name in _SKIPPED_DIRS or name.endswith(".egg-info")
72
+
73
+
74
+ def pyproject_pins_v1(path: str, text: str) -> bool:
75
+ if path != PYPROJECT:
76
+ return False
77
+ return _V1_DEP.search(text) is not None
78
+
79
+
80
+ def module_uses_v1(path: str, text: str) -> bool:
81
+ if not path.endswith(".py"):
82
+ return False
83
+ return bool(_V1_IMPORT.search(text)) or ("__all__" in text and bool(_V1_TASKSET.search(text)))
84
+
85
+
86
+ class WorldManifest:
87
+ """A world's ``gateway-env.toml``, parsed once. An absent manifest and an
88
+ unparsable one are both manifests: ``present`` and ``error`` say which,
89
+ and every accessor answers "declares nothing" for them."""
90
+
91
+ def __init__(self, text: str | None, root: dict | None, error: str | None) -> None:
92
+ self.text = text
93
+ self._root = root
94
+ self.error = error
95
+
96
+ ABSENT: ClassVar[WorldManifest]
97
+
98
+ @staticmethod
99
+ def parse(text: str) -> WorldManifest:
100
+ try:
101
+ return WorldManifest(text, tomllib.loads(text), None)
102
+ except tomllib.TOMLDecodeError as error:
103
+ return WorldManifest(text, None, f"{WORLD_MANIFEST} is invalid TOML: {error}")
104
+
105
+ @property
106
+ def present(self) -> bool:
107
+ return self.text is not None
108
+
109
+ @property
110
+ def invalid(self) -> bool:
111
+ return self.present and self._root is None
112
+
113
+ def table(self, name: str) -> dict | None:
114
+ value = (self._root or {}).get(name)
115
+ return value if isinstance(value, dict) else None
116
+
117
+ def has(self, name: str) -> bool:
118
+ return self._root is not None and name in self._root
119
+
120
+ @property
121
+ def environment(self) -> dict | None:
122
+ if self._root is None:
123
+ return None
124
+ if self.has("environment"):
125
+ return self.table("environment")
126
+ value = self._root.get("env", {})
127
+ return value if isinstance(value, dict) else None
128
+
129
+ @property
130
+ def kind(self) -> object:
131
+ env = self.environment
132
+ return None if env is None else env.get("kind")
133
+
134
+ @property
135
+ def declares_schema(self) -> bool:
136
+ return self.has("schema")
137
+
138
+
139
+ WorldManifest.ABSENT = WorldManifest(None, None, None)
140
+
141
+
142
+ @dataclass(frozen=True)
143
+ class WorldTree:
144
+ """A tree on disk and where the authored world lives inside it. Immutable;
145
+ the root decision is made once at construction."""
146
+
147
+ root: Path
148
+ world_root: str
149
+
150
+ @classmethod
151
+ def from_dir(cls, root: str | os.PathLike[str]) -> WorldTree:
152
+ root = Path(root)
153
+ nested = root / BUNDLED_WORLD_PREFIX
154
+ bundled = _present(root / API_BUNDLE_MANIFEST) and any(
155
+ _present(nested / marker) for marker in WORLD_ROOT_MARKERS
156
+ )
157
+ return cls(root, BUNDLED_WORLD_PREFIX if bundled else "")
158
+
159
+ def has(self, relative: str) -> bool:
160
+ return _present(self.root / relative)
161
+
162
+ def world_path(self, relative: str) -> str:
163
+ return self.world_root + relative
164
+
165
+ @property
166
+ def world(self) -> Path:
167
+ """The authored world's directory."""
168
+ return self.root / self.world_root if self.world_root else self.root
169
+
170
+ @property
171
+ def is_api_bundle(self) -> bool:
172
+ return self.has(API_BUNDLE_MANIFEST)
173
+
174
+ @property
175
+ def has_schema_marker(self) -> bool:
176
+ return any(self.has(self.world_path(marker)) for marker in WORLD_SCHEMA_MARKERS)
177
+
178
+ @property
179
+ def has_connector(self) -> bool:
180
+ return self.has(self.world_path(CONNECTOR_SPEC))
181
+
182
+ @cached_property
183
+ def manifest(self) -> WorldManifest:
184
+ path = self.world / WORLD_MANIFEST
185
+ if not _present(path):
186
+ return WorldManifest.ABSENT
187
+ try:
188
+ return WorldManifest.parse(path.read_text(encoding="utf-8"))
189
+ except (OSError, UnicodeDecodeError) as error:
190
+ return WorldManifest("", None, f"cannot read {WORLD_MANIFEST}: {error}")
191
+
192
+ def harbor_task_names(self) -> list[str]:
193
+ names = set()
194
+ for pattern in ("tasks/*/task.toml", "*/task.toml"):
195
+ for path in self.root.glob(pattern):
196
+ match = _HARBOR_TASK.match(path.relative_to(self.root).as_posix())
197
+ if match:
198
+ names.add(match.group(1))
199
+ return sorted(names)
200
+
201
+ def scenario_names(self) -> list[str]:
202
+ return sorted(path.parent.name for path in self.root.glob("scenarios/*/scenario.toml") if path.is_file())
203
+
204
+ def v1_evidence(self) -> Iterator[tuple[str, str]]:
205
+ """``(relpath, text)`` of the files a verifiers package's API version is
206
+ read from: the root pyproject and every ``.py`` the archive rules keep
207
+ (``benchmark_hub._archive``: no hidden, build, dist, outputs, pycache or
208
+ egg-info directories)."""
209
+ for dirpath, dirnames, filenames in os.walk(self.root):
210
+ dirnames[:] = sorted(name for name in dirnames if not _skipped_dir(name))
211
+ for filename in sorted(filenames):
212
+ path = Path(dirpath) / filename
213
+ relative = path.relative_to(self.root).as_posix()
214
+ if filename.startswith(".") or not (relative == PYPROJECT or filename.endswith(".py")):
215
+ continue
216
+ try:
217
+ yield relative, path.read_text(encoding="utf-8", errors="replace")
218
+ except OSError:
219
+ continue
220
+
221
+
222
+ class World:
223
+ """What a tree is, and what that means for the paths that touch it.
224
+ Construct through ``World.from_tree`` / ``World.from_dir`` only."""
225
+
226
+ kind: str
227
+ shape: str
228
+
229
+ def __init__(self, tree: WorldTree) -> None:
230
+ self.tree = tree
231
+
232
+ @staticmethod
233
+ def from_tree(tree: WorldTree) -> World:
234
+ if tree.is_api_bundle:
235
+ return ApiBundle(tree)
236
+ if tree.has(WORLD_MANIFEST):
237
+ schema = tree.has_schema_marker or tree.manifest.declares_schema
238
+ return SchemaWorld(tree) if schema else ToolsWorld(tree)
239
+ if tree.harbor_task_names():
240
+ return HarborBench(tree)
241
+ v1 = VerifiersBench.is_v1(tree)
242
+ if v1 or tree.has(PYPROJECT):
243
+ return VerifiersBench(tree, v1)
244
+ return PlainTree(tree)
245
+
246
+ @staticmethod
247
+ def from_dir(root: str | os.PathLike[str]) -> World:
248
+ return World.from_tree(WorldTree.from_dir(root))
249
+
250
+ @property
251
+ def reported_kind(self) -> str:
252
+ """What ``worlds create|describe|list`` and the data commands report."""
253
+ return self.kind
254
+
255
+ @property
256
+ def runner_engine(self) -> str:
257
+ return "openai-compatible"
258
+
259
+ @property
260
+ def substrate(self) -> str:
261
+ """Hosted on the World Host, or executed by the benchmark runner."""
262
+ return "world"
263
+
264
+ @property
265
+ def tools_engine(self) -> bool:
266
+ """Runs on the tools engine: handlers over a per-session SQLite."""
267
+ return False
268
+
269
+ @property
270
+ def local_runtime(self) -> bool:
271
+ """``gwenv`` can run the tree in-process."""
272
+ return True
273
+
274
+ def task_names(self) -> list[str]:
275
+ """The tasks the tree defines by layout; a schema world's live in
276
+ its manifest."""
277
+ return []
278
+
279
+ @property
280
+ def schema_mode(self) -> str:
281
+ """``schema`` (a compiled marker or a declared ``[schema]``),
282
+ ``invalid`` (a manifest that does not parse) or ``legacy``."""
283
+ if self.tree.has_schema_marker:
284
+ return "schema"
285
+ if self.tree.manifest.invalid:
286
+ return "invalid"
287
+ return "schema" if self.tree.manifest.declares_schema else "legacy"
288
+
289
+ @property
290
+ def is_schema(self) -> bool:
291
+ return self.schema_mode == "schema"
292
+
293
+
294
+ class SchemaWorld(World):
295
+ """A gateway-world/1 contract tree stored as itself."""
296
+
297
+ kind = KIND_MOCK_TOOLS
298
+ shape = "schema"
299
+
300
+ @property
301
+ def reported_kind(self) -> str:
302
+ return SCHEMA_MANIFEST_KIND
303
+
304
+ @property
305
+ def tools_engine(self) -> bool:
306
+ return True
307
+
308
+
309
+ class ToolsWorld(World):
310
+ """``gateway-env.toml`` + ``db/schema.sql`` + handlers, no contract."""
311
+
312
+ kind = KIND_MOCK_TOOLS
313
+ shape = "legacy-tools"
314
+
315
+ @property
316
+ def tools_engine(self) -> bool:
317
+ return True
318
+
319
+
320
+ class ApiBundle(World):
321
+ """A world packaged with ``gateway-api-world.toml`` over ``server/world/``."""
322
+
323
+ kind = KIND_API
324
+ shape = "api-bundle"
325
+
326
+ def task_names(self) -> list[str]:
327
+ return self.tree.scenario_names()
328
+
329
+
330
+ class ContainerBench(World):
331
+ @property
332
+ def substrate(self) -> str:
333
+ return "container"
334
+
335
+
336
+ class HarborBench(ContainerBench):
337
+ """``<task>/task.toml`` or ``tasks/<task>/task.toml`` directories."""
338
+
339
+ kind = KIND_HARBOR
340
+ shape = "harbor"
341
+
342
+ @property
343
+ def runner_engine(self) -> str:
344
+ return "harbor"
345
+
346
+ def task_names(self) -> list[str]:
347
+ return self.tree.harbor_task_names()
348
+
349
+
350
+ class VerifiersBench(ContainerBench):
351
+ """A Python package the runner installs and grades with reward functions."""
352
+
353
+ shape = "verifiers"
354
+
355
+ def __init__(self, tree: WorldTree, v1: bool = False) -> None:
356
+ super().__init__(tree)
357
+ self.kind = KIND_VERIFIERS_V1 if v1 else KIND_VERIFIERS
358
+
359
+ @staticmethod
360
+ def is_v1(tree: WorldTree) -> bool:
361
+ return any(pyproject_pins_v1(path, text) or module_uses_v1(path, text) for path, text in tree.v1_evidence())
362
+
363
+ @property
364
+ def local_runtime(self) -> bool:
365
+ return False
366
+
367
+
368
+ class PlainTree(VerifiersBench):
369
+ """No Gateway marker, no harbor task, no Python package: not yet a world
370
+ and not a benchmark. The runner's fallback reads it as a verifiers
371
+ package, so that is the kind it answers."""
372
+
373
+
374
+ __all__ = [
375
+ "API_BUNDLE_MANIFEST",
376
+ "BUNDLED_WORLD_PREFIX",
377
+ "CONNECTOR_SPEC",
378
+ "PYPROJECT",
379
+ "WORLD_MANIFEST",
380
+ "WORLD_ROOT_MARKERS",
381
+ "WORLD_SCHEMA_MARKERS",
382
+ "ApiBundle",
383
+ "HarborBench",
384
+ "PlainTree",
385
+ "SchemaWorld",
386
+ "ToolsWorld",
387
+ "VerifiersBench",
388
+ "World",
389
+ "WorldManifest",
390
+ "WorldTree",
391
+ ]
@@ -129,10 +129,12 @@ personas to people: keep it with the run key, out of version control, never besi
129
129
 
130
130
  ## Wiring
131
131
 
132
- - **Agent SDK** — `guarded = run.wrap({ lookup_email: lookupEmail })` and register the wrapped
133
- function wherever the SDK takes a tool implementation; `run.tools()` materializes the file's
134
- `[tools.*]` (a keyed web search, a connector operation) already wrapped;
135
- `verdict = run.end(report)` runs `run_end`.
132
+ - **Agent SDK** — open the file (`from gatewaysdk.hooks import HookRun; run = HookRun("gateway-hooks.toml")`
133
+ / `import { HookRun } from "@withgateway/sdk/hooks"; const run = await HookRun.fromConfig("gateway-hooks.toml")`),
134
+ then wrap the tools: Python `guarded = run.wrap({"lookup_email": lookup_email})`, TypeScript
135
+ `guarded = run.wrapTools({ lookup_email: lookupEmail })`; register the wrapped function wherever
136
+ the SDK takes a tool implementation. `run.tools()` materializes the file's `[tools.*]` (a keyed
137
+ web search, a connector operation) already wrapped; `verdict = run.end(report)` runs `run_end`.
136
138
  - **Claude Code / coding agents** — `.claude/settings.json`: `PreToolUse`, `PostToolUse` and
137
139
  `Stop` entries whose command is `gateway hooks run`. State (run key + seeds) persists under
138
140
  `--state`, `$GATEWAY_HOOKS_STATE`, else `.gateway/hooks/<session id>`. A coding agent shows the