@withgateway/sdk 0.3.1 → 0.4.0

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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,227 @@
1
+ """A served answer in the vendor's shape: one page of rows, and the envelope around it.
2
+
3
+ A list answers ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next}``; a dotted
4
+ envelope (``message.items``) nests that object (``{message: {items, total-results,
5
+ next-cursor}}``), and a route's ``wrapper`` is the rest of the vendor's envelope the
6
+ answer is laid onto (``{status, message-type, message: {items-per-page, query}}``).
7
+ A single row answers bare, or at its route's own envelope (``message`` →
8
+ ``{message: row}``) inside the wrapper. The world's ``[api].envelope`` is for lists;
9
+ a single row is wrapped only by its own route's.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import base64
15
+ import copy
16
+ import urllib.parse
17
+ from dataclasses import dataclass
18
+ from typing import TYPE_CHECKING, Any
19
+
20
+ if TYPE_CHECKING:
21
+ from .api import ApiSettings
22
+
23
+ #: The largest offset or page size a request can ask for: what a store takes as one integer.
24
+ MAX_ROWS = 2**63 - 1
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class Paging:
29
+ style: str = "none"
30
+ limit_param: str = "limit"
31
+ offset_param: str = "offset"
32
+ cursor_param: str = "cursor"
33
+ page_size: int = 100
34
+
35
+ @property
36
+ def params(self) -> frozenset[str]:
37
+ """The query parameters the pager reads, which never filter a route's rows."""
38
+ return frozenset({self.limit_param, self.offset_param, self.cursor_param})
39
+
40
+ def window(self, query: dict[str, str]) -> tuple[int, int | None]:
41
+ """Where the page a request asks for starts and how many rows it holds; every row
42
+ (``None``) for a route that does not page."""
43
+ if self.style == "none":
44
+ return 0, None
45
+ limit = _int_param(query.get(self.limit_param), self.page_size)
46
+ if self.style == "offset":
47
+ return _int_param(query.get(self.offset_param), 0), limit
48
+ return _cursor_offset(query.get(self.cursor_param)), limit
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class Page:
53
+ rows: list[dict]
54
+ total: int
55
+ offset: int
56
+ limit: int
57
+ style: str
58
+
59
+ @property
60
+ def next_offset(self) -> int | None:
61
+ following = self.offset + self.limit
62
+ return following if self.style != "none" and following < self.total else None
63
+
64
+ @property
65
+ def previous_offset(self) -> int | None:
66
+ return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
67
+
68
+ @classmethod
69
+ def of(cls, rows: list[dict], total: int, offset: int, limit: int | None, style: str) -> Page:
70
+ """The page :meth:`Paging.window` asked for, ``rows`` already cut to it."""
71
+ return cls(rows, total, offset, total if limit is None else limit, style)
72
+
73
+
74
+ def _encode_cursor(offset: int) -> str:
75
+ return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
76
+
77
+
78
+ def _cursor_offset(raw: str | None) -> int:
79
+ if not raw:
80
+ return 0
81
+ try:
82
+ return min(max(int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode()), 0), MAX_ROWS)
83
+ except (ValueError, UnicodeDecodeError):
84
+ return 0
85
+
86
+
87
+ def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
88
+ """One page of rows with the offsets the next and previous pages start at."""
89
+ offset, limit = paging.window(query)
90
+ end = None if limit is None else offset + limit
91
+ return Page.of(rows[offset:end], len(rows), offset, limit, paging.style)
92
+
93
+
94
+ def _int_param(value: str | None, default: int) -> int:
95
+ try:
96
+ parsed = int(value) if value is not None else default
97
+ except ValueError:
98
+ return default
99
+ return min(parsed, MAX_ROWS) if parsed >= 0 else default
100
+
101
+
102
+ @dataclass(frozen=True)
103
+ class PageLink:
104
+ """The URL a page was asked at, from which its neighbours are built: the request's origin and
105
+ path and every value of its query, in order, less ``dropped`` (the parameters a credential the
106
+ door presented rides in, never the caller's to see again)."""
107
+
108
+ base: str
109
+ query: tuple[tuple[str, tuple[str, ...]], ...] = ()
110
+
111
+ @classmethod
112
+ def of(cls, base: str, query_all: dict[str, list[str]], dropped: frozenset[str] = frozenset()) -> PageLink:
113
+ return cls(base, tuple((name, tuple(values)) for name, values in query_all.items() if name not in dropped))
114
+
115
+ @property
116
+ def first_values(self) -> tuple[str, dict[str, str]]:
117
+ """``(url, {name: first value})``, the link a world's handler reads as ``ctx.link``."""
118
+ return self.base, {name: values[0] for name, values in self.query}
119
+
120
+ def at(self, page: Page, offset: int, paging: Paging) -> str:
121
+ """The neighbouring page at ``offset``: every value the request sent, its paging parameters
122
+ set where the request named them, else after them."""
123
+ following: dict[str, Any] = dict(self.query)
124
+ if page.style == "offset":
125
+ following[paging.offset_param] = str(offset)
126
+ else:
127
+ following[paging.cursor_param] = _encode_cursor(offset)
128
+ following[paging.limit_param] = str(page.limit)
129
+ return f"{self.base}?{urllib.parse.urlencode(following, doseq=True)}"
130
+
131
+
132
+ def _page_ref(page: Page, offset: int | None, paging: Paging, link: PageLink | None) -> Any:
133
+ """What the vendor's client is handed for a neighbouring page: '' or None when there is
134
+ none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
135
+ if offset is None:
136
+ return None if link is not None else ""
137
+ if link is None:
138
+ return _encode_cursor(offset)
139
+ return link.at(page, offset, paging)
140
+
141
+
142
+ def page_headers(
143
+ page: Page,
144
+ settings: ApiSettings,
145
+ paging: Paging | None = None,
146
+ link: PageLink | None = None,
147
+ ) -> dict[str, str] | None:
148
+ """The page's cursor/total/previous as response headers, when the vendor sends them that way,
149
+ and with ``link_header`` its neighbours as an RFC 8288 ``Link`` on the request's own origin."""
150
+ paging = paging or settings.paging
151
+ headers = {**_named_headers(page, settings, paging), **_link_header(page, settings, paging, link)}
152
+ return headers or None
153
+
154
+
155
+ def _named_headers(page: Page, settings: ApiSettings, paging: Paging) -> dict[str, str]:
156
+ values = {
157
+ "cursor": _page_ref(page, page.next_offset, paging, None),
158
+ "total": str(page.total),
159
+ "previous": _page_ref(page, page.previous_offset, paging, None),
160
+ }
161
+ return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
162
+
163
+
164
+ def _link_header(page: Page, settings: ApiSettings, paging: Paging, link: PageLink | None) -> dict[str, str]:
165
+ """``Link: <next>; rel="next", <prev>; rel="prev"`` (GitHub's shape), each URL the request's
166
+ own with the page's paging parameters set; none unless the world declares ``link_header``."""
167
+ if not settings.link_header or link is None:
168
+ return {}
169
+ neighbours = (("next", page.next_offset), ("prev", page.previous_offset))
170
+ relations = [f'<{_page_ref(page, at, paging, link)}>; rel="{rel}"' for rel, at in neighbours if at is not None]
171
+ return {"Link": ", ".join(relations)} if relations else {}
172
+
173
+
174
+ def wrap(
175
+ page: Page | list[dict],
176
+ settings: ApiSettings,
177
+ envelope: str | None = None,
178
+ *,
179
+ paging: Paging | None = None,
180
+ link: PageLink | None = None,
181
+ omit_done_cursor: bool = False,
182
+ wrapper: dict | None = None,
183
+ ) -> Any:
184
+ """Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
185
+ [, <previous_key>: previous]}`` at the envelope's dotted path inside ``wrapper``; an empty
186
+ envelope key means the bare array, an empty ``hits_key`` leaves the count out, and
187
+ ``omit_done_cursor`` leaves the cursor key out on the last page — together they make the
188
+ ``{items, next_cursor?}`` shape vendors such as Brex answer, which a client may check with
189
+ ``"next_cursor" in body``."""
190
+ if not isinstance(page, Page):
191
+ page = Page(page, len(page), 0, len(page), "none")
192
+ key = settings.envelope if envelope is None else envelope
193
+ if not key:
194
+ return page.rows
195
+ paging = paging or settings.paging
196
+ link = link if settings.page_links else None
197
+ *outer, leaf = key.split(".")
198
+ out = {leaf: page.rows}
199
+ if settings.hits_key:
200
+ out[settings.hits_key] = page.total
201
+ if page.next_offset is not None or not omit_done_cursor:
202
+ out[settings.cursor_key] = _page_ref(page, page.next_offset, paging, link)
203
+ if settings.previous_key:
204
+ out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
205
+ return laid(wrapper, _nested(outer, out))
206
+
207
+
208
+ def single(row: Any, envelope: str | None, wrapper: dict | None) -> Any:
209
+ """One row at its route's own envelope inside ``wrapper``, or bare when the route sets none."""
210
+ if not envelope:
211
+ return row
212
+ *outer, leaf = envelope.split(".")
213
+ return laid(wrapper, _nested(outer, {leaf: row}))
214
+
215
+
216
+ def _nested(path: list[str], value: dict) -> dict:
217
+ for part in reversed(path):
218
+ value = {part: value}
219
+ return value
220
+
221
+
222
+ def laid(template: dict | None, value: dict) -> dict:
223
+ """``value`` laid over a copy of ``template``: objects merge key by key, the rest is ``value``'s."""
224
+ out = copy.deepcopy(template) if template else {}
225
+ for key, item in value.items():
226
+ out[key] = laid(out[key], item) if isinstance(out.get(key), dict) and isinstance(item, dict) else item
227
+ return out
@@ -35,6 +35,7 @@ from .._toml import tomllib
35
35
  from .batch import _Reader, _stream_array, encode_row
