@withgateway/sdk 0.3.0 → 0.3.3

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 (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,169 @@
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
+
24
+ @dataclass(frozen=True)
25
+ class Paging:
26
+ style: str = "none"
27
+ limit_param: str = "limit"
28
+ offset_param: str = "offset"
29
+ cursor_param: str = "cursor"
30
+ page_size: int = 100
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class Page:
35
+ rows: list[dict]
36
+ total: int
37
+ offset: int
38
+ limit: int
39
+ style: str
40
+
41
+ @property
42
+ def next_offset(self) -> int | None:
43
+ following = self.offset + self.limit
44
+ return following if self.style != "none" and following < self.total else None
45
+
46
+ @property
47
+ def previous_offset(self) -> int | None:
48
+ return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
49
+
50
+
51
+ def _encode_cursor(offset: int) -> str:
52
+ return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
53
+
54
+
55
+ def _cursor_offset(raw: str | None) -> int:
56
+ if not raw:
57
+ return 0
58
+ try:
59
+ return int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode())
60
+ except (ValueError, UnicodeDecodeError):
61
+ return 0
62
+
63
+
64
+ def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
65
+ """One page of rows with the offsets the next and previous pages start at."""
66
+ total = len(rows)
67
+ if paging.style == "none":
68
+ return Page(rows, total, 0, total, "none")
69
+ limit = _int_param(query.get(paging.limit_param), paging.page_size)
70
+ offset = (
71
+ _int_param(query.get(paging.offset_param), 0)
72
+ if paging.style == "offset"
73
+ else _cursor_offset(query.get(paging.cursor_param))
74
+ )
75
+ return Page(rows[offset : offset + limit], total, offset, limit, paging.style)
76
+
77
+
78
+ def _int_param(value: str | None, default: int) -> int:
79
+ try:
80
+ parsed = int(value) if value is not None else default
81
+ except ValueError:
82
+ return default
83
+ return parsed if parsed >= 0 else default
84
+
85
+
86
+ def _page_ref(page: Page, offset: int | None, paging: Paging, link: tuple[str, dict[str, str]] | None) -> Any:
87
+ """What the vendor's client is handed for a neighbouring page: '' or None when there is
88
+ none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
89
+ if offset is None:
90
+ return None if link is not None else ""
91
+ if link is None:
92
+ return _encode_cursor(offset)
93
+ base, query = link
94
+ following = dict(query)
95
+ if page.style == "offset":
96
+ following[paging.offset_param] = str(offset)
97
+ else:
98
+ following[paging.cursor_param] = _encode_cursor(offset)
99
+ following[paging.limit_param] = str(page.limit)
100
+ return f"{base}?{urllib.parse.urlencode(following)}"
101
+
102
+
103
+ def page_headers(page: Page, settings: ApiSettings, paging: Paging | None = None) -> dict[str, str] | None:
104
+ """The page's cursor/total/previous as response headers, when the vendor sends them that way."""
105
+ if not settings.page_headers:
106
+ return None
107
+ paging = paging or settings.paging
108
+ values = {
109
+ "cursor": _page_ref(page, page.next_offset, paging, None),
110
+ "total": str(page.total),
111
+ "previous": _page_ref(page, page.previous_offset, paging, None),
112
+ }
113
+ return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
114
+
115
+
116
+ def wrap(
117
+ page: Page | list[dict],
118
+ settings: ApiSettings,
119
+ envelope: str | None = None,
120
+ *,
121
+ paging: Paging | None = None,
122
+ link: tuple[str, dict[str, str]] | None = None,
123
+ omit_done_cursor: bool = False,
124
+ wrapper: dict | None = None,
125
+ ) -> Any:
126
+ """Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
127
+ [, <previous_key>: previous]}`` at the envelope's dotted path inside ``wrapper``; an empty
128
+ envelope key means the bare array, an empty ``hits_key`` leaves the count out, and
129
+ ``omit_done_cursor`` leaves the cursor key out on the last page — together they make the
130
+ ``{items, next_cursor?}`` shape vendors such as Brex answer, which a client may check with
131
+ ``"next_cursor" in body``."""
132
+ if not isinstance(page, Page):
133
+ page = Page(page, len(page), 0, len(page), "none")
134
+ key = settings.envelope if envelope is None else envelope
135
+ if not key:
136
+ return page.rows
137
+ paging = paging or settings.paging
138
+ link = link if settings.page_links else None
139
+ *outer, leaf = key.split(".")
140
+ out = {leaf: page.rows}
141
+ if settings.hits_key:
142
+ out[settings.hits_key] = page.total
143
+ if page.next_offset is not None or not omit_done_cursor:
144
+ out[settings.cursor_key] = _page_ref(page, page.next_offset, paging, link)
145
+ if settings.previous_key:
146
+ out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
147
+ return laid(wrapper, _nested(outer, out))
148
+
149
+
150
+ def single(row: Any, envelope: str | None, wrapper: dict | None) -> Any:
151
+ """One row at its route's own envelope inside ``wrapper``, or bare when the route sets none."""
152
+ if not envelope:
153
+ return row
154
+ *outer, leaf = envelope.split(".")
155
+ return laid(wrapper, _nested(outer, {leaf: row}))
156
+
157
+
158
+ def _nested(path: list[str], value: dict) -> dict:
159
+ for part in reversed(path):
160
+ value = {part: value}
161
+ return value
162
+
163
+
164
+ def laid(template: dict | None, value: dict) -> dict:
165
+ """``value`` laid over a copy of ``template``: objects merge key by key, the rest is ``value``'s."""
166
+ out = copy.deepcopy(template) if template else {}
167
+ for key, item in value.items():
168
+ out[key] = laid(out[key], item) if isinstance(out.get(key), dict) and isinstance(item, dict) else item
169
+ 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
@@ -27,7 +27,9 @@ from dataclasses import dataclass, field
27
27
  from pathlib import Path
