@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.
- package/README.md +8 -6
- package/dist/cli.js +4372 -2265
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +4362 -2256
- 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 +259 -58
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +249 -50
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- 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 +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +2240 -789
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2150 -739
- 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 +253 -52
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +243 -44
- 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 +75 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +75 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +893 -482
- package/dist/worlds/index.d.ts +893 -482
- package/dist/worlds/index.js +1968 -669
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1960 -662
- 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 +48 -88
- package/runtime/gatewaysdk/environment/_world.py +155 -237
- package/runtime/gatewaysdk/environment/backing.py +133 -0
- package/runtime/gatewaysdk/environment/core.py +2 -17
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -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/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +347 -892
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
- package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +60 -216
- 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 +936 -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 +215 -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/reads.py +169 -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 +393 -0
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
- package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +58 -170
- 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 +137 -187
- 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/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -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 +516 -140
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
- package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
- 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 +235 -41
- package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
- package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +43 -4
- package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +10 -11
- package/skills/connector-schema-authoring/SKILL.md +49 -16
- package/skills/connector-schema-authoring/connector-worlds.md +142 -11
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +39 -9
- package/skills/world-data-ingestion/SKILL.md +27 -27
- package/skills/worlds-getting-started/SKILL.md +33 -33
- package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
- package/skills/worlds-getting-started/references/gotchas.md +49 -1
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- 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
|
|
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
|
|
@@ -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 .
|
|
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
|
-
"""
|
|
40
|
-
|
|
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
|
-
"""
|
|
68
|
-
|
|
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
|
|
79
|
-
|
|
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
|
-
"""
|
|
87
|
-
|
|
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
|
|
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 =
|
|
212
|
-
|
|
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
|
-
"""
|
|
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
|
-
|
|
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():
|