@withgateway/sdk 0.3.1 → 0.3.3
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 +2880 -2032
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2982 -2135
- 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 +180 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +172 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
- package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1309 -540
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1287 -532
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +177 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +169 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +69 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +69 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +249 -120
- package/dist/worlds/index.d.ts +249 -120
- package/dist/worlds/index.js +1240 -484
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1231 -476
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -514
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +19 -11
- package/skills/connector-schema-authoring/connector-worlds.md +13 -4
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +14 -14
- package/skills/worlds-getting-started/SKILL.md +12 -12
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
|
@@ -1,18 +1,15 @@
|
|
|
1
1
|
"""Worlds — deterministic instances of a mock-tools environment's seeded state.
|
|
2
2
|
|
|
3
|
-
A world is one
|
|
4
|
-
prepared template
|
|
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
5
|
against it: ``execute``, ``as_registry`` (the exact replay ``ToolStubRegistry``
|
|
6
6
|
mapping contract), ``wrap_tools``, and grading (``verify`` / ``state``).
|
|
7
7
|
"""
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
10
10
|
|
|
11
|
-
import shutil
|
|
12
|
-
import sqlite3
|
|
13
11
|
import time
|
|
14
12
|
import uuid
|
|
15
|
-
from contextlib import nullcontext
|
|
16
13
|
from dataclasses import dataclass, field
|
|
17
14
|
from pathlib import Path
|
|
18
15
|
from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Union
|
|
@@ -20,19 +17,16 @@ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional,
|
|
|
20
17
|
try:
|
|
21
18
|
from ..replay import StubRegistryMapping
|
|
22
19
|
except ImportError:
|
|
23
|
-
#
|
|
24
|
-
# that only needs worlds + verifiers (e.g. the benchmark runner's
|
|
25
|
-
# mock_tools engine, which vendors just this ``environment`` subpackage —
|
|
26
|
-
# no ``replay``) still imports ``World``/``verify``; only ``as_registry``
|
|
27
|
-
# (the replay registry contract) is unavailable there, and it is never
|
|
28
|
-
# called on that path. The full SDK always has ``replay``, so real
|
|
29
|
-
# behaviour is unchanged.
|
|
20
|
+
# The benchmark runner vendors only environment/ (no replay, no requests) and never calls as_registry.
|
|
30
21
|
StubRegistryMapping = dict # type: ignore[assignment,misc]
|
|
31
22
|
from . import runtime
|
|
23
|
+
from .backing import WorldBacking
|
|
32
24
|
from .errors import ToolRouteError, VerifierError
|
|
25
|
+
from .score import Score
|
|
33
26
|
|
|
34
27
|
if TYPE_CHECKING: # pragma: no cover
|
|
35
28
|
from .core import Environment
|
|
29
|
+
from .schema.session_files import ProvenTemplate, SessionExport
|
|
36
30
|
|
|
37
31
|
|
|
38
32
|
@dataclass
|
|
@@ -48,98 +42,49 @@ class VerifierResult:
|
|
|
48
42
|
rewards: Dict[str, float] = field(default_factory=dict)
|
|
49
43
|
|
|
50
44
|
|
|
51
|
-
def split_sql_statements(script: str) -> List[str]:
|
|
52
|
-
"""Split a SQL script into complete statements (via
|
|
53
|
-
``sqlite3.complete_statement`` accumulation, so semicolons inside string
|
|
54
|
-
literals don't split). Text that is only comments — a note after the last
|
|
55
|
-
semicolon, a commented-out block — is not a statement and is dropped, so
|
|
56
|
-
every reader of a verifier (check, grade, the host) sees the same list."""
|
|
57
|
-
statements: List[str] = []
|
|
58
|
-
buffer = ""
|
|
59
|
-
for line in script.splitlines(keepends=True):
|
|
60
|
-
buffer += line
|
|
61
|
-
if sqlite3.complete_statement(buffer):
|
|
62
|
-
_append_statement(statements, buffer)
|
|
63
|
-
buffer = ""
|
|
64
|
-
_append_statement(statements, buffer)
|
|
65
|
-
return statements
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
def _append_statement(statements: List[str], text: str) -> None:
|
|
69
|
-
stripped = text.strip()
|
|
70
|
-
if _without_comments(stripped).strip(" \t\r\n;"):
|
|
71
|
-
statements.append(stripped)
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
def _without_comments(sql: str) -> str:
|
|
75
|
-
"""``sql`` with ``--`` line comments and ``/* */`` blocks removed, string
|
|
76
|
-
literals left alone (a ``--`` inside quotes is text, not a comment)."""
|
|
77
|
-
out: List[str] = []
|
|
78
|
-
i, n = 0, len(sql)
|
|
79
|
-
quote: Optional[str] = None
|
|
80
|
-
while i < n:
|
|
81
|
-
ch = sql[i]
|
|
82
|
-
if quote is not None:
|
|
83
|
-
out.append(ch)
|
|
84
|
-
quote = None if ch == quote else quote
|
|
85
|
-
i += 1
|
|
86
|
-
continue
|
|
87
|
-
if ch in ("'", '"', "`"):
|
|
88
|
-
quote = ch
|
|
89
|
-
out.append(ch)
|
|
90
|
-
i += 1
|
|
91
|
-
continue
|
|
92
|
-
if sql.startswith("--", i):
|
|
93
|
-
end = sql.find("\n", i)
|
|
94
|
-
i = n if end == -1 else end
|
|
95
|
-
continue
|
|
96
|
-
if sql.startswith("/*", i):
|
|
97
|
-
end = sql.find("*/", i + 2)
|
|
98
|
-
i = n if end == -1 else end + 2
|
|
99
|
-
continue
|
|
100
|
-
out.append(ch)
|
|
101
|
-
i += 1
|
|
102
|
-
return "".join(out)
|
|
103
|
-
|
|
104
|
-
|
|
105
45
|
class SqlVerifier:
|
|
106
46
|
"""One ``verifiers/<name>.sql``: the statements it runs and the one score
|
|
107
47
|
rule every reader applies — ``schema check``, a local session's grade, the
|
|
108
48
|
World Host's grade. Statements run in order; the score is the first column
|
|
109
49
|
of the first row of the LAST statement that returns rows (or could). No
|
|
110
|
-
rows / NULL → ``None``, never coerced to 0
|
|
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)."""
|
|
111
53
|
|
|
112
|
-
def __init__(self, name: str, script: str) -> None:
|
|
54
|
+
def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
|
|
113
55
|
self.name = name[:-4] if name.endswith(".sql") else name
|
|
114
|
-
self.statements =
|
|
56
|
+
self.statements = split(script)
|
|
115
57
|
|
|
116
58
|
@classmethod
|
|
117
|
-
def read(cls, path: Path) -> "SqlVerifier":
|
|
118
|
-
|
|
59
|
+
def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
|
|
60
|
+
"""``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
|
|
61
|
+
return cls(path.stem, path.read_text(encoding="utf-8"), split)
|
|
119
62
|
|
|
120
|
-
def score(
|
|
121
|
-
self, execute: Callable[[str], Optional[List[Any]]]
|
|
122
|
-
) -> "tuple[Optional[float], Optional[str]]":
|
|
63
|
+
def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
|
|
123
64
|
"""Run every statement through ``execute`` (rows, or ``None`` for a
|
|
124
65
|
statement that returns none, e.g. a temp-table DDL) and answer
|
|
125
66
|
``(score, sql)`` — the score and the statement it came from, both
|
|
126
67
|
``None`` when nothing returned rows."""
|
|
127
|
-
|
|
68
|
+
value: Any = None
|
|
128
69
|
last_sql: Optional[str] = None
|
|
129
70
|
for statement in self.statements:
|
|
130
71
|
rows = execute(statement)
|
|
131
72
|
if rows is None:
|
|
132
73
|
continue
|
|
133
74
|
last_sql = statement
|
|
134
|
-
value = rows[0][0] if rows else None
|
|
135
|
-
|
|
136
|
-
|
|
75
|
+
value = self._number(rows[0][0] if rows else None)
|
|
76
|
+
return self._score(value), last_sql
|
|
77
|
+
|
|
78
|
+
def _number(self, value: Any) -> Any:
|
|
79
|
+
if value is None or (isinstance(value, (int, float)) and not isinstance(value, bool)):
|
|
80
|
+
return value
|
|
81
|
+
raise VerifierError(f"verifier '{self.name}' returned {value!r}, not a number")
|
|
137
82
|
|
|
138
|
-
def
|
|
83
|
+
def _score(self, value: Any) -> Optional[float]:
|
|
139
84
|
if value is None:
|
|
140
85
|
return None
|
|
141
|
-
if
|
|
142
|
-
raise VerifierError(f"verifier '{self.name}' returned {value
|
|
86
|
+
if not Score.admits(value):
|
|
87
|
+
raise VerifierError(f"verifier '{self.name}' returned {Score.shown(value)}; {Score.RULE}")
|
|
143
88
|
return float(value)
|
|
144
89
|
|
|
145
90
|
|
|
@@ -170,9 +115,7 @@ class WorldRegistry(StubRegistryMapping):
|
|
|
170
115
|
stub.__qualname__ = f"gateway_env.{name}"
|
|
171
116
|
return stub
|
|
172
117
|
|
|
173
|
-
super().__init__(
|
|
174
|
-
{name: make(name) for name in world.env._handlers}, make
|
|
175
|
-
)
|
|
118
|
+
super().__init__({name: make(name) for name in world.env._handlers}, make)
|
|
176
119
|
|
|
177
120
|
@property
|
|
178
121
|
def call_log(self) -> List[Dict[str, Any]]:
|
|
@@ -186,41 +129,57 @@ class WorldRegistry(StubRegistryMapping):
|
|
|
186
129
|
|
|
187
130
|
|
|
188
131
|
class World:
|
|
189
|
-
"""One live, isolated instance of the environment's seeded state.
|
|
190
|
-
|
|
191
|
-
|
|
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
|
+
def __init__(
|
|
141
|
+
self,
|
|
142
|
+
env: "Environment",
|
|
143
|
+
*,
|
|
144
|
+
world_id: Optional[str] = None,
|
|
145
|
+
snapshot: Optional[Path] = None,
|
|
146
|
+
template: Optional["ProvenTemplate"] = None,
|
|
147
|
+
) -> None:
|
|
192
148
|
self.env = env
|
|
193
149
|
self.id = world_id or uuid.uuid4().hex[:8]
|
|
194
150
|
self.db_path: Path = env._worlds_dir / f"world-{self.id}.db"
|
|
195
151
|
self.call_log: List[Dict[str, Any]] = []
|
|
152
|
+
self._template = self._proven(template)
|
|
153
|
+
self.contract = template.contract if template is not None else self._bundle_contract()
|
|
154
|
+
source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
|
|
155
|
+
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
156
|
+
|
|
157
|
+
@staticmethod
|
|
158
|
+
def _proven(template: Any) -> Any:
|
|
159
|
+
if template is None:
|
|
160
|
+
return None
|
|
161
|
+
from .schema.session_files import ProvenTemplate
|
|
162
|
+
|
|
163
|
+
return ProvenTemplate.required(template)
|
|
164
|
+
|
|
165
|
+
def _bundle_contract(self) -> Any:
|
|
196
166
|
from .schema import bundle_mode, check_bundle
|
|
197
167
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
def
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
if self.contract is not None:
|
|
211
|
-
from .schema import SQLiteStore
|
|
212
|
-
|
|
213
|
-
self.store = SQLiteStore.open(self.db_path, self.contract)
|
|
214
|
-
return self.store._conn # Trusted host only; handlers receive ReadConnection.
|
|
215
|
-
conn = sqlite3.connect(self.db_path, isolation_level=None, check_same_thread=False)
|
|
216
|
-
conn.row_factory = sqlite3.Row
|
|
217
|
-
return conn
|
|
218
|
-
|
|
219
|
-
# -- execution seams -------------------------------------------------
|
|
168
|
+
return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
|
|
169
|
+
|
|
170
|
+
def _seed(self) -> "tuple[Path, bool]":
|
|
171
|
+
"""The file a fresh or reset world copies, and whether its rows are audited."""
|
|
172
|
+
if self._template is None:
|
|
173
|
+
return Path(self.env._template_db), True
|
|
174
|
+
return self._template.path, False
|
|
175
|
+
|
|
176
|
+
@property
|
|
177
|
+
def store(self):
|
|
178
|
+
"""The world database of a schema world; ``None`` for a contract-less mock-tools world."""
|
|
179
|
+
return self._backing.store
|
|
220
180
|
|
|
221
181
|
def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
222
182
|
"""Execute atomically in schema mode, validating both input and output."""
|
|
223
|
-
from .schema.store import ReadConnection
|
|
224
183
|
from .schema.validation import validate
|
|
225
184
|
|
|
226
185
|
handler = self.env._handlers.get(tool_name)
|
|
@@ -228,14 +187,14 @@ class World:
|
|
|
228
187
|
raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
|
|
229
188
|
supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
|
|
230
189
|
started = time.perf_counter()
|
|
231
|
-
with self.
|
|
190
|
+
with self._backing.transaction():
|
|
232
191
|
if self.contract is not None:
|
|
233
192
|
validate(
|
|
234
193
|
self.contract.tools[tool_name]["input_schema"],
|
|
235
194
|
supplied,
|
|
236
195
|
location=f"world.json#/x-gateway/tools/{tool_name}/input",
|
|
237
196
|
)
|
|
238
|
-
token = runtime._active_connection.set(
|
|
197
|
+
token = runtime._active_connection.set(self._backing.handler_connection())
|
|
239
198
|
store_token = runtime._active_store.set(self.store)
|
|
240
199
|
try:
|
|
241
200
|
if isinstance(supplied, Mapping):
|
|
@@ -258,9 +217,7 @@ class World:
|
|
|
258
217
|
self.env._record_route(tool_name, "env", duration_ms, self.id)
|
|
259
218
|
return result
|
|
260
219
|
|
|
261
|
-
def _registry_call(
|
|
262
|
-
self, tool_name: str, tool_input: Any = _NO_INPUT
|
|
263
|
-
) -> Any:
|
|
220
|
+
def _registry_call(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
264
221
|
if tool_name in self.env._handlers and self.env.resolve_route(tool_name) == "env":
|
|
265
222
|
return self.execute(tool_name, tool_input)
|
|
266
223
|
route = self.env.resolve_route(tool_name)
|
|
@@ -275,8 +232,7 @@ class World:
|
|
|
275
232
|
"through to the original function."
|
|
276
233
|
)
|
|
277
234
|
raise ToolRouteError(
|
|
278
|
-
f"tool '{tool_name}' has no env handler "
|
|
279
|
-
f"(served: {sorted(self.env._handlers)}) and no prod route."
|
|
235
|
+
f"tool '{tool_name}' has no env handler (served: {sorted(self.env._handlers)}) and no prod route."
|
|
280
236
|
)
|
|
281
237
|
|
|
282
238
|
def as_registry(self) -> WorldRegistry:
|
|
@@ -284,9 +240,7 @@ class World:
|
|
|
284
240
|
identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
|
|
285
241
|
return WorldRegistry(self)
|
|
286
242
|
|
|
287
|
-
def wrap_tools(
|
|
288
|
-
self, tools: Union[Mapping[str, Any], List[Any]]
|
|
289
|
-
) -> Union[Dict[str, Any], List[Any]]:
|
|
243
|
+
def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
|
|
290
244
|
"""Substitute env-served callables by name in a list/dict of tools;
|
|
291
245
|
everything not served (or not env-routed) passes through unchanged."""
|
|
292
246
|
|
|
@@ -301,10 +255,7 @@ class World:
|
|
|
301
255
|
return stub
|
|
302
256
|
|
|
303
257
|
if isinstance(tools, Mapping):
|
|
304
|
-
return {
|
|
305
|
-
name: (stub_for(name) if routed_to_env(name) else value)
|
|
306
|
-
for name, value in tools.items()
|
|
307
|
-
}
|
|
258
|
+
return {name: (stub_for(name) if routed_to_env(name) else value) for name, value in tools.items()}
|
|
308
259
|
wrapped: List[Any] = []
|
|
309
260
|
for item in tools:
|
|
310
261
|
name = getattr(item, "name", None)
|
|
@@ -313,67 +264,65 @@ class World:
|
|
|
313
264
|
wrapped.append(stub_for(name) if routed_to_env(name) else item)
|
|
314
265
|
return wrapped
|
|
315
266
|
|
|
316
|
-
# -- state lifecycle -------------------------------------------------
|
|
317
|
-
|
|
318
267
|
def reset(self) -> None:
|
|
319
268
|
"""Back to the seed, in place (same world instance)."""
|
|
320
|
-
if self.
|
|
321
|
-
|
|
269
|
+
if self._template is None:
|
|
270
|
+
self._refuse_a_changed_contract()
|
|
271
|
+
source, audit = self._seed()
|
|
272
|
+
self._relay(source, audit=audit)
|
|
322
273
|
|
|
323
|
-
|
|
324
|
-
|
|
274
|
+
def _refuse_a_changed_contract(self) -> None:
|
|
275
|
+
"""An environment's bundle can change under a live world; a version's cannot."""
|
|
276
|
+
if self.contract is None:
|
|
277
|
+
return
|
|
278
|
+
from .schema import ContractError, check_bundle
|
|
325
279
|
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
self.store.close()
|
|
329
|
-
else:
|
|
330
|
-
self._conn.close()
|
|
331
|
-
shutil.copyfile(self.env._template_db, self.db_path)
|
|
332
|
-
self._conn = self._connect()
|
|
280
|
+
if check_bundle(self.env.bundle_path).lock != self.contract.lock:
|
|
281
|
+
raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
|
|
333
282
|
|
|
334
283
|
def restore(self, source: Union[str, Path]) -> None:
|
|
335
284
|
"""Replace this world's state with a file :meth:`snapshot` wrote, in place.
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
285
|
+
A schema-backed world audits it against its contract row by row, as it would
|
|
286
|
+
any file it did not write."""
|
|
287
|
+
self._relay(Path(source), audit=True)
|
|
288
|
+
|
|
289
|
+
def resume(self, export: "SessionExport") -> None:
|
|
290
|
+
"""Replace this world's state with an export whose bytes were verified against
|
|
291
|
+
the sha256 recorded when the store wrote them, without a second row audit."""
|
|
292
|
+
from .schema.session_files import SessionExport
|
|
293
|
+
|
|
294
|
+
self._relay(SessionExport.required(export).path, audit=False)
|
|
295
|
+
|
|
296
|
+
def _relay(self, source: Path, *, audit: bool) -> None:
|
|
297
|
+
self._backing.close()
|
|
298
|
+
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
344
299
|
|
|
345
300
|
def snapshot(self, destination: Union[str, Path]) -> Path:
|
|
346
301
|
"""Pin this world's current state to a file (for debugging fixtures)."""
|
|
347
|
-
|
|
348
|
-
return self.store.snapshot(destination)
|
|
349
|
-
dest = Path(destination)
|
|
350
|
-
dest.parent.mkdir(parents=True, exist_ok=True)
|
|
351
|
-
shutil.copyfile(self.db_path, dest)
|
|
352
|
-
return dest
|
|
302
|
+
return self._backing.snapshot(Path(destination))
|
|
353
303
|
|
|
354
304
|
def close(self) -> None:
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
305
|
+
self._backing.close()
|
|
306
|
+
|
|
307
|
+
def set_task_context(self, scenario_id: str) -> bool:
|
|
308
|
+
"""Name the active task for verifiers; ``False`` when a mock-tools world does not declare the table."""
|
|
309
|
+
return self._backing.set_task_context(scenario_id)
|
|
310
|
+
|
|
311
|
+
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
312
|
+
"""Bind the run's conditions; ``False`` when a mock-tools world does not declare the table."""
|
|
313
|
+
return self._backing.set_run_parameters(parameters)
|
|
314
|
+
|
|
315
|
+
def record_conversation_event(
|
|
316
|
+
self, scenario_id: str, user_turn_index: int, event_type: str, actor: str, name: Optional[str], payload_json: str
|
|
317
|
+
) -> bool:
|
|
318
|
+
"""Log one turn event for verifiers; ``False`` when a mock-tools world does not declare the table."""
|
|
319
|
+
return self._backing.record_conversation_event(
|
|
320
|
+
scenario_id, user_turn_index, event_type, actor, name, payload_json
|
|
321
|
+
)
|
|
364
322
|
|
|
365
323
|
def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
|
|
366
324
|
"""Read-only SQL against the world's db (SELECT/WITH only)."""
|
|
367
|
-
|
|
368
|
-
return [dict(row) for row in self.store.query(sql, params)]
|
|
369
|
-
head = sql.lstrip().split(None, 1)[0].upper() if sql.strip() else ""
|
|
370
|
-
if head not in ("SELECT", "WITH"):
|
|
371
|
-
raise ValueError(
|
|
372
|
-
"world.state() is read-only — only SELECT/WITH queries are "
|
|
373
|
-
"allowed (use tool handlers or verifiers for writes)."
|
|
374
|
-
)
|
|
375
|
-
rows = self._conn.execute(sql, params).fetchall()
|
|
376
|
-
return [dict(row) for row in rows]
|
|
325
|
+
return self._backing.rows(sql, params)
|
|
377
326
|
|
|
378
327
|
def verify(self, name: str) -> VerifierResult:
|
|
379
328
|
"""Run ``verifiers/<name>.sql`` against this world.
|
|
@@ -382,8 +331,6 @@ class World:
|
|
|
382
331
|
the LAST row-returning statement. NULL / no rows → score None (passed
|
|
383
332
|
None) — never coerced to 0.
|
|
384
333
|
"""
|
|
385
|
-
from .schema import ContractError
|
|
386
|
-
|
|
387
334
|
verifier_name = name[:-4] if name.endswith(".sql") else name
|
|
388
335
|
path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
|
|
389
336
|
if not path.is_file():
|
|
@@ -391,31 +338,9 @@ class World:
|
|
|
391
338
|
raise VerifierError(f"unknown verifier '{name}' (available: {available})")
|
|
392
339
|
|
|
393
340
|
def execute(statement: str) -> Optional[List[Any]]:
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
return self.store.query(statement, private=True)
|
|
398
|
-
except ContractError as error:
|
|
399
|
-
# A verifier naming a column the contract never projected
|
|
400
|
-
# must fail with SQLite's own words and the statement, not
|
|
401
|
-
# read as a zero (Brex retrospective).
|
|
402
|
-
reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
|
|
403
|
-
raise ContractError(
|
|
404
|
-
"verifier",
|
|
405
|
-
f"verifier '{verifier_name}' failed: {reason}",
|
|
406
|
-
sql=statement,
|
|
407
|
-
) from error
|
|
408
|
-
cursor = self._conn.execute(statement)
|
|
409
|
-
except sqlite3.Error as error:
|
|
410
|
-
raise VerifierError(
|
|
411
|
-
f"verifier '{verifier_name}' failed: {error}\n SQL: {statement}"
|
|
412
|
-
) from error
|
|
413
|
-
if cursor.description is None:
|
|
414
|
-
return None
|
|
415
|
-
row = cursor.fetchone()
|
|
416
|
-
return [] if row is None else [row]
|
|
417
|
-
|
|
418
|
-
score, last_sql = SqlVerifier.read(path).score(execute)
|
|
341
|
+
return self._backing.verifier_rows(verifier_name, statement)
|
|
342
|
+
|
|
343
|
+
score, last_sql = SqlVerifier.read(path, self._backing.split_statements).score(execute)
|
|
419
344
|
if last_sql is None:
|
|
420
345
|
detail = "no row-returning statement — score is null"
|
|
421
346
|
elif score is None:
|
|
@@ -0,0 +1,137 @@
|
|
|
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
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC, abstractmethod
|
|
8
|
+
from contextlib import AbstractContextManager
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any, Dict, List, Optional
|
|
11
|
+
|
|
12
|
+
from .schema.compiler import Contract
|
|
13
|
+
from .schema.database import WorldDatabase
|
|
14
|
+
from .schema.validation import ContractError
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class WorldBacking(ABC):
|
|
18
|
+
"""One world's open state file."""
|
|
19
|
+
|
|
20
|
+
store: Optional[WorldDatabase] = None
|
|
21
|
+
|
|
22
|
+
@staticmethod
|
|
23
|
+
def branch(source: Path, path: Path, contract: Optional[Contract], *, audit: bool = True) -> "WorldBacking":
|
|
24
|
+
"""A copy of ``source`` at ``path``, opened as the backing ``contract`` calls for;
|
|
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)."""
|
|
27
|
+
from .legacy_sqlite import LegacySQLiteBacking
|
|
28
|
+
|
|
29
|
+
WorldDatabase.clone_file(Path(source), Path(path))
|
|
30
|
+
try:
|
|
31
|
+
if contract is None:
|
|
32
|
+
return LegacySQLiteBacking(Path(path))
|
|
33
|
+
return ContractBacking(Path(path), contract, audit=audit)
|
|
34
|
+
except BaseException:
|
|
35
|
+
Path(path).unlink(missing_ok=True)
|
|
36
|
+
raise
|
|
37
|
+
|
|
38
|
+
@abstractmethod
|
|
39
|
+
def transaction(self) -> AbstractContextManager[Any]:
|
|
40
|
+
"""The unit one tool call runs in."""
|
|
41
|
+
|
|
42
|
+
@abstractmethod
|
|
43
|
+
def handler_connection(self) -> Any:
|
|
44
|
+
"""What a tool handler receives as ``conn``."""
|
|
45
|
+
|
|
46
|
+
@abstractmethod
|
|
47
|
+
def split_statements(self, script: str) -> List[str]: ...
|
|
48
|
+
|
|
49
|
+
@abstractmethod
|
|
50
|
+
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
51
|
+
"""Read-only SQL, each row as a dict (``world.state``)."""
|
|
52
|
+
|
|
53
|
+
@abstractmethod
|
|
54
|
+
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
55
|
+
"""One verifier statement's rows (the first is the score), or ``None`` when it projects no columns."""
|
|
56
|
+
|
|
57
|
+
@abstractmethod
|
|
58
|
+
def snapshot(self, destination: Path) -> Path: ...
|
|
59
|
+
|
|
60
|
+
@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."""
|
|
63
|
+
|
|
64
|
+
@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."""
|
|
67
|
+
|
|
68
|
+
@abstractmethod
|
|
69
|
+
def record_conversation_event(
|
|
70
|
+
self,
|
|
71
|
+
scenario_id: str,
|
|
72
|
+
user_turn_index: int,
|
|
73
|
+
event_type: str,
|
|
74
|
+
actor: str,
|
|
75
|
+
name: Optional[str],
|
|
76
|
+
payload_json: str,
|
|
77
|
+
) -> bool:
|
|
78
|
+
"""Log one turn event; ``False`` when the world does not declare the table."""
|
|
79
|
+
|
|
80
|
+
@abstractmethod
|
|
81
|
+
def close(self) -> None: ...
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class ContractBacking(WorldBacking):
|
|
85
|
+
"""A schema world's state: the world database its contract compiled to."""
|
|
86
|
+
|
|
87
|
+
def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
|
|
88
|
+
self.store = WorldDatabase.open(path, contract, audit=audit)
|
|
89
|
+
|
|
90
|
+
def transaction(self) -> AbstractContextManager[Any]:
|
|
91
|
+
return self.store.transaction()
|
|
92
|
+
|
|
93
|
+
def handler_connection(self) -> Any:
|
|
94
|
+
return self.store.read_connection()
|
|
95
|
+
|
|
96
|
+
def split_statements(self, script: str) -> List[str]:
|
|
97
|
+
return self.store.split_statements(script)
|
|
98
|
+
|
|
99
|
+
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
100
|
+
return [dict(row) for row in self.store.query(sql, params)]
|
|
101
|
+
|
|
102
|
+
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
103
|
+
try:
|
|
104
|
+
return self.store.query(statement, private=True)
|
|
105
|
+
except ContractError as error:
|
|
106
|
+
# An unprojected column must fail with the engine's words, not read as a zero.
|
|
107
|
+
reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
|
|
108
|
+
raise ContractError("verifier", f"verifier '{verifier}' failed: {reason}", sql=statement) from error
|
|
109
|
+
|
|
110
|
+
def snapshot(self, destination: Path) -> Path:
|
|
111
|
+
return self.store.snapshot(destination)
|
|
112
|
+
|
|
113
|
+
def set_task_context(self, scenario_id: str) -> bool:
|
|
114
|
+
self.store.set_task_context(scenario_id)
|
|
115
|
+
return True
|
|
116
|
+
|
|
117
|
+
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
118
|
+
self.store.set_run_parameters(parameters)
|
|
119
|
+
return True
|
|
120
|
+
|
|
121
|
+
def record_conversation_event(
|
|
122
|
+
self,
|
|
123
|
+
scenario_id: str,
|
|
124
|
+
user_turn_index: int,
|
|
125
|
+
event_type: str,
|
|
126
|
+
actor: str,
|
|
127
|
+
name: Optional[str],
|
|
128
|
+
payload_json: str,
|
|
129
|
+
) -> bool:
|
|
130
|
+
self.store.record_conversation_event(scenario_id, user_turn_index, event_type, actor, name, payload_json)
|
|
131
|
+
return True
|
|
132
|
+
|
|
133
|
+
def close(self) -> None:
|
|
134
|
+
try:
|
|
135
|
+
self.store.close()
|
|
136
|
+
except self.store.native_error:
|
|
137
|
+
pass
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
Local mode only in P1: the version bundle is pulled via the existing
|
|
12
12
|
environments/benchmark-hub clients, extracted to a cache dir, and executed
|
|
13
|
-
in-process (
|
|
13
|
+
in-process (database-backed worlds for ``mock-tools``; per-task docker sandboxes for
|
|
14
14
|
``harbor``). ``mode="remote"`` and ``hosts=`` transport patching are P2/P3.
|
|
15
15
|
"""
|
|
16
16
|
|