@withgateway/sdk 0.2.1 → 0.2.2
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 +309 -59
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +309 -59
- package/dist/cli.mjs.map +1 -1
- package/dist/index.js +8 -3
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +8 -3
- package/dist/index.mjs.map +1 -1
- package/dist/tracing/index.js +1 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +1 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.js +7 -2
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +7 -2
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/schema/api.py +61 -3
- package/runtime/gatewaysdk/environment/schema/batch.py +5 -1
- package/runtime/gatewaysdk/environment/schema/connector.py +11 -0
- package/runtime/gatewaysdk/environment/schema/data.py +76 -2
- package/runtime/gatewaysdk/environment/schema/dependencies.py +11 -1
- package/runtime/gatewaysdk/environment/schema/host.py +8 -17
- package/runtime/gatewaysdk/environment/schema/local.py +105 -19
- package/runtime/gatewaysdk/environment/schema/mapping.py +13 -1
- package/runtime/gatewaysdk/environment/schema/platform.py +32 -5
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +4 -1
- package/runtime/gatewaysdk/environment/schema/tools_world.py +5 -1
- package/runtime/gatewaysdk/environment/schema/validation.py +4 -3
- package/skills/benchmarks-getting-started/SKILL.md +4 -1
package/package.json
CHANGED
|
@@ -302,8 +302,19 @@ def _operation_settings(entry: dict, operation: Operation, location: str) -> Ope
|
|
|
302
302
|
fail("spec", f"api.action must be one of {', '.join(ACTIONS)}", f"{location}/action")
|
|
303
303
|
if action in ("create", "update", "delete") and not operation.entity:
|
|
304
304
|
fail("spec", f"api.action {action} needs an entity to write", f"{location}/action")
|
|
305
|
-
if action in ("update", "delete") and
|
|
306
|
-
fail(
|
|
305
|
+
if action in ("create", "update", "delete") and set(operation.methods) == {"GET"}:
|
|
306
|
+
fail(
|
|
307
|
+
"spec",
|
|
308
|
+
f"api.action {action} writes, but the route only answers GET; declare method = "
|
|
309
|
+
f"\"{'DELETE' if action == 'delete' else 'POST' if action == 'create' else 'PATCH'}\"",
|
|
310
|
+
f"{location}/action",
|
|
311
|
+
)
|
|
312
|
+
if action in ("update", "delete") and not mapping and not operation.placeholders:
|
|
313
|
+
fail(
|
|
314
|
+
"spec",
|
|
315
|
+
f"api.action {action} needs a filter to find the row, or a {{segment}} in its path naming the entity's key",
|
|
316
|
+
f"{location}/filter",
|
|
317
|
+
)
|
|
307
318
|
handler = table.get("handler")
|
|
308
319
|
if action == "handler":
|
|
309
320
|
if not isinstance(handler, str) or not re.match(r"^[a-z_][a-z0-9_]*$", handler):
|
|
@@ -756,6 +767,16 @@ def _matches(
|
|
|
756
767
|
return True
|
|
757
768
|
|
|
758
769
|
|
|
770
|
+
def _key_filter(operation: Operation, ctx: ApiContext, entity: str) -> dict[str, str]:
|
|
771
|
+
"""The filter a route with no ``filter`` of its own implies: each ``{segment}``
|
|
772
|
+
of its path that names a primary-key field of its entity narrows to the row
|
|
773
|
+
keyed so, as ``GET /wallets/{id}`` reads everywhere. A segment naming no key
|
|
774
|
+
field (``/users/{user_id}/messages``) implies nothing, the route's rows are
|
|
775
|
+
its entity's; a declared ``filter`` says it all itself."""
|
|
776
|
+
keys = set(ctx.key_of(entity, {}))
|
|
777
|
+
return {name: name for name in operation.placeholders if name in keys}
|
|
778
|
+
|
|
779
|
+
|
|
759
780
|
def _compare(have: str, wanted: str, mode: str) -> bool:
|
|
760
781
|
if mode == "contains":
|
|
761
782
|
return wanted in have
|
|
@@ -1286,6 +1307,35 @@ def with_query(target: str, extra: dict[str, str]) -> str:
|
|
|
1286
1307
|
return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
|
|
1287
1308
|
|
|
1288
1309
|
|
|
1310
|
+
def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str, str, bytes]:
|
|
1311
|
+
"""``(method, target, raw body)`` of an operation called by name with a
|
|
1312
|
+
tool call's ``args``, the way a session's ``call`` verb takes one:
|
|
1313
|
+
``args.path`` fills the route's ``{segments}`` (a top-level argument of
|
|
1314
|
+
the segment's name does too, so ``get_wallet {"id": "W1"}`` reads as
|
|
1315
|
+
``/wallets/W1``), ``args.query`` is its query string, ``args.body`` (or
|
|
1316
|
+
every other key, for a call written like a tool's) its JSON body; a GET
|
|
1317
|
+
carries none. The target is under the spec's ``base_url`` path."""
|
|
1318
|
+
path = operation.path
|
|
1319
|
+
path_params = dict(args.get("path")) if isinstance(args.get("path"), dict) else {}
|
|
1320
|
+
consumed: set[str] = set()
|
|
1321
|
+
for name in operation.placeholders:
|
|
1322
|
+
if name not in path_params and name in args and not isinstance(args[name], (dict, list)):
|
|
1323
|
+
path_params[name] = args[name]
|
|
1324
|
+
consumed.add(name)
|
|
1325
|
+
for key, value in path_params.items():
|
|
1326
|
+
path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
|
|
1327
|
+
query = args.get("query") if isinstance(args.get("query"), dict) else {}
|
|
1328
|
+
if query:
|
|
1329
|
+
path = f"{path}?" + urllib.parse.urlencode(query)
|
|
1330
|
+
body = args.get("body") if isinstance(args.get("body"), dict) else None
|
|
1331
|
+
if body is None:
|
|
1332
|
+
leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body") and k not in consumed}
|
|
1333
|
+
body = leftovers or None
|
|
1334
|
+
raw = json.dumps(body).encode("utf-8") if body is not None and operation.method != "GET" else b""
|
|
1335
|
+
base = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
|
|
1336
|
+
return operation.method, f"{base}{path}", raw
|
|
1337
|
+
|
|
1338
|
+
|
|
1289
1339
|
# ---------------------------------------------------------------- the server
|
|
1290
1340
|
|
|
1291
1341
|
|
|
@@ -1473,7 +1523,15 @@ class WorldApp:
|
|
|
1473
1523
|
if op.action == "create":
|
|
1474
1524
|
row = ctx.insert(entity, _bind(op, ctx, body))
|
|
1475
1525
|
return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
|
|
1476
|
-
|
|
1526
|
+
filters = op.filter or _key_filter(operation, ctx, entity)
|
|
1527
|
+
if op.action in ("update", "delete") and not filters:
|
|
1528
|
+
fail(
|
|
1529
|
+
"spec",
|
|
1530
|
+
f"route {operation.name} finds its row by nothing: its path names no primary-key field of {entity} "
|
|
1531
|
+
f"and it declares no api.filter",
|
|
1532
|
+
f"/operations/{operation.name}/api/filter",
|
|
1533
|
+
)
|
|
1534
|
+
rows = [row for row in ctx.rows(entity) if _matches(row, filters, values, op.match)]
|
|
1477
1535
|
if op.action in ("update", "delete"):
|
|
1478
1536
|
if len(rows) != 1:
|
|
1479
1537
|
return ctx.not_found()
|
|
@@ -409,7 +409,11 @@ def iter_chunk_rows(path: str | Path, entity: str | None = None) -> Iterator[tup
|
|
|
409
409
|
|
|
410
410
|
def _field_of(error: ContractError) -> str | None:
|
|
411
411
|
path = error.detail.get("path") or ""
|
|
412
|
-
|
|
412
|
+
inside = path[1:] if path.startswith("/") and len(path) > 1 else None
|
|
413
|
+
named = error.detail.get("property")
|
|
414
|
+
if not isinstance(named, str):
|
|
415
|
+
return inside
|
|
416
|
+
return f"{inside}/{named}" if inside else named
|
|
413
417
|
|
|
414
418
|
|
|
415
419
|
def refusal(
|
|
@@ -348,6 +348,7 @@ def parse_spec(text: str) -> Spec:
|
|
|
348
348
|
hash_fields, drop_fields, round_fields, preserve_fields = parse_redact(raw.get("redact", {}), "/redact")
|
|
349
349
|
|
|
350
350
|
operations: dict[str, Operation] = {}
|
|
351
|
+
routes: dict[tuple[str, str, tuple[str, ...]], str] = {}
|
|
351
352
|
listed = raw.get("operations", [])
|
|
352
353
|
if not isinstance(listed, list) or not listed:
|
|
353
354
|
fail("spec", "Declare at least one [[operations]] entry", "/operations")
|
|
@@ -389,6 +390,16 @@ def parse_spec(text: str) -> Spec:
|
|
|
389
390
|
operations[name] = Operation(
|
|
390
391
|
name, method, path, params, entity, results.strip("."), drop, explode, carry_args, methods
|
|
391
392
|
)
|
|
393
|
+
for verb in operations[name].methods:
|
|
394
|
+
route = (verb, re.sub(r"\{[^}]*\}", "{}", path), tuple(sorted(params)))
|
|
395
|
+
if route in routes:
|
|
396
|
+
fail(
|
|
397
|
+
"spec",
|
|
398
|
+
f"operation {name} answers {verb} {path} with the same params as {routes[route]}, "
|
|
399
|
+
"which would never be reached; give it another path, verb or params",
|
|
400
|
+
f"{location}/path",
|
|
401
|
+
)
|
|
402
|
+
routes[route] = name
|
|
392
403
|
|
|
393
404
|
return Spec(
|
|
394
405
|
slug=slug,
|
|
@@ -37,7 +37,7 @@ from typing import Any, Iterable, Iterator
|
|
|
37
37
|
|
|
38
38
|
from .compiler import bundle_mode, check_bundle, compile_bundle
|
|
39
39
|
from .store import SQLiteStore
|
|
40
|
-
from .validation import ContractError, digest, encoded, fail, journal_paths, read_json
|
|
40
|
+
from .validation import ContractError, digest, encoded, fail, journal_paths, read_json, validate
|
|
41
41
|
|
|
42
42
|
MODES = ("append", "replace")
|
|
43
43
|
MERGES = ("upsert", "fill")
|
|
@@ -132,6 +132,7 @@ def import_rows(
|
|
|
132
132
|
rows: Rows,
|
|
133
133
|
*,
|
|
134
134
|
mode: str = "append",
|
|
135
|
+
merge: str = "upsert",
|
|
135
136
|
batch_id: str | None = None,
|
|
136
137
|
redact: str = "off",
|
|
137
138
|
) -> dict:
|
|
@@ -141,6 +142,11 @@ def import_rows(
|
|
|
141
142
|
named entities wholesale. Nothing is written until the result has been
|
|
142
143
|
proven to load in a scratch copy.
|
|
143
144
|
|
|
145
|
+
``merge`` settles two rows of one key inside ``rows``: ``upsert`` (the
|
|
146
|
+
default) keeps the last, ``fill`` keeps the first and lets the later ones
|
|
147
|
+
add the fields it lacks — the platform batch's rule, so a directory and a
|
|
148
|
+
slug import the same file the same way.
|
|
149
|
+
|
|
144
150
|
``redact`` — ``off`` (default) stores the rows as given; ``apply`` runs them
|
|
145
151
|
through the world's ``[redact]`` policy first; ``refuse`` rejects a row that
|
|
146
152
|
carries plaintext in a redacted field (:mod:`.redaction`).
|
|
@@ -150,13 +156,17 @@ def import_rows(
|
|
|
150
156
|
root = Path(root)
|
|
151
157
|
if mode not in MODES:
|
|
152
158
|
fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
|
|
159
|
+
if merge not in MERGES:
|
|
160
|
+
fail("merge", f"merge must be one of {', '.join(MERGES)}", "/merge")
|
|
153
161
|
if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
|
|
154
162
|
fail("rows", "rows must map entity names to arrays of rows", "/rows")
|
|
155
163
|
redact = parse_mode(redact)
|
|
156
164
|
rows = redact_rows(require_policy(root, redact), rows, redact)
|
|
157
165
|
kind = world_kind(root)
|
|
158
166
|
if kind == KIND_SCHEMA:
|
|
159
|
-
|
|
167
|
+
settled = _merged(root, rows, merge)
|
|
168
|
+
_refuse_shapes(root, settled)
|
|
169
|
+
report = _import_schema(root, settled, mode, batch_id)
|
|
160
170
|
elif kind == KIND_MOCK_TOOLS:
|
|
161
171
|
report = _import_mock_tools(root, rows, mode)
|
|
162
172
|
else:
|
|
@@ -166,6 +176,70 @@ def import_rows(
|
|
|
166
176
|
return report
|
|
167
177
|
|
|
168
178
|
|
|
179
|
+
def _refuse_shapes(root: Path, rows: Rows) -> None:
|
|
180
|
+
"""Every row's shape against the contract (type, bounds, required, unknown
|
|
181
|
+
property, primary key present), all of them, before any is applied: one
|
|
182
|
+
``ContractError`` with the first refusal's own code (``required``,
|
|
183
|
+
``additionalProperties``, ``primary_key``, ``entity``, ...), the entity and
|
|
184
|
+
the row's index in the file, carrying the full ``refusals`` list — each
|
|
185
|
+
naming its entity, index, primary key and field — the shape the batch lane
|
|
186
|
+
reports."""
|
|
187
|
+
from .batch import shape_refusal
|
|
188
|
+
|
|
189
|
+
contract = compile_bundle(root)
|
|
190
|
+
refusals = [
|
|
191
|
+
refused
|
|
192
|
+
for entity, listed in rows.items()
|
|
193
|
+
for index, row in enumerate(listed)
|
|
194
|
+
if (refused := shape_refusal(contract, 0, index, entity, row)) is not None
|
|
195
|
+
]
|
|
196
|
+
if not refusals:
|
|
197
|
+
return
|
|
198
|
+
first = refusals[0]
|
|
199
|
+
entity, index = first["entity"], first["index"]
|
|
200
|
+
row = rows[entity][index]
|
|
201
|
+
total = sum(len(listed) for listed in rows.values())
|
|
202
|
+
summary = f"{len(refusals)} of {total} row(s) refused; {first['pointer']}: " if len(refusals) > 1 else ""
|
|
203
|
+
context = {"entity": entity, "index": index, "refused": len(refusals), "rows": total, "refusals": refusals}
|
|
204
|
+
if entity not in contract.entities:
|
|
205
|
+
fail("entity", summary + first["detail"], f"/{entity}", **context)
|
|
206
|
+
if not isinstance(row, dict):
|
|
207
|
+
fail("rows", summary + first["detail"], first["pointer"], **context)
|
|
208
|
+
spec = contract.entities[entity]
|
|
209
|
+
if any(name not in row for name in spec["primary_key"]):
|
|
210
|
+
fail("primary_key", summary + first["detail"], first["pointer"], **context)
|
|
211
|
+
try:
|
|
212
|
+
validate(spec["schema"], row, location=f"{spec['location']}/schema")
|
|
213
|
+
except ContractError as error:
|
|
214
|
+
raise error.contextualize(message=summary + error.detail["message"], **context)
|
|
215
|
+
fail("rows", summary + first["detail"], first["pointer"], **context)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _merged(root: Path, rows: Rows, merge: str) -> Rows:
|
|
219
|
+
"""``rows`` with each entity's duplicate keys settled by ``merge``; a row the
|
|
220
|
+
plan will refuse (not an object, key missing) is left in place for it."""
|
|
221
|
+
if merge != "fill":
|
|
222
|
+
return rows
|
|
223
|
+
contract = compile_bundle(root)
|
|
224
|
+
settled: Rows = {}
|
|
225
|
+
for entity, listed in rows.items():
|
|
226
|
+
first: dict[tuple, dict] = {}
|
|
227
|
+
kept: list = []
|
|
228
|
+
for row in listed:
|
|
229
|
+
key = _key(contract, entity, row) if isinstance(row, dict) else None
|
|
230
|
+
if key is None:
|
|
231
|
+
kept.append(row)
|
|
232
|
+
continue
|
|
233
|
+
if key in first:
|
|
234
|
+
for name, value in row.items():
|
|
235
|
+
first[key].setdefault(name, value)
|
|
236
|
+
continue
|
|
237
|
+
first[key] = dict(row)
|
|
238
|
+
kept.append(first[key])
|
|
239
|
+
settled[entity] = kept
|
|
240
|
+
return settled
|
|
241
|
+
|
|
242
|
+
|
|
169
243
|
def _import_schema(root: Path, rows: Rows, mode: str, batch_id: str | None) -> dict:
|
|
170
244
|
"""Rows into a schema world, landing after everything the world already replays.
|
|
171
245
|
|
|
@@ -230,6 +230,16 @@ def local_dependency_trees(bundle: Path, dependencies: dict[str, Dependency]) ->
|
|
|
230
230
|
)
|
|
231
231
|
tree = (bundle / dep.path).resolve()
|
|
232
232
|
if not (tree / "gateway-env.toml").is_file():
|
|
233
|
-
|
|
233
|
+
what = (
|
|
234
|
+
"does not exist"
|
|
235
|
+
if not tree.exists()
|
|
236
|
+
else "is not a directory"
|
|
237
|
+
if not tree.is_dir()
|
|
238
|
+
else "is not a schema world (no gateway-env.toml)"
|
|
239
|
+
)
|
|
240
|
+
fail(
|
|
241
|
+
f"'{alias}'.path {dep.path!r} ({tree}) {what}; point [dependencies.{alias}].path in "
|
|
242
|
+
"gateway-env.toml at the world's directory, or re-run `gateway worlds schema link` with --replace"
|
|
243
|
+
)
|
|
234
244
|
trees[alias] = tree
|
|
235
245
|
return trees
|
|
@@ -82,6 +82,7 @@ from .api import (
|
|
|
82
82
|
WorldState,
|
|
83
83
|
load_api_settings,
|
|
84
84
|
load_handlers,
|
|
85
|
+
operation_request,
|
|
85
86
|
send_response,
|
|
86
87
|
vendor_credential,
|
|
87
88
|
with_query,
|
|
@@ -1612,7 +1613,11 @@ class WorldHost:
|
|
|
1612
1613
|
def seed(self, session_id: str, args: dict) -> dict:
|
|
1613
1614
|
rows = args.get("rows")
|
|
1614
1615
|
if not isinstance(rows, dict):
|
|
1615
|
-
fail(
|
|
1616
|
+
fail(
|
|
1617
|
+
"host",
|
|
1618
|
+
'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
|
|
1619
|
+
"a dependency's entity is named alias.entity",
|
|
1620
|
+
)
|
|
1616
1621
|
mode = args.get("mode", "append")
|
|
1617
1622
|
from .redaction import parse_mode
|
|
1618
1623
|
|
|
@@ -1764,23 +1769,9 @@ class WorldHost:
|
|
|
1764
1769
|
if session.task_spec is not None and not session.task_spec.allows_tool(tool):
|
|
1765
1770
|
allowed = ", ".join(session.task_spec.tools or ())
|
|
1766
1771
|
fail("tool_not_allowed", f"tool '{tool}' is not allowed by this session's task; it allows: {allowed}")
|
|
1767
|
-
|
|
1768
|
-
path_params = args.get("path") if isinstance(args.get("path"), dict) else {}
|
|
1769
|
-
for key, value in (path_params or {}).items():
|
|
1770
|
-
path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
|
|
1771
|
-
query = args.get("query") if isinstance(args.get("query"), dict) else {}
|
|
1772
|
-
if query:
|
|
1773
|
-
path = f"{path}?" + urllib.parse.urlencode(query)
|
|
1774
|
-
body = args.get("body") if isinstance(args.get("body"), dict) else None
|
|
1775
|
-
if body is None:
|
|
1776
|
-
leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body")}
|
|
1777
|
-
body = leftovers or None
|
|
1778
|
-
method = operation.method # type: ignore[union-attr]
|
|
1779
|
-
raw = json.dumps(body).encode("utf-8") if body is not None and method != "GET" else b""
|
|
1780
|
-
base = urllib.parse.urlsplit(session.spec.base_url).path.rstrip("/")
|
|
1772
|
+
method, target, raw = operation_request(session.spec, operation, args)
|
|
1781
1773
|
headers, credential_query = world_credential(session)
|
|
1782
|
-
|
|
1783
|
-
status, answer, _ = session.app.handle(method, target, headers, raw, "127.0.0.1")
|
|
1774
|
+
status, answer, _ = session.app.handle(method, with_query(target, credential_query), headers, raw, "127.0.0.1")
|
|
1784
1775
|
return {"status": status, "body": answer}
|
|
1785
1776
|
|
|
1786
1777
|
|
|
@@ -37,7 +37,7 @@ from pathlib import Path
|
|
|
37
37
|
from typing import Any, Callable
|
|
38
38
|
|
|
39
39
|
from . import snapshot as snapshots
|
|
40
|
-
from .api import Router, WorldApp, load_api_settings, send_response, vendor_credential, with_query
|
|
40
|
+
from .api import Router, WorldApp, load_api_settings, operation_request, send_response, vendor_credential, with_query
|
|
41
41
|
from .host_surfaces import UiSurface, api_target, load_ui_surface, static_file
|
|
42
42
|
from .compiler import bundle_mode, fail
|
|
43
43
|
from .conform import PIN
|
|
@@ -63,6 +63,19 @@ def refusal(error: ContractError) -> dict:
|
|
|
63
63
|
return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
|
|
64
64
|
|
|
65
65
|
|
|
66
|
+
def seed_args(body: dict) -> dict:
|
|
67
|
+
"""The seed a ``POST /__session/seed`` body asks for: ``{rows, mode}``, the
|
|
68
|
+
same under ``args``, or bare ``{entity: [row, ...]}`` — the shape a rows
|
|
69
|
+
file has — taken as the rows of an append."""
|
|
70
|
+
if isinstance(body.get("args"), dict):
|
|
71
|
+
body = body["args"]
|
|
72
|
+
if "rows" in body or "mode" in body:
|
|
73
|
+
return body
|
|
74
|
+
if body and all(isinstance(value, list) for value in body.values()):
|
|
75
|
+
return {"rows": body}
|
|
76
|
+
return body
|
|
77
|
+
|
|
78
|
+
|
|
66
79
|
def has_http(root: str | Path) -> bool:
|
|
67
80
|
"""Whether the world serves HTTP at all: only a tree with ``connector.toml``
|
|
68
81
|
has routes. A schema world without one is tools-only, and that is a whole
|
|
@@ -97,6 +110,11 @@ class LocalSession:
|
|
|
97
110
|
world: ToolsWorld
|
|
98
111
|
server: ThreadingHTTPServer | None
|
|
99
112
|
_scratch: str
|
|
113
|
+
#: The routes connector.toml declares, over the session's store, when the
|
|
114
|
+
#: world has any: :meth:`call` answers an operation by name through them.
|
|
115
|
+
app: WorldApp | None = None
|
|
116
|
+
#: The credential the app takes: the pin a local serve is opened with.
|
|
117
|
+
api_key: str | None = PIN
|
|
100
118
|
#: The static ui connector.toml's ``[ui]`` declares, when the server serves one.
|
|
101
119
|
ui: UiSurface | None = None
|
|
102
120
|
#: The ui's own origin: the page at ``/`` and its ``api_path`` beside it,
|
|
@@ -148,9 +166,10 @@ class LocalSession:
|
|
|
148
166
|
return task_card(self.world)
|
|
149
167
|
|
|
150
168
|
def call(self, tool: str, args: dict[str, Any]) -> dict:
|
|
151
|
-
"""The tool's ``{status, body}
|
|
169
|
+
"""The tool's ``{status, body}``, a route's when ``tool`` names an
|
|
170
|
+
operation of connector.toml; a refusal is a 400 answer, not an error."""
|
|
152
171
|
try:
|
|
153
|
-
return self.world.
|
|
172
|
+
return call_served(self.world, self.app, tool, args, api_key=self.api_key)
|
|
154
173
|
except ContractError as error:
|
|
155
174
|
return refusal(error)
|
|
156
175
|
|
|
@@ -238,12 +257,13 @@ def open_world(
|
|
|
238
257
|
server = None
|
|
239
258
|
ui_server = None
|
|
240
259
|
ui = None
|
|
260
|
+
app = None
|
|
261
|
+
if has_http(root):
|
|
262
|
+
spec = load_spec(root)
|
|
263
|
+
settings = load_api_settings(root, spec)
|
|
264
|
+
app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
|
|
241
265
|
if http:
|
|
242
|
-
app
|
|
243
|
-
if has_http(root):
|
|
244
|
-
spec = load_spec(root)
|
|
245
|
-
settings = load_api_settings(root, spec)
|
|
246
|
-
app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
|
|
266
|
+
if app is not None:
|
|
247
267
|
ui = load_ui_surface(root)
|
|
248
268
|
server = bind_server(host, port, make_session_handler(world, app, closing, ui=ui, api_key=api_key))
|
|
249
269
|
threading.Thread(target=server.serve_forever, daemon=True).start()
|
|
@@ -261,7 +281,15 @@ def open_world(
|
|
|
261
281
|
shutil.rmtree(scratch, ignore_errors=True)
|
|
262
282
|
raise
|
|
263
283
|
return LocalSession(
|
|
264
|
-
root=root,
|
|
284
|
+
root=root,
|
|
285
|
+
world=world,
|
|
286
|
+
server=server,
|
|
287
|
+
_scratch=scratch,
|
|
288
|
+
app=app,
|
|
289
|
+
api_key=api_key,
|
|
290
|
+
closing=closing,
|
|
291
|
+
ui=ui,
|
|
292
|
+
ui_server=ui_server,
|
|
265
293
|
)
|
|
266
294
|
|
|
267
295
|
|
|
@@ -372,12 +400,10 @@ def make_session_handler(
|
|
|
372
400
|
falls back to ``index.html``, for a client-side router) and its
|
|
373
401
|
``api_path`` prefix answered with the pin — nothing else, as on the host."""
|
|
374
402
|
closing = closing if closing is not None else threading.Event()
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": api_key or ""}, api_key)
|
|
380
|
-
grant = issued["access_token"] if issued else None
|
|
403
|
+
# The page's calls and a `/__session/call` of an operation are presented
|
|
404
|
+
# as a granted client, as the host presents them; the world's own token
|
|
405
|
+
# dance stays available beside.
|
|
406
|
+
grant = local_grant(app, api_key)
|
|
381
407
|
|
|
382
408
|
def close(_body: dict) -> dict:
|
|
383
409
|
closing.set()
|
|
@@ -389,8 +415,8 @@ def make_session_handler(
|
|
|
389
415
|
("GET", "state"): lambda _body: world.state(),
|
|
390
416
|
("POST", "grade"): lambda _body: world.grade(),
|
|
391
417
|
("POST", "reset"): lambda _body: world.reset(),
|
|
392
|
-
("POST", "seed"): lambda body: world.seed(
|
|
393
|
-
("POST", "call"): lambda body: _call(world, body),
|
|
418
|
+
("POST", "seed"): lambda body: world.seed(seed_args(body)),
|
|
419
|
+
("POST", "call"): lambda body: _call(world, app, body, api_key=api_key, grant=grant),
|
|
394
420
|
("POST", "close"): close,
|
|
395
421
|
}
|
|
396
422
|
|
|
@@ -515,14 +541,74 @@ def _local_origin(origin: str) -> bool:
|
|
|
515
541
|
return host in ("127.0.0.1", "localhost", "::1")
|
|
516
542
|
|
|
517
543
|
|
|
518
|
-
def
|
|
544
|
+
def local_grant(app: WorldApp | None, api_key: str | None) -> str | None:
|
|
545
|
+
"""The bearer an ``oauth2`` world's routes take when the session itself
|
|
546
|
+
calls them (the page's api prefix, an operation by name); None for any
|
|
547
|
+
other scheme, or when the world refuses the client-credentials grant."""
|
|
548
|
+
if app is None or app.router.spec.scheme != "oauth2":
|
|
549
|
+
return None
|
|
550
|
+
issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": api_key or ""}, api_key)
|
|
551
|
+
return issued["access_token"] if issued else None
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
def call_served(
|
|
555
|
+
world: ToolsWorld,
|
|
556
|
+
app: WorldApp | None,
|
|
557
|
+
tool: str,
|
|
558
|
+
args: dict,
|
|
559
|
+
*,
|
|
560
|
+
api_key: str | None = PIN,
|
|
561
|
+
grant: str | None = None,
|
|
562
|
+
) -> dict:
|
|
563
|
+
"""One name of what the session serves, answered as the World Host answers
|
|
564
|
+
it: a tool by name (a dependency's as ``alias.tool``); on a tree with
|
|
565
|
+
connector.toml, an operation by name too, answered by its route over the
|
|
566
|
+
same store, ``{status, body}`` the route's own. A name that is both is the
|
|
567
|
+
tool's."""
|
|
568
|
+
if app is not None and tool not in world.version.tool_names and tool in app.router.spec.operations:
|
|
569
|
+
return call_operation(world, app, tool, args, api_key=api_key, grant=grant)
|
|
570
|
+
return world.call(tool, args)
|
|
571
|
+
|
|
572
|
+
|
|
573
|
+
def call_operation(
|
|
574
|
+
world: ToolsWorld,
|
|
575
|
+
app: WorldApp,
|
|
576
|
+
name: str,
|
|
577
|
+
args: dict,
|
|
578
|
+
*,
|
|
579
|
+
api_key: str | None = PIN,
|
|
580
|
+
grant: str | None = None,
|
|
581
|
+
) -> dict:
|
|
582
|
+
"""An operation of connector.toml called by name (:func:`operation_request`
|
|
583
|
+
reads the args); the world's own credential is presented, as the host
|
|
584
|
+
presents a session's. The answer is the route's ``{status, body}``."""
|
|
585
|
+
operation = app.router.spec.operations.get(name)
|
|
586
|
+
if operation is None:
|
|
587
|
+
known = ", ".join(sorted(app.router.spec.operations)) or "(none)"
|
|
588
|
+
fail("host", f"unknown tool '{name}'; this world serves: {known}")
|
|
589
|
+
if world.allowed is not None and name not in world.allowed:
|
|
590
|
+
fail(
|
|
591
|
+
"tool_not_allowed",
|
|
592
|
+
f"tool '{name}' is not allowed by this session's task; it allows: {', '.join(sorted(world.allowed))}",
|
|
593
|
+
)
|
|
594
|
+
method, target, raw = operation_request(app.router.spec, operation, args)
|
|
595
|
+
headers, credential_query = vendor_credential(app.router.spec, api_key or "", grant=grant)
|
|
596
|
+
status, answer, _ = app.handle(
|
|
597
|
+
method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
|
|
598
|
+
)
|
|
599
|
+
return {"status": status, "body": answer}
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
def _call(
|
|
603
|
+
world: ToolsWorld, app: WorldApp | None, body: dict, *, api_key: str | None = PIN, grant: str | None = None
|
|
604
|
+
) -> dict:
|
|
519
605
|
tool = body.get("tool")
|
|
520
606
|
if not isinstance(tool, str) or not tool:
|
|
521
607
|
fail("host", "tool must be a tool name (root) or alias.tool (a dependency's)")
|
|
522
608
|
args = body.get("args") or {}
|
|
523
609
|
if not isinstance(args, dict):
|
|
524
610
|
fail("host", "args must be an object of the tool's arguments")
|
|
525
|
-
return world
|
|
611
|
+
return call_served(world, app, tool, args, api_key=api_key, grant=grant)
|
|
526
612
|
|
|
527
613
|
|
|
528
614
|
def _apply_scenario(world: ToolsWorld, root: Path, name: str) -> None:
|
|
@@ -757,9 +757,16 @@ def apply_mapping(mapping: Mapping, records: Iterable[Any], entities: Entities)
|
|
|
757
757
|
claimed = False
|
|
758
758
|
for position, item in enumerate(items):
|
|
759
759
|
if not isinstance(item, dict):
|
|
760
|
+
if not fanned and isinstance(item, list):
|
|
761
|
+
fail(
|
|
762
|
+
"mapping",
|
|
763
|
+
f"records[{index}]: {source.select_text} is an array of {len(item)} items, not one object; "
|
|
764
|
+
f'select each item with select = "{source.select_text}[*]"',
|
|
765
|
+
f"/records/{index}",
|
|
766
|
+
)
|
|
760
767
|
fail(
|
|
761
768
|
"mapping",
|
|
762
|
-
f"records[{index}]: {source.select_text}[{position}] is not an object",
|
|
769
|
+
f"records[{index}]: {source.select_text}[{position}] is {_shape(item)}, not an object",
|
|
763
770
|
f"/records/{index}",
|
|
764
771
|
)
|
|
765
772
|
scope = Scope(item=item, record=record, meta=meta)
|
|
@@ -890,6 +897,11 @@ def skeleton(
|
|
|
890
897
|
select = "result" if kind == "tool-call" else "$record"
|
|
891
898
|
if kind == "tool-call" and group["shapes"] and all(shape == "an array of objects" for shape in group["shapes"]):
|
|
892
899
|
select = "result[*]"
|
|
900
|
+
elif kind == "tool-call" and group["shapes"] and all(shape == "an object" for shape in group["shapes"]):
|
|
901
|
+
listed = [name for name, info in group["fields"].items() if info["list"] and info["nested"]]
|
|
902
|
+
if len(listed) == 1:
|
|
903
|
+
select = f"result.{listed[0]}[*]"
|
|
904
|
+
lines.append(f"# result.{listed[0]} holds the rows: [*] selects each item of an array")
|
|
893
905
|
lines.append("[[sources]]")
|
|
894
906
|
lines.append(f'name = "{name}"')
|
|
895
907
|
lines.append(f'kind = "{kind}"')
|
|
@@ -234,7 +234,7 @@ def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
|
|
|
234
234
|
this runtime may run authored code (:func:`may_execute`)."""
|
|
235
235
|
bundle = Path(bundle)
|
|
236
236
|
if bundle_mode(bundle) is None:
|
|
237
|
-
fail("mode", "Expected a schema
|
|
237
|
+
fail("mode", "Expected a schema world: gateway-env.toml with [schema] beside schema/world.json")
|
|
238
238
|
contract = check_bundle(bundle)
|
|
239
239
|
declared = set(contract.tools)
|
|
240
240
|
found: dict[str, str] = {}
|
|
@@ -273,7 +273,31 @@ def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
|
|
|
273
273
|
fail("handler", f"Duplicate handler for {name}")
|
|
274
274
|
found[name] = path.name
|
|
275
275
|
if set(found) != declared:
|
|
276
|
-
|
|
276
|
+
undeclared = sorted(set(found) - declared)
|
|
277
|
+
unhandled = sorted(declared - set(found))
|
|
278
|
+
parts = []
|
|
279
|
+
if unhandled:
|
|
280
|
+
parts.append(
|
|
281
|
+
"declared in schema/world.json (tools) without a handler under tools/: "
|
|
282
|
+
+ ", ".join(unhandled)
|
|
283
|
+
+ " — add `@tool` def <name>(...) to a tools/*.py, or drop the declaration"
|
|
284
|
+
)
|
|
285
|
+
if undeclared:
|
|
286
|
+
parts.append(
|
|
287
|
+
"handled under tools/ without a declaration: "
|
|
288
|
+
+ ", ".join(f"{name} ({found[name]})" for name in undeclared)
|
|
289
|
+
+ " — declare each in schema/world.json, or remove the handler"
|
|
290
|
+
)
|
|
291
|
+
fail(
|
|
292
|
+
"handler",
|
|
293
|
+
"Declared tools and Python handlers must match exactly; " + "; ".join(parts),
|
|
294
|
+
"/tools",
|
|
295
|
+
)
|
|
296
|
+
if (bundle / "connector.toml").is_file():
|
|
297
|
+
from .api import load_api_settings
|
|
298
|
+
from .connector import parse_spec
|
|
299
|
+
|
|
300
|
+
load_api_settings(bundle, parse_spec((bundle / "connector.toml").read_text(encoding="utf-8")))
|
|
277
301
|
_check_mappings(bundle, contract)
|
|
278
302
|
check_world_redaction(bundle)
|
|
279
303
|
pinned = _pinned_state(bundle, contract)
|
|
@@ -509,7 +533,7 @@ def _handler_execution(bundle: Path, execute: bool) -> dict[str, Any]:
|
|
|
509
533
|
if not execute:
|
|
510
534
|
return {
|
|
511
535
|
"status": "not_run",
|
|
512
|
-
"reason": "handlers run where the world runs; `gateway worlds check` "
|
|
536
|
+
"reason": "handlers run where the world runs; `gateway worlds schema check` "
|
|
513
537
|
"with the bundled runtime imports them, `gateway worlds call` runs one",
|
|
514
538
|
}
|
|
515
539
|
if not may_execute():
|
|
@@ -931,22 +955,25 @@ def _import_data(request: dict) -> dict:
|
|
|
931
955
|
(the same gate the CLI uses, scratch copy first), and every file of the updated
|
|
932
956
|
tree comes back the way ``init-template`` returns one, so the platform commits a
|
|
933
957
|
version from it without knowing which file changed."""
|
|
934
|
-
from .data import KIND_SCHEMA, MODES, import_rows
|
|
958
|
+
from .data import KIND_SCHEMA, MERGES, MODES, import_rows
|
|
935
959
|
from .redaction import parse_mode
|
|
936
960
|
|
|
937
961
|
rows = request.get("rows")
|
|
938
962
|
mode = request.get("mode", "append")
|
|
963
|
+
merge = request.get("merge", "upsert")
|
|
939
964
|
if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
|
|
940
965
|
fail("input", "Expected rows as {entity: [row, …]}")
|
|
941
966
|
if mode not in MODES:
|
|
942
967
|
fail("input", f"mode must be one of {', '.join(MODES)}")
|
|
968
|
+
if merge not in MERGES:
|
|
969
|
+
fail("input", f"merge must be one of {', '.join(MERGES)}")
|
|
943
970
|
redact = parse_mode(request.get("redact"))
|
|
944
971
|
with tempfile.TemporaryDirectory(prefix="gateway-import-") as directory:
|
|
945
972
|
root = Path(directory) / "bundle"
|
|
946
973
|
root.mkdir()
|
|
947
974
|
_write_files(root, request.get("files"))
|
|
948
975
|
world = world_root(root)
|
|
949
|
-
result = import_rows(world, rows, mode=mode, redact=redact)
|
|
976
|
+
result = import_rows(world, rows, mode=mode, merge=merge, redact=redact)
|
|
950
977
|
if result["kind"] == KIND_SCHEMA and snapshots.default_snapshot(world).is_file():
|
|
951
978
|
# The journals grew; a snapshot built before this import would be
|
|
952
979
|
# served over them. Rebuild so the tree that travels back is one thing.
|
|
@@ -244,12 +244,15 @@ crm-bench/
|
|
|
244
244
|
Entities, tools and routes: `worlds-getting-started` §2 and `connector-schema-authoring`. Tasks:
|
|
245
245
|
|
|
246
246
|
```bash
|
|
247
|
+
gateway worlds schema verifier add ./crm-bench ticket_closed --entity crm_tickets --where "id = 'T-7' AND status = 'closed'"
|
|
247
248
|
gateway worlds schema task add ./crm-bench close_ticket --prompt "Close ticket T-7 and note the reason." --verifier ticket_closed
|
|
248
249
|
gateway worlds schema task add ./crm-bench escalate --prompt "..." --verifier state_present --world slack=state_present
|
|
249
250
|
```
|
|
250
251
|
|
|
251
252
|
- `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must
|
|
252
|
-
exist
|
|
253
|
+
exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
|
|
254
|
+
it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`;
|
|
255
|
+
`reward` is their mean.
|
|
253
256
|
- A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity
|
|
254
257
|
names from `schema/world.json`): `SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM
|
|
255
258
|
"crm_tickets" WHERE id = 'T-7' AND status = 'closed';`
|