28
28
  from typing import Any, Protocol
29
29
 
30
+ from ..score import Score
30
31
  from ..world_session_contract import NO_GRADER_REASON
32
+ from .primary_key import PrimaryKey
31
33
  from .tasks import GraderError, evaluate_assertions
32
34
 
33
35
  GRADER_KINDS = ("assertions", "python", "rubric")
@@ -64,20 +66,47 @@ class Grade:
64
66
 
65
67
  @staticmethod
66
68
  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)."""
69
+ """The grade a verifier printed: one flat object, the scalar under
70
+ ``reward`` and every other key a check (a number from 0 to 1, a
71
+ boolean as the 1.0 / 0.0 it claims; a string or null is an ungraded
72
+ check, the World Host's contract for annotations). A nested object or
73
+ array is a :class:`GraderError` naming the key: read as one null check,
74
+ a nested ``rewards`` map would lose every score inside it while the
75
+ grade still answers. So is a number outside 0..1 or a non-finite one
76
+ (``json.dumps(nan)`` prints ``NaN``), by key and value: out-of-range
77
+ checks average into a perfect 1.0, and NaN is not JSON the platform
78
+ can read."""
79
+ refused = [f"{key!r} as {_kind(value)}" for key, value in printed.items() if not _is_score(value)]
80
+ if refused:
81
+ raise GraderError(
82
+ f"verify.py printed {', '.join(refused)} where a score belongs; print one flat JSON object, "
83
+ '"reward" plus one number per check, e.g. {"reward": 0.5, "card_moved": 1}'
84
+ )
85
+ out_of_range = Score.problem(printed.items())
86
+ if out_of_range is not None:
87
+ raise GraderError(f"verify.py printed {out_of_range}")
69
88
  return Grade(
70
89
  reward=_number(printed.get("reward")),
71
- rewards={
72
- key: _number(value) for key, value in printed.items() if key != "reward"
73
- },
90
+ rewards={key: _number(value) for key, value in printed.items() if key != "reward"},
74
91
  )
75
92
 
76
93
 
94
+ NOT_A_SCORE = {dict: "an object", list: "an array"}
95
+
96
+
97
+ def _is_score(value: Any) -> bool:
98
+ return not isinstance(value, (dict, list))
99
+
100
+
101
+ def _kind(value: Any) -> str:
102
+ return NOT_A_SCORE.get(type(value), type(value).__name__)
103
+
104
+
77
105
  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)):
106
+ """A finite number as a float; a boolean is the 1.0 / 0.0 it claims (the
107
+ tracing reward emitter's convention), anything else (NaN and Infinity
108
+ included) null."""
109
+ if isinstance(value, (int, float)) and Score.finite(value):
81
110
  return float(value)
82
111
  return None
83
112
 
@@ -124,9 +153,7 @@ class TaskGrader:
124
153
  ) -> None:
125
154
  kind = grader.get("kind")
126
155
  if kind not in GRADER_KINDS:
127
- raise GraderError(
128
- f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}"
129
- )
156
+ raise GraderError(f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}")
130
157
  self.grader = dict(grader)
131
158
  self.kind: str = kind
132
159
  self.verify = verify
@@ -136,9 +163,7 @@ class TaskGrader:
136
163
  self.name = name
137
164
  timeout = grader.get("timeoutSeconds")
138
165
  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
- )
166
+ self.timeout_s = own if own is not None and own > 0 else float(default_timeout_s)
142
167
 
143
168
  @property
144
169
  def anchor(self) -> str | None:
@@ -232,19 +257,13 @@ class TaskGrader:
232
257
  env=self.sandbox.environment(home),
233
258
  )
234
259
  except subprocess.TimeoutExpired:
235
- raise GraderError(
236
- f"verify.py timed out after {self.timeout_s:g}s"
237
- ) from None
260
+ raise GraderError(f"verify.py timed out after {self.timeout_s:g}s") from None
238
261
  if proc.returncode != 0:
239
- raise GraderError(
240
- f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}"
241
- )
262
+ raise GraderError(f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}")
242
263
  try:
243
264
  printed = json.loads(proc.stdout.strip().splitlines()[-1])
244
265
  except (json.JSONDecodeError, IndexError):
245
- raise GraderError(
246
- f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}"
247
- ) from None
266
+ raise GraderError(f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}") from None
248
267
  if not isinstance(printed, dict):
249
268
  raise GraderError("verify.py rewards output is not an object")
250
269
  return Grade.of_rewards(printed)
@@ -260,10 +279,8 @@ def keyed_entities(
260
279
  written against one shape of the world grades the other."""
261
280
  out: dict[str, dict[str, Any]] = {}
262
281
  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
282
+ key = PrimaryKey.of(spec)
283
+ out[entity] = {":".join(str(value) for value in key.values(row)): row for row in rows_of(entity)}
267
284
  return out
268
285
 
269
286
 
@@ -278,9 +295,7 @@ class StoredWorld(Protocol):
278
295
  def store(self) -> Any: ...
279
296
 
280
297
 
281
- def world_state(
282
- root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]
283
- ) -> dict:
298
+ def world_state(root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]) -> dict:
284
299
  """The rows as a task's grader reads them, on the host and in the batch
285
300
  runner alike: the root's entities by name and each dependency's as
286
301
  ``<alias>.<entity>``, every entity's rows keyed by primary key — the api
@@ -1,7 +1,6 @@
1
1
  """What a failing handler answers — structured, classified, never a bare string.
