@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
|
@@ -47,9 +47,9 @@ from dataclasses import dataclass, field
|
|
|
47
47
|
from pathlib import Path
|
|
48
48
|
from typing import Any
|
|
49
49
|
|
|
50
|
-
from .._toml import tomllib
|
|
51
50
|
from .. import _bundle
|
|
52
51
|
from .._materialize import materialize_template
|
|
52
|
+
from .._toml import tomllib
|
|
53
53
|
from .._world import World
|
|
54
54
|
from ..errors import WorldStartError
|
|
55
55
|
from ..world import World as WorldDetector
|
|
@@ -60,7 +60,8 @@ from .compiler import ContractError, bundle_mode, check_bundle, fail
|
|
|
60
60
|
from .connector import SPEC, Spec, load_spec
|
|
61
61
|
from .data import seed_batch
|
|
62
62
|
from .dependencies import Dependency, parse_dependencies
|
|
63
|
-
from .grading import world_state
|
|
63
|
+
from .grading import Grade, world_state
|
|
64
|
+
from .handler_errors import HANDLER_BUG_ERRORS, engine_failure_body, handler_bug_body
|
|
64
65
|
from .tasks import TaskSpec
|
|
65
66
|
|
|
66
67
|
Handler = Callable[..., Any]
|
|
@@ -93,10 +94,16 @@ class ToolsTask:
|
|
|
93
94
|
#: The scenario's ``checks/verify.py``, when it grades by one instead of
|
|
94
95
|
#: the world's SQL verifiers (the runtime's :class:`TaskGrader` runs it).
|
|
95
96
|
verify: Path | None = None
|
|
97
|
+
#: Whether the world's verifiers grade this task at all. A bundled task's
|
|
98
|
+
#: do (all of them when it names none); a session task's never do — it
|
|
99
|
+
#: grades by its own grader or is ungraded (the platform's ``no grader``).
|
|
100
|
+
graded_by_world: bool = True
|
|
96
101
|
|
|
97
102
|
def selected(self, all_verifiers: list[str]) -> list[str]:
|
|
98
103
|
"""The verifiers this task grades with: its own list, else the
|
|
99
104
|
primary one, else every verifier the bundle ships."""
|
|
105
|
+
if not self.graded_by_world:
|
|
106
|
+
return []
|
|
100
107
|
if self.verifiers:
|
|
101
108
|
return list(self.verifiers)
|
|
102
109
|
if self.verifier is not None:
|
|
@@ -105,6 +112,8 @@ class ToolsTask:
|
|
|
105
112
|
|
|
106
113
|
def selected_of(self, alias: str, all_verifiers: list[str]) -> list[str]:
|
|
107
114
|
"""The verifiers of dependency ``alias`` this task grades with."""
|
|
115
|
+
if not self.graded_by_world:
|
|
116
|
+
return []
|
|
108
117
|
if self.worlds is None:
|
|
109
118
|
return list(all_verifiers) if not self.verifiers and self.verifier is None else []
|
|
110
119
|
return list(self.worlds.get(alias, ()))
|
|
@@ -116,12 +125,14 @@ INLINE_TASK_ID = "session"
|
|
|
116
125
|
|
|
117
126
|
def inline_task(spec: TaskSpec) -> ToolsTask:
|
|
118
127
|
"""A session task (:mod:`tasks`) as a schema-world task: the spec's
|
|
119
|
-
instruction as the prompt.
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
applied by :class:`ToolsWorld` once the template copy exists."""
|
|
124
|
-
return ToolsTask(
|
|
128
|
+
instruction as the prompt. It grades by its own grader (assertions,
|
|
129
|
+
python, rubric) the way an api world's session task does, over
|
|
130
|
+
:meth:`ToolsWorld.grader_state`; without one it is ungraded — the
|
|
131
|
+
bundle's verifiers were written for the bundle's tasks, not this one.
|
|
132
|
+
The seed is applied by :class:`ToolsWorld` once the template copy exists."""
|
|
133
|
+
return ToolsTask(
|
|
134
|
+
id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata), graded_by_world=False
|
|
135
|
+
)
|
|
125
136
|
|
|
126
137
|
|
|
127
138
|
@dataclass
|
|
@@ -548,6 +559,11 @@ class ToolsWorld:
|
|
|
548
559
|
raise AssertionError # fail() never returns
|
|
549
560
|
|
|
550
561
|
def call(self, tool: str, args: dict) -> dict:
|
|
562
|
+
"""Run ``tool`` and answer as the handler's HTTP twin would: 200 with
|
|
563
|
+
the result, 400 when the handler itself is wrong (a name, attribute or
|
|
564
|
+
type error is the author's bug, never the engine's), 500 when anything
|
|
565
|
+
else fails inside the handler. Both failure bodies are structured
|
|
566
|
+
``{error, detail, handler}`` — never a bare exception string."""
|
|
551
567
|
world, local = self._route(tool)
|
|
552
568
|
if self.allowed is not None and tool not in self.allowed:
|
|
553
569
|
fail(
|
|
@@ -558,20 +574,26 @@ class ToolsWorld:
|
|
|
558
574
|
result = world.execute(local, args)
|
|
559
575
|
except ContractError:
|
|
560
576
|
raise
|
|
577
|
+
except HANDLER_BUG_ERRORS as error:
|
|
578
|
+
return {"status": 400, "body": handler_bug_body(local, error)}
|
|
561
579
|
except Exception as error: # noqa: BLE001 - the handler's failure is the call's answer
|
|
562
|
-
return {"status": 500, "body":
|
|
580
|
+
return {"status": 500, "body": engine_failure_body(local, error)}
|
|
563
581
|
return {"status": 200, "body": result}
|
|
564
582
|
|
|
565
583
|
def grade(self) -> dict:
|
|
566
584
|
"""The task's verifiers, the root's by name and each dependency's as
|
|
567
585
|
``<alias>/<name>``; ``reward`` is the primary verifier's score when the
|
|
568
|
-
task names one, else the mean of the numeric scores
|
|
586
|
+
task names one, else the mean of the numeric scores — null when no
|
|
587
|
+
verifier answered a number (never 0). A task no verifier grades is
|
|
588
|
+
ungraded, with the reason."""
|
|
569
589
|
rewards: dict[str, float | None] = {}
|
|
570
590
|
for name in self.task.selected(self.version.verifiers):
|
|
571
591
|
rewards[name] = self.world.verify(name).score
|
|
572
592
|
for alias, dep in self.dependencies.items():
|
|
573
593
|
for name in self.task.selected_of(alias, dep.version.verifiers):
|
|
574
594
|
rewards[f"{alias}/{name}"] = self.worlds[alias].verify(name).score
|
|
595
|
+
if not rewards:
|
|
596
|
+
return Grade.ungraded().as_dict()
|
|
575
597
|
if self.task.verifier is not None and self.task.verifier in rewards:
|
|
576
598
|
reward = rewards[self.task.verifier]
|
|
577
599
|
else:
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
"""The tree door: rows files into a world *directory*'s data files.
|
|
2
|
+
|
|
3
|
+
:class:`TreeImport` is what ``gateway worlds data import|check <dir> <files>``
|
|
4
|
+
runs, in both CLIs (the Python one directly, the TypeScript one through the
|
|
5
|
+
bundled runtime's ``import-files`` command, which hands over the *paths* — the
|
|
6
|
+
rows never travel through the bridge request). The files are streamed
|
|
7
|
+
(:func:`batch.iter_rows`), a ``.csv``/``.tsv`` is split by ``delimiter`` (or by
|
|
8
|
+
name) and its cells cast by the tree's contract (:mod:`.cast`), and the rows go
|
|
9
|
+
in through :func:`data.import_rows` — the one gate, scratch copy first.
|
|
10
|
+
|
|
11
|
+
The same typed stream cut into the gzipped JSONL chunks a platform data batch
|
|
12
|
+
takes is :meth:`TreeImport.chunks` — ``gateway worlds data chunks`` in both CLIs
|
|
13
|
+
(the TypeScript one through the bundled runtime's ``chunk-files``), and the
|
|
14
|
+
sandbox-side half of ``gateway worlds sandbox import``: the platform runs it
|
|
15
|
+
inside the sandbox (whose staged ``gateway`` is the TypeScript CLI on this
|
|
16
|
+
runtime), then reads the chunk files out itself.
|
|
17
|
+
|
|
18
|
+
What this door cannot be: a home for bulk data. A directory import lands in the
|
|
19
|
+
source tree (``data/initial.json`` / ``data/batches/``), a JSON journal the
|
|
20
|
+
compiler reads whole, the runtime bridge carries whole (``platform.MAX_BYTES``)
|
|
21
|
+
and publication reads whole — and refuses over :data:`PUBLICATION_FILE_BYTES`
|
|
22
|
+
(the Node gate's ``WORLD_PUBLICATION_FILE_MAX_BYTES``). So the door has the same
|
|
23
|
+
cap, named in MiB and rows (:data:`TREE_BYTES`, :data:`TREE_ROWS`), checked on
|
|
24
|
+
the input before a row is held and on the journal before it is written, and the
|
|
25
|
+
refusal names the door bulk data takes: the platform world's snapshot —
|
|
26
|
+
``gateway worlds sandbox import`` from a sandbox (the platform reads the file
|
|
27
|
+
out of it), ``gateway worlds data import <slug>`` where the keys are.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import json
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
from typing import Any
|
|
35
|
+
|
|
36
|
+
from .csv_rows import is_delimited_name
|
|
37
|
+
from .validation import fail
|
|
38
|
+
|
|
39
|
+
#: The most publication reads out of one contract file (``data/initial.json`` among
|
|
40
|
+
#: them): the TypeScript ``WORLD_PUBLICATION_FILE_MAX_BYTES``, declared once per runtime.
|
|
41
|
+
PUBLICATION_FILE_BYTES = 4 * 1024 * 1024
|
|
42
|
+
#: What a world's source tree carries as data, at most: the journal is a source file
|
|
43
|
+
#: publication reads whole, so the door admits no more than publication does.
|
|
44
|
+
TREE_BYTES = PUBLICATION_FILE_BYTES
|
|
45
|
+
TREE_ROWS = 100_000
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def world_slug(root: Path) -> str:
|
|
49
|
+
"""The platform slug a local world would import into: its pulled metadata, else its name."""
|
|
50
|
+
meta = root / ".gateway" / ".env-metadata.json"
|
|
51
|
+
if meta.is_file():
|
|
52
|
+
try:
|
|
53
|
+
slug = json.loads(meta.read_text(encoding="utf-8")).get("slug")
|
|
54
|
+
if isinstance(slug, str) and slug:
|
|
55
|
+
return slug
|
|
56
|
+
except (OSError, ValueError):
|
|
57
|
+
pass
|
|
58
|
+
return root.resolve().name
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def bulk_door(slug: str) -> str:
|
|
62
|
+
"""Where rows over the tree cap go, as the refusal names it."""
|
|
63
|
+
return (
|
|
64
|
+
f"import into the platform world `{slug}` instead — its data snapshot has no such cap. From a sandbox: "
|
|
65
|
+
f"`gateway worlds sandbox import <sandbox-id> <path> --entity <entity>` (run where the project keys are; "
|
|
66
|
+
f"the platform reads the file out of the sandbox). With keys on this machine: "
|
|
67
|
+
f"`gateway worlds data import {slug} <file>`."
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def tree_cap_message(files: list[Path], size: int, slug: str) -> str:
|
|
72
|
+
named = f"{files[0]}" if len(files) == 1 else f"{len(files)} files"
|
|
73
|
+
return (
|
|
74
|
+
f"{named} ({size / (1024 * 1024):.1f} MiB) is over what a world's source tree carries as data "
|
|
75
|
+
f"(data/initial.json is a source file publication reads whole: {TREE_BYTES // (1024 * 1024)} MiB / "
|
|
76
|
+
f"{TREE_ROWS} rows at most); {bulk_door(slug)}"
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def journal_cap_message(path: Path, size: int, slug: str) -> str:
|
|
81
|
+
"""The refusal when the rows fit but the journal they land in would not publish."""
|
|
82
|
+
return (
|
|
83
|
+
f"{path} would be {size / (1024 * 1024):.1f} MiB with these rows, over the {PUBLICATION_FILE_BYTES // (1024 * 1024)} MiB "
|
|
84
|
+
f"publication reads a source file whole (a push would refuse it); {bulk_door(slug)}"
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def refuse_unpublishable_journal(root: Path, path: Path, payload: bytes) -> None:
|
|
89
|
+
"""A journal publication would refuse is refused here, before it is written."""
|
|
90
|
+
if len(payload) <= PUBLICATION_FILE_BYTES:
|
|
91
|
+
return
|
|
92
|
+
fail("tree_cap", journal_cap_message(path, len(payload), world_slug(root)), "/rows")
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
class TreeImport:
|
|
96
|
+
"""Rows files against one world directory. ``entity`` names what bare-row files
|
|
97
|
+
and ``.csv``/``.tsv`` columns hold; ``delimiter`` splits the cells (``None``: by
|
|
98
|
+
name); the tree's contract types them."""
|
|
99
|
+
|
|
100
|
+
def __init__(
|
|
101
|
+
self,
|
|
102
|
+
root: Path,
|
|
103
|
+
files: list[Path],
|
|
104
|
+
*,
|
|
105
|
+
entity: str | None = None,
|
|
106
|
+
delimiter: str | None = None,
|
|
107
|
+
) -> None:
|
|
108
|
+
self.root = Path(root)
|
|
109
|
+
self.files = [Path(f) for f in files]
|
|
110
|
+
self.entity = entity
|
|
111
|
+
self.delimiter = delimiter
|
|
112
|
+
self._casters: Any = None
|
|
113
|
+
|
|
114
|
+
@property
|
|
115
|
+
def casters(self) -> Any:
|
|
116
|
+
"""The tree's cell casters, compiled once and only for delimited inputs."""
|
|
117
|
+
if self._casters is None and any(is_delimited_name(str(f)) for f in self.files):
|
|
118
|
+
from .cast import tree_casters
|
|
119
|
+
|
|
120
|
+
self._casters = tree_casters(self.root)
|
|
121
|
+
return self._casters
|
|
122
|
+
|
|
123
|
+
def size(self) -> int:
|
|
124
|
+
return sum(path.stat().st_size for path in self.files if path.is_file())
|
|
125
|
+
|
|
126
|
+
def refuse_unreadable(self) -> None:
|
|
127
|
+
for path in self.files:
|
|
128
|
+
if not path.is_file():
|
|
129
|
+
fail("rows", f"Cannot read {path}", "/rows")
|
|
130
|
+
|
|
131
|
+
def refuse_over_tree_cap(self) -> None:
|
|
132
|
+
"""Over :data:`TREE_BYTES` or :data:`TREE_ROWS` the import is refused before any
|
|
133
|
+
row is held, and told the door big data takes."""
|
|
134
|
+
from .batch import count_rows
|
|
135
|
+
|
|
136
|
+
size = self.size()
|
|
137
|
+
sources = [str(f) for f in self.files]
|
|
138
|
+
over_rows = count_rows(sources, entity=self.entity, cap=TREE_ROWS, delimiter=self.delimiter) > TREE_ROWS
|
|
139
|
+
if size > TREE_BYTES or over_rows:
|
|
140
|
+
fail(
|
|
141
|
+
"tree_cap",
|
|
142
|
+
tree_cap_message(self.files, size, world_slug(self.root)),
|
|
143
|
+
"/rows",
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
def rows(self, seen: dict[str, int] | None = None) -> Any:
|
|
147
|
+
"""The typed rows, streamed: ``(entity, row)`` pairs."""
|
|
148
|
+
from .batch import iter_rows
|
|
149
|
+
|
|
150
|
+
return iter_rows(
|
|
151
|
+
[str(f) for f in self.files],
|
|
152
|
+
entity=self.entity,
|
|
153
|
+
seen=seen,
|
|
154
|
+
delimiter=self.delimiter,
|
|
155
|
+
casters=self.casters,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
def parsed(self) -> dict[str, list[dict]]:
|
|
159
|
+
from .data import parse_rows
|
|
160
|
+
|
|
161
|
+
return parse_rows(
|
|
162
|
+
self.files,
|
|
163
|
+
entity=self.entity,
|
|
164
|
+
delimiter=self.delimiter,
|
|
165
|
+
casters=self.casters,
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
def chunks(
|
|
169
|
+
self,
|
|
170
|
+
workdir: Path,
|
|
171
|
+
*,
|
|
172
|
+
chunk_bytes: int | None = None,
|
|
173
|
+
chunk_rows: int | None = None,
|
|
174
|
+
) -> list[Any]:
|
|
175
|
+
"""The typed rows as the gzipped JSONL chunk files a data batch takes, written
|
|
176
|
+
under ``workdir`` (:func:`batch.chunk_rows`): one chunk of memory at a time, no tree
|
|
177
|
+
cap — the chunks are bound for a platform snapshot, not the source tree."""
|
|
178
|
+
from .batch import CHUNK_BYTES
|
|
179
|
+
from .batch import chunk_rows as split
|
|
180
|
+
|
|
181
|
+
self.refuse_unreadable()
|
|
182
|
+
return list(
|
|
183
|
+
split(
|
|
184
|
+
self.rows(),
|
|
185
|
+
workdir,
|
|
186
|
+
chunk_bytes=chunk_bytes or CHUNK_BYTES,
|
|
187
|
+
chunk_rows=chunk_rows,
|
|
188
|
+
entity=self.entity,
|
|
189
|
+
)
|
|
190
|
+
)
|
|
191
|
+
|
|
192
|
+
@staticmethod
|
|
193
|
+
def chunk_report(chunks: list[Any]) -> dict[str, Any]:
|
|
194
|
+
"""What ``worlds data chunks`` prints and ``chunk-files`` answers: ``rows`` and,
|
|
195
|
+
per chunk, ``ordinal``, ``path``, ``rows``, ``bytes``, ``digest``, ``entity``."""
|
|
196
|
+
return {
|
|
197
|
+
"rows": sum(chunk.rows for chunk in chunks),
|
|
198
|
+
"chunks": [
|
|
199
|
+
{
|
|
200
|
+
"ordinal": chunk.ordinal,
|
|
201
|
+
"path": str(chunk.path),
|
|
202
|
+
"rows": chunk.rows,
|
|
203
|
+
"bytes": chunk.bytes,
|
|
204
|
+
"digest": chunk.digest,
|
|
205
|
+
"entity": chunk.entity,
|
|
206
|
+
}
|
|
207
|
+
for chunk in chunks
|
|
208
|
+
],
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
def run(
|
|
212
|
+
self,
|
|
213
|
+
*,
|
|
214
|
+
mode: str = "append",
|
|
215
|
+
merge: str = "upsert",
|
|
216
|
+
redact: str = "off",
|
|
217
|
+
dry_run: bool = False,
|
|
218
|
+
) -> dict:
|
|
219
|
+
"""The import (or, ``dry_run``, its proof): :func:`data.import_rows`'s report plus
|
|
220
|
+
``rows``, how many the files held. The cap is checked first, streaming, for a proof
|
|
221
|
+
as for an import: what is held in memory is bounded by the cap, never by the file."""
|
|
222
|
+
from .data import import_rows
|
|
223
|
+
|
|
224
|
+
self.refuse_unreadable()
|
|
225
|
+
self.refuse_over_tree_cap()
|
|
226
|
+
parsed = self.parsed()
|
|
227
|
+
report = import_rows(self.root, parsed, mode=mode, merge=merge, redact=redact, dry_run=dry_run)
|
|
228
|
+
return {**report, "rows": sum(len(listed) for listed in parsed.values())}
|
|
@@ -65,6 +65,20 @@ class UiDeclaration:
|
|
|
65
65
|
#: so a world that built its own ui before this key existed keeps it.
|
|
66
66
|
generated: bool | None
|
|
67
67
|
|
|
68
|
+
@property
|
|
69
|
+
def kind(self) -> str:
|
|
70
|
+
"""``product`` when the ui is hand-built (``generated = false``: a
|
|
71
|
+
replica of the vendor's own product), else ``generated`` (made from the
|
|
72
|
+
contract at compile time). What the connector pages badge and label."""
|
|
73
|
+
return "product" if self.generated is False else "generated"
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def ui_kind(world: Path) -> str:
|
|
77
|
+
"""The world's ui as the connector pages show it: ``product``,
|
|
78
|
+
``generated``, or ``none`` when it declares no ``[ui]``."""
|
|
79
|
+
declaration = read_ui_declaration(world)
|
|
80
|
+
return declaration.kind if declaration is not None else "none"
|
|
81
|
+
|
|
68
82
|
|
|
69
83
|
def read_ui_declaration(world: Path) -> UiDeclaration | None:
|
|
70
84
|
"""``[ui]`` of the world's connector.toml, or None when the world declares
|
|
@@ -89,8 +103,10 @@ def read_ui_declaration(world: Path) -> UiDeclaration | None:
|
|
|
89
103
|
if not isinstance(static, str) or not static or static.startswith("/") or ".." in static.split("/"):
|
|
90
104
|
fail("spec", "ui.static is a directory inside the world holding the ui", "/ui/static")
|
|
91
105
|
entry = ui.get("entry", DEFAULT_ENTRY)
|
|
92
|
-
|
|
93
|
-
|
|
106
|
+
# `//host` and `/\host` are paths only in form: a browser resolves them to
|
|
107
|
+
# another origin, which would carry the session token off the ui's own.
|
|
108
|
+
if not isinstance(entry, str) or not entry.startswith("/") or entry.startswith("//") or "\\" in entry:
|
|
109
|
+
fail("spec", "ui.entry is the path the agent lands on, starting with / on the ui's own origin", "/ui/entry")
|
|
94
110
|
api_path = ui.get("api_path", "/__world-api")
|
|
95
111
|
if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
|
|
96
112
|
fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
|
|
@@ -15,6 +15,8 @@ import struct
|
|
|
15
15
|
from pathlib import Path
|
|
16
16
|
from typing import Any, NoReturn
|
|
17
17
|
|
|
18
|
+
from .._toml import tomllib
|
|
19
|
+
|
|
18
20
|
DIALECT = "https://json-schema.org/draft/2020-12/schema"
|
|
19
21
|
LANGUAGE = "gateway-world/1"
|
|
20
22
|
SAFE_INTEGER = 2**53 - 1
|
|
@@ -217,6 +219,39 @@ def nonempty(value: Any, location: str) -> None:
|
|
|
217
219
|
fail("schema", "Expected a nonempty string of at most 256 characters", location)
|
|
218
220
|
|
|
219
221
|
|
|
222
|
+
#: A connector operation name: snake_case, at most this long. The bound is shared with
|
|
223
|
+
#: the TypeScript ``route add`` (``MAX_OPERATION_NAME`` in scaffoldRoutes.ts) and the
|
|
224
|
+
#: OpenAPI importer, which truncates an ``operationId`` to fit; a 300-character name
|
|
225
|
+
#: used to compile (zero-context round 2, W3).
|
|
226
|
+
MAX_OPERATION_NAME = 64
|
|
227
|
+
#: An entity name: at most this long, so ``data-import:<entity>:<identity>`` source
|
|
228
|
+
#: records and SQLite table names stay inside the 256-character record limit. Shared
|
|
229
|
+
#: with the TypeScript ``schema entity add`` (``MAX_ENTITY_NAME`` in scaffold.ts) and
|
|
230
|
+
#: the OpenAPI importer, which truncates a schema name to fit.
|
|
231
|
+
MAX_ENTITY_NAME = 64
|
|
232
|
+
OPERATION_NAME = re.compile(r"^[a-z][a-z0-9_]*$")
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def parse_toml(text: str) -> dict:
|
|
236
|
+
"""A connector.toml's tables, or the structured refusal every reader of it raises."""
|
|
237
|
+
try:
|
|
238
|
+
return tomllib.loads(text)
|
|
239
|
+
except tomllib.TOMLDecodeError as error:
|
|
240
|
+
fail("spec", f"connector.toml is not valid TOML: {error}", "/connector.toml")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def operation_name(name: Any, location: str) -> None:
|
|
244
|
+
if type(name) is not str or not OPERATION_NAME.match(name):
|
|
245
|
+
fail("spec", "operation name must be snake_case ([a-z][a-z0-9_]*)", location)
|
|
246
|
+
if len(name) > MAX_OPERATION_NAME:
|
|
247
|
+
fail(
|
|
248
|
+
"spec",
|
|
249
|
+
f"operation name must be at most {MAX_OPERATION_NAME} characters, got {len(name)}",
|
|
250
|
+
location,
|
|
251
|
+
limit=MAX_OPERATION_NAME,
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
|
|
220
255
|
def equal(left: Any, right: Any) -> bool:
|
|
221
256
|
"""JSON equality: bool is distinct from number; 1 and 1.0 are equal."""
|
|
222
257
|
if type(left) in (int, float) and type(right) in (int, float):
|
|
@@ -69,11 +69,16 @@ def read_seed(body: dict) -> dict[str, Any]:
|
|
|
69
69
|
def read_grade(body: dict) -> dict[str, Any]:
|
|
70
70
|
"""``report`` is the agent's own account of the run, read by a rubric
|
|
71
71
|
judge or put beside the state for a deterministic grader; absent is fine,
|
|
72
|
-
anything but a string is not.
|
|
72
|
+
anything but a string is not. ``context`` is the evidence of the task's
|
|
73
|
+
other worlds (``{alias: state}``, each what that session's ``evidence``
|
|
74
|
+
answers), read by the cross-world verifiers anchored on this session."""
|
|
73
75
|
report = body.get("report")
|
|
74
76
|
if report is not None and not isinstance(report, str):
|
|
75
77
|
fail("input", "report must be a string", "/report")
|
|
76
|
-
|
|
78
|
+
context = body.get("context")
|
|
79
|
+
if context is not None and (not isinstance(context, dict) or any(not isinstance(v, dict) for v in context.values())):
|
|
80
|
+
fail("input", "context must be {alias: state} of the task's other worlds", "/context")
|
|
81
|
+
return {"report": report, "context": context}
|
|
77
82
|
|
|
78
83
|
|
|
79
84
|
def read_call(body: dict) -> dict[str, Any]:
|
|
@@ -95,6 +100,7 @@ SESSION_VERBS: tuple[SessionVerb, ...] = (
|
|
|
95
100
|
SessionVerb("GET", "tools", read_nothing),
|
|
96
101
|
SessionVerb("GET", "task", read_nothing),
|
|
97
102
|
SessionVerb("GET", "state", read_nothing),
|
|
103
|
+
SessionVerb("GET", "evidence", read_nothing),
|
|
98
104
|
SessionVerb("POST", "grade", read_grade),
|
|
99
105
|
SessionVerb("POST", "reset", read_nothing),
|
|
100
106
|
SessionVerb("POST", "seed", read_seed),
|
|
@@ -37,6 +37,7 @@ API_BUNDLE_MANIFEST = "gateway-api-world.toml"
|
|
|
37
37
|
BUNDLED_WORLD_PREFIX = "server/world/"
|
|
38
38
|
CONNECTOR_SPEC = "connector.toml"
|
|
39
39
|
PYPROJECT = "pyproject.toml"
|
|
40
|
+
BENCHMARK_CONFIG = "benchmark.json"
|
|
40
41
|
WORLD_SCHEMA_MARKERS = ("schema/world.json", "schema/runtime.json", "schema/lock.json")
|
|
41
42
|
WORLD_ROOT_MARKERS = (CONNECTOR_SPEC, *WORLD_SCHEMA_MARKERS)
|
|
42
43
|
SCHEMA_MANIFEST_KIND = "schema"
|
|
@@ -48,10 +49,11 @@ KIND_HARBOR = "harbor"
|
|
|
48
49
|
KIND_VERIFIERS = "verifiers"
|
|
49
50
|
KIND_VERIFIERS_V1 = "verifiers-v1"
|
|
50
51
|
|
|
51
|
-
_SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
|
|
52
|
+
_SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__", "node_modules"})
|
|
52
53
|
# A root Gateway marker widens the hashed root from Prime's source globs to
|
|
53
|
-
# every ordinary root file: those kinds keep executable contract
|
|
54
|
-
|
|
54
|
+
# every ordinary root file: those kinds keep executable contract (tasks.json,
|
|
55
|
+
# connector.toml, a benchmark's config and fixtures) at the root.
|
|
56
|
+
_BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG})
|
|
55
57
|
_HASH_CHUNK = 1 << 20
|
|
56
58
|
_HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
|
|
57
59
|
|
|
@@ -178,6 +180,15 @@ class WorldManifest:
|
|
|
178
180
|
WorldManifest.ABSENT = WorldManifest(None, None, None)
|
|
179
181
|
|
|
180
182
|
|
|
183
|
+
@dataclass(frozen=True)
|
|
184
|
+
class Exclusion:
|
|
185
|
+
"""One entry the archive rules dropped: a whole directory (``name/``,
|
|
186
|
+
``files`` counted) or a single root file."""
|
|
187
|
+
|
|
188
|
+
path: str
|
|
189
|
+
files: int
|
|
190
|
+
|
|
191
|
+
|
|
181
192
|
@dataclass(frozen=True)
|
|
182
193
|
class WorldTree:
|
|
183
194
|
"""A tree on disk and where the authored world lives inside it. Immutable;
|
|
@@ -276,6 +287,34 @@ class WorldTree:
|
|
|
276
287
|
def hashed_paths(self) -> list[str]:
|
|
277
288
|
return [path.relative_to(self.root).as_posix() for path in self.archive_files()]
|
|
278
289
|
|
|
290
|
+
def exclusions(self) -> list[Exclusion]:
|
|
291
|
+
"""What the archive rules leave out, collapsed to the entry that
|
|
292
|
+
decided it: a pruned directory counts its files once, a dropped root
|
|
293
|
+
file is named. Dot entries (``.git/``, ``.gateway/``, ``.gitignore``)
|
|
294
|
+
are the one universal convention and stay unreported. ``push`` prints
|
|
295
|
+
the rest so nothing disappears silently."""
|
|
296
|
+
kept = {path.relative_to(self.root).as_posix() for path in self.archive_files()}
|
|
297
|
+
out: list[Exclusion] = []
|
|
298
|
+
for entry in sorted(self.root.iterdir(), key=lambda p: p.name):
|
|
299
|
+
relative = entry.name
|
|
300
|
+
if relative.startswith("."):
|
|
301
|
+
continue
|
|
302
|
+
if entry.is_dir() and not entry.is_symlink():
|
|
303
|
+
dropped = [
|
|
304
|
+
Path(dirpath, name).relative_to(self.root).as_posix()
|
|
305
|
+
for dirpath, _dirnames, filenames in os.walk(entry)
|
|
306
|
+
for name in filenames
|
|
307
|
+
]
|
|
308
|
+
missing = [path for path in dropped if path not in kept]
|
|
309
|
+
if not missing:
|
|
310
|
+
continue
|
|
311
|
+
whole = len(missing) == len(dropped)
|
|
312
|
+
out.extend([Exclusion(f"{relative}/", len(missing))] if whole else [Exclusion(p, 1) for p in missing])
|
|
313
|
+
continue
|
|
314
|
+
if relative not in kept:
|
|
315
|
+
out.append(Exclusion(relative, 1))
|
|
316
|
+
return out
|
|
317
|
+
|
|
279
318
|
@property
|
|
280
319
|
def content_hash(self) -> str:
|
|
281
320
|
"""Streams every file; a large tree never has to fit in memory.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""THE NUMBERS AND WORDS A WORLD SESSION PROMISES — the Python twin.
|
|
2
|
+
|
|
3
|
+
Stdlib only, and inside ``gatewaysdk.environment`` because that package is
|
|
4
|
+
what gets vendored on its own — the web/worker images ship
|
|
5
|
+
``/opt/gateway-schema/gatewaysdk/environment``, ``installSandboxRuntime``
|
|
6
|
+
copies it into agent sandboxes and api bundles stage it beside
|
|
7
|
+
``server/main.py`` — so the World Host's grader, the SDK client
|
|
8
|
+
(:mod:`gatewaysdk.world_sessions`) and the CLI all read this one module.
|
|
9
|
+
|
|
10
|
+
The TypeScript source of truth is
|
|
11
|
+
``gateway/packages/shared/src/server/services/worldSessionContract.ts``;
|
|
12
|
+
both are pinned to ``conformance/world-sessions.json`` by a test on each
|
|
13
|
+
side, so the route, the World Host and the two CLIs cannot drift apart.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from datetime import datetime, timezone
|
|
19
|
+
|
|
20
|
+
#: The largest body ``POST world-sessions/{id}/calls`` accepts. The CLI
|
|
21
|
+
#: measures the serialized body against the byte count and refuses before
|
|
22
|
+
#: sending; the label is what help and the refusal name.
|
|
23
|
+
CALL_BODY_LIMIT_BYTES = 4 * 1024 * 1024
|
|
24
|
+
CALL_BODY_LIMIT_LABEL = "4mb"
|
|
25
|
+
|
|
26
|
+
#: ``session status`` warns once an unpinned session has less than this left.
|
|
27
|
+
IDLE_WARNING_MINUTES = 5
|
|
28
|
+
|
|
29
|
+
#: The task an exploratory session runs on when the caller names none, and
|
|
30
|
+
#: the ``task.source`` the platform reports for it.
|
|
31
|
+
EXPLORATORY_TASK: dict[str, str] = {"instruction": "exploratory session"}
|
|
32
|
+
EXPLORATORY_TASK_SOURCE = "none"
|
|
33
|
+
|
|
34
|
+
#: What a session that has no grader answers ``grade`` with, beside
|
|
35
|
+
#: ``reward: null``.
|
|
36
|
+
NO_GRADER_REASON = "no grader"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def idle_warning(idle_expires_at: str | None, *, now: str | None = None) -> str | None:
|
|
40
|
+
"""The line ``session status`` prints when an unpinned session has under
|
|
41
|
+
:data:`IDLE_WARNING_MINUTES` left, else ``None``. ``now`` is for tests."""
|
|
42
|
+
if not idle_expires_at:
|
|
43
|
+
return None
|
|
44
|
+
expires = datetime.fromisoformat(idle_expires_at.replace("Z", "+00:00"))
|
|
45
|
+
current = (
|
|
46
|
+
datetime.fromisoformat(now.replace("Z", "+00:00"))
|
|
47
|
+
if now
|
|
48
|
+
else datetime.now(timezone.utc)
|
|
49
|
+
)
|
|
50
|
+
left_s = (expires - current).total_seconds()
|
|
51
|
+
if left_s >= IDLE_WARNING_MINUTES * 60:
|
|
52
|
+
return None
|
|
53
|
+
minutes = max(0, int(left_s // 60))
|
|
54
|
+
return (
|
|
55
|
+
f"warning: session expires in {minutes}m (idle TTL); "
|
|
56
|
+
"call a tool to extend it or `gateway worlds session pin` to keep it"
|
|
57
|
+
)
|