@withgateway/sdk 0.3.1 → 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.
- package/README.md +4 -3
- package/dist/cli.js +2880 -2032
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2982 -2135
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +180 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +172 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
- package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1309 -540
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1287 -532
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +177 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +169 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +69 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +69 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +249 -120
- package/dist/worlds/index.d.ts +249 -120
- package/dist/worlds/index.js +1240 -484
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1231 -476
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -514
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +19 -11
- package/skills/connector-schema-authoring/connector-worlds.md +13 -4
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +14 -14
- package/skills/worlds-getting-started/SKILL.md +12 -12
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- 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
|
|
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
|
-
|
|
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
|
|
229
|
+
if primary.missing(row) is not None:
|
|
237
230
|
continue
|
|
238
|
-
key = json.dumps(
|
|
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
|
|
68
|
-
other key a
|
|
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
|
|
79
|
-
reward emitter's convention), anything else
|
|
80
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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)
|