36
36
  from .compiler import Contract, build
37
37
  from .connector import SPEC, Spec, redact
38
+ from .primary_key import PrimaryKey
38
39
  from .redaction import RedactPolicy, policy_for
39
40
  from .validation import ContractError, fail
40
41
 
@@ -59,9 +60,6 @@ class Summary:
59
60
  }
60
61
 
61
62
 
62
- # ---------------------------------------------------------------- the world
63
-
64
-
65
63
  def envelope_key(world: Path) -> str:
66
64
  """``[api].envelope`` of the world's connector.toml; "" when unset or absent."""
67
65
  spec = world / SPEC
@@ -76,9 +74,6 @@ def redaction_spec(world: Path) -> Spec | RedactPolicy | None:
76
74
  return policy_for(world)
77
75
 
78
76
 
79
- # ---------------------------------------------------------------- adapters
80
-
81
-
82
77
  def _lines(stream: IO[str], where: str) -> Iterator[Any]:
83
78
  for number, line in enumerate(stream, start=1):
84
79
  if not line.strip():
@@ -116,7 +111,7 @@ def tool_results(stream: IO[str], where: str, *, keys: list[str], envelope: str
116
111
  if listed is None:
117
112
  listed = raw.get("items")
118
113
  for item in _objects(listed):
119
- if all(name in item for name in keys):
114
+ if PrimaryKey(tuple(keys)).missing(item) is None:
120
115
  yield item
121
116
 
122
117
 
@@ -175,9 +170,6 @@ def session_export(stream: IO[str], where: str, *, keys: list[str], envelope: st
175
170
  ADAPTERS = {"tool-results": tool_results, "vendor-envelope": vendor_envelope, "session-export": session_export}
176
171
 
177
172
 
178
- # ---------------------------------------------------------------- the pipeline
179
-
180
-
181
173
  def _clean(row: dict, declared: set[str], summary: Summary) -> dict:
182
174
  out: dict = {}
183
175
  for name, value in row.items():
@@ -218,7 +210,8 @@ def extract(
218
210
  if entity not in contract.entities:
219
211
  fail("entity", f"Unknown entity {entity}; the world has {', '.join(sorted(contract.entities))}", f"/{entity}")
220
212
  spec_entity = contract.entities[entity]
221
- keys = list(spec_entity["primary_key"])
213
+ primary = PrimaryKey.of(spec_entity)
214
+ keys = list(primary.fields)
222
215
  declared = set(spec_entity["schema"].get("properties", {}))
223
216
  envelope = envelope_key(root)
224
217
  policy = redaction_spec(root) if redaction else None
@@ -233,9 +226,9 @@ def extract(
233
226
  for raw in adapter(stream, where, keys=keys, envelope=envelope):
234
227
  summary.read += 1
235
228
  row = _clean(raw, declared, summary)
236
- if not all(name in row for name in keys):
229
+ if primary.missing(row) is not None:
237
230
  continue
238
- key = json.dumps([row[name] for name in keys], sort_keys=True, separators=(",", ":"))
231
+ key = json.dumps(primary.values(row), sort_keys=True, separators=(",", ":"))
239
232
  if key in held:
240
233
  if merge == "upsert":
241
234
  held[key] = row
@@ -1,22 +1,3 @@
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
1
  from __future__ import annotations
21
2
 
22
3
  import json
@@ -27,66 +8,92 @@ from dataclasses import dataclass, field
27
8
  from pathlib import Path
28
9
  from typing import Any, Protocol
29
10
 
11
+ from ..score import Score
30
12
  from ..world_session_contract import NO_GRADER_REASON
31
- from .tasks import GraderError, evaluate_assertions
13
+ from .assertions import Assertions
14
+ from .journal import NOT_RECORDED
15
+ from .primary_key import PrimaryKey
16
+ from .tasks import CALL_LOG, JOURNAL, JOURNAL_META, GraderError
32
17
 
33
18
  GRADER_KINDS = ("assertions", "python", "rubric")
34
19
  VERIFY_TIMEOUT_S = 30.0
20
+ JOURNAL_READS = (JOURNAL, CALL_LOG)
35
21
 
36
22
 
37
23
  @dataclass(frozen=True)
38
24
  class Grade:
39
- """A task's grade: the scalar ``reward`` (None when ungraded) and every
40
- named dimension under ``rewards`` (nulls kept). ``pending`` is a grade the
41
- platform still owes (a rubric); ``reason`` says why a grade is null when
42
- no grader ran at all (an exploratory session, a task without one)."""
25
+ """``reward`` is None when no grader decided it (never 0) and 0 when one failed closed; ``pending`` means the
26
+ platform still owes the grade (a rubric)."""
43
27
 
44
28
  reward: float | None
45
29
  rewards: dict[str, float | None] = field(default_factory=dict)
46
30
  pending: bool = False
47
31
  grader: str | None = None
48
32
  reason: str | None = None
33
+ reasons: dict[str, str] = field(default_factory=dict)
34
+ checks: dict[str, dict] = field(default_factory=dict)
49
35
 
50
36
  def as_dict(self) -> dict[str, Any]:
51
- """The wire shape ``grade`` answers with (and ``verify.py`` prints)."""
52
37
  out: dict[str, Any] = {"reward": self.reward, "rewards": dict(self.rewards)}
53
38
  if self.pending:
54
39
  out["pending"] = True
55
40
  out["grader"] = self.grader
56
41
  if self.reason is not None:
57
42
  out["reason"] = self.reason
43
+ if self.reasons:
44
+ out["reasons"] = dict(self.reasons)
45
+ if self.checks:
46
+ out["checks"] = dict(self.checks)
58
47
  return out
59
48
 
49
+ @staticmethod
50
+ def closed(reason: str) -> Grade:
51
+ return Grade(0.0, reason=reason)
52
+
60
53
  @staticmethod
61
54
  def ungraded() -> Grade:
62
- """The grade of a session with no grader: null, and it says so."""
63
55
  return Grade(None, reason=NO_GRADER_REASON)
64
56
 
65
57
  @staticmethod
66
58
  def of_rewards(printed: Mapping[str, Any]) -> Grade:
67
- """The grade a verifier printed: the scalar under ``reward``, every
68
- other key a dimension (non-numeric ones null)."""
59
+ """A nested value would hide the scores inside it, an out-of-range one would average into 1.0 and NaN is not
60
+ JSON, so each is refused by key; a string or null is an ungraded check."""
61
+ refused = [f"{key!r} as {_kind(value)}" for key, value in printed.items() if not _is_score(value)]
62
+ if refused:
63
+ raise GraderError(
64
+ f"verify.py printed {', '.join(refused)} where a score belongs; print one flat JSON object, "
65
+ '"reward" plus one number per check, e.g. {"reward": 0.5, "card_moved": 1}'
66
+ )
67
+ out_of_range = Score.problem(printed.items())
68
+ if out_of_range is not None:
69
+ raise GraderError(f"verify.py printed {out_of_range}")
69
70
  return Grade(
70
71
  reward=_number(printed.get("reward")),
71
- rewards={
72
- key: _number(value) for key, value in printed.items() if key != "reward"
73
- },
72
+ rewards={key: _number(value) for key, value in printed.items() if key != "reward"},
74
73
  )
75
74
 
76
75
 
76
+ NOT_A_SCORE = {dict: "an object", list: "an array"}
77
+
78
+
79
+ def _is_score(value: Any) -> bool:
80
+ return not isinstance(value, (dict, list))
81
+
82
+
83
+ def _kind(value: Any) -> str:
84
+ return NOT_A_SCORE.get(type(value), type(value).__name__)
85
+
86
+
77
87
  def _number(value: Any) -> float | None:
78
- """A score is a number; a boolean is the 1.0 / 0.0 it claims (the tracing
79
- reward emitter's convention), anything else null."""
80
- if isinstance(value, (int, float)):
88
+ """A boolean is the 1.0 / 0.0 it claims, the tracing reward emitter's convention."""
89
+ if isinstance(value, (int, float)) and Score.finite(value):
81
90
  return float(value)
82
91
  return None
83
92
 
84
93
 
85
94
  class VerifierSandbox:
86
- """How a ``verify.py`` is run: the argv and the environment. The base runs
87
- it with this interpreter and the inherited environment — a container that
88
- is itself the confinement (the batch runner). A host that must confine the
89
- verifier further subclasses this."""
95
+ """Runs verify.py with the inherited environment, safe only where its container is the confinement (the batch
96
+ runner); the World Host confines it further in a subclass."""
90
97
 
91
98
  def command(self, script: Path) -> list[str]:
92
99
  return [sys.executable, str(script)]
@@ -96,21 +103,6 @@ class VerifierSandbox:
96
103
 
97
104
 
98
105
  class TaskGrader:
99
- """A task's grader, ready to grade a state dump.
100
-
101
- ``grader`` is the spec's normalised ``grader`` table. A python grader's
102
- source must already be on disk at ``verify`` (the session's or the run's
103
- ``<task>/checks/verify.py``); a bundled scenario's ``verify.py`` is graded
104
- as a python grader with no table of its own.
105
-
106
- A grader with a ``scope`` is a CROSS-WORLD VERIFIER: the same table, read
107
- over several of a multi-world task's worlds at once. ``scope`` names the
108
- aliases (the first is the session it runs on); :meth:`evidence` builds
109
- the dump it grades, every scoped world's rows as ``<alias>.<entity>`` and
110
- its calls as ``<alias>.calls`` — the naming a world's dependencies use, so
111
- a check or a ``verify.py`` reads it unchanged. An unscoped grader's
112
- evidence is the session's own state, untouched."""
113
-
114
106
  def __init__(
115
107
  self,
116
108
  grader: Mapping[str, Any],
@@ -121,12 +113,11 @@ class TaskGrader:
121
113
  default_timeout_s: float = VERIFY_TIMEOUT_S,
122
114
  scope: Iterable[str] = (),
123
115
  name: str | None = None,
116
+ explain: bool = False,
124
117
  ) -> None:
125
118
  kind = grader.get("kind")
126
119
  if kind not in GRADER_KINDS:
127
- raise GraderError(
128
- f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}"
129
- )
120
+ raise GraderError(f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}")
130
121
  self.grader = dict(grader)
131
122
  self.kind: str = kind
132
123
  self.verify = verify
@@ -134,25 +125,16 @@ class TaskGrader:
134
125
  self.home = home
135
126
  self.scope: tuple[str, ...] = tuple(scope)
136
127
  self.name = name
128
+ self.explain = explain
137
129
  timeout = grader.get("timeoutSeconds")
138
130
  own = None if isinstance(timeout, bool) else _number(timeout)
139
- self.timeout_s = (
140
- own if own is not None and own > 0 else float(default_timeout_s)
141
- )
131
+ self.timeout_s = own if own is not None and own > 0 else float(default_timeout_s)
142
132
 
143
133
  @property
144
134
  def anchor(self) -> str | None:
145
- """The alias whose session runs a scoped grader; None when unscoped."""
146
135
  return self.scope[0] if self.scope else None
147
136
 
148
137
  def evidence(self, own: Mapping[str, Any], context: Mapping[str, Mapping[str, Any]]) -> dict:
149
- """The dump this grader reads. Unscoped: ``own`` as it is. Scoped:
150
- every scoped world's state under ``<alias>.<key>`` — the anchor's from
151
- ``own``, the others from ``context`` (``{alias: state}``, what the
152
- platform gathered from those sessions) — with the agent's ``report``
153
- kept at the top. A scoped alias ``context`` lacks, or a check over an
154
- entity no scoped world holds, is a :class:`GraderError`: ungraded with
155
- the reason, never zero."""
156
138
  if not self.scope:
157
139
  return dict(own)
158
140
  missing = [alias for alias in self.scope[1:] if alias not in context]
@@ -167,9 +149,7 @@ class TaskGrader:
167
149
  dump.update({f"{alias}.{key}": value for key, value in states[alias].items() if key != "report"})
168
150
  if "report" in own:
169
151
  dump["report"] = own["report"]
170
- # No world's contract vets a cross-world check's entity (a session knows
171
- # only its own), and a check over a key the dump lacks selects nothing —
172
- # which `absent` and `count: eq 0` would pass on a typo.
152
+ # No contract vets a cross-world entity, and one the dump lacks selects nothing: absent would pass on a typo.
173
153
  unknown = [check["entity"] for check in self.grader.get("checks", ()) if check["entity"] not in dump]
174
154
  if unknown:
175
155
  raise GraderError(
@@ -185,7 +165,6 @@ class TaskGrader:
185
165
  home: Path | None = None,
186
166
  timeout_s: float = VERIFY_TIMEOUT_S,
187
167
  ) -> TaskGrader:
188
- """A bundled scenario's ``verify.py``: a python grader with the host's timeout."""
189
168
  return TaskGrader(
190
169
  {"kind": "python"},
191
170
  verify=verify,
@@ -196,9 +175,13 @@ class TaskGrader:
196
175
 
197
176
  @property
198
177
  def pending(self) -> bool:
199
- """Whether the platform grades this task (a rubric), not this process."""
200
178
  return self.kind == "rubric"
201
179
 
180
+ @property
181
+ def reads_journal(self) -> bool:
182
+ checks = self.grader.get("checks", ())
183
+ return self.grader.get("readsJournal") is True or any(check["entity"] in JOURNAL_READS for check in checks)
184
+
202
185
  def grade(self, state: Mapping[str, Any]) -> Grade:
203
186
  graders: dict[str, Callable[[Mapping[str, Any]], Grade]] = {
204
187
  "assertions": self._assertions,
@@ -208,13 +191,17 @@ class TaskGrader:
208
191
  return graders[self.kind](state)
209
192
 
210
193
  def _assertions(self, state: Mapping[str, Any]) -> Grade:
211
- graded = evaluate_assertions(self.grader["checks"], dict(state))
212
- return Grade(reward=graded["reward"], rewards=graded["rewards"])
194
+ graded = Assertions(self.grader["checks"]).grade(state)
195
+ checks = {key: outcome.as_dict() for key, outcome in graded.outcomes.items()} if self.explain else {}
196
+ return Grade(reward=graded.reward, rewards=graded.rewards, reasons=graded.reasons, checks=checks)
213
197
 
214
198
  def _rubric(self, state: Mapping[str, Any]) -> Grade:
215
199
  return Grade(reward=None, rewards={}, pending=True, grader="rubric")
216
200
 
217
201
  def _python(self, state: Mapping[str, Any]) -> Grade:
202
+ refused = self._incomplete_journal(state)
203
+ if refused is not None:
204
+ return Grade.closed(refused)
218
205
  verify = self.verify
219
206
  if verify is None or not verify.is_file():
220
207
  raise GraderError(f"the task's verify.py is missing at {verify}")
@@ -232,45 +219,53 @@ class TaskGrader:
232
219
  env=self.sandbox.environment(home),
233
220
  )
234
221
  except subprocess.TimeoutExpired:
235
- raise GraderError(
236
- f"verify.py timed out after {self.timeout_s:g}s"
237
- ) from None
222
+ raise GraderError(f"verify.py timed out after {self.timeout_s:g}s") from None
238
223
  if proc.returncode != 0:
239
- raise GraderError(
240
- f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}"
241
- )
224
+ raise GraderError(f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}")
242
225
  try:
243
226
  printed = json.loads(proc.stdout.strip().splitlines()[-1])
244
227
  except (json.JSONDecodeError, IndexError):
245
- raise GraderError(
246
- f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}"
247
- ) from None
228
+ raise GraderError(f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}") from None
248
229
  if not isinstance(printed, dict):
249
230
  raise GraderError("verify.py rewards output is not an object")
250
231
  return Grade.of_rewards(printed)
251
232
 
233
+ def _incomplete_journal(self, state: Mapping[str, Any]) -> str | None:
234
+ if not self.grader.get("readsJournal"):
235
+ return None
236
+ if JOURNAL not in state:
237
+ return f"journal incomplete ({NOT_RECORDED}): this verify.py reads the journal"
238
+ if self.grader.get("acceptsIncompleteJournal"):
239
+ return None
240
+ meta = state.get(JOURNAL_META)
241
+ meta = meta if isinstance(meta, Mapping) else {}
242
+ withheld = meta.get("withheld") or 0
243
+ if meta.get("complete") is True and not withheld:
244
+ return None
245
+ why = (
246
+ meta.get("reason") or "it may be missing requests"
247
+ if meta.get("complete") is not True
248
+ else f"the bodies of {withheld} requests were withheld past the grade's budget"
249
+ )
250
+ return (
251
+ f"journal incomplete ({why}): this verify.py reads the journal, "
252
+ "so it does not grade one that may be missing requests; declare acceptsIncompleteJournal: true to grade it"
253
+ )
254
+
252
255
 
253
256
  def keyed_entities(
254
257
  entities: Mapping[str, Mapping[str, Any]],
255
258
  rows_of: Callable[[str], Iterable[Mapping[str, Any]]],
256
259
  ) -> dict:
257
- """A world's rows the way a grader reads them: every contract entity by
258
- name, its rows keyed by their primary key (``a:b`` for a composite key) —
259
- the api runtime's ``/__world/state`` dump, so a check or a ``verify.py``
260
- written against one shape of the world grades the other."""
260
+ """Twin of the api runtime's ``/__world/state`` dump, so a check grades either shape of a world."""
261
261
  out: dict[str, dict[str, Any]] = {}
262
262
  for entity, spec in entities.items():
263
- keyed: dict[str, Any] = {}
264
- for row in rows_of(entity):
265
- keyed[":".join(str(row.get(name)) for name in spec["primary_key"])] = row
266
- out[entity] = keyed
263
+ key = PrimaryKey.of(spec)
264
+ out[entity] = {":".join(str(value) for value in key.values(row)): row for row in rows_of(entity)}
267
265
  return out
268
266
 
269
267
 
270
268
  class StoredWorld(Protocol):
271
- """What a grader needs of a live world: its contract and the store holding
272
- its rows — a World Host session's world and the batch runner's are both."""
273
-
274
269
  @property
275
270
  def contract(self) -> Any: ...
276
271
 
@@ -278,15 +273,7 @@ class StoredWorld(Protocol):
278
273
  def store(self) -> Any: ...
279
274
 
280
275
 
281
- def world_state(
282
- root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]
283
- ) -> dict:
284
- """The rows as a task's grader reads them, on the host and in the batch
285
- runner alike: the root's entities by name and each dependency's as
286
- ``<alias>.<entity>``, every entity's rows keyed by primary key — the api
287
- runtime's dump, so one ``verify.py`` grades the world in either shape. A
288
- world without a contract (a legacy tools bundle) contributes nothing, as
289
- does a task set that owns no root world (``root`` None)."""
276
+ def world_state(root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]) -> dict:
290
277
  out: dict[str, Any] = dict(_keyed_rows_of(root))
291
278
  for alias, world in dependencies.items():
292
279
  for entity, rows in _keyed_rows_of(world).items():