@withgateway/sdk 0.2.4 → 0.2.6

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 (85) hide show
  1. package/dist/cli.js +4304 -2381
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +4266 -2343
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +56 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +52 -27
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/hooks/index.d.mts +1 -1
  10. package/dist/hooks/index.d.ts +1 -1
  11. package/dist/hooks/index.js +280 -8
  12. package/dist/hooks/index.js.map +1 -1
  13. package/dist/hooks/index.mjs +272 -8
  14. package/dist/hooks/index.mjs.map +1 -1
  15. package/dist/{index-1xnxt0Cc.d.ts → index-BO2SNSgy.d.ts} +12 -1
  16. package/dist/{index-B0R3IgsV.d.mts → index-BaKu5ZSU.d.mts} +124 -2
  17. package/dist/{index-B0R3IgsV.d.ts → index-BaKu5ZSU.d.ts} +124 -2
  18. package/dist/{index-C1wDEwH4.d.mts → index-Cz8Q6Keo.d.mts} +12 -1
  19. package/dist/index.d.mts +4 -4
  20. package/dist/index.d.ts +4 -4
  21. package/dist/index.js +1100 -438
  22. package/dist/index.js.map +1 -1
  23. package/dist/index.mjs +1079 -424
  24. package/dist/index.mjs.map +1 -1
  25. package/dist/traces/index.js +45 -20
  26. package/dist/traces/index.js.map +1 -1
  27. package/dist/traces/index.mjs +41 -16
  28. package/dist/traces/index.mjs.map +1 -1
  29. package/dist/tracing/index.d.mts +1 -1
  30. package/dist/tracing/index.d.ts +1 -1
  31. package/dist/tracing/index.js +98 -61
  32. package/dist/tracing/index.js.map +1 -1
  33. package/dist/tracing/index.mjs +98 -61
  34. package/dist/tracing/index.mjs.map +1 -1
  35. package/dist/worlds/index.d.mts +179 -25
  36. package/dist/worlds/index.d.ts +179 -25
  37. package/dist/worlds/index.js +639 -284
  38. package/dist/worlds/index.js.map +1 -1
  39. package/dist/worlds/index.mjs +631 -276
  40. package/dist/worlds/index.mjs.map +1 -1
  41. package/package.json +2 -1
  42. package/runtime/gatewaysdk/environment/_bundle.py +15 -25
  43. package/runtime/gatewaysdk/environment/_materialize.py +53 -9
  44. package/runtime/gatewaysdk/environment/_toml.py +13 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +40 -25
  46. package/runtime/gatewaysdk/environment/schema/batch.py +15 -11
  47. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +24 -0
  48. package/runtime/gatewaysdk/environment/schema/compiler.py +60 -28
  49. package/runtime/gatewaysdk/environment/schema/conform.py +1 -1
  50. package/runtime/gatewaysdk/environment/schema/connector.py +1 -1
  51. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.ingest.toml +25 -0
  52. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +17 -0
  53. package/runtime/gatewaysdk/environment/schema/data.py +21 -19
  54. package/runtime/gatewaysdk/environment/schema/extract.py +1 -5
  55. package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
  56. package/runtime/gatewaysdk/environment/schema/host.py +156 -546
  57. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +1 -5
  58. package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
  59. package/runtime/gatewaysdk/environment/schema/local.py +32 -126
  60. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  61. package/runtime/gatewaysdk/environment/schema/platform.py +30 -26
  62. package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
  63. package/runtime/gatewaysdk/environment/schema/redaction.py +1 -1
  64. package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
  65. package/runtime/gatewaysdk/environment/schema/scaffold.py +9 -2
  66. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  67. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +67 -9
  68. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +67 -6
  69. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -1
  70. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
  71. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
  72. package/runtime/gatewaysdk/environment/schema/snapshot.py +1 -5
  73. package/runtime/gatewaysdk/environment/schema/tools_world.py +71 -23
  74. package/runtime/gatewaysdk/environment/schema/ui.py +1 -5
  75. package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
  76. package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
  77. package/runtime/gatewaysdk/environment/schema/world_tests.py +1 -1
  78. package/runtime/gatewaysdk/environment/world.py +507 -0
  79. package/skills/benchmarks-getting-started/SKILL.md +67 -9
  80. package/skills/connector-schema-authoring/connector-worlds.md +8 -1
  81. package/skills/connector-schema-authoring/world-schema.md +1 -1
  82. package/skills/hooks-getting-started/SKILL.md +67 -6
  83. package/skills/world-data-ingestion/SKILL.md +4 -1
  84. package/skills/worlds-getting-started/SKILL.md +11 -11
  85. package/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
