@withgateway/sdk 0.2.4 → 0.2.6
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/dist/cli.js +4304 -2381
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +4266 -2343
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +56 -31
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +52 -27
- 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 +280 -8
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +272 -8
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-1xnxt0Cc.d.ts → index-BO2SNSgy.d.ts} +12 -1
- package/dist/{index-B0R3IgsV.d.mts → index-BaKu5ZSU.d.mts} +124 -2
- package/dist/{index-B0R3IgsV.d.ts → index-BaKu5ZSU.d.ts} +124 -2
- package/dist/{index-C1wDEwH4.d.mts → index-Cz8Q6Keo.d.mts} +12 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1100 -438
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1079 -424
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +45 -20
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +41 -16
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +98 -61
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +98 -61
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +179 -25
- package/dist/worlds/index.d.ts +179 -25
- package/dist/worlds/index.js +639 -284
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +631 -276
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +2 -1
- package/runtime/gatewaysdk/environment/_bundle.py +15 -25
- package/runtime/gatewaysdk/environment/_materialize.py +53 -9
- package/runtime/gatewaysdk/environment/_toml.py +13 -0
- package/runtime/gatewaysdk/environment/schema/api.py +40 -25
- package/runtime/gatewaysdk/environment/schema/batch.py +15 -11
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +24 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +60 -28
- package/runtime/gatewaysdk/environment/schema/conform.py +1 -1
- package/runtime/gatewaysdk/environment/schema/connector.py +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.ingest.toml +25 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +17 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -19
- package/runtime/gatewaysdk/environment/schema/extract.py +1 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
- package/runtime/gatewaysdk/environment/schema/host.py +156 -546
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +1 -5
- package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
- package/runtime/gatewaysdk/environment/schema/local.py +32 -126
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/platform.py +30 -26
- package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +1 -1
- package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +9 -2
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +67 -9
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +67 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
- package/runtime/gatewaysdk/environment/schema/snapshot.py +1 -5
- package/runtime/gatewaysdk/environment/schema/tools_world.py +71 -23
- package/runtime/gatewaysdk/environment/schema/ui.py +1 -5
- package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +507 -0
- package/skills/benchmarks-getting-started/SKILL.md +67 -9
- package/skills/connector-schema-authoring/connector-worlds.md +8 -1
- package/skills/connector-schema-authoring/world-schema.md +1 -1
- package/skills/hooks-getting-started/SKILL.md +67 -6
- package/skills/world-data-ingestion/SKILL.md +4 -1
- package/skills/worlds-getting-started/SKILL.md +11 -11
- package/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""The session protocol, once: every verb a world session answers, with the
|
|
2
|
+
method it takes and how its body is read. Both HTTP transports dispatch
|
|
3
|
+
through this table — the local session (``local.py``, ``/__session/<verb>``)
|
|
4
|
+
and the World Host control plane (``host.py``, ``/__host/sessions/<sid>/
|
|
5
|
+
<verb>``) — so the two cannot drift: a verb added here is served by both, a
|
|
6
|
+
body shape accepted here is accepted by both. The transports stay distinct
|
|
7
|
+
(loopback with no secret against a fleet with leases, workers and exports);
|
|
8
|
+
only the verbs are shared.
|
|
9
|
+
|
|
10
|
+
A verb marked ``hosted`` is the platform's rendezvous with a session it keeps
|
|
11
|
+
alive across hosts (the lease, the state export, DELETE as the platform's
|
|
12
|
+
close); the local session, which lives as long as the process serving it,
|
|
13
|
+
refuses them by name."""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from collections.abc import Callable
|
|
18
|
+
from dataclasses import dataclass
|
|
19
|
+
from typing import Any
|
|
20
|
+
|
|
21
|
+
from .redaction import parse_mode
|
|
22
|
+
from .validation import ContractError, fail
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True)
|
|
26
|
+
class SessionVerb:
|
|
27
|
+
"""One row of the protocol: ``method`` and ``name`` are the route (``name``
|
|
28
|
+
None addresses the session itself, as ``DELETE`` does); ``read`` turns the
|
|
29
|
+
request body into the keyword arguments the session operation takes, or
|
|
30
|
+
refuses the shape (a :class:`ContractError` the transport answers 400)."""
|
|
31
|
+
|
|
32
|
+
method: str
|
|
33
|
+
name: str | None
|
|
34
|
+
read: Callable[[dict], dict[str, Any]]
|
|
35
|
+
hosted: bool = False
|
|
36
|
+
|
|
37
|
+
@property
|
|
38
|
+
def route(self) -> str:
|
|
39
|
+
return f"{self.method} {self.name}" if self.name is not None else f"{self.method} <session>"
|
|
40
|
+
|
|
41
|
+
def matches(self, method: str, name: str | None) -> bool:
|
|
42
|
+
return self.method == method and self.name == (name or None)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def read_nothing(_body: dict) -> dict[str, Any]:
|
|
46
|
+
return {}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def read_seed(body: dict) -> dict[str, Any]:
|
|
50
|
+
"""``{rows, mode, redact}``, the same under ``args`` (the platform wraps
|
|
51
|
+
the seed it forwards), or bare ``{entity: [row, ...]}`` — the shape a rows
|
|
52
|
+
file has — taken as the rows of an append."""
|
|
53
|
+
args = body["args"] if isinstance(body.get("args"), dict) else body
|
|
54
|
+
if "rows" not in args and "mode" not in args and args and all(isinstance(v, list) for v in args.values()):
|
|
55
|
+
args = {"rows": args}
|
|
56
|
+
rows = args.get("rows")
|
|
57
|
+
if not isinstance(rows, dict):
|
|
58
|
+
fail(
|
|
59
|
+
"host",
|
|
60
|
+
'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
|
|
61
|
+
"a dependency's entity is named alias.entity",
|
|
62
|
+
)
|
|
63
|
+
mode = args.get("mode", "append")
|
|
64
|
+
if mode not in ("append", "replace"):
|
|
65
|
+
fail("host", 'seed mode must be "append" or "replace"', "/args/mode")
|
|
66
|
+
return {"rows": rows, "mode": mode, "redact": parse_mode(args.get("redact"), "/args/redact")}
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def read_grade(body: dict) -> dict[str, Any]:
|
|
70
|
+
"""``report`` is the agent's own account of the run, read by a rubric
|
|
71
|
+
judge or put beside the state for a deterministic grader; absent is fine,
|
|
72
|
+
anything but a string is not."""
|
|
73
|
+
report = body.get("report")
|
|
74
|
+
if report is not None and not isinstance(report, str):
|
|
75
|
+
fail("input", "report must be a string", "/report")
|
|
76
|
+
return {"report": report}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def read_call(body: dict) -> dict[str, Any]:
|
|
80
|
+
tool = body.get("tool")
|
|
81
|
+
if not isinstance(tool, str) or not tool:
|
|
82
|
+
fail("input", "tool must be a tool name (root) or alias.tool (a dependency's)", "/tool")
|
|
83
|
+
args = body.get("args") or {}
|
|
84
|
+
if not isinstance(args, dict):
|
|
85
|
+
fail("input", "args must be an object of the tool's arguments", "/args")
|
|
86
|
+
return {"tool": tool, "args": args}
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def read_export(body: dict) -> dict[str, Any]:
|
|
90
|
+
known = body.get("knownSha256")
|
|
91
|
+
return {"known_sha256": known if isinstance(known, str) else None}
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
SESSION_VERBS: tuple[SessionVerb, ...] = (
|
|
95
|
+
SessionVerb("GET", "tools", read_nothing),
|
|
96
|
+
SessionVerb("GET", "task", read_nothing),
|
|
97
|
+
SessionVerb("GET", "state", read_nothing),
|
|
98
|
+
SessionVerb("POST", "grade", read_grade),
|
|
99
|
+
SessionVerb("POST", "reset", read_nothing),
|
|
100
|
+
SessionVerb("POST", "seed", read_seed),
|
|
101
|
+
SessionVerb("POST", "call", read_call),
|
|
102
|
+
SessionVerb("POST", "close", read_nothing),
|
|
103
|
+
SessionVerb("POST", "renew", read_nothing, hosted=True),
|
|
104
|
+
SessionVerb("POST", "export", read_export, hosted=True),
|
|
105
|
+
SessionVerb("DELETE", None, read_nothing, hosted=True),
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def session_verb(method: str, name: str | None) -> SessionVerb | None:
|
|
110
|
+
return next((verb for verb in SESSION_VERBS if verb.matches(method, name)), None)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def served_verbs(*, hosted: bool) -> tuple[SessionVerb, ...]:
|
|
114
|
+
"""The rows a transport answers: every one on the host, the session's own
|
|
115
|
+
(not the lease's) locally."""
|
|
116
|
+
return tuple(verb for verb in SESSION_VERBS if hosted or not verb.hosted)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def unknown_verb(method: str, name: str | None, *, hosted: bool, prefix: str) -> dict:
|
|
120
|
+
"""The 404 body for a route off the table, naming what is on it. A hosted
|
|
121
|
+
verb sent to the local session is refused by name, not as unknown."""
|
|
122
|
+
verb = session_verb(method, name)
|
|
123
|
+
if verb is not None and verb.hosted and not hosted:
|
|
124
|
+
return {"error": f"{verb.route} is a hosted session's verb (the platform's lease); the local session has none"}
|
|
125
|
+
known = ", ".join(
|
|
126
|
+
f"{v.method} {prefix}{v.name}" if v.name else f"{v.method} {prefix.rstrip('/')}"
|
|
127
|
+
for v in served_verbs(hosted=hosted)
|
|
128
|
+
)
|
|
129
|
+
return {"error": f"unknown session route {method} {prefix}{name or ''}; one of {known}"}
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def refusal(error: ContractError) -> dict:
|
|
133
|
+
"""A refused call as the answer a session gives it: an unknown tool,
|
|
134
|
+
arguments off the schema, a tool outside the task's allow-list, a write the
|
|
135
|
+
store will not take, all ``{status: 400, body: {error, detail}}``."""
|
|
136
|
+
return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
|
|
@@ -51,6 +51,8 @@ from dataclasses import dataclass, field
|
|
|
51
51
|
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
|
52
52
|
from pathlib import Path
|
|
53
53
|
|
|
54
|
+
from .grading import VerifierSandbox
|
|
55
|
+
|
|
54
56
|
#: Address space a worker may use, in MiB, unless ``WORLDS_WORKER_MEMORY_MB`` says otherwise.
|
|
55
57
|
DEFAULT_WORKER_MEMORY_MB = 2048
|
|
56
58
|
#: Memory every worker together may use, in MiB, unless
|
|
@@ -281,6 +283,18 @@ def confined_command(script: Path, python: str = sys.executable) -> list[str]:
|
|
|
281
283
|
return [python, "-c", _CONFINED_PRELUDE, str(script)]
|
|
282
284
|
|
|
283
285
|
|
|
286
|
+
class ConfinedVerifierSandbox(VerifierSandbox):
|
|
287
|
+
"""How the host runs a task's ``verify.py``: confined like a worker, with a
|
|
288
|
+
scrubbed environment and a home under the session. World-authored code
|
|
289
|
+
sees no secret of this process, be it the host's or a worker's."""
|
|
290
|
+
|
|
291
|
+
def command(self, script: Path) -> list[str]:
|
|
292
|
+
return confined_command(script)
|
|
293
|
+
|
|
294
|
+
def environment(self, home: Path) -> dict[str, str]:
|
|
295
|
+
return verifier_environment(home=home)
|
|
296
|
+
|
|
297
|
+
|
|
284
298
|
# --------------------------------------------------------------------------- #
|
|
285
299
|
# The supervisor's side: start, reach and stop workers.
|
|
286
300
|
# --------------------------------------------------------------------------- #
|
|
@@ -64,7 +64,6 @@ import shutil
|
|
|
64
64
|
import subprocess
|
|
65
65
|
import sys
|
|
66
66
|
import tempfile
|
|
67
|
-
import tomllib
|
|
68
67
|
import urllib.error
|
|
69
68
|
import urllib.parse
|
|
70
69
|
import urllib.request
|
|
@@ -72,6 +71,7 @@ from dataclasses import asdict, dataclass, field
|
|
|
72
71
|
from pathlib import Path
|
|
73
72
|
from typing import Any
|
|
74
73
|
|
|
74
|
+
from .._toml import tomllib
|
|
75
75
|
from .api import load_api_settings
|
|
76
76
|
from .conform import PIN, _credentials
|
|
77
77
|
from .connector import load_spec
|
|
@@ -0,0 +1,507 @@
|
|
|
1
|
+
"""What a tree on disk IS, decided once.
|
|
2
|
+
|
|
3
|
+
``World.from_tree`` is the one Python detector: the local runtime
|
|
4
|
+
(``_bundle.detect_kind``), the data commands (``data.world_kind``), the hub
|
|
5
|
+
client (``harbor_adapter.detect_env_kind``), the benchmark runner
|
|
6
|
+
(``engines/hub_bundle.detect_env_kind``), the platform bridge
|
|
7
|
+
(``platform.world_root``) and the World Host (``host.world_tree``) all read
|
|
8
|
+
their answer from here. The TypeScript twin is
|
|
9
|
+
``packages/shared/src/world/`` (``WorldTree`` + ``World.fromTree``); the
|
|
10
|
+
corpus under ``conformance/worlds/`` pins both to the same answers.
|
|
11
|
+
|
|
12
|
+
Stdlib only: the benchmark runner vendors this subpackage without the SDK's
|
|
13
|
+
dependencies.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import hashlib
|
|
19
|
+
import os
|
|
20
|
+
import re
|
|
21
|
+
from collections.abc import Callable, Iterator
|
|
22
|
+
from dataclasses import dataclass
|
|
23
|
+
from functools import cached_property
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import ClassVar
|
|
26
|
+
from ._toml import tomllib
|
|
27
|
+
|
|
28
|
+
try: # optional: only consulted when a tree ships a root .gitignore
|
|
29
|
+
from gitignore_parser import parse_gitignore
|
|
30
|
+
except ImportError: # pragma: no cover - the runner and the sandbox vendor this module alone
|
|
31
|
+
parse_gitignore = None # type: ignore[assignment]
|
|
32
|
+
|
|
33
|
+
# ── Markers (twin of packages/shared/src/world/markers.ts) ──────────────────
|
|
34
|
+
|
|
35
|
+
WORLD_MANIFEST = "gateway-env.toml"
|
|
36
|
+
API_BUNDLE_MANIFEST = "gateway-api-world.toml"
|
|
37
|
+
BUNDLED_WORLD_PREFIX = "server/world/"
|
|
38
|
+
CONNECTOR_SPEC = "connector.toml"
|
|
39
|
+
PYPROJECT = "pyproject.toml"
|
|
40
|
+
WORLD_SCHEMA_MARKERS = ("schema/world.json", "schema/runtime.json", "schema/lock.json")
|
|
41
|
+
WORLD_ROOT_MARKERS = (CONNECTOR_SPEC, *WORLD_SCHEMA_MARKERS)
|
|
42
|
+
SCHEMA_MANIFEST_KIND = "schema"
|
|
43
|
+
SCHEMA_MANIFEST_KINDS = frozenset({SCHEMA_MANIFEST_KIND, "mock-tools"})
|
|
44
|
+
|
|
45
|
+
KIND_MOCK_TOOLS = "mock-tools"
|
|
46
|
+
KIND_API = "api"
|
|
47
|
+
KIND_HARBOR = "harbor"
|
|
48
|
+
KIND_VERIFIERS = "verifiers"
|
|
49
|
+
KIND_VERIFIERS_V1 = "verifiers-v1"
|
|
50
|
+
|
|
51
|
+
_SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
|
|
52
|
+
# A root Gateway marker widens the hashed root from Prime's source globs to
|
|
53
|
+
# every ordinary root file: those kinds keep executable contract at the root.
|
|
54
|
+
_BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST})
|
|
55
|
+
_HASH_CHUNK = 1 << 20
|
|
56
|
+
_HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
|
|
57
|
+
|
|
58
|
+
# The `verifiers.v1` namespace first shipped in verifiers 0.2.0, so a v1
|
|
59
|
+
# package declares verifiers>=0.2 (or ~=0.2 / ==0.2.* / >=1 / ==1.*) in
|
|
60
|
+
# pyproject — minor >= 2 on the 0.x line or any major >= 1, never 0.0/0.1 —
|
|
61
|
+
# and/or imports the namespace or subclasses Taskset alongside the v1
|
|
62
|
+
# packaging convention of an ``__all__`` export (any library may name a class
|
|
63
|
+
# Taskset). A bare unversioned dependency or a pre-0.2 pin is v0.
|
|
64
|
+
_V1_DEP = re.compile(
|
|
65
|
+
r"""["']verifiers\s*(?:\[[^\]]*\])?\s*(?:>=|~=|==|>)\s*""" r"""(?:0\.(?:[2-9]\d*|[1-9]\d+)|[1-9]\d*)"""
|
|
66
|
+
)
|
|
67
|
+
_V1_IMPORT = re.compile(
|
|
68
|
+
r"^\s*(?:from\s+verifiers\.v1\s+import\b|from\s+verifiers\s+import\s+v1\b|import\s+verifiers\.v1\b)",
|
|
69
|
+
re.MULTILINE,
|
|
70
|
+
)
|
|
71
|
+
_V1_TASKSET = re.compile(r"class\s+\w+\s*\(\s*(?:(?:vf|v1|verifiers(?:\.v1)?)\.)?Taskset\s*[,)]")
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _present(path: Path) -> bool:
|
|
75
|
+
"""A file exists — or a symlink to one is dangling: a broken authority
|
|
76
|
+
must fail loudly downstream, never quietly downgrade the tree."""
|
|
77
|
+
return path.is_file() or path.is_symlink()
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _skipped_dir(name: str) -> bool:
|
|
81
|
+
return name.startswith(".") or name in _SKIPPED_DIRS or name.endswith(".egg-info")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _ordinary_root_file(name: str, broad: bool) -> bool:
|
|
85
|
+
return broad or name in ("README.md", PYPROJECT) or name in _BROAD_ROOT_MARKERS or name.endswith(".py")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def is_hashed_path(relative: str, broad_root: bool) -> bool:
|
|
89
|
+
"""Twin of ``worldTree.ts isHashedPath``: the path-only half of the archive
|
|
90
|
+
rule (hidden names, pruned directories, the root globs)."""
|
|
91
|
+
parts = relative.split("/")
|
|
92
|
+
name = parts[-1]
|
|
93
|
+
if name.startswith(".") or "__pycache__" in parts:
|
|
94
|
+
return False
|
|
95
|
+
directories = parts[:-1]
|
|
96
|
+
if not directories:
|
|
97
|
+
return _ordinary_root_file(name, broad_root)
|
|
98
|
+
return not any(_skipped_dir(component) for component in directories)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _gitignore_matcher(root: Path) -> Callable[[str], bool] | None:
|
|
102
|
+
gitignore = root / ".gitignore"
|
|
103
|
+
if not gitignore.exists():
|
|
104
|
+
return None
|
|
105
|
+
if parse_gitignore is None:
|
|
106
|
+
raise RuntimeError(
|
|
107
|
+
"A .gitignore is present but 'gitignore_parser' is not installed. Install it (a declared "
|
|
108
|
+
"dependency of gatewaysdk) so the content hash stays compatible with the hub."
|
|
109
|
+
)
|
|
110
|
+
return parse_gitignore(str(gitignore), base_dir=str(root))
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def pyproject_pins_v1(path: str, text: str) -> bool:
|
|
114
|
+
if path != PYPROJECT:
|
|
115
|
+
return False
|
|
116
|
+
return _V1_DEP.search(text) is not None
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def module_uses_v1(path: str, text: str) -> bool:
|
|
120
|
+
if not path.endswith(".py"):
|
|
121
|
+
return False
|
|
122
|
+
return bool(_V1_IMPORT.search(text)) or ("__all__" in text and bool(_V1_TASKSET.search(text)))
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
class WorldManifest:
|
|
126
|
+
"""A world's ``gateway-env.toml``, parsed once. An absent manifest and an
|
|
127
|
+
unparsable one are both manifests: ``present`` and ``error`` say which,
|
|
128
|
+
and every accessor answers "declares nothing" for them."""
|
|
129
|
+
|
|
130
|
+
def __init__(self, text: str | None, root: dict | None, error: str | None) -> None:
|
|
131
|
+
self.text = text
|
|
132
|
+
self._root = root
|
|
133
|
+
self.error = error
|
|
134
|
+
|
|
135
|
+
ABSENT: ClassVar[WorldManifest]
|
|
136
|
+
|
|
137
|
+
@staticmethod
|
|
138
|
+
def parse(text: str) -> WorldManifest:
|
|
139
|
+
try:
|
|
140
|
+
return WorldManifest(text, tomllib.loads(text), None)
|
|
141
|
+
except tomllib.TOMLDecodeError as error:
|
|
142
|
+
return WorldManifest(text, None, f"{WORLD_MANIFEST} is invalid TOML: {error}")
|
|
143
|
+
|
|
144
|
+
@property
|
|
145
|
+
def present(self) -> bool:
|
|
146
|
+
return self.text is not None
|
|
147
|
+
|
|
148
|
+
@property
|
|
149
|
+
def invalid(self) -> bool:
|
|
150
|
+
return self.present and self._root is None
|
|
151
|
+
|
|
152
|
+
def table(self, name: str) -> dict | None:
|
|
153
|
+
value = (self._root or {}).get(name)
|
|
154
|
+
return value if isinstance(value, dict) else None
|
|
155
|
+
|
|
156
|
+
def has(self, name: str) -> bool:
|
|
157
|
+
return self._root is not None and name in self._root
|
|
158
|
+
|
|
159
|
+
@property
|
|
160
|
+
def environment(self) -> dict | None:
|
|
161
|
+
if self._root is None:
|
|
162
|
+
return None
|
|
163
|
+
if self.has("environment"):
|
|
164
|
+
return self.table("environment")
|
|
165
|
+
value = self._root.get("env", {})
|
|
166
|
+
return value if isinstance(value, dict) else None
|
|
167
|
+
|
|
168
|
+
@property
|
|
169
|
+
def kind(self) -> object:
|
|
170
|
+
env = self.environment
|
|
171
|
+
return None if env is None else env.get("kind")
|
|
172
|
+
|
|
173
|
+
@property
|
|
174
|
+
def declares_schema(self) -> bool:
|
|
175
|
+
return self.has("schema")
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
WorldManifest.ABSENT = WorldManifest(None, None, None)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
@dataclass(frozen=True)
|
|
182
|
+
class WorldTree:
|
|
183
|
+
"""A tree on disk and where the authored world lives inside it. Immutable;
|
|
184
|
+
the root decision is made once at construction."""
|
|
185
|
+
|
|
186
|
+
root: Path
|
|
187
|
+
world_root: str
|
|
188
|
+
|
|
189
|
+
@classmethod
|
|
190
|
+
def from_dir(cls, root: str | os.PathLike[str]) -> WorldTree:
|
|
191
|
+
root = Path(root)
|
|
192
|
+
nested = root / BUNDLED_WORLD_PREFIX
|
|
193
|
+
bundled = _present(root / API_BUNDLE_MANIFEST) and any(
|
|
194
|
+
_present(nested / marker) for marker in WORLD_ROOT_MARKERS
|
|
195
|
+
)
|
|
196
|
+
return cls(root, BUNDLED_WORLD_PREFIX if bundled else "")
|
|
197
|
+
|
|
198
|
+
def has(self, relative: str) -> bool:
|
|
199
|
+
return _present(self.root / relative)
|
|
200
|
+
|
|
201
|
+
def world_path(self, relative: str) -> str:
|
|
202
|
+
return self.world_root + relative
|
|
203
|
+
|
|
204
|
+
@property
|
|
205
|
+
def world(self) -> Path:
|
|
206
|
+
"""The authored world's directory."""
|
|
207
|
+
return self.root / self.world_root if self.world_root else self.root
|
|
208
|
+
|
|
209
|
+
@property
|
|
210
|
+
def is_api_bundle(self) -> bool:
|
|
211
|
+
return self.has(API_BUNDLE_MANIFEST)
|
|
212
|
+
|
|
213
|
+
@property
|
|
214
|
+
def has_schema_marker(self) -> bool:
|
|
215
|
+
return any(self.has(self.world_path(marker)) for marker in WORLD_SCHEMA_MARKERS)
|
|
216
|
+
|
|
217
|
+
@property
|
|
218
|
+
def has_connector(self) -> bool:
|
|
219
|
+
return self.has(self.world_path(CONNECTOR_SPEC))
|
|
220
|
+
|
|
221
|
+
# ── The archive: the file set a version IS ───────────────────────────────
|
|
222
|
+
#
|
|
223
|
+
# Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES)
|
|
224
|
+
# so a container hashed here resolves to the same logical version on their
|
|
225
|
+
# Environments Hub: SHA-256 over ``file:<relpath>`` + raw bytes, in sorted
|
|
226
|
+
# path order, over README.md / pyproject.toml / *.py at the root plus every
|
|
227
|
+
# non-hidden nested file outside dist, build, outputs, __pycache__ and
|
|
228
|
+
# *.egg-info. A root Gateway marker widens the root to every ordinary file
|
|
229
|
+
# (the marker itself must be hashed or a manifest-only edit dedups into the
|
|
230
|
+
# previous version and is silently discarded). Symlinks and ``.gitignore``-d
|
|
231
|
+
# paths are dropped. This is the version primary key, NOT a tarball digest.
|
|
232
|
+
# Twin: ``packages/shared/src/world/worldTree.ts`` (``isHashedPath`` +
|
|
233
|
+
# ``contentHash``); the corpus under ``conformance/worlds/`` pins both.
|
|
234
|
+
|
|
235
|
+
@property
|
|
236
|
+
def broad_root(self) -> bool:
|
|
237
|
+
return any(self.has(marker) for marker in _BROAD_ROOT_MARKERS)
|
|
238
|
+
|
|
239
|
+
def archive_files(self) -> list[Path]:
|
|
240
|
+
"""The hashed files, absolute, in sorted relative-path order."""
|
|
241
|
+
ignored = _gitignore_matcher(self.root)
|
|
242
|
+
broad = self.broad_root
|
|
243
|
+
found: dict[str, Path] = {}
|
|
244
|
+
|
|
245
|
+
def keep(path: Path) -> None:
|
|
246
|
+
if not path.is_file() or path.is_symlink():
|
|
247
|
+
return
|
|
248
|
+
relative = path.relative_to(self.root).as_posix()
|
|
249
|
+
if not is_hashed_path(relative, broad):
|
|
250
|
+
return
|
|
251
|
+
if ignored is not None and ignored(str(path)):
|
|
252
|
+
return
|
|
253
|
+
found[relative] = path
|
|
254
|
+
|
|
255
|
+
def pruned(directory: Path) -> bool:
|
|
256
|
+
"""A symlinked directory is not part of the tree: it can point anywhere."""
|
|
257
|
+
return (
|
|
258
|
+
directory.is_symlink()
|
|
259
|
+
or _skipped_dir(directory.name)
|
|
260
|
+
or (ignored is not None and ignored(str(directory)))
|
|
261
|
+
)
|
|
262
|
+
|
|
263
|
+
for entry in sorted(self.root.iterdir(), key=lambda p: p.name):
|
|
264
|
+
if entry.is_file():
|
|
265
|
+
keep(entry)
|
|
266
|
+
continue
|
|
267
|
+
if not entry.is_dir() or pruned(entry):
|
|
268
|
+
continue
|
|
269
|
+
for dirpath, dirnames, filenames in os.walk(entry):
|
|
270
|
+
here = Path(dirpath)
|
|
271
|
+
dirnames[:] = sorted(name for name in dirnames if not pruned(here / name))
|
|
272
|
+
for filename in sorted(filenames):
|
|
273
|
+
keep(here / filename)
|
|
274
|
+
return [found[relative] for relative in sorted(found)]
|
|
275
|
+
|
|
276
|
+
def hashed_paths(self) -> list[str]:
|
|
277
|
+
return [path.relative_to(self.root).as_posix() for path in self.archive_files()]
|
|
278
|
+
|
|
279
|
+
@property
|
|
280
|
+
def content_hash(self) -> str:
|
|
281
|
+
"""Streams every file; a large tree never has to fit in memory.
|
|
282
|
+
|
|
283
|
+
An unreadable file raises: a digest that silently omitted it would
|
|
284
|
+
name a tree the manifest and archive do not describe.
|
|
285
|
+
"""
|
|
286
|
+
digest = hashlib.sha256()
|
|
287
|
+
for path in self.archive_files():
|
|
288
|
+
relative = path.relative_to(self.root).as_posix()
|
|
289
|
+
digest.update(f"file:{relative}".encode("utf-8"))
|
|
290
|
+
try:
|
|
291
|
+
with open(path, "rb") as handle:
|
|
292
|
+
for chunk in iter(lambda: handle.read(_HASH_CHUNK), b""):
|
|
293
|
+
digest.update(chunk)
|
|
294
|
+
except OSError as error:
|
|
295
|
+
raise OSError(f"cannot read {relative} while hashing the tree: {error}") from error
|
|
296
|
+
return digest.hexdigest()
|
|
297
|
+
|
|
298
|
+
@cached_property
|
|
299
|
+
def manifest(self) -> WorldManifest:
|
|
300
|
+
path = self.world / WORLD_MANIFEST
|
|
301
|
+
if not _present(path):
|
|
302
|
+
return WorldManifest.ABSENT
|
|
303
|
+
try:
|
|
304
|
+
return WorldManifest.parse(path.read_text(encoding="utf-8"))
|
|
305
|
+
except (OSError, UnicodeDecodeError) as error:
|
|
306
|
+
return WorldManifest("", None, f"cannot read {WORLD_MANIFEST}: {error}")
|
|
307
|
+
|
|
308
|
+
def harbor_task_names(self) -> list[str]:
|
|
309
|
+
names = set()
|
|
310
|
+
for pattern in ("tasks/*/task.toml", "*/task.toml"):
|
|
311
|
+
for path in self.root.glob(pattern):
|
|
312
|
+
match = _HARBOR_TASK.match(path.relative_to(self.root).as_posix())
|
|
313
|
+
if match:
|
|
314
|
+
names.add(match.group(1))
|
|
315
|
+
return sorted(names)
|
|
316
|
+
|
|
317
|
+
def scenario_names(self) -> list[str]:
|
|
318
|
+
return sorted(path.parent.name for path in self.root.glob("scenarios/*/scenario.toml") if path.is_file())
|
|
319
|
+
|
|
320
|
+
def v1_evidence(self) -> Iterator[tuple[str, str]]:
|
|
321
|
+
"""``(relpath, text)`` of the files a verifiers package's API version is
|
|
322
|
+
read from: the root pyproject and every ``.py`` the archive rules keep
|
|
323
|
+
(``archive_files``: no hidden, build, dist, outputs, pycache or egg-info
|
|
324
|
+
directories)."""
|
|
325
|
+
for dirpath, dirnames, filenames in os.walk(self.root):
|
|
326
|
+
dirnames[:] = sorted(name for name in dirnames if not _skipped_dir(name))
|
|
327
|
+
for filename in sorted(filenames):
|
|
328
|
+
path = Path(dirpath) / filename
|
|
329
|
+
relative = path.relative_to(self.root).as_posix()
|
|
330
|
+
if filename.startswith(".") or not (relative == PYPROJECT or filename.endswith(".py")):
|
|
331
|
+
continue
|
|
332
|
+
try:
|
|
333
|
+
yield relative, path.read_text(encoding="utf-8", errors="replace")
|
|
334
|
+
except OSError:
|
|
335
|
+
continue
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
class World:
|
|
339
|
+
"""What a tree is, and what that means for the paths that touch it.
|
|
340
|
+
Construct through ``World.from_tree`` / ``World.from_dir`` only."""
|
|
341
|
+
|
|
342
|
+
kind: str
|
|
343
|
+
shape: str
|
|
344
|
+
|
|
345
|
+
def __init__(self, tree: WorldTree) -> None:
|
|
346
|
+
self.tree = tree
|
|
347
|
+
|
|
348
|
+
@staticmethod
|
|
349
|
+
def from_tree(tree: WorldTree) -> World:
|
|
350
|
+
if tree.is_api_bundle:
|
|
351
|
+
return ApiBundle(tree)
|
|
352
|
+
if tree.has(WORLD_MANIFEST):
|
|
353
|
+
schema = tree.has_schema_marker or tree.manifest.declares_schema
|
|
354
|
+
return SchemaWorld(tree) if schema else ToolsWorld(tree)
|
|
355
|
+
if tree.harbor_task_names():
|
|
356
|
+
return HarborBench(tree)
|
|
357
|
+
v1 = VerifiersBench.is_v1(tree)
|
|
358
|
+
if v1 or tree.has(PYPROJECT):
|
|
359
|
+
return VerifiersBench(tree, v1)
|
|
360
|
+
return PlainTree(tree)
|
|
361
|
+
|
|
362
|
+
@staticmethod
|
|
363
|
+
def from_dir(root: str | os.PathLike[str]) -> World:
|
|
364
|
+
return World.from_tree(WorldTree.from_dir(root))
|
|
365
|
+
|
|
366
|
+
@property
|
|
367
|
+
def reported_kind(self) -> str:
|
|
368
|
+
"""What ``worlds create|describe|list`` and the data commands report."""
|
|
369
|
+
return self.kind
|
|
370
|
+
|
|
371
|
+
@property
|
|
372
|
+
def runner_engine(self) -> str:
|
|
373
|
+
return "openai-compatible"
|
|
374
|
+
|
|
375
|
+
@property
|
|
376
|
+
def substrate(self) -> str:
|
|
377
|
+
"""Hosted on the World Host, or executed by the benchmark runner."""
|
|
378
|
+
return "world"
|
|
379
|
+
|
|
380
|
+
@property
|
|
381
|
+
def tools_engine(self) -> bool:
|
|
382
|
+
"""Runs on the tools engine: handlers over a per-session SQLite."""
|
|
383
|
+
return False
|
|
384
|
+
|
|
385
|
+
@property
|
|
386
|
+
def local_runtime(self) -> bool:
|
|
387
|
+
"""``gwenv`` can run the tree in-process."""
|
|
388
|
+
return True
|
|
389
|
+
|
|
390
|
+
def task_names(self) -> list[str]:
|
|
391
|
+
"""The tasks the tree defines by layout; a schema world's live in
|
|
392
|
+
its manifest."""
|
|
393
|
+
return []
|
|
394
|
+
|
|
395
|
+
@property
|
|
396
|
+
def schema_mode(self) -> str:
|
|
397
|
+
"""``schema`` (a compiled marker or a declared ``[schema]``),
|
|
398
|
+
``invalid`` (a manifest that does not parse) or ``legacy``."""
|
|
399
|
+
if self.tree.has_schema_marker:
|
|
400
|
+
return "schema"
|
|
401
|
+
if self.tree.manifest.invalid:
|
|
402
|
+
return "invalid"
|
|
403
|
+
return "schema" if self.tree.manifest.declares_schema else "legacy"
|
|
404
|
+
|
|
405
|
+
@property
|
|
406
|
+
def is_schema(self) -> bool:
|
|
407
|
+
return self.schema_mode == "schema"
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
class SchemaWorld(World):
|
|
411
|
+
"""A gateway-world/1 contract tree stored as itself."""
|
|
412
|
+
|
|
413
|
+
kind = KIND_MOCK_TOOLS
|
|
414
|
+
shape = "schema"
|
|
415
|
+
|
|
416
|
+
@property
|
|
417
|
+
def reported_kind(self) -> str:
|
|
418
|
+
return SCHEMA_MANIFEST_KIND
|
|
419
|
+
|
|
420
|
+
@property
|
|
421
|
+
def tools_engine(self) -> bool:
|
|
422
|
+
return True
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
class ToolsWorld(World):
|
|
426
|
+
"""``gateway-env.toml`` + ``db/schema.sql`` + handlers, no contract."""
|
|
427
|
+
|
|
428
|
+
kind = KIND_MOCK_TOOLS
|
|
429
|
+
shape = "legacy-tools"
|
|
430
|
+
|
|
431
|
+
@property
|
|
432
|
+
def tools_engine(self) -> bool:
|
|
433
|
+
return True
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
class ApiBundle(World):
|
|
437
|
+
"""A world packaged with ``gateway-api-world.toml`` over ``server/world/``."""
|
|
438
|
+
|
|
439
|
+
kind = KIND_API
|
|
440
|
+
shape = "api-bundle"
|
|
441
|
+
|
|
442
|
+
def task_names(self) -> list[str]:
|
|
443
|
+
return self.tree.scenario_names()
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
class ContainerBench(World):
|
|
447
|
+
@property
|
|
448
|
+
def substrate(self) -> str:
|
|
449
|
+
return "container"
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
class HarborBench(ContainerBench):
|
|
453
|
+
"""``<task>/task.toml`` or ``tasks/<task>/task.toml`` directories."""
|
|
454
|
+
|
|
455
|
+
kind = KIND_HARBOR
|
|
456
|
+
shape = "harbor"
|
|
457
|
+
|
|
458
|
+
@property
|
|
459
|
+
def runner_engine(self) -> str:
|
|
460
|
+
return "harbor"
|
|
461
|
+
|
|
462
|
+
def task_names(self) -> list[str]:
|
|
463
|
+
return self.tree.harbor_task_names()
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
class VerifiersBench(ContainerBench):
|
|
467
|
+
"""A Python package the runner installs and grades with reward functions."""
|
|
468
|
+
|
|
469
|
+
shape = "verifiers"
|
|
470
|
+
|
|
471
|
+
def __init__(self, tree: WorldTree, v1: bool = False) -> None:
|
|
472
|
+
super().__init__(tree)
|
|
473
|
+
self.kind = KIND_VERIFIERS_V1 if v1 else KIND_VERIFIERS
|
|
474
|
+
|
|
475
|
+
@staticmethod
|
|
476
|
+
def is_v1(tree: WorldTree) -> bool:
|
|
477
|
+
return any(pyproject_pins_v1(path, text) or module_uses_v1(path, text) for path, text in tree.v1_evidence())
|
|
478
|
+
|
|
479
|
+
@property
|
|
480
|
+
def local_runtime(self) -> bool:
|
|
481
|
+
return False
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
class PlainTree(VerifiersBench):
|
|
485
|
+
"""No Gateway marker, no harbor task, no Python package: not yet a world
|
|
486
|
+
and not a benchmark. The runner's fallback reads it as a verifiers
|
|
487
|
+
package, so that is the kind it answers."""
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
__all__ = [
|
|
491
|
+
"API_BUNDLE_MANIFEST",
|
|
492
|
+
"BUNDLED_WORLD_PREFIX",
|
|
493
|
+
"CONNECTOR_SPEC",
|
|
494
|
+
"PYPROJECT",
|
|
495
|
+
"WORLD_MANIFEST",
|
|
496
|
+
"WORLD_ROOT_MARKERS",
|
|
497
|
+
"WORLD_SCHEMA_MARKERS",
|
|
498
|
+
"ApiBundle",
|
|
499
|
+
"HarborBench",
|
|
500
|
+
"PlainTree",
|
|
501
|
+
"SchemaWorld",
|
|
502
|
+
"ToolsWorld",
|
|
503
|
+
"VerifiersBench",
|
|
504
|
+
"World",
|
|
505
|
+
"WorldManifest",
|
|
506
|
+
"WorldTree",
|
|
507
|
+
]
|