@withgateway/sdk 0.3.3 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -3
- package/dist/cli.js +2221 -962
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2212 -953
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +81 -19
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +79 -17
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- package/dist/index.d.mts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +903 -221
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +868 -212
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +78 -16
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +76 -14
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +692 -410
- package/dist/worlds/index.d.ts +692 -410
- package/dist/worlds/index.js +740 -197
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +736 -193
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +58 -65
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +174 -471
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
- package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +31 -116
- package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
- package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/SKILL.md +31 -6
- package/skills/connector-schema-authoring/connector-worlds.md +129 -7
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +13 -13
- package/skills/worlds-getting-started/SKILL.md +23 -23
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
package/package.json
CHANGED
|
@@ -2,11 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
import sys
|
|
6
5
|
from pathlib import Path
|
|
7
|
-
from tempfile import TemporaryDirectory
|
|
8
6
|
|
|
9
|
-
from ._bundle import load_handlers, parse_manifest
|
|
10
7
|
from .errors import WorldStartError
|
|
11
8
|
from .legacy_sqlite import materialize
|
|
12
9
|
from .schema import WorldDatabase, bundle_mode, check_bundle
|
|
@@ -29,16 +26,16 @@ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool =
|
|
|
29
26
|
|
|
30
27
|
|
|
31
28
|
def _materialize_schema(bundle: Path, destination: Path) -> dict | None:
|
|
32
|
-
from .schema.snapshot import
|
|
29
|
+
from .schema.snapshot import held_default, refuse_unheld_pin
|
|
33
30
|
|
|
34
31
|
contract = check_bundle(bundle)
|
|
35
32
|
if destination.exists():
|
|
36
33
|
raise ContractError("state_exists", "Refusing to overwrite an existing template")
|
|
37
|
-
|
|
38
|
-
if
|
|
34
|
+
held = held_default(bundle, contract)
|
|
35
|
+
if held is not None:
|
|
39
36
|
# The compiled snapshot holds rows this contract may open; whether they are proven is the caller's (ProvenTemplate).
|
|
40
|
-
WorldDatabase.clone_file(
|
|
41
|
-
return
|
|
37
|
+
WorldDatabase.clone_file(held[0], destination)
|
|
38
|
+
return held[1]
|
|
42
39
|
refuse_unheld_pin(bundle, contract)
|
|
43
40
|
initial = read_json(bundle / "data/initial.json")
|
|
44
41
|
refuse_initial_rows(contract, initial)
|
|
@@ -102,20 +99,3 @@ def refuse_initial_rows(contract: Contract, initial: object) -> None:
|
|
|
102
99
|
}
|
|
103
100
|
row = initial["mutations"][first["index"]].get("value")
|
|
104
101
|
raise_shape_refusal(contract, first, row, summary, context, first["pointer"])
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
def validate_schema_materialization(bundle: Path) -> None:
|
|
108
|
-
"""Validate compiled artifacts and initial state without retaining a database."""
|
|
109
|
-
bundle = Path(bundle)
|
|
110
|
-
write_bytecode = sys.dont_write_bytecode
|
|
111
|
-
sys.dont_write_bytecode = True
|
|
112
|
-
try:
|
|
113
|
-
load_handlers(bundle, parse_manifest(bundle))
|
|
114
|
-
finally:
|
|
115
|
-
sys.dont_write_bytecode = write_bytecode
|
|
116
|
-
with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
|
|
117
|
-
materialize_template(
|
|
118
|
-
bundle,
|
|
119
|
-
Path(directory) / "template.db",
|
|
120
|
-
require_sql=True,
|
|
121
|
-
)
|
|
@@ -1,11 +1,3 @@
|
|
|
1
|
-
"""Worlds — deterministic instances of a mock-tools environment's seeded state.
|
|
2
|
-
|
|
3
|
-
A world is one database file, branched (file-copied) from the environment's
|
|
4
|
-
prepared template, plus the seams that let an agent's tool calls execute
|
|
5
|
-
against it: ``execute``, ``as_registry`` (the exact replay ``ToolStubRegistry``
|
|
6
|
-
mapping contract), ``wrap_tools``, and grading (``verify`` / ``state``).
|
|
7
|
-
"""
|
|
8
|
-
|
|
9
1
|
from __future__ import annotations
|
|
10
2
|
|
|
11
3
|
import time
|
|
@@ -26,30 +18,24 @@ from .score import Score
|
|
|
26
18
|
|
|
27
19
|
if TYPE_CHECKING: # pragma: no cover
|
|
28
20
|
from .core import Environment
|
|
21
|
+
from .schema.journal import JournalUse, WorldJournal
|
|
29
22
|
from .schema.session_files import ProvenTemplate, SessionExport
|
|
30
23
|
|
|
31
24
|
|
|
32
25
|
@dataclass
|
|
33
26
|
class VerifierResult:
|
|
34
|
-
"""
|
|
35
|
-
scores are their own category, never coerced to 0) and yields
|
|
36
|
-
``passed=None``; otherwise ``passed = score >= 1.0``."""
|
|
27
|
+
"""``passed`` is ``score >= 1.0``; a ``None`` score is ungraded, never 0, and has ``passed=None``."""
|
|
37
28
|
|
|
38
29
|
name: str
|
|
39
30
|
passed: Optional[bool]
|
|
40
31
|
score: Optional[float]
|
|
41
32
|
detail: str = ""
|
|
42
33
|
rewards: Dict[str, float] = field(default_factory=dict)
|
|
34
|
+
closed: Optional[str] = None
|
|
43
35
|
|
|
44
36
|
|
|
45
37
|
class SqlVerifier:
|
|
46
|
-
"""
|
|
47
|
-
rule every reader applies — ``schema check``, a local session's grade, the
|
|
48
|
-
World Host's grade. Statements run in order; the score is the first column
|
|
49
|
-
of the first row of the LAST statement that returns rows (or could). No
|
|
50
|
-
rows / NULL → ``None``, never coerced to 0; a value that is not a number
|
|
51
|
-
is a :class:`VerifierError` naming it, and so is a score that is not one
|
|
52
|
-
from 0 to 1 (:class:`Score`; earlier statements may count rows)."""
|
|
38
|
+
"""Every reader's score rule, pinned by ``sql-verifier-vectors.json``: NULL or no rows is ``None``, never 0."""
|
|
53
39
|
|
|
54
40
|
def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
|
|
55
41
|
self.name = name[:-4] if name.endswith(".sql") else name
|
|
@@ -57,14 +43,9 @@ class SqlVerifier:
|
|
|
57
43
|
|
|
58
44
|
@classmethod
|
|
59
45
|
def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
|
|
60
|
-
"""``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
|
|
61
46
|
return cls(path.stem, path.read_text(encoding="utf-8"), split)
|
|
62
47
|
|
|
63
48
|
def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
|
|
64
|
-
"""Run every statement through ``execute`` (rows, or ``None`` for a
|
|
65
|
-
statement that returns none, e.g. a temp-table DDL) and answer
|
|
66
|
-
``(score, sql)`` — the score and the statement it came from, both
|
|
67
|
-
``None`` when nothing returned rows."""
|
|
68
49
|
value: Any = None
|
|
69
50
|
last_sql: Optional[str] = None
|
|
70
51
|
for statement in self.statements:
|
|
@@ -92,18 +73,12 @@ _NO_INPUT = object()
|
|
|
92
73
|
|
|
93
74
|
|
|
94
75
|
def _stub_input(tool_input: Any, kwargs: Dict[str, Any]) -> Any:
|
|
95
|
-
"""One rule for callable seams: an explicit positional input (even None)
|
|
96
|
-
is the input; keyword arguments are the input; nothing means omitted."""
|
|
97
76
|
if tool_input is not _NO_INPUT:
|
|
98
77
|
return tool_input
|
|
99
78
|
return kwargs if kwargs else _NO_INPUT
|
|
100
79
|
|
|
101
80
|
|
|
102
81
|
class WorldRegistry(StubRegistryMapping):
|
|
103
|
-
"""``world.as_registry()`` — the replay registry contract (mapping with
|
|
104
|
-
``__missing__``, ``lookup``, ``call_log``/``called_names``) backed by the
|
|
105
|
-
live env world instead of recordings."""
|
|
106
|
-
|
|
107
82
|
def __init__(self, world: "World") -> None:
|
|
108
83
|
self._world = world
|
|
109
84
|
|
|
@@ -129,14 +104,6 @@ class WorldRegistry(StubRegistryMapping):
|
|
|
129
104
|
|
|
130
105
|
|
|
131
106
|
class World:
|
|
132
|
-
"""One live, isolated instance of the environment's seeded state.
|
|
133
|
-
|
|
134
|
-
``template`` is a version's :class:`~.schema.session_files.ProvenTemplate`:
|
|
135
|
-
the world starts from it, and resets to it, with the contract and DDL check
|
|
136
|
-
and no row audit. Without one the world copies its environment's own
|
|
137
|
-
template and audits every row on each open and reset; a ``snapshot`` file
|
|
138
|
-
to start from is always audited."""
|
|
139
|
-
|
|
140
107
|
def __init__(
|
|
141
108
|
self,
|
|
142
109
|
env: "Environment",
|
|
@@ -147,13 +114,17 @@ class World:
|
|
|
147
114
|
) -> None:
|
|
148
115
|
self.env = env
|
|
149
116
|
self.id = world_id or uuid.uuid4().hex[:8]
|
|
150
|
-
self.db_path: Path = env._worlds_dir
|
|
117
|
+
self.db_path: Path = self.database_file(env._worlds_dir, self.id)
|
|
151
118
|
self.call_log: List[Dict[str, Any]] = []
|
|
152
119
|
self._template = self._proven(template)
|
|
153
120
|
self.contract = template.contract if template is not None else self._bundle_contract()
|
|
154
121
|
source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
|
|
155
122
|
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
156
123
|
|
|
124
|
+
@staticmethod
|
|
125
|
+
def database_file(directory: Path, world_id: str) -> Path:
|
|
126
|
+
return Path(directory) / f"world-{world_id}.db"
|
|
127
|
+
|
|
157
128
|
@staticmethod
|
|
158
129
|
def _proven(template: Any) -> Any:
|
|
159
130
|
if template is None:
|
|
@@ -168,18 +139,16 @@ class World:
|
|
|
168
139
|
return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
|
|
169
140
|
|
|
170
141
|
def _seed(self) -> "tuple[Path, bool]":
|
|
171
|
-
"""The file a fresh or reset world copies, and whether its rows are audited."""
|
|
172
142
|
if self._template is None:
|
|
173
143
|
return Path(self.env._template_db), True
|
|
174
144
|
return self._template.path, False
|
|
175
145
|
|
|
176
146
|
@property
|
|
177
147
|
def store(self):
|
|
178
|
-
"""
|
|
148
|
+
"""``None`` for a contract-less mock-tools world."""
|
|
179
149
|
return self._backing.store
|
|
180
150
|
|
|
181
151
|
def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
182
|
-
"""Execute atomically in schema mode, validating both input and output."""
|
|
183
152
|
from .schema.validation import validate
|
|
184
153
|
|
|
185
154
|
handler = self.env._handlers.get(tool_name)
|
|
@@ -236,14 +205,10 @@ class World:
|
|
|
236
205
|
)
|
|
237
206
|
|
|
238
207
|
def as_registry(self) -> WorldRegistry:
|
|
239
|
-
"""
|
|
240
|
-
identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
|
|
208
|
+
"""Drop-in for agent tool layers, with the contract of replay's ``ToolStubRegistry.as_registry()``."""
|
|
241
209
|
return WorldRegistry(self)
|
|
242
210
|
|
|
243
211
|
def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
|
|
244
|
-
"""Substitute env-served callables by name in a list/dict of tools;
|
|
245
|
-
everything not served (or not env-routed) passes through unchanged."""
|
|
246
|
-
|
|
247
212
|
def routed_to_env(name: Optional[str]) -> bool:
|
|
248
213
|
return bool(name) and name in self.env._handlers and self.env.resolve_route(name) == "env"
|
|
249
214
|
|
|
@@ -265,7 +230,6 @@ class World:
|
|
|
265
230
|
return wrapped
|
|
266
231
|
|
|
267
232
|
def reset(self) -> None:
|
|
268
|
-
"""Back to the seed, in place (same world instance)."""
|
|
269
233
|
if self._template is None:
|
|
270
234
|
self._refuse_a_changed_contract()
|
|
271
235
|
source, audit = self._seed()
|
|
@@ -281,14 +245,11 @@ class World:
|
|
|
281
245
|
raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
|
|
282
246
|
|
|
283
247
|
def restore(self, source: Union[str, Path]) -> None:
|
|
284
|
-
"""
|
|
285
|
-
A schema-backed world audits it against its contract row by row, as it would
|
|
286
|
-
any file it did not write."""
|
|
248
|
+
"""Audited row by row: the file is not one this store wrote."""
|
|
287
249
|
self._relay(Path(source), audit=True)
|
|
288
250
|
|
|
289
251
|
def resume(self, export: "SessionExport") -> None:
|
|
290
|
-
"""
|
|
291
|
-
the sha256 recorded when the store wrote them, without a second row audit."""
|
|
252
|
+
"""No second row audit: a :class:`SessionExport` is digest-verified or this session's own recovered store."""
|
|
292
253
|
from .schema.session_files import SessionExport
|
|
293
254
|
|
|
294
255
|
self._relay(SessionExport.required(export).path, audit=False)
|
|
@@ -298,39 +259,43 @@ class World:
|
|
|
298
259
|
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
299
260
|
|
|
300
261
|
def snapshot(self, destination: Union[str, Path]) -> Path:
|
|
301
|
-
"""Pin this world's current state to a file (for debugging fixtures)."""
|
|
302
262
|
return self._backing.snapshot(Path(destination))
|
|
303
263
|
|
|
304
264
|
def close(self) -> None:
|
|
305
265
|
self._backing.close()
|
|
306
266
|
|
|
307
267
|
def set_task_context(self, scenario_id: str) -> bool:
|
|
308
|
-
"""
|
|
268
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
309
269
|
return self._backing.set_task_context(scenario_id)
|
|
310
270
|
|
|
311
271
|
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
312
|
-
"""
|
|
272
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
313
273
|
return self._backing.set_run_parameters(parameters)
|
|
314
274
|
|
|
315
275
|
def record_conversation_event(
|
|
316
|
-
self,
|
|
276
|
+
self,
|
|
277
|
+
scenario_id: str,
|
|
278
|
+
user_turn_index: int,
|
|
279
|
+
event_type: str,
|
|
280
|
+
actor: str,
|
|
281
|
+
name: Optional[str],
|
|
282
|
+
payload_json: str,
|
|
317
283
|
) -> bool:
|
|
318
|
-
"""
|
|
284
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
319
285
|
return self._backing.record_conversation_event(
|
|
320
286
|
scenario_id, user_turn_index, event_type, actor, name, payload_json
|
|
321
287
|
)
|
|
322
288
|
|
|
323
289
|
def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
|
|
324
|
-
"""Read-only SQL against the world's db (SELECT/WITH only)."""
|
|
325
290
|
return self._backing.rows(sql, params)
|
|
326
291
|
|
|
327
|
-
def verify(self, name: str) -> VerifierResult:
|
|
328
|
-
"""
|
|
292
|
+
def verify(self, name: str, journal: Optional["WorldJournal"] = None) -> VerifierResult:
|
|
293
|
+
"""NULL or no rows scores ``None``, never 0. A verifier that read the journal fails closed when none was
|
|
294
|
+
recorded, and on an incomplete one unless ``gateway-env.toml`` declares
|
|
295
|
+
``[verifiers.<name>] accepts_incomplete_journal = true``."""
|
|
296
|
+
from .schema.journal import JournalDatabase, WorldJournal
|
|
297
|
+
from .schema.validation import ContractError
|
|
329
298
|
|
|
330
|
-
:class:`SqlVerifier` is the rule: the first column of the first row of
|
|
331
|
-
the LAST row-returning statement. NULL / no rows → score None (passed
|
|
332
|
-
None) — never coerced to 0.
|
|
333
|
-
"""
|
|
334
299
|
verifier_name = name[:-4] if name.endswith(".sql") else name
|
|
335
300
|
path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
|
|
336
301
|
if not path.is_file():
|
|
@@ -340,7 +305,20 @@ class World:
|
|
|
340
305
|
def execute(statement: str) -> Optional[List[Any]]:
|
|
341
306
|
return self._backing.verifier_rows(verifier_name, statement)
|
|
342
307
|
|
|
343
|
-
|
|
308
|
+
database = JournalDatabase(journal or WorldJournal.unrecorded(), self.db_path.parent / "journal")
|
|
309
|
+
verifier = SqlVerifier.read(path, self._backing.split_statements)
|
|
310
|
+
with self._backing.journal(database) as used:
|
|
311
|
+
try:
|
|
312
|
+
score, last_sql = verifier.score(execute)
|
|
313
|
+
except (ContractError, VerifierError):
|
|
314
|
+
closed = self._closed_on(verifier_name, database.journal, used(verifier.statements))
|
|
315
|
+
if closed is None:
|
|
316
|
+
raise
|
|
317
|
+
return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
|
|
318
|
+
use = used(verifier.statements)
|
|
319
|
+
closed = self._closed_on(verifier_name, database.journal, use)
|
|
320
|
+
if closed is not None:
|
|
321
|
+
return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
|
|
344
322
|
if last_sql is None:
|
|
345
323
|
detail = "no row-returning statement — score is null"
|
|
346
324
|
elif score is None:
|
|
@@ -349,3 +327,18 @@ class World:
|
|
|
349
327
|
detail = f"score {score} from: {last_sql}"
|
|
350
328
|
passed = None if score is None else score >= 1.0
|
|
351
329
|
return VerifierResult(name=verifier_name, passed=passed, score=score, detail=detail)
|
|
330
|
+
|
|
331
|
+
def _closed_on(self, verifier: str, journal: "WorldJournal", use: "JournalUse") -> Optional[str]:
|
|
332
|
+
from .schema.journal import accepting_incomplete
|
|
333
|
+
|
|
334
|
+
gap = journal.gap(use)
|
|
335
|
+
if gap is None:
|
|
336
|
+
return None
|
|
337
|
+
if not journal.recorded:
|
|
338
|
+
return f"{gap}: verifier '{verifier}' reads the journal"
|
|
339
|
+
if verifier in accepting_incomplete(self.env.bundle_path):
|
|
340
|
+
return None
|
|
341
|
+
return (
|
|
342
|
+
f"{gap}: verifier '{verifier}' reads the journal; declare "
|
|
343
|
+
f"[verifiers.{verifier}] accepts_incomplete_journal = true to grade an incomplete one"
|
|
344
|
+
)
|
|
@@ -1,29 +1,25 @@
|
|
|
1
|
-
"""What a :class:`~gatewaysdk.environment._world.World`'s state lives in: a
|
|
2
|
-
contract-bound world database, or the raw SQLite file of a contract-less
|
|
3
|
-
mock-tools world. The world asks its backing and never branches on which."""
|
|
4
|
-
|
|
5
1
|
from __future__ import annotations
|
|
6
2
|
|
|
7
3
|
from abc import ABC, abstractmethod
|
|
4
|
+
from collections.abc import Callable
|
|
8
5
|
from contextlib import AbstractContextManager
|
|
9
6
|
from pathlib import Path
|
|
10
|
-
from typing import Any, Dict, List, Optional
|
|
7
|
+
from typing import TYPE_CHECKING, Any, Dict, List, Optional
|
|
11
8
|
|
|
12
9
|
from .schema.compiler import Contract
|
|
13
10
|
from .schema.database import WorldDatabase
|
|
14
11
|
from .schema.validation import ContractError
|
|
15
12
|
|
|
13
|
+
if TYPE_CHECKING:
|
|
14
|
+
from .schema.journal import JournalDatabase, JournalUse
|
|
16
15
|
|
|
17
|
-
class WorldBacking(ABC):
|
|
18
|
-
"""One world's open state file."""
|
|
19
16
|
|
|
17
|
+
class WorldBacking(ABC):
|
|
20
18
|
store: Optional[WorldDatabase] = None
|
|
21
19
|
|
|
22
20
|
@staticmethod
|
|
23
21
|
def branch(source: Path, path: Path, contract: Optional[Contract], *, audit: bool = True) -> "WorldBacking":
|
|
24
|
-
"""
|
|
25
|
-
``path`` is removed again when the copy does not open. ``audit=False`` is for a
|
|
26
|
-
source whose rows are already proven (a version's template, a verified export)."""
|
|
22
|
+
"""``audit=False`` only for a source whose rows are already proven: a version's template, a verified export."""
|
|
27
23
|
from .legacy_sqlite import LegacySQLiteBacking
|
|
28
24
|
|
|
29
25
|
WorldDatabase.clone_file(Path(source), Path(path))
|
|
@@ -36,34 +32,34 @@ class WorldBacking(ABC):
|
|
|
36
32
|
raise
|
|
37
33
|
|
|
38
34
|
@abstractmethod
|
|
39
|
-
def transaction(self) -> AbstractContextManager[Any]:
|
|
40
|
-
"""The unit one tool call runs in."""
|
|
35
|
+
def transaction(self) -> AbstractContextManager[Any]: ...
|
|
41
36
|
|
|
42
37
|
@abstractmethod
|
|
43
|
-
def handler_connection(self) -> Any:
|
|
44
|
-
"""What a tool handler receives as ``conn``."""
|
|
38
|
+
def handler_connection(self) -> Any: ...
|
|
45
39
|
|
|
46
40
|
@abstractmethod
|
|
47
41
|
def split_statements(self, script: str) -> List[str]: ...
|
|
48
42
|
|
|
49
43
|
@abstractmethod
|
|
50
44
|
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
51
|
-
"""Read-only SQL
|
|
45
|
+
"""Read-only SQL: every backing refuses a write here (``world.state``)."""
|
|
52
46
|
|
|
53
47
|
@abstractmethod
|
|
54
48
|
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
55
|
-
"""
|
|
49
|
+
"""``None`` when the statement projects no columns, which the score skips; ``[]`` (no rows) scores ``None``."""
|
|
50
|
+
|
|
51
|
+
@abstractmethod
|
|
52
|
+
def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
|
|
53
|
+
"""Yields what a verifier's statements read of ``database``, so one that read an incomplete journal fails closed."""
|
|
56
54
|
|
|
57
55
|
@abstractmethod
|
|
58
56
|
def snapshot(self, destination: Path) -> Path: ...
|
|
59
57
|
|
|
60
58
|
@abstractmethod
|
|
61
|
-
def set_task_context(self, scenario_id: str) -> bool:
|
|
62
|
-
"""Name the active task; ``False`` when the world does not declare the table."""
|
|
59
|
+
def set_task_context(self, scenario_id: str) -> bool: ...
|
|
63
60
|
|
|
64
61
|
@abstractmethod
|
|
65
|
-
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
66
|
-
"""Bind the run's conditions; ``False`` when the world does not declare the table."""
|
|
62
|
+
def set_run_parameters(self, parameters: Dict[str, str]) -> bool: ...
|
|
67
63
|
|
|
68
64
|
@abstractmethod
|
|
69
65
|
def record_conversation_event(
|
|
@@ -74,16 +70,13 @@ class WorldBacking(ABC):
|
|
|
74
70
|
actor: str,
|
|
75
71
|
name: Optional[str],
|
|
76
72
|
payload_json: str,
|
|
77
|
-
) -> bool:
|
|
78
|
-
"""Log one turn event; ``False`` when the world does not declare the table."""
|
|
73
|
+
) -> bool: ...
|
|
79
74
|
|
|
80
75
|
@abstractmethod
|
|
81
76
|
def close(self) -> None: ...
|
|
82
77
|
|
|
83
78
|
|
|
84
79
|
class ContractBacking(WorldBacking):
|
|
85
|
-
"""A schema world's state: the world database its contract compiled to."""
|
|
86
|
-
|
|
87
80
|
def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
|
|
88
81
|
self.store = WorldDatabase.open(path, contract, audit=audit)
|
|
89
82
|
|
|
@@ -99,6 +92,9 @@ class ContractBacking(WorldBacking):
|
|
|
99
92
|
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
100
93
|
return [dict(row) for row in self.store.query(sql, params)]
|
|
101
94
|
|
|
95
|
+
def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
|
|
96
|
+
return database.attached(self.store)
|
|
97
|
+
|
|
102
98
|
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
103
99
|
try:
|
|
104
100
|
return self.store.query(statement, private=True)
|
|
@@ -153,7 +153,6 @@ class Environment:
|
|
|
153
153
|
|
|
154
154
|
_install_ambient_interceptor()
|
|
155
155
|
|
|
156
|
-
# -- kind guards -----------------------------------------------------
|
|
157
156
|
|
|
158
157
|
def _require_mock(self, operation: str) -> None:
|
|
159
158
|
if self.kind != KIND_MOCK_TOOLS:
|
|
@@ -172,7 +171,6 @@ class Environment:
|
|
|
172
171
|
"the registry/execute seams instead."
|
|
173
172
|
)
|
|
174
173
|
|
|
175
|
-
# -- mock-tools: template + worlds ------------------------------------
|
|
176
174
|
|
|
177
175
|
def _build_template_db(self) -> None:
|
|
178
176
|
from ._materialize import materialize_template
|
|
@@ -235,7 +233,6 @@ class Environment:
|
|
|
235
233
|
self._implicit_world = World(self)
|
|
236
234
|
return self._implicit_world
|
|
237
235
|
|
|
238
|
-
# -- delegates to the implicit world ----------------------------------
|
|
239
236
|
|
|
240
237
|
def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
241
238
|
return self._ensure_world().execute(tool_name, tool_input)
|
|
@@ -255,7 +252,6 @@ class Environment:
|
|
|
255
252
|
def reset(self) -> None:
|
|
256
253
|
self._ensure_world().reset()
|
|
257
254
|
|
|
258
|
-
# -- harbor ----------------------------------------------------------
|
|
259
255
|
|
|
260
256
|
@property
|
|
261
257
|
def tasks(self) -> List[HarborTask]:
|
|
@@ -284,7 +280,6 @@ class Environment:
|
|
|
284
280
|
self._docker_runtime = CliDockerRuntime()
|
|
285
281
|
return self._docker_runtime
|
|
286
282
|
|
|
287
|
-
# -- routing ----------------------------------------------------------
|
|
288
283
|
|
|
289
284
|
def resolve_route(self, tool_name: str) -> str:
|
|
290
285
|
"""Route map > effects default (read→default_route, write→env,
|
|
@@ -339,11 +334,6 @@ def _effects_of(tool_name: str) -> Optional[str]:
|
|
|
339
334
|
return None
|
|
340
335
|
|
|
341
336
|
|
|
342
|
-
# ---------------------------------------------------------------------------
|
|
343
|
-
# Ambient interception — the define_tool wrapper's hook (spec §4.4, rung 1.5)
|
|
344
|
-
# ---------------------------------------------------------------------------
|
|
345
|
-
|
|
346
|
-
|
|
347
337
|
def _ambient_intercept(name: str, fn: Any, args: tuple, kwargs: dict) -> Any:
|
|
348
338
|
"""Called by the ``define_tool`` wrapper on every invocation. No active
|
|
349
339
|
world → miss sentinel (the wrapper calls the original fn — the identity
|
|
@@ -410,11 +400,6 @@ def _install_ambient_interceptor() -> None:
|
|
|
410
400
|
_interceptor_installed = True
|
|
411
401
|
|
|
412
402
|
|
|
413
|
-
# ---------------------------------------------------------------------------
|
|
414
|
-
# init
|
|
415
|
-
# ---------------------------------------------------------------------------
|
|
416
|
-
|
|
417
|
-
|
|
418
403
|
def init_from_path(
|
|
419
404
|
path: Union[str, Path],
|
|
420
405
|
*,
|
|
@@ -494,7 +479,7 @@ def init(
|
|
|
494
479
|
|
|
495
480
|
bench = GatewayBenchmarkClient(resolved_host, resolved_public, resolved_secret)
|
|
496
481
|
try:
|
|
497
|
-
details = bench.resolve_version(slug, version
|
|
482
|
+
details = bench.resolve_version(slug, version)
|
|
498
483
|
except BenchmarkPushError as error:
|
|
499
484
|
raise EnvironmentNotReady(f"no runnable version for '{slug}': {error}") from None
|
|
500
485
|
content_hash = details.get("contentHash")
|
|
@@ -1,7 +1,4 @@
|
|
|
1
|
-
"""
|
|
2
|
-
``db/schema.sql`` + ``db/seed.sql``. Its handlers write SQL through ``conn`` and
|
|
3
|
-
its seeds are SQL text, so it is SQLite by definition and stays outside the
|
|
4
|
-
contract-bound :class:`~gatewaysdk.environment.schema.database.WorldDatabase`."""
|
|
1
|
+
"""Handlers write SQL through ``conn`` and seeds are SQL text, so a mock-tools world is SQLite by definition."""
|
|
5
2
|
|
|
6
3
|
from __future__ import annotations
|
|
7
4
|
|
|
@@ -10,7 +7,7 @@ import sqlite3
|
|
|
10
7
|
import tempfile
|
|
11
8
|
from contextlib import AbstractContextManager, nullcontext
|
|
12
9
|
from pathlib import Path
|
|
13
|
-
from typing import Any, Dict, List, Optional
|
|
10
|
+
from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
|
|
14
11
|
|
|
15
12
|
from .backing import WorldBacking
|
|
16
13
|
from .errors import VerifierError, WorldStartError
|
|
@@ -19,6 +16,9 @@ from .schema.database import SQLiteWorldDatabase
|
|
|
19
16
|
from .schema.database.runtime_rows import CONVERSATION_EVENTS, RUN_PARAMETERS, TASK_CONTEXT, RuntimeRows, Statement
|
|
20
17
|
from .schema.validation import fail
|
|
21
18
|
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
from .schema.journal import JournalDatabase, JournalUse
|
|
21
|
+
|
|
22
22
|
MODES = ("append", "replace")
|
|
23
23
|
#: Undoing a failed runtime write: the outermost savepoint is the transaction, and its RELEASE is the
|
|
24
24
|
#: commit, so a busy RELEASE must be answered with ROLLBACK or the connection stays inside it.
|
|
@@ -67,12 +67,7 @@ def _check_row(columns: List[str], table: str, index: int, row: dict) -> None:
|
|
|
67
67
|
|
|
68
68
|
|
|
69
69
|
def seed_statements(columns: Dict[str, List[str]], rows: Rows, mode: str = "append") -> List[str]:
|
|
70
|
-
"""
|
|
71
|
-
|
|
72
|
-
``append`` writes ``INSERT OR REPLACE`` (an upsert by the table's own
|
|
73
|
-
primary key); ``replace`` prefixes ``DELETE FROM`` for each named table and
|
|
74
|
-
writes plain inserts.
|
|
75
|
-
"""
|
|
70
|
+
"""``append`` upserts by each table's own primary key; ``replace`` first empties only the tables ``rows`` names."""
|
|
76
71
|
if mode not in MODES:
|
|
77
72
|
fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
|
|
78
73
|
_check_rows(columns, rows)
|
|
@@ -94,7 +89,6 @@ def _insert(verb: str, table: str, row: dict) -> str:
|
|
|
94
89
|
|
|
95
90
|
|
|
96
91
|
def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
|
|
97
|
-
"""Every user table's columns, in declaration order."""
|
|
98
92
|
tables = [
|
|
99
93
|
row[0]
|
|
100
94
|
for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
|
|
@@ -103,11 +97,6 @@ def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
|
|
|
103
97
|
|
|
104
98
|
|
|
105
99
|
def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> Dict[str, int]:
|
|
106
|
-
"""Execute the seed for ``rows`` against a live sqlite, in one transaction.
|
|
107
|
-
|
|
108
|
-
Columns come from the live database itself. A refused row rolls the whole
|
|
109
|
-
seed back. Returns the row count of every touched table afterwards.
|
|
110
|
-
"""
|
|
111
100
|
statements = seed_statements(columns_of(conn), rows, mode)
|
|
112
101
|
try:
|
|
113
102
|
conn.execute("BEGIN")
|
|
@@ -121,7 +110,6 @@ def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> D
|
|
|
121
110
|
|
|
122
111
|
|
|
123
112
|
def schema_columns(schema: Path) -> Dict[str, List[str]]:
|
|
124
|
-
"""The tables and columns ``db/schema.sql`` declares, loaded in memory."""
|
|
125
113
|
with sqlite3.connect(":memory:") as probe:
|
|
126
114
|
try:
|
|
127
115
|
probe.executescript(schema.read_text(encoding="utf-8"))
|
|
@@ -131,7 +119,6 @@ def schema_columns(schema: Path) -> Dict[str, List[str]]:
|
|
|
131
119
|
|
|
132
120
|
|
|
133
121
|
def materialize(schema: Path, seed: Path, destination: Path) -> None:
|
|
134
|
-
"""``db/schema.sql`` then ``db/seed.sql`` (each when present) into a new file."""
|
|
135
122
|
conn = sqlite3.connect(destination)
|
|
136
123
|
try:
|
|
137
124
|
if schema.is_file():
|
|
@@ -146,8 +133,7 @@ def materialize(schema: Path, seed: Path, destination: Path) -> None:
|
|
|
146
133
|
|
|
147
134
|
|
|
148
135
|
class LegacySQLiteBacking(WorldBacking):
|
|
149
|
-
"""
|
|
150
|
-
autocommit, across threads (agents call tools from worker threads)."""
|
|
136
|
+
"""Autocommit, shared across threads: agents call tools from worker threads."""
|
|
151
137
|
|
|
152
138
|
def __init__(self, path: Path, contract: Optional[Contract] = None) -> None:
|
|
153
139
|
self.path = Path(path)
|
|
@@ -172,6 +158,12 @@ class LegacySQLiteBacking(WorldBacking):
|
|
|
172
158
|
)
|
|
173
159
|
return [dict(row) for row in self._conn.execute(sql, params).fetchall()]
|
|
174
160
|
|
|
161
|
+
def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
|
|
162
|
+
"""A legacy tools world keeps no journal: its verifiers read none."""
|
|
163
|
+
from .schema.journal import JournalUse
|
|
164
|
+
|
|
165
|
+
return nullcontext(lambda statements: JournalUse.none())
|
|
166
|
+
|
|
175
167
|
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
176
168
|
try:
|
|
177
169
|
cursor = self._conn.execute(statement)
|
|
@@ -197,11 +189,9 @@ class LegacySQLiteBacking(WorldBacking):
|
|
|
197
189
|
}
|
|
198
190
|
|
|
199
191
|
def seed(self, rows: Rows, mode: str = "append") -> Dict[str, int]:
|
|
200
|
-
""":func:`seed_sqlite` into this world's live file."""
|
|
201
192
|
return seed_sqlite(self._conn, rows, mode)
|
|
202
193
|
|
|
203
194
|
def entities(self) -> Rows:
|
|
204
|
-
"""Every table's rows, tables by name."""
|
|
205
195
|
return {
|
|
206
196
|
table: [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")]
|
|
207
197
|
for table in sorted(self.columns())
|
|
@@ -218,7 +208,6 @@ class LegacySQLiteBacking(WorldBacking):
|
|
|
218
208
|
return found.fetchone() is not None
|
|
219
209
|
|
|
220
210
|
def _write_runtime(self, table: str, statements: list[Statement]) -> bool:
|
|
221
|
-
"""The store's runtime statements, all or none, where the world declares ``table``."""
|
|
222
211
|
if not self._declares(table):
|
|
223
212
|
return False
|
|
224
213
|
outer = not self._conn.in_transaction
|
|
@@ -261,15 +250,13 @@ class LegacySQLiteBacking(WorldBacking):
|
|
|
261
250
|
|
|
262
251
|
|
|
263
252
|
class LegacyVerifiers:
|
|
264
|
-
"""
|
|
265
|
-
against its own copy of the seeded state, so no verifier sees another's writes."""
|
|
253
|
+
"""Each verifier scores its own copy of the seeded state, so no verifier sees another's writes."""
|
|
266
254
|
|
|
267
255
|
def __init__(self, root: Path) -> None:
|
|
268
256
|
self.root = Path(root)
|
|
269
257
|
self.paths = sorted((self.root / "verifiers").glob("*.sql"))
|
|
270
258
|
|
|
271
259
|
def scores(self) -> List[Dict[str, Any]]:
|
|
272
|
-
"""``{path, ok, score[, error]}`` per verifier; a world that does not build fails every one."""
|
|
273
260
|
schema = self.root / "db" / "schema.sql"
|
|
274
261
|
if not schema.is_file():
|
|
275
262
|
return [self._refused(path, "db/schema.sql is missing") for path in self.paths]
|