2
2
 
3
- A tool call that raises inside ``tools/handlers.py`` is answered like the
4
- HTTP twin of the tool would answer:
3
+ A tool or a route whose handler raises is answered the same way on every door:
5
4
 
6
5
  * ``AttributeError`` / ``TypeError`` / ``NameError`` are the author's bug
7
6
  (``store.upsert`` on a store with no ``upsert``, a misspelled name, a
@@ -9,13 +8,28 @@ HTTP twin of the tool would answer:
9
8
  * Anything else is a failure inside the handler's own logic — status **500**,
10
9
  ``error: "engine"``.
11
10
 
12
- Both carry ``detail`` (one line, bounded) and ``handler`` (the tool's local
13
- name) so the caller knows which handler to fix without reading a trace.
11
+ A route handler (or its ``[api].before`` gate) that answers without a status
12
+ from 200 to 599, with a header value HTTP cannot carry (outside latin-1), or
13
+ with a value JSON cannot carry (a ``datetime``, a set, NaN, an unpaired
14
+ surrogate) is the author's bug too, a 400; bytes go out as they are, under the
15
+ type the handler names. Every body carries ``detail`` (one line, bounded) and
16
+ ``handler`` (the function's name) so the caller knows which handler to fix
17
+ without reading a trace. A failure the host meets answering a request outside
18
+ any handler is a 500 ``engine`` without ``handler`` (:func:`request_failure_body`).
19
+ What no reply can carry (an unpaired surrogate, a NaN, an infinity) goes out as
20
+ text where the platform reads it (:func:`carried`).
14
21
  """
15
22
 
16
23
  from __future__ import annotations
17
24
 
18
- #: The exception classes that mark a handler bug rather than a runtime failure.
25
+ import json
26
+ import math
27
+ import re
28
+ import sys
29
+ from typing import Any, Callable
30
+
31
+ from .validation import ContractError, fail
32
+
19
33
  HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
20
34
  AttributeError,
21
35
  TypeError,
@@ -23,6 +37,7 @@ HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
23
37
  )
24
38
 
25
39
  _DETAIL_LIMIT = 2000
40
+ _SURROGATE = re.compile("[\ud800-\udfff]")
26
41
 
27
42
 
28
43
  def _detail(error: BaseException) -> str:
@@ -30,15 +45,130 @@ def _detail(error: BaseException) -> str:
30
45
  return text[:_DETAIL_LIMIT]
31
46
 
32
47
 
33
- def handler_bug_body(handler: str, error: BaseException) -> dict:
48
+ def handler_bug_body(handler: str, error: BaseException, about: str = "") -> dict:
34
49
  """The 400 body for a handler-authored bug."""
35
- return {"error": "handler", "detail": _detail(error), "handler": handler}
50
+ return {"error": "handler", "detail": f"{about}{_detail(error)}"[:_DETAIL_LIMIT], "handler": handler}
51
+
52
+
53
+ def log_request_failure(error: BaseException, method: str, path: str) -> None:
54
+ """One stderr line for a failure met answering a request: its class, the
55
+ method and the path's first segment only, since a later one can be a credential."""
56
+ segment = path.lstrip("/").split("/", 1)[0]
57
+ print(f"world host: {type(error).__name__} on {method} /{segment}", file=sys.stderr)
58
+
59
+
60
+ def request_failure_body(error: BaseException) -> dict:
61
+ """The 500 body for a failure met answering a request, outside any handler."""
62
+ return {"error": "engine", "detail": f"{type(error).__name__}: {_detail(error)}"[:_DETAIL_LIMIT]}
36
63
 
37
64
 
38
65
  def engine_failure_body(handler: str, error: BaseException) -> dict:
39
66
  """The 500 body for a failure inside the handler that is not a coding bug."""
40
- return {
41
- "error": "engine",
42
- "detail": f"{type(error).__name__}: {_detail(error)}"[:_DETAIL_LIMIT],
43
- "handler": handler,
44
- }
67
+ return {**request_failure_body(error), "handler": handler}
68
+
69
+
70
+ def failure_answer(handler: str, error: Exception) -> tuple[int, dict]:
71
+ """A handler's raise as its ``(status, body)``: its author's bug or the engine's failure."""
72
+ if isinstance(error, HANDLER_BUG_ERRORS):
73
+ return 400, handler_bug_body(handler, error)
74
+ return 500, engine_failure_body(handler, error)
75
+
76
+
77
+ def unencodable(body: Any) -> Exception | None:
78
+ """Why a body cannot go out as JSON, or None when it can (bytes go out as they are)."""
79
+ if isinstance(body, bytes):
80
+ return None
81
+ try:
82
+ json.dumps(body, ensure_ascii=False, allow_nan=False).encode("utf-8")
83
+ except (TypeError, ValueError, RecursionError) as error:
84
+ return error
85
+ return None
86
+
87
+
88
+ def _unsendable_header(headers: dict[str, str] | None) -> Exception | None:
89
+ try:
90
+ for name, value in (headers or {}).items():
91
+ f"{name}: {value}".encode("latin-1")
92
+ except UnicodeEncodeError as error:
93
+ return error
94
+ return None
95
+
96
+
97
+ def unencodable_answer(handler: str, response: tuple) -> tuple[int, dict] | None:
98
+ """The 400 for a handler answer the wire cannot carry, or None when it can."""
99
+ status, body, headers = response
100
+ if isinstance(status, bool) or not isinstance(status, int) or not 200 <= status <= 599:
101
+ return 400, handler_bug_body(handler, ValueError(f"an answer names a status from 200 to 599, not {status!r}"))
102
+ header = _unsendable_header(headers)
103
+ if header is not None:
104
+ return 400, handler_bug_body(handler, header, "a header is not latin-1: ")
105
+ error = unencodable(body)
106
+ return None if error is None else (400, handler_bug_body(handler, error, "the answer is not JSON: "))
107
+
108
+
109
+ def carried_scalar(value: Any) -> Any:
110
+ """A scalar as a JSON reply can carry it: an unpaired surrogate as U+FFFD,
111
+ a NaN or an infinity as ``"NaN"``, ``"Infinity"`` or ``"-Infinity"``."""
112
+ if isinstance(value, str):
113
+ return _SURROGATE.sub("\ufffd", value)
114
+ if isinstance(value, float) and not math.isfinite(value):
115
+ return "NaN" if math.isnan(value) else ("Infinity" if value > 0 else "-Infinity")
116
+ return value
117
+
118
+
119
+ def carried(value: Any) -> Any:
120
+ """``value`` as a JSON reply can carry it (:func:`carried_scalar`, keys
121
+ included); a value too deep to walk goes out as it is."""
122
+ try:
123
+ return _carried_tree(value)
124
+ except RecursionError:
125
+ return value
126
+
127
+
128
+ def _carried_tree(value: Any) -> Any:
129
+ if isinstance(value, dict):
130
+ return {carried_scalar(str(key)): _carried_tree(item) for key, item in value.items()}
131
+ if isinstance(value, list):
132
+ return [_carried_tree(item) for item in value]
133
+ return carried_scalar(value)
134
+
135
+
136
+ def normalize_answer(result: Any, default_status: int | None) -> Any:
137
+ """What a handler (or the gate) hands back, as ``(status, body, headers)``.
138
+
139
+ A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
140
+ the gate returns ``None`` to let the request through or one of those to stop it."""
141
+ if result is None and default_status is None:
142
+ return None
143
+ if (
144
+ isinstance(result, tuple)
145
+ and len(result) in (2, 3)
146
+ and isinstance(result[0], int)
147
+ and not isinstance(result[0], bool)
148
+ ):
149
+ status, body = result[0], result[1]
150
+ extra = result[2] if len(result) == 3 else None
151
+ if extra is not None and not (
152
+ isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
153
+ ):
154
+ fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
155
+ if isinstance(body, bytes) and not any(k.lower() == "content-type" for k in extra or {}):
156
+ fail("handlers", "A handler answering bytes names the Content-Type in its headers", "/api/handlers")
157
+ return status, body, extra
158
+ return default_status, result, None
159
+
160
+
161
+ def handled_answer(name: str, handler: Callable[..., Any], request: tuple, default_status: int | None) -> Any:
162
+ """A handler's answer, or the answer for how it failed (``handler_errors``):
163
+ a raise is its 400 or 500, an answer JSON cannot carry its 400. A refusal
164
+ the contract raises (``ContractError``) is the route's to answer."""
165
+ try:
166
+ response = normalize_answer(handler(*request), default_status)
167
+ except ContractError:
168
+ raise
169
+ except Exception as error:
170
+ return (*failure_answer(name, error), None)
171
+ if response is None:
172
+ return None
173
+ refused = unencodable_answer(name, response)
174
+ return response if refused is None else (*refused, None)