@@ -35,7 +35,9 @@ from contextlib import contextmanager
35
35
  from pathlib import Path
36
36
  from typing import Any, Iterable, Iterator
37
37
 
38
+ from ..world import KIND_API, KIND_HARBOR, KIND_MOCK_TOOLS, SCHEMA_MANIFEST_KIND, World
38
39
  from .compiler import bundle_mode, check_bundle, compile_bundle
40
+ from .proof import SCRATCH_IGNORE, RowProof
39
41
  from .store import SQLiteStore
40
42
  from .validation import ContractError, digest, encoded, fail, journal_paths, read_json, validate
41
43
 
@@ -48,14 +50,8 @@ INLINE_BYTES = 4 * 1024 * 1024
48
50
  #: The most rows one ``entity_query`` page returns, the vendor pages' cap.
49
51
  QUERY_LIMIT = 1000
50
52
  QUERY_DEFAULT_LIMIT = 100
51
- KIND_SCHEMA = "schema"
52
- KIND_MOCK_TOOLS = "mock-tools"
53
- KIND_API = "api"
54
- KIND_HARBOR = "harbor"
55
- KIND_UNKNOWN = "unknown"
53
+ KIND_SCHEMA = SCHEMA_MANIFEST_KIND
56
54
  MAPPING = {"id": "data-import", "version": "1"}
57
- #: Left out of scratch copies: captures, caches, and the snapshots (rebuilt from the data).
58
- SCRATCH_IGNORE = ("captures", "__pycache__", ".gateway", "state.sqlite", "state.json", ".state.sqlite.*")
59
55
 
60
56
  Rows = dict[str, list[dict]]
61
57
 
@@ -87,17 +83,13 @@ def parse_rows(paths: Iterable[str | Path], *, entity: str | None = None) -> Row
87
83
 
88
84
 
89
85
  def world_kind(root: str | Path) -> str:
90
- """``schema`` (gateway-world/1), ``mock-tools``, ``api``, ``harbor`` or ``unknown``."""
86
+ """The kind the worlds paths report (``World.from_dir(...).reported_kind``):
87
+ ``schema``, ``mock-tools``, ``api``, ``harbor``, ``verifiers`` or
88
+ ``verifiers-v1``. An invalid schema declaration refuses here rather than
89
+ downgrading the tree."""
91
90
  root = Path(root)
92
- if bundle_mode(root) is not None:
93
- return KIND_SCHEMA
94
- if (root / "gateway-api-world.toml").is_file():
95
- return KIND_API
96
- if (root / "gateway-env.toml").is_file():
97
- return KIND_MOCK_TOOLS
98
- if list(root.glob("tasks/*/task.toml")) or list(root.glob("*/task.toml")):
99
- return KIND_HARBOR
100
- return KIND_UNKNOWN
91
+ bundle_mode(root)
92
+ return World.from_dir(root).reported_kind
101
93
 
102
94
 
103
95
  def _refuse_kind(kind: str, root: Path) -> None:
@@ -135,6 +127,7 @@ def import_rows(
135
127
  merge: str = "upsert",
136
128
  batch_id: str | None = None,
137
129
  redact: str = "off",
130
+ dry_run: bool = False,
138
131
  ) -> dict:
139
132
  """Write ``rows`` into the world at ``root`` the way its kind seeds.
140
133
 
@@ -150,6 +143,13 @@ def import_rows(
150
143
  ``redact`` — ``off`` (default) stores the rows as given; ``apply`` runs them
151
144
  through the world's ``[redact]`` policy first; ``refuse`` rejects a row that
152
145
  carries plaintext in a redacted field (:mod:`.redaction`).
146
+
147
+ ``dry_run`` proves the rows and writes nothing (``changed`` always ``False``):
148
+ the :class:`.proof.RowProof` the tree calls for — the same gate over a scratch
149
+ copy of an authored tree, the platform's batch lane over the hosted snapshot a
150
+ pinned checkout carries, or shape-only with references and unique keys
151
+ ``deferred`` to the platform when the pinned checkout lacks its snapshot. A
152
+ pinned checkout refuses a real import: the rows belong on the platform.
153
153
  """
154
154
  from .redaction import parse_mode, redact_rows, require_policy
155
155
 
@@ -160,6 +160,8 @@ def import_rows(
160
160
  fail("merge", f"merge must be one of {', '.join(MERGES)}", "/merge")
161
161
  if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
162
162
  fail("rows", "rows must map entity names to arrays of rows", "/rows")
163
+ if dry_run:
164
+ return RowProof.of(root).run(rows, mode=mode, merge=merge, batch_id=batch_id, redact=redact)
163
165
  redact = parse_mode(redact)
164
166
  rows = redact_rows(require_policy(root, redact), rows, redact)
165
167
  kind = world_kind(root)
@@ -186,7 +188,7 @@ def _refuse_shapes(root: Path, rows: Rows) -> None:
186
188
  reports."""
187
189
  from .batch import shape_refusal
188
190
 
189
- contract = compile_bundle(root)
191
+ contract = compile_bundle(root, snapshots=False)
190
192
  refusals = [
191
193
  refused
192
194
  for entity, listed in rows.items()
@@ -220,7 +222,7 @@ def _merged(root: Path, rows: Rows, merge: str) -> Rows:
220
222
  plan will refuse (not an object, key missing) is left in place for it."""
221
223
  if merge != "fill":
222
224
  return rows
223
- contract = compile_bundle(root)
225
+ contract = compile_bundle(root, snapshots=False)
224
226
  settled: Rows = {}
225
227
  for entity, listed in rows.items():
226
228
  first: dict[tuple, dict] = {}
@@ -31,6 +31,7 @@ from dataclasses import dataclass, field
31
31
  from pathlib import Path
32
32
  from typing import IO, Any, Iterable, Iterator
33
33
 
34
+ from .._toml import tomllib
34
35
  from .batch import _Reader, _stream_array, encode_row
35
36
  from .compiler import Contract, build
36
37
  from .connector import SPEC, Spec, redact
@@ -63,11 +64,6 @@ class Summary:
63
64
 
64
65
  def envelope_key(world: Path) -> str:
65
66
  """``[api].envelope`` of the world's connector.toml; "" when unset or absent."""
66
- try:
67
- import tomllib
68
- except ModuleNotFoundError: # pragma: no cover - python 3.10
69
- import tomli as tomllib
70
-
71
67
  spec = world / SPEC
72
68
  if not spec.is_file():
73
69
  return ""
@@ -0,0 +1,225 @@
1
+ """One grader path: a task's grader over a world's end state.
2
+
3
+ A task grades one of three ways — ``assertions`` (declarative checks, in
4
+ process), ``python`` (a ``verify.py`` fed the state on stdin, printing the
5
+ rewards on stdout) or ``rubric`` (judged by the platform; here, pending). The
6
+ World Host grades a session this way and the batch runner grades a stored
7
+ task this way, whether the world is stored as itself (a schema world) or
8
+ packaged as an api bundle: :class:`TaskGrader` is the one place the three
9
+ kinds are told apart, and :func:`keyed_entities` is the one shape of the state
10
+ they read (``{entity: {primary key: row}}``, the api runtime's dump).
11
+
12
+ The two hosts differ only in how they run world-authored code: the World Host
13
+ confines the verifier like a worker (:class:`VerifierSandbox` subclass in
14
+ :mod:`workers`), the runner's container is the confinement. A verifier that
15
+ cannot deliver a grade — missing, timed out, crashed, printed no JSON — is a
16
+ :class:`GraderError`; the host turns it into a refusal, the runner into a
17
+ null-graded sample that names the reason. Null is "ungraded", never zero.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import subprocess
24
+ import sys
25
+ from collections.abc import Callable, Iterable, Mapping
26
+ from dataclasses import dataclass, field
27
+ from pathlib import Path
28
+ from typing import Any, Protocol
29
+
30
+ from .tasks import evaluate_assertions
31
+
32
+ GRADER_KINDS = ("assertions", "python", "rubric")
33
+ VERIFY_TIMEOUT_S = 30.0
34
+
35
+
36
+ class GraderError(Exception):
37
+ """A grader that could not deliver a grade, with the reason a reader acts on."""
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class Grade:
42
+ """A task's grade: the scalar ``reward`` (None when ungraded) and every
43
+ named dimension under ``rewards`` (nulls kept). ``pending`` is a grade the
44
+ platform still owes (a rubric)."""
45
+
46
+ reward: float | None
47
+ rewards: dict[str, float | None] = field(default_factory=dict)
48
+ pending: bool = False
49
+ grader: str | None = None
50
+
51
+ def as_dict(self) -> dict[str, Any]:
52
+ """The wire shape ``grade`` answers with (and ``verify.py`` prints)."""
53
+ out: dict[str, Any] = {"reward": self.reward, "rewards": dict(self.rewards)}
54
+ if self.pending:
55
+ out["pending"] = True
56
+ out["grader"] = self.grader
57
+ return out
58
+
59
+ @staticmethod
60
+ def of_rewards(printed: Mapping[str, Any]) -> "Grade":
61
+ """The grade a verifier printed: the scalar under ``reward``, every
62
+ other key a dimension (non-numeric ones null)."""
63
+ return Grade(
64
+ reward=_number(printed.get("reward")),
65
+ rewards={key: _number(value) for key, value in printed.items() if key != "reward"},
66
+ )
67
+
68
+
69
+ def _number(value: Any) -> float | None:
70
+ if isinstance(value, (int, float)):
71
+ return float(value)
72
+ return None
73
+
74
+
75
+ class VerifierSandbox:
76
+ """How a ``verify.py`` is run: the argv and the environment. The base runs
77
+ it with this interpreter and the inherited environment — a container that
78
+ is itself the confinement (the batch runner). A host that must confine the
79
+ verifier further subclasses this."""
80
+
81
+ def command(self, script: Path) -> list[str]:
82
+ return [sys.executable, str(script)]
83
+
84
+ def environment(self, home: Path) -> dict[str, str] | None:
85
+ return None
86
+
87
+
88
+ class TaskGrader:
89
+ """A task's grader, ready to grade a state dump.
90
+
91
+ ``grader`` is the spec's normalised ``grader`` table. A python grader's
92
+ source must already be on disk at ``verify`` (the session's or the run's
93
+ ``<task>/checks/verify.py``); a bundled scenario's ``verify.py`` is graded
94
+ as a python grader with no table of its own."""
95
+
96
+ def __init__(
97
+ self,
98
+ grader: Mapping[str, Any],
99
+ *,
100
+ verify: Path | None = None,
101
+ sandbox: VerifierSandbox | None = None,
102
+ home: Path | None = None,
103
+ default_timeout_s: float = VERIFY_TIMEOUT_S,
104
+ ) -> None:
105
+ kind = grader.get("kind")
106
+ if kind not in GRADER_KINDS:
107
+ raise GraderError(f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}")
108
+ self.grader = dict(grader)
109
+ self.kind: str = kind
110
+ self.verify = verify
111
+ self.sandbox = sandbox or VerifierSandbox()
112
+ self.home = home
113
+ timeout = grader.get("timeoutSeconds")
114
+ own = None if isinstance(timeout, bool) else _number(timeout)
115
+ self.timeout_s = own if own is not None and own > 0 else float(default_timeout_s)
116
+
117
+ @staticmethod
118
+ def for_verifier(
119
+ verify: Path,
120
+ *,
121
+ sandbox: VerifierSandbox | None = None,
122
+ home: Path | None = None,
123
+ timeout_s: float = VERIFY_TIMEOUT_S,
124
+ ) -> "TaskGrader":
125
+ """A bundled scenario's ``verify.py``: a python grader with the host's timeout."""
126
+ return TaskGrader({"kind": "python"}, verify=verify, sandbox=sandbox, home=home, default_timeout_s=timeout_s)
127
+
128
+ @property
129
+ def pending(self) -> bool:
130
+ """Whether the platform grades this task (a rubric), not this process."""
131
+ return self.kind == "rubric"
132
+
133
+ def grade(self, state: Mapping[str, Any]) -> Grade:
134
+ graders: dict[str, Callable[[Mapping[str, Any]], Grade]] = {
135
+ "assertions": self._assertions,
136
+ "python": self._python,
137
+ "rubric": self._rubric,
138
+ }
139
+ return graders[self.kind](state)
140
+
141
+ def _assertions(self, state: Mapping[str, Any]) -> Grade:
142
+ graded = evaluate_assertions(self.grader["checks"], dict(state))
143
+ return Grade(reward=graded["reward"], rewards=graded["rewards"])
144
+
145
+ def _rubric(self, state: Mapping[str, Any]) -> Grade:
146
+ return Grade(reward=None, rewards={}, pending=True, grader="rubric")
147
+
148
+ def _python(self, state: Mapping[str, Any]) -> Grade:
149
+ verify = self.verify
150
+ if verify is None or not verify.is_file():
151
+ raise GraderError(f"the task's verify.py is missing at {verify}")
152
+ home = self.home if self.home is not None else verify.parent
153
+ home.mkdir(parents=True, exist_ok=True)
154
+ try:
155
+ proc = subprocess.run(
156
+ self.sandbox.command(verify),
157
+ input=json.dumps(state),
158
+ check=False,
159
+ capture_output=True,
160
+ text=True,
161
+ timeout=self.timeout_s,
162
+ cwd=str(verify.parent),
163
+ env=self.sandbox.environment(home),
164
+ )
165
+ except subprocess.TimeoutExpired:
166
+ raise GraderError(f"verify.py timed out after {self.timeout_s:g}s") from None
167
+ if proc.returncode != 0:
168
+ raise GraderError(f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}")
169
+ try:
170
+ printed = json.loads(proc.stdout.strip().splitlines()[-1])
171
+ except (json.JSONDecodeError, IndexError):
172
+ raise GraderError(f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}") from None
173
+ if not isinstance(printed, dict):
174
+ raise GraderError("verify.py rewards output is not an object")
175
+ return Grade.of_rewards(printed)
176
+
177
+
178
+ def keyed_entities(
179
+ entities: Mapping[str, Mapping[str, Any]], rows_of: Callable[[str], Iterable[Mapping[str, Any]]]
180
+ ) -> dict:
181
+ """A world's rows the way a grader reads them: every contract entity by
182
+ name, its rows keyed by their primary key (``a:b`` for a composite key) —
183
+ the api runtime's ``/__world/state`` dump, so a check or a ``verify.py``
184
+ written against one shape of the world grades the other."""
185
+ out: dict[str, dict[str, Any]] = {}
186
+ for entity, spec in entities.items():
187
+ keyed: dict[str, Any] = {}
188
+ for row in rows_of(entity):
189
+ keyed[":".join(str(row.get(name)) for name in spec["primary_key"])] = row
190
+ out[entity] = keyed
191
+ return out
192
+
193
+
194
+ class StoredWorld(Protocol):
195
+ """What a grader needs of a live world: its contract and the store holding
196
+ its rows — a World Host session's world and the batch runner's are both."""
197
+
198
+ @property
199
+ def contract(self) -> Any: ...
200
+
201
+ @property
202
+ def store(self) -> Any: ...
203
+
204
+
205
+ def world_state(root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]) -> dict:
206
+ """The rows as a task's grader reads them, on the host and in the batch
207
+ runner alike: the root's entities by name and each dependency's as
208
+ ``<alias>.<entity>``, every entity's rows keyed by primary key — the api
209
+ runtime's dump, so one ``verify.py`` grades the world in either shape. A
210
+ world without a contract (a legacy tools bundle) contributes nothing, as
211
+ does a task set that owns no root world (``root`` None)."""
212
+ out: dict[str, Any] = dict(_keyed_rows_of(root))
213
+ for alias, world in dependencies.items():
214
+ for entity, rows in _keyed_rows_of(world).items():
215
+ out[f"{alias}.{entity}"] = rows
216
+ return out
217
+
218
+
219
+ def _keyed_rows_of(world: StoredWorld | None) -> dict[str, dict]:
220
+ if world is None:
221
+ return {}
222
+ store, contract = world.store, world.contract
223
+ if store is None or contract is None:
224
+ return {}
225
+ return keyed_entities(contract.entities, store.list)