@withgateway/sdk 0.2.6 → 0.2.9
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 +24 -8
- package/dist/cli.js +15468 -11263
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +15233 -11028
- 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 +291 -40
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +284 -37
- 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 +203 -47
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +198 -42
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
- package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
- package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
- package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2149 -615
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2053 -566
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +268 -31
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +262 -28
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +19 -11
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +19 -11
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +886 -117
- package/dist/worlds/index.d.ts +886 -117
- package/dist/worlds/index.js +1770 -452
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1752 -434
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +14 -10
- package/runtime/gatewaysdk/environment/_toml.py +3 -10
- package/runtime/gatewaysdk/environment/_world.py +95 -28
- package/runtime/gatewaysdk/environment/runtime.py +10 -6
- package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/api.py +19 -23
- package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
- package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
- package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
- package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
- package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
- package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
- package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
- package/runtime/gatewaysdk/environment/schema/host.py +68 -115
- package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
- package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
- package/runtime/gatewaysdk/environment/schema/local.py +7 -10
- package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
- package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
- package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
- package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
- package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
- package/runtime/gatewaysdk/environment/schema/store.py +15 -6
- package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
- package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
- package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
- package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
- package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
- package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
- package/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/skills/connector-schema-authoring/SKILL.md +54 -4
- package/skills/connector-schema-authoring/connector-worlds.md +21 -7
- package/skills/connector-schema-authoring/world-schema.md +144 -83
- package/skills/hooks-getting-started/SKILL.md +27 -2
- package/skills/world-data-ingestion/ROWS.md +62 -0
- package/skills/world-data-ingestion/SKILL.md +91 -54
- package/skills/worlds-getting-started/SKILL.md +146 -146
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/skills/worlds-getting-started/references/openapi-import.md +90 -0
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""Delimited rows files (``.csv``, ``.tsv``, gzipped or not), streamed one record at a time.
|
|
2
|
+
|
|
3
|
+
The header row names the fields; each later record is numbered from 2 as ``where``
|
|
4
|
+
pointers count (``file:2`` is the first data row), a blank line skipped, a record
|
|
5
|
+
wider than the header refused. A quoted cell may span physical lines; the file is
|
|
6
|
+
never read whole. Cells are text (an empty cell ``None``) until a :class:`.cast.RowCaster`
|
|
7
|
+
types them by the entity's schema. The TypeScript twin is ``worldData/csv.ts``.
|
|
8
|
+
|
|
9
|
+
Standard library only, so the bridge and the api bundle can load it.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import csv
|
|
15
|
+
import io
|
|
16
|
+
from collections.abc import Iterator
|
|
17
|
+
from typing import IO
|
|
18
|
+
|
|
19
|
+
from .validation import fail
|
|
20
|
+
|
|
21
|
+
DELIMITER_HELP = "Cell separator for .csv/.tsv inputs: one character, \\t for a tab. Default , (tab for a .tsv)."
|
|
22
|
+
BAD_DELIMITER = "--delimiter is one character (\\t for a tab), not a quote or a newline"
|
|
23
|
+
#: A quoted cell longer than this is refused rather than held (the stdlib default is 128 KiB).
|
|
24
|
+
FIELD_CAP = 16 * 1024 * 1024
|
|
25
|
+
|
|
26
|
+
Record = dict[str, "str | None"]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def is_csv_name(name: str) -> bool:
|
|
30
|
+
"""A CSV by name (``.csv``, ``.csv.gz``): the one rows shape decided by name, not by its first byte."""
|
|
31
|
+
lowered = name.lower()
|
|
32
|
+
return lowered.endswith((".csv", ".csv.gz"))
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def is_tsv_name(name: str) -> bool:
|
|
36
|
+
lowered = name.lower()
|
|
37
|
+
return lowered.endswith((".tsv", ".tsv.gz"))
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def is_delimited_name(name: str) -> bool:
|
|
41
|
+
return is_csv_name(name) or is_tsv_name(name)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def parse_delimiter(text: str) -> str:
|
|
45
|
+
"""``--delimiter`` as given: one character, ``\\t`` spelled out for a tab."""
|
|
46
|
+
value = "\t" if text == "\\t" else text
|
|
47
|
+
if len(value) != 1 or value in ('"', "\n", "\r"):
|
|
48
|
+
fail("rows", BAD_DELIMITER, "/delimiter")
|
|
49
|
+
return value
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def csv_delimiter(name: str, explicit: str | None = None) -> str:
|
|
53
|
+
"""The separator a delimited file uses: ``--delimiter`` when given, else tab for a ``.tsv``, else a comma."""
|
|
54
|
+
if explicit is None:
|
|
55
|
+
return "\t" if is_tsv_name(name) else ","
|
|
56
|
+
return parse_delimiter(explicit)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class _Dialect(csv.Dialect):
|
|
60
|
+
quotechar = '"'
|
|
61
|
+
doublequote = True
|
|
62
|
+
skipinitialspace = False
|
|
63
|
+
lineterminator = "\n"
|
|
64
|
+
quoting = csv.QUOTE_MINIMAL
|
|
65
|
+
#: A quote never closed or text after a closing quote is a refusal, as in the TypeScript twin.
|
|
66
|
+
strict = True
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def iter_csv_records(stream: IO[str], where: str, delimiter: str) -> Iterator[tuple[int, Record]]:
|
|
70
|
+
"""``(number, record)`` per data row of a delimited text stream, header first, never whole.
|
|
71
|
+
``stream`` is opened with ``newline=""`` so the reader sees every line ending itself."""
|
|
72
|
+
dialect = type("Dialect", (_Dialect,), {"delimiter": delimiter})
|
|
73
|
+
if csv.field_size_limit() < FIELD_CAP:
|
|
74
|
+
csv.field_size_limit(FIELD_CAP)
|
|
75
|
+
reader = csv.reader(stream, dialect=dialect)
|
|
76
|
+
try:
|
|
77
|
+
header = next(reader, None)
|
|
78
|
+
if header is None:
|
|
79
|
+
return
|
|
80
|
+
if not header or any(not name.strip() for name in header):
|
|
81
|
+
fail("rows", f"{where}: the first row must name every column", where)
|
|
82
|
+
for number, cells in enumerate(reader, 2):
|
|
83
|
+
if not cells or cells == [""]:
|
|
84
|
+
continue
|
|
85
|
+
if len(cells) > len(header):
|
|
86
|
+
fail(
|
|
87
|
+
"rows",
|
|
88
|
+
f"{where}:{number} has more cells than the header names",
|
|
89
|
+
where,
|
|
90
|
+
)
|
|
91
|
+
cells.extend([""] * (len(header) - len(cells)))
|
|
92
|
+
yield (
|
|
93
|
+
number,
|
|
94
|
+
{name: (cell if cell != "" else None) for name, cell in zip(header, cells)},
|
|
95
|
+
)
|
|
96
|
+
except csv.Error as error:
|
|
97
|
+
fail("rows", f"{where}: not a readable delimited file ({error})", where)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def read_csv(text: str, where: str, delimiter: str = ",") -> list[Record]:
|
|
101
|
+
"""A whole text as records — for the readers that hold a file whole anyway (a sample, a mapping preview)."""
|
|
102
|
+
stripped = text.removeprefix("\ufeff")
|
|
103
|
+
return [record for _, record in iter_csv_records(io.StringIO(stripped, newline=""), where, delimiter)]
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
__all__ = [
|
|
107
|
+
"BAD_DELIMITER",
|
|
108
|
+
"DELIMITER_HELP",
|
|
109
|
+
"Record",
|
|
110
|
+
"csv_delimiter",
|
|
111
|
+
"is_csv_name",
|
|
112
|
+
"is_delimited_name",
|
|
113
|
+
"is_tsv_name",
|
|
114
|
+
"iter_csv_records",
|
|
115
|
+
"parse_delimiter",
|
|
116
|
+
"read_csv",
|
|
117
|
+
]
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""Reference cycles in a world's schema (zero-context round 2, W4).
|
|
2
|
+
|
|
3
|
+
``NodeA -> NodeB -> NodeA`` used to compile silently. The resolver projects a
|
|
4
|
+
reference met again to its bare type, so a value below the first level is
|
|
5
|
+
stored as JSON and checked as "an object", not against the shape the author
|
|
6
|
+
wrote. Three cases, decided here:
|
|
7
|
+
|
|
8
|
+
* a cycle with an untyped hop (``{"$ref": ...}`` and nothing else on the way
|
|
9
|
+
round, so no type can be projected): refused by the resolver itself, before
|
|
10
|
+
this module runs, as ``recursive_reference``.
|
|
11
|
+
* a typed cycle an entity reaches — its own root nesting itself (Brex's
|
|
12
|
+
``Expense.parent``), or a definition below it (Jira's ``LinkGroup``): a
|
|
13
|
+
warning naming the entity and the cycle. The row compiles; the nested copy is
|
|
14
|
+
stored as JSON and checked as its bare type, the resolver's documented
|
|
15
|
+
typed-recursion contract. A model that means entity recursion is better told
|
|
16
|
+
as a relationship (``parent_id`` targeting the same entity, as the custom
|
|
17
|
+
template's records do), and the warning says so.
|
|
18
|
+
* a cycle among ``$defs`` no entity reaches: a warning; no row is affected.
|
|
19
|
+
|
|
20
|
+
:class:`ReferenceCycles` finds every cycle in linear time: only ``$ref``
|
|
21
|
+
targets go on the stack, a target proven acyclic is never walked twice, and a
|
|
22
|
+
cycle is reported once however many entities reach it.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
from typing import Any
|
|
28
|
+
|
|
29
|
+
from .validation import Resolver
|
|
30
|
+
|
|
31
|
+
CODE = "recursive_reference"
|
|
32
|
+
_BRANCHES = ("allOf", "anyOf", "oneOf")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class ReferenceCycles:
|
|
36
|
+
def __init__(self, resolver: Resolver):
|
|
37
|
+
self.resolver = resolver
|
|
38
|
+
self.acyclic: set[str] = set()
|
|
39
|
+
self.reported: set[str] = set()
|
|
40
|
+
|
|
41
|
+
def through(self, schema: Any, name: str) -> list[list[str]]:
|
|
42
|
+
"""The cycles one depth-first walk from ``schema`` closes: each is the
|
|
43
|
+
reference targets on the stack from the repeated one, which ends it. Every
|
|
44
|
+
target reachable from ``schema`` is walked once, so a cycle back to the
|
|
45
|
+
root target is always among them."""
|
|
46
|
+
found: list[list[str]] = []
|
|
47
|
+
self._walk(schema, name, (), set(), found)
|
|
48
|
+
return found
|
|
49
|
+
|
|
50
|
+
def reached(self, entity: str, schema: Any, location: str) -> list[dict]:
|
|
51
|
+
"""One warning per cycle the entity's root reaches, the first entity to reach it."""
|
|
52
|
+
return [
|
|
53
|
+
self._warning(
|
|
54
|
+
cycle,
|
|
55
|
+
f"Entity {entity} reaches a $ref cycle ({_spell(cycle)}); below the first level rows store that "
|
|
56
|
+
"value as JSON checked only as its bare type. If it models entity recursion, make it a relationship "
|
|
57
|
+
"(a parent_id field targeting the entity), not a nested object",
|
|
58
|
+
location,
|
|
59
|
+
entity=entity,
|
|
60
|
+
)
|
|
61
|
+
for cycle in self.through(schema, "world.json")
|
|
62
|
+
if self._fresh(cycle)
|
|
63
|
+
]
|
|
64
|
+
|
|
65
|
+
def unreached(self, defs: dict, name: str) -> list[dict]:
|
|
66
|
+
"""One warning per ``$defs`` cycle no entity reached (entities were walked first)."""
|
|
67
|
+
return [
|
|
68
|
+
self._warning(
|
|
69
|
+
cycle,
|
|
70
|
+
f"$defs/{key} reaches itself through $ref ({_spell(cycle)}); no entity uses it, so no row is "
|
|
71
|
+
"affected — a definition meant for an entity must not nest itself",
|
|
72
|
+
f"{name}#/$defs/{key}",
|
|
73
|
+
)
|
|
74
|
+
for key in defs
|
|
75
|
+
for cycle in self.through({"$ref": f"#/$defs/{key}"}, name)
|
|
76
|
+
if self._fresh(cycle)
|
|
77
|
+
]
|
|
78
|
+
|
|
79
|
+
def _fresh(self, cycle: list[str]) -> bool:
|
|
80
|
+
if self.reported & set(cycle):
|
|
81
|
+
return False
|
|
82
|
+
self.reported.update(cycle)
|
|
83
|
+
return True
|
|
84
|
+
|
|
85
|
+
def _warning(self, cycle: list[str], message: str, location: str, **context: Any) -> dict:
|
|
86
|
+
return {"code": CODE, "message": message, "schema_path": location, "cycle": cycle, **context}
|
|
87
|
+
|
|
88
|
+
def _walk(self, schema: Any, name: str, stack: tuple[str, ...], done: set[str], found: list[list[str]]) -> None:
|
|
89
|
+
if type(schema) is not dict:
|
|
90
|
+
return
|
|
91
|
+
if "$ref" in schema:
|
|
92
|
+
self._follow(schema["$ref"], name, stack, done, found)
|
|
93
|
+
for child in _children(schema):
|
|
94
|
+
self._walk(child, name, stack, done, found)
|
|
95
|
+
|
|
96
|
+
def _follow(self, ref: str, name: str, stack: tuple[str, ...], done: set[str], found: list[list[str]]) -> None:
|
|
97
|
+
target, target_name, target_location = self.resolver.reference(ref, name, "")
|
|
98
|
+
if target_location in stack:
|
|
99
|
+
found.append([*stack[stack.index(target_location) :], target_location])
|
|
100
|
+
return
|
|
101
|
+
if target_location in self.acyclic or target_location in done:
|
|
102
|
+
return
|
|
103
|
+
before = len(found)
|
|
104
|
+
self._walk(target, target_name, (*stack, target_location), done, found)
|
|
105
|
+
done.add(target_location)
|
|
106
|
+
if len(found) == before:
|
|
107
|
+
self.acyclic.add(target_location)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def _spell(cycle: list[str]) -> str:
|
|
111
|
+
return " -> ".join(location.rsplit("/", 1)[-1] for location in cycle)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _children(schema: dict) -> list[Any]:
|
|
115
|
+
properties = schema.get("properties")
|
|
116
|
+
children: list[Any] = list(properties.values()) if isinstance(properties, dict) else []
|
|
117
|
+
children.extend(schema[key] for key in ("items", "additionalProperties") if isinstance(schema.get(key), dict))
|
|
118
|
+
for key in _BRANCHES:
|
|
119
|
+
branches = schema.get(key)
|
|
120
|
+
children.extend(branches if isinstance(branches, list) else [])
|
|
121
|
+
return children
|
|
@@ -36,9 +36,11 @@ from pathlib import Path
|
|
|
36
36
|
from typing import Any, Iterable, Iterator
|
|
37
37
|
|
|
38
38
|
from ..world import KIND_API, KIND_HARBOR, KIND_MOCK_TOOLS, SCHEMA_MANIFEST_KIND, World
|
|
39
|
+
from .cast import EntityCasters
|
|
39
40
|
from .compiler import bundle_mode, check_bundle, compile_bundle
|
|
40
41
|
from .proof import SCRATCH_IGNORE, RowProof
|
|
41
42
|
from .store import SQLiteStore
|
|
43
|
+
from .tree_import import refuse_unpublishable_journal
|
|
42
44
|
from .validation import ContractError, digest, encoded, fail, journal_paths, read_json, validate
|
|
43
45
|
|
|
44
46
|
MODES = ("append", "replace")
|
|
@@ -59,20 +61,33 @@ Rows = dict[str, list[dict]]
|
|
|
59
61
|
# ---------------------------------------------------------------- rows files
|
|
60
62
|
|
|
61
63
|
|
|
62
|
-
def parse_rows(
|
|
64
|
+
def parse_rows(
|
|
65
|
+
paths: Iterable[str | Path],
|
|
66
|
+
*,
|
|
67
|
+
entity: str | None = None,
|
|
68
|
+
delimiter: str | None = None,
|
|
69
|
+
casters: EntityCasters | None = None,
|
|
70
|
+
) -> Rows:
|
|
63
71
|
"""Read rows from files into ``{entity: [row, …]}``.
|
|
64
72
|
|
|
65
73
|
Each file is one of: a JSON object ``{"<entity>": [row, …]}``; JSONL where
|
|
66
74
|
every line is ``{"entity": "<name>", "row": {…}}``; or — only with
|
|
67
|
-
``entity`` — a JSON array or JSONL of bare rows
|
|
68
|
-
|
|
69
|
-
files
|
|
75
|
+
``entity`` — a JSON array or JSONL of bare rows, or a ``.csv``/``.tsv`` whose
|
|
76
|
+
cells ``casters`` type by the entity's fields (:mod:`.cast`; text without them).
|
|
77
|
+
Several files merge in order. A file that fits none of these is refused, naming
|
|
78
|
+
the file. The files are streamed (:func:`batch.iter_rows`); this holds the result.
|
|
70
79
|
"""
|
|
71
80
|
from .batch import iter_rows
|
|
72
81
|
|
|
73
82
|
rows: Rows = {}
|
|
74
83
|
seen: dict[str, int] = {}
|
|
75
|
-
for name, row in iter_rows(
|
|
84
|
+
for name, row in iter_rows(
|
|
85
|
+
[str(path) for path in paths],
|
|
86
|
+
entity=entity,
|
|
87
|
+
seen=seen,
|
|
88
|
+
delimiter=delimiter,
|
|
89
|
+
casters=casters,
|
|
90
|
+
):
|
|
76
91
|
rows.setdefault(name, []).append(row)
|
|
77
92
|
for name in seen:
|
|
78
93
|
rows.setdefault(name, []) # an entity named with no rows: a replace empties it
|
|
@@ -299,6 +314,7 @@ def _import_schema(root: Path, rows: Rows, mode: str, batch_id: str | None) -> d
|
|
|
299
314
|
}
|
|
300
315
|
written = Path("data/initial.json")
|
|
301
316
|
payload = (json.dumps(batch, sort_keys=True, indent=1) + "\n").encode("utf-8")
|
|
317
|
+
refuse_unpublishable_journal(root, written, payload)
|
|
302
318
|
from .snapshot import build_default, default_snapshot, sidecar_path
|
|
303
319
|
|
|
304
320
|
with tempfile.TemporaryDirectory(prefix="gateway-import-") as scratch:
|
|
@@ -27,6 +27,7 @@ from dataclasses import dataclass, field
|
|
|
27
27
|
from pathlib import Path
|
|
28
28
|
from typing import Any, Protocol
|
|
29
29
|
|
|
30
|
+
from ..world_session_contract import NO_GRADER_REASON
|
|
30
31
|
from .tasks import evaluate_assertions
|
|
31
32
|
|
|
32
33
|
GRADER_KINDS = ("assertions", "python", "rubric")
|
|
@@ -41,12 +42,14 @@ class GraderError(Exception):
|
|
|
41
42
|
class Grade:
|
|
42
43
|
"""A task's grade: the scalar ``reward`` (None when ungraded) and every
|
|
43
44
|
named dimension under ``rewards`` (nulls kept). ``pending`` is a grade the
|
|
44
|
-
platform still owes (a rubric)
|
|
45
|
+
platform still owes (a rubric); ``reason`` says why a grade is null when
|
|
46
|
+
no grader ran at all (an exploratory session, a task without one)."""
|
|
45
47
|
|
|
46
48
|
reward: float | None
|
|
47
49
|
rewards: dict[str, float | None] = field(default_factory=dict)
|
|
48
50
|
pending: bool = False
|
|
49
51
|
grader: str | None = None
|
|
52
|
+
reason: str | None = None
|
|
50
53
|
|
|
51
54
|
def as_dict(self) -> dict[str, Any]:
|
|
52
55
|
"""The wire shape ``grade`` answers with (and ``verify.py`` prints)."""
|
|
@@ -54,19 +57,30 @@ class Grade:
|
|
|
54
57
|
if self.pending:
|
|
55
58
|
out["pending"] = True
|
|
56
59
|
out["grader"] = self.grader
|
|
60
|
+
if self.reason is not None:
|
|
61
|
+
out["reason"] = self.reason
|
|
57
62
|
return out
|
|
58
63
|
|
|
59
64
|
@staticmethod
|
|
60
|
-
def
|
|
65
|
+
def ungraded() -> Grade:
|
|
66
|
+
"""The grade of a session with no grader: null, and it says so."""
|
|
67
|
+
return Grade(None, reason=NO_GRADER_REASON)
|
|
68
|
+
|
|
69
|
+
@staticmethod
|
|
70
|
+
def of_rewards(printed: Mapping[str, Any]) -> Grade:
|
|
61
71
|
"""The grade a verifier printed: the scalar under ``reward``, every
|
|
62
72
|
other key a dimension (non-numeric ones null)."""
|
|
63
73
|
return Grade(
|
|
64
74
|
reward=_number(printed.get("reward")),
|
|
65
|
-
rewards={
|
|
75
|
+
rewards={
|
|
76
|
+
key: _number(value) for key, value in printed.items() if key != "reward"
|
|
77
|
+
},
|
|
66
78
|
)
|
|
67
79
|
|
|
68
80
|
|
|
69
81
|
def _number(value: Any) -> float | None:
|
|
82
|
+
"""A score is a number; a boolean is the 1.0 / 0.0 it claims (the tracing
|
|
83
|
+
reward emitter's convention), anything else null."""
|
|
70
84
|
if isinstance(value, (int, float)):
|
|
71
85
|
return float(value)
|
|
72
86
|
return None
|
|
@@ -91,7 +105,15 @@ class TaskGrader:
|
|
|
91
105
|
``grader`` is the spec's normalised ``grader`` table. A python grader's
|
|
92
106
|
source must already be on disk at ``verify`` (the session's or the run's
|
|
93
107
|
``<task>/checks/verify.py``); a bundled scenario's ``verify.py`` is graded
|
|
94
|
-
as a python grader with no table of its own.
|
|
108
|
+
as a python grader with no table of its own.
|
|
109
|
+
|
|
110
|
+
A grader with a ``scope`` is a CROSS-WORLD VERIFIER: the same table, read
|
|
111
|
+
over several of a multi-world task's worlds at once. ``scope`` names the
|
|
112
|
+
aliases (the first is the session it runs on); :meth:`evidence` builds
|
|
113
|
+
the dump it grades, every scoped world's rows as ``<alias>.<entity>`` and
|
|
114
|
+
its calls as ``<alias>.calls`` — the naming a world's dependencies use, so
|
|
115
|
+
a check or a ``verify.py`` reads it unchanged. An unscoped grader's
|
|
116
|
+
evidence is the session's own state, untouched."""
|
|
95
117
|
|
|
96
118
|
def __init__(
|
|
97
119
|
self,
|
|
@@ -101,18 +123,63 @@ class TaskGrader:
|
|
|
101
123
|
sandbox: VerifierSandbox | None = None,
|
|
102
124
|
home: Path | None = None,
|
|
103
125
|
default_timeout_s: float = VERIFY_TIMEOUT_S,
|
|
126
|
+
scope: Iterable[str] = (),
|
|
127
|
+
name: str | None = None,
|
|
104
128
|
) -> None:
|
|
105
129
|
kind = grader.get("kind")
|
|
106
130
|
if kind not in GRADER_KINDS:
|
|
107
|
-
raise GraderError(
|
|
131
|
+
raise GraderError(
|
|
132
|
+
f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}"
|
|
133
|
+
)
|
|
108
134
|
self.grader = dict(grader)
|
|
109
135
|
self.kind: str = kind
|
|
110
136
|
self.verify = verify
|
|
111
137
|
self.sandbox = sandbox or VerifierSandbox()
|
|
112
138
|
self.home = home
|
|
139
|
+
self.scope: tuple[str, ...] = tuple(scope)
|
|
140
|
+
self.name = name
|
|
113
141
|
timeout = grader.get("timeoutSeconds")
|
|
114
142
|
own = None if isinstance(timeout, bool) else _number(timeout)
|
|
115
|
-
self.timeout_s =
|
|
143
|
+
self.timeout_s = (
|
|
144
|
+
own if own is not None and own > 0 else float(default_timeout_s)
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
@property
|
|
148
|
+
def anchor(self) -> str | None:
|
|
149
|
+
"""The alias whose session runs a scoped grader; None when unscoped."""
|
|
150
|
+
return self.scope[0] if self.scope else None
|
|
151
|
+
|
|
152
|
+
def evidence(self, own: Mapping[str, Any], context: Mapping[str, Mapping[str, Any]]) -> dict:
|
|
153
|
+
"""The dump this grader reads. Unscoped: ``own`` as it is. Scoped:
|
|
154
|
+
every scoped world's state under ``<alias>.<key>`` — the anchor's from
|
|
155
|
+
``own``, the others from ``context`` (``{alias: state}``, what the
|
|
156
|
+
platform gathered from those sessions) — with the agent's ``report``
|
|
157
|
+
kept at the top. A scoped alias ``context`` lacks, or a check over an
|
|
158
|
+
entity no scoped world holds, is a :class:`GraderError`: ungraded with
|
|
159
|
+
the reason, never zero."""
|
|
160
|
+
if not self.scope:
|
|
161
|
+
return dict(own)
|
|
162
|
+
missing = [alias for alias in self.scope[1:] if alias not in context]
|
|
163
|
+
if missing:
|
|
164
|
+
raise GraderError(
|
|
165
|
+
f"no evidence for {', '.join(missing)}: not named on the grade (worlds: {{alias: sessionId}}), "
|
|
166
|
+
"or no longer a live session of this task"
|
|
167
|
+
)
|
|
168
|
+
states = {self.anchor: own, **{alias: context[alias] for alias in self.scope[1:]}}
|
|
169
|
+
dump: dict[str, Any] = {}
|
|
170
|
+
for alias in self.scope:
|
|
171
|
+
dump.update({f"{alias}.{key}": value for key, value in states[alias].items() if key != "report"})
|
|
172
|
+
if "report" in own:
|
|
173
|
+
dump["report"] = own["report"]
|
|
174
|
+
# No world's contract vets a cross-world check's entity (a session knows
|
|
175
|
+
# only its own), and a check over a key the dump lacks selects nothing —
|
|
176
|
+
# which `absent` and `count: eq 0` would pass on a typo.
|
|
177
|
+
unknown = [check["entity"] for check in self.grader.get("checks", ()) if check["entity"] not in dump]
|
|
178
|
+
if unknown:
|
|
179
|
+
raise GraderError(
|
|
180
|
+
f"no scoped world's evidence holds {', '.join(unknown)}; the evidence holds {', '.join(sorted(dump))}"
|
|
181
|
+
)
|
|
182
|
+
return dump
|
|
116
183
|
|
|
117
184
|
@staticmethod
|
|
118
185
|
def for_verifier(
|
|
@@ -121,9 +188,15 @@ class TaskGrader:
|
|
|
121
188
|
sandbox: VerifierSandbox | None = None,
|
|
122
189
|
home: Path | None = None,
|
|
123
190
|
timeout_s: float = VERIFY_TIMEOUT_S,
|
|
124
|
-
) ->
|
|
191
|
+
) -> TaskGrader:
|
|
125
192
|
"""A bundled scenario's ``verify.py``: a python grader with the host's timeout."""
|
|
126
|
-
return TaskGrader(
|
|
193
|
+
return TaskGrader(
|
|
194
|
+
{"kind": "python"},
|
|
195
|
+
verify=verify,
|
|
196
|
+
sandbox=sandbox,
|
|
197
|
+
home=home,
|
|
198
|
+
default_timeout_s=timeout_s,
|
|
199
|
+
)
|
|
127
200
|
|
|
128
201
|
@property
|
|
129
202
|
def pending(self) -> bool:
|
|
@@ -163,20 +236,27 @@ class TaskGrader:
|
|
|
163
236
|
env=self.sandbox.environment(home),
|
|
164
237
|
)
|
|
165
238
|
except subprocess.TimeoutExpired:
|
|
166
|
-
raise GraderError(
|
|
239
|
+
raise GraderError(
|
|
240
|
+
f"verify.py timed out after {self.timeout_s:g}s"
|
|
241
|
+
) from None
|
|
167
242
|
if proc.returncode != 0:
|
|
168
|
-
raise GraderError(
|
|
243
|
+
raise GraderError(
|
|
244
|
+
f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}"
|
|
245
|
+
)
|
|
169
246
|
try:
|
|
170
247
|
printed = json.loads(proc.stdout.strip().splitlines()[-1])
|
|
171
248
|
except (json.JSONDecodeError, IndexError):
|
|
172
|
-
raise GraderError(
|
|
249
|
+
raise GraderError(
|
|
250
|
+
f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}"
|
|
251
|
+
) from None
|
|
173
252
|
if not isinstance(printed, dict):
|
|
174
253
|
raise GraderError("verify.py rewards output is not an object")
|
|
175
254
|
return Grade.of_rewards(printed)
|
|
176
255
|
|
|
177
256
|
|
|
178
257
|
def keyed_entities(
|
|
179
|
-
entities: Mapping[str, Mapping[str, Any]],
|
|
258
|
+
entities: Mapping[str, Mapping[str, Any]],
|
|
259
|
+
rows_of: Callable[[str], Iterable[Mapping[str, Any]]],
|
|
180
260
|
) -> dict:
|
|
181
261
|
"""A world's rows the way a grader reads them: every contract entity by
|
|
182
262
|
name, its rows keyed by their primary key (``a:b`` for a composite key) —
|
|
@@ -202,7 +282,9 @@ class StoredWorld(Protocol):
|
|
|
202
282
|
def store(self) -> Any: ...
|
|
203
283
|
|
|
204
284
|
|
|
205
|
-
def world_state(
|
|
285
|
+
def world_state(
|
|
286
|
+
root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]
|
|
287
|
+
) -> dict:
|
|
206
288
|
"""The rows as a task's grader reads them, on the host and in the batch
|
|
207
289
|
runner alike: the root's entities by name and each dependency's as
|
|
208
290
|
``<alias>.<entity>``, every entity's rows keyed by primary key — the api
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""What a failing handler answers — structured, classified, never a bare string.
|
|
2
|
+
|
|
3
|
+
A tool call that raises inside ``tools/handlers.py`` is answered like the
|
|
4
|
+
HTTP twin of the tool would answer:
|
|
5
|
+
|
|
6
|
+
* ``AttributeError`` / ``TypeError`` / ``NameError`` are the author's bug
|
|
7
|
+
(``store.upsert`` on a store with no ``upsert``, a misspelled name, a
|
|
8
|
+
wrong argument shape) — status **400**, ``error: "handler"``.
|
|
9
|
+
* Anything else is a failure inside the handler's own logic — status **500**,
|
|
10
|
+
``error: "engine"``.
|
|
11
|
+
|
|
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.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
#: The exception classes that mark a handler bug rather than a runtime failure.
|
|
19
|
+
HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
|
|
20
|
+
AttributeError,
|
|
21
|
+
TypeError,
|
|
22
|
+
NameError,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
_DETAIL_LIMIT = 2000
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _detail(error: BaseException) -> str:
|
|
29
|
+
text = str(error).strip() or type(error).__name__
|
|
30
|
+
return text[:_DETAIL_LIMIT]
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def handler_bug_body(handler: str, error: BaseException) -> dict:
|
|
34
|
+
"""The 400 body for a handler-authored bug."""
|
|
35
|
+
return {"error": "handler", "detail": _detail(error), "handler": handler}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def engine_failure_body(handler: str, error: BaseException) -> dict:
|
|
39
|
+
"""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
|
+
}
|