agent-instruction-protocol 0.7.0__py3-none-any.whl
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.
- agent_instruction_protocol-0.7.0.dist-info/METADATA +474 -0
- agent_instruction_protocol-0.7.0.dist-info/RECORD +37 -0
- agent_instruction_protocol-0.7.0.dist-info/WHEEL +4 -0
- agent_instruction_protocol-0.7.0.dist-info/entry_points.txt +2 -0
- agent_instruction_protocol-0.7.0.dist-info/licenses/LICENSE +201 -0
- aip/__init__.py +15 -0
- aip/client/__init__.py +20 -0
- aip/client/aip-runtime/SKILL.md +117 -0
- aip/client/backend.py +306 -0
- aip/client/cli.py +702 -0
- aip/client/executor.py +139 -0
- aip/client/resolver.py +120 -0
- aip/client/runner.py +304 -0
- aip/client/server.py +219 -0
- aip/db/__init__.py +1 -0
- aip/db/neo4j.py +58 -0
- aip/errors.py +18 -0
- aip/model/__init__.py +24 -0
- aip/model/engine.py +314 -0
- aip/model/environment.py +150 -0
- aip/model/procedure.py +116 -0
- aip/model/resources.py +85 -0
- aip/model/steps.py +607 -0
- aip/model/types.py +150 -0
- aip/sdk.py +716 -0
- aip/server/__init__.py +1 -0
- aip/server/app.py +639 -0
- aip/server/backend.py +132 -0
- aip/server/backends/__init__.py +1 -0
- aip/server/backends/filesystem.py +414 -0
- aip/server/backends/neo4j.py +1030 -0
- aip/server/config.py +236 -0
- aip/server/governance.py +196 -0
- aip/server/records.py +293 -0
- aip/server/search.py +220 -0
- aip/spec/__init__.py +18 -0
- aip/spec/loader.py +119 -0
aip/client/server.py
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
"""The client's side of the HTTP API (design §4.1, §8): where the server is, how to call
|
|
2
|
+
it, and the catalog operations `aip search|list|publish|get|pin|retire` are built on.
|
|
3
|
+
|
|
4
|
+
`Server(url, token)` is one HTTP session with the bearer token attached and the error
|
|
5
|
+
envelope turned into `ServerError`. Where the client points comes from `settings()`:
|
|
6
|
+
`AIP_SERVER` and `AIP_TOKEN` override `~/.config/aip/config.json` (`aip config` writes
|
|
7
|
+
it); nothing configured means local folders only.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import hashlib
|
|
13
|
+
import io
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
import shutil
|
|
17
|
+
import tarfile
|
|
18
|
+
import tempfile
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import Any, Dict, List
|
|
21
|
+
|
|
22
|
+
from aip.errors import AipError
|
|
23
|
+
|
|
24
|
+
JSON = Dict[str, Any]
|
|
25
|
+
MANIFEST = ".aip-manifest.json"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# -------------------------------------------------------------------------- config
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def config_path() -> Path:
|
|
32
|
+
override = os.environ.get("AIP_CONFIG")
|
|
33
|
+
return Path(override) if override else Path.home() / ".config" / "aip" / "config.json"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def load_config() -> JSON:
|
|
37
|
+
path = config_path()
|
|
38
|
+
if not path.is_file():
|
|
39
|
+
return {}
|
|
40
|
+
try:
|
|
41
|
+
data = json.loads(path.read_text())
|
|
42
|
+
except (OSError, ValueError):
|
|
43
|
+
return {}
|
|
44
|
+
return data if isinstance(data, dict) else {}
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def save_config(config: JSON) -> Path:
|
|
48
|
+
path = config_path()
|
|
49
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
50
|
+
path.write_text(json.dumps(config, indent=2) + "\n")
|
|
51
|
+
try:
|
|
52
|
+
path.chmod(0o600) # it may hold the token
|
|
53
|
+
except OSError:
|
|
54
|
+
pass
|
|
55
|
+
return path
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def settings() -> JSON:
|
|
59
|
+
"""`{"server", "token", "source"}`: the environment first, then the config file."""
|
|
60
|
+
config = load_config()
|
|
61
|
+
server = os.environ.get("AIP_SERVER") or config.get("server") or None
|
|
62
|
+
token = os.environ.get("AIP_TOKEN") or config.get("token") or None
|
|
63
|
+
source = "AIP_SERVER" if os.environ.get("AIP_SERVER") else (str(config_path()) if config.get("server") else None)
|
|
64
|
+
return {"server": server, "token": token, "source": source}
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def configured() -> "Server | None":
|
|
68
|
+
"""The server the client points at, or None when none is configured."""
|
|
69
|
+
s = settings()
|
|
70
|
+
return Server(s["server"], s["token"]) if s["server"] else None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
# -------------------------------------------------------------------------- errors
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class ServerError(AipError):
|
|
77
|
+
"""A failed call: the server's error envelope, or no server to speak of."""
|
|
78
|
+
|
|
79
|
+
def __init__(self, status: int, kind: str, message: str, location: str | None = None, **extra: Any):
|
|
80
|
+
super().__init__(message, kind)
|
|
81
|
+
self.status, self.location, self.extra = status, location, extra
|
|
82
|
+
|
|
83
|
+
def __str__(self) -> str:
|
|
84
|
+
where = f" at {self.location}" if self.location else ""
|
|
85
|
+
return f"{self.kind}{where}: {self.message}"
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
# ------------------------------------------------------------------------- the server
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class Server:
|
|
92
|
+
"""One HTTP session against an AIP server. `session` is any httpx-style client (FastAPI's
|
|
93
|
+
test client qualifies); by default a real one on `url`."""
|
|
94
|
+
|
|
95
|
+
def __init__(self, url: str, token: str | None = None, session: Any = None):
|
|
96
|
+
self.url = url.rstrip("/")
|
|
97
|
+
self.token = token
|
|
98
|
+
if session is None:
|
|
99
|
+
import httpx
|
|
100
|
+
|
|
101
|
+
session = httpx.Client(base_url=self.url, timeout=httpx.Timeout(None, connect=10.0))
|
|
102
|
+
self._session = session
|
|
103
|
+
|
|
104
|
+
def request(self, method: str, path: str, **kwargs: Any):
|
|
105
|
+
import httpx
|
|
106
|
+
|
|
107
|
+
headers = dict(kwargs.pop("headers", {}) or {})
|
|
108
|
+
if self.token:
|
|
109
|
+
headers["Authorization"] = f"Bearer {self.token}"
|
|
110
|
+
try:
|
|
111
|
+
response = self._session.request(method, path, headers=headers, **kwargs)
|
|
112
|
+
except httpx.HTTPError as exc:
|
|
113
|
+
raise ServerError(0, "unreachable", f"{self.url}: {exc}") from exc
|
|
114
|
+
if response.status_code >= 400:
|
|
115
|
+
raise self._error(response)
|
|
116
|
+
return response
|
|
117
|
+
|
|
118
|
+
@staticmethod
|
|
119
|
+
def _error(response) -> ServerError:
|
|
120
|
+
try:
|
|
121
|
+
error = response.json()["error"]
|
|
122
|
+
return ServerError(response.status_code, error.pop("kind"), error.pop("message"),
|
|
123
|
+
error.pop("location", None), **error)
|
|
124
|
+
except (ValueError, KeyError, TypeError, AttributeError):
|
|
125
|
+
return ServerError(response.status_code, "http_error", f"HTTP {response.status_code}: {response.text[:200]}")
|
|
126
|
+
|
|
127
|
+
def get(self, path: str, **params: Any) -> Any:
|
|
128
|
+
return self.request("GET", path, params={k: v for k, v in params.items() if v is not None}).json()
|
|
129
|
+
|
|
130
|
+
def post(self, path: str, body: JSON | None = None) -> Any:
|
|
131
|
+
return self.request("POST", path, json=body or {}).json()
|
|
132
|
+
|
|
133
|
+
def bytes(self, path: str, **params: Any) -> bytes:
|
|
134
|
+
return self.request("GET", path, params={k: v for k, v in params.items() if v is not None}).content
|
|
135
|
+
|
|
136
|
+
# ------------------------------------------------------------------ catalog
|
|
137
|
+
|
|
138
|
+
def search(self, query: str, limit: int = 10) -> List[JSON]:
|
|
139
|
+
return self.get("/catalog/search", q=query, limit=limit)
|
|
140
|
+
|
|
141
|
+
def list(self) -> List[JSON]:
|
|
142
|
+
return self.get("/catalog")
|
|
143
|
+
|
|
144
|
+
def info(self, ref: str) -> JSON:
|
|
145
|
+
return self.get(f"/catalog/{ref}")
|
|
146
|
+
|
|
147
|
+
def file(self, ref: str, path: str) -> bytes:
|
|
148
|
+
return self.bytes(f"/catalog/{ref}/files/{path}")
|
|
149
|
+
|
|
150
|
+
def capabilities(self, ref: str) -> JSON:
|
|
151
|
+
return self.get(f"/procedures/{ref}/capabilities")
|
|
152
|
+
|
|
153
|
+
def pin(self, name: str, revision: str | None) -> JSON:
|
|
154
|
+
return self.post(f"/catalog/{name}/pin", {"revision": revision})
|
|
155
|
+
|
|
156
|
+
def retire(self, name: str, revision: str) -> JSON:
|
|
157
|
+
return self.post(f"/catalog/{name}/retire", {"revision": revision})
|
|
158
|
+
|
|
159
|
+
def runs(self, name: str | None = None, status: str | None = None, limit: int = 50) -> List[JSON]:
|
|
160
|
+
return self.get("/runs", name=name, status=status, limit=limit)
|
|
161
|
+
|
|
162
|
+
def run(self, run_id: str) -> JSON:
|
|
163
|
+
return self.get(f"/runs/{run_id}")
|
|
164
|
+
|
|
165
|
+
# --------------------------------------------------------------- transfers
|
|
166
|
+
|
|
167
|
+
def publish(self, folder: Path) -> JSON:
|
|
168
|
+
"""Upload every file of a skill folder; the server validates and returns `{name, revision, ...}`.
|
|
169
|
+
Validate locally first (`aip publish` does) so a rejection is never a surprise."""
|
|
170
|
+
from aip.server.app import upload_of
|
|
171
|
+
|
|
172
|
+
return self.post("/catalog", upload_of(Path(folder)))
|
|
173
|
+
|
|
174
|
+
def download(self, ref: str, out_dir: Path) -> Path:
|
|
175
|
+
"""Fetch a revision losslessly to `<out_dir>/<name>/`: the tar of every file plus its
|
|
176
|
+
manifest, modes restored from the manifest, every file hashed against it (the first
|
|
177
|
+
mismatch aborts, naming the file), and the revision recomputed. Refuses to overwrite."""
|
|
178
|
+
from aip.server.records import revision, walk
|
|
179
|
+
|
|
180
|
+
out_dir = Path(out_dir)
|
|
181
|
+
out_dir.mkdir(parents=True, exist_ok=True)
|
|
182
|
+
data = self.bytes(f"/catalog/{ref}/files", archive="tar")
|
|
183
|
+
tmp = Path(tempfile.mkdtemp(prefix=".aip-get-", dir=out_dir))
|
|
184
|
+
try:
|
|
185
|
+
with tarfile.open(fileobj=io.BytesIO(data)) as tar:
|
|
186
|
+
tar.extractall(tmp, filter="data")
|
|
187
|
+
manifest_path = tmp / MANIFEST
|
|
188
|
+
if not manifest_path.is_file():
|
|
189
|
+
raise ServerError(0, "bad_archive", f"{ref}: the archive carries no {MANIFEST}")
|
|
190
|
+
manifest = json.loads(manifest_path.read_text())
|
|
191
|
+
name, expected = manifest["name"], manifest["revision"]
|
|
192
|
+
folder = tmp / name
|
|
193
|
+
if not folder.is_dir():
|
|
194
|
+
raise ServerError(0, "bad_archive", f"{ref}: the archive has no {name}/ folder")
|
|
195
|
+
for entry in sorted(manifest["files"], key=lambda e: e["path"]):
|
|
196
|
+
path = folder / entry["path"]
|
|
197
|
+
if not path.is_file():
|
|
198
|
+
raise ServerError(0, "hash_mismatch", f"{name}/{entry['path']}: missing from the archive",
|
|
199
|
+
location=entry["path"])
|
|
200
|
+
path.chmod(int(entry["mode"]) & 0o777)
|
|
201
|
+
digest = hashlib.sha256(path.read_bytes()).hexdigest()
|
|
202
|
+
if digest != entry["sha256"]:
|
|
203
|
+
raise ServerError(0, "hash_mismatch",
|
|
204
|
+
f"{name}/{entry['path']}: sha256 {digest[:12]}… does not match the manifest's "
|
|
205
|
+
f"{entry['sha256'][:12]}…", location=entry["path"])
|
|
206
|
+
files, _ = walk(folder)
|
|
207
|
+
if revision(files) != expected:
|
|
208
|
+
raise ServerError(0, "hash_mismatch", f"{name}: the files on disk hash to {revision(files)}, "
|
|
209
|
+
f"not the manifest's {expected}")
|
|
210
|
+
target = out_dir / name
|
|
211
|
+
if target.exists():
|
|
212
|
+
raise ServerError(0, "exists", f"{target} already exists; choose another --out or remove it")
|
|
213
|
+
shutil.move(str(folder), str(target))
|
|
214
|
+
return target
|
|
215
|
+
finally:
|
|
216
|
+
shutil.rmtree(tmp, ignore_errors=True)
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
__all__ = ["Server", "ServerError", "config_path", "configured", "load_config", "save_config", "settings"]
|
aip/db/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Database projections of AIP skills. Neo4j today: `aip.db.neo4j`."""
|
aip/db/neo4j.py
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Compatibility shim for the 0.4 `aip db` API over the Neo4j backend.
|
|
2
|
+
|
|
3
|
+
The projection itself lives in `aip.server.backends.neo4j` (graph shape, Cypher,
|
|
4
|
+
`Neo4jBackend`); the records and the folder <-> record conversions in
|
|
5
|
+
`aip.server.records`. This module keeps the four functions `aip db` and older callers
|
|
6
|
+
use, each opening a backend for the call:
|
|
7
|
+
|
|
8
|
+
- `load(skill_dir)`: validate, snapshot, publish; returns `name@revision`.
|
|
9
|
+
- `fetch(name, revision=None)`: the record as JSON (files with bytes), or None.
|
|
10
|
+
- `export(name, out_dir, revision=None)`: rebuild the folder at `out_dir/<name>`, hash-verified.
|
|
11
|
+
- `list_skills()`: one row per revision, newest first per name.
|
|
12
|
+
|
|
13
|
+
`Bundle` stays as an alias of `SkillRecord`, and `Connection` is re-exported.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
from typing import Any, Dict, List
|
|
20
|
+
|
|
21
|
+
from aip.server.backend import NotFound
|
|
22
|
+
from aip.server.backends.neo4j import Connection, Neo4jBackend # noqa: F401
|
|
23
|
+
from aip.server.records import (IGNORE_DIRS, IGNORE_FILES, IGNORE_SUFFIXES, FileRecord, SkillRecord, # noqa: F401
|
|
24
|
+
materialize, snapshot, write_files)
|
|
25
|
+
|
|
26
|
+
JSON = Dict[str, Any]
|
|
27
|
+
|
|
28
|
+
Bundle = SkillRecord
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def load(skill_dir: Path, conn: Connection | None = None) -> str:
|
|
32
|
+
"""Validate, snapshot, and publish a skill. Returns the skill id (`name@revision`)."""
|
|
33
|
+
record = snapshot(skill_dir)
|
|
34
|
+
with Neo4jBackend(conn) as backend:
|
|
35
|
+
backend.catalog.publish(record)
|
|
36
|
+
return record.id
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def fetch(name: str, revision: str | None = None, conn: Connection | None = None) -> JSON | None:
|
|
40
|
+
"""The resolved (or named) revision as JSON, files included; None when there is no such skill."""
|
|
41
|
+
with Neo4jBackend(conn) as backend:
|
|
42
|
+
try:
|
|
43
|
+
return backend.catalog.get(name, revision).to_json()
|
|
44
|
+
except NotFound:
|
|
45
|
+
return None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def export(name: str, out_dir: Path, revision: str | None = None, conn: Connection | None = None) -> Path:
|
|
49
|
+
"""Rebuild a skill folder from the database at out_dir/<name>. Verifies every file hash."""
|
|
50
|
+
with Neo4jBackend(conn) as backend:
|
|
51
|
+
record = backend.catalog.get(name, revision) # NotFound is a KeyError
|
|
52
|
+
return materialize(record, Path(out_dir) / record.name)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def list_skills(conn: Connection | None = None) -> List[JSON]:
|
|
56
|
+
"""Every revision of every name: name, revision, aip_version, published_at, retired, pinned, files, steps."""
|
|
57
|
+
with Neo4jBackend(conn) as backend:
|
|
58
|
+
return backend.catalog.revisions()
|
aip/errors.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""The root of every error the SDK raises (`aip.AipError`), in a module of its own so the client's
|
|
2
|
+
HTTP layer and the SDK can both build on it without importing each other."""
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class AipError(Exception):
|
|
6
|
+
"""An AIP operation that could not be done. `kind` names what went wrong, in the same
|
|
7
|
+
vocabulary as the CLI's error objects and the server's error envelope."""
|
|
8
|
+
|
|
9
|
+
kind = "error"
|
|
10
|
+
|
|
11
|
+
def __init__(self, message: str, kind: str | None = None):
|
|
12
|
+
super().__init__(message)
|
|
13
|
+
self.message = message
|
|
14
|
+
if kind is not None:
|
|
15
|
+
self.kind = kind
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
__all__ = ["AipError"]
|
aip/model/__init__.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""AIP runtime model."""
|
|
2
|
+
|
|
3
|
+
from aip.model.environment import Requires, RequiresUnmet
|
|
4
|
+
from aip.model.procedure import Procedure
|
|
5
|
+
from aip.model.resources import Asset, Reference, Resource, ResourceLoader, Script
|
|
6
|
+
from aip.model.steps import (
|
|
7
|
+
DEFAULT_MIN_CONFIDENCE, DEFAULT_NOUL_MARGIN,
|
|
8
|
+
BaseStep, ClientTask, Decision, DecisionQuestion, EndStep, Execution, Meta, Node,
|
|
9
|
+
Router, State, StepResponse, describe_next,
|
|
10
|
+
)
|
|
11
|
+
from aip.model.types import (
|
|
12
|
+
JSON, DataType, InputValidationError, Inputs, OutputValidationError, ScriptFailed, ScriptTimeout, StepError,
|
|
13
|
+
describe_inputs, project, to_json_schema, validate_input, validate_output,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"Requires", "RequiresUnmet", "Procedure", "Asset", "Reference", "Resource", "ResourceLoader", "Script",
|
|
18
|
+
"DEFAULT_MIN_CONFIDENCE", "DEFAULT_NOUL_MARGIN",
|
|
19
|
+
"BaseStep", "ClientTask", "Decision", "DecisionQuestion", "EndStep", "Execution", "Meta", "Node",
|
|
20
|
+
"Router", "State", "StepResponse", "describe_next",
|
|
21
|
+
"JSON", "DataType", "InputValidationError", "Inputs", "OutputValidationError", "ScriptFailed", "ScriptTimeout",
|
|
22
|
+
"StepError", "describe_inputs", "project",
|
|
23
|
+
"to_json_schema", "validate_input", "validate_output",
|
|
24
|
+
]
|
aip/model/engine.py
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
"""The run loop: one procedure, one cursor, one answer at a time.
|
|
2
|
+
|
|
3
|
+
A run is a `Cursor`: the step whose output the next input answers (`after`), the full state,
|
|
4
|
+
the history, and what the run waits for (`pause`). `start` opens one from the start input;
|
|
5
|
+
`submit` carries one thing to it: the answer to its pause, or nothing to retry a failed step.
|
|
6
|
+
Each steps the procedure until a pause, the end, or a failure, and returns an `Advance`.
|
|
7
|
+
|
|
8
|
+
The same loop runs in both places a run can live: the local client (`aip run ./folder`)
|
|
9
|
+
keeps the cursor in its run file; the server keeps it in its run backend and the client
|
|
10
|
+
holds only the run id. Neither keeps anything in memory between calls.
|
|
11
|
+
|
|
12
|
+
Pause kinds, as `cursor.pause["kind"]`:
|
|
13
|
+
|
|
14
|
+
- `client_task`: the client must answer. The block is what the CLI prints, minus `run_id` and
|
|
15
|
+
`run_file`.
|
|
16
|
+
- `decision`: every decision stops here; the loop never calls a decision model. The client
|
|
17
|
+
resolves it (`aip.client.resolver`) with its own model when one is configured, else prints
|
|
18
|
+
it for the agent to answer; the next `submit` carries the answers and their attribution
|
|
19
|
+
(`Decision.accept_answers`). The block also carries the author's `thresholds` and, when the
|
|
20
|
+
step sets `history: true`, the run's `history`: what a resolver needs, never printed (`PRIVATE`).
|
|
21
|
+
A `review` (the model answered a question under its threshold) is the client's pause, not
|
|
22
|
+
the loop's: the loop still waits at the decision.
|
|
23
|
+
- `execute`: an execution step, in a run whose loop does not run scripts (`scripts=False`: the
|
|
24
|
+
server's, and the local client's, which runs them itself between calls). The block is
|
|
25
|
+
`Execution.request`; the next `submit` carries the client's report of running it (`{"output":
|
|
26
|
+
{...}, "seconds"}` or a failure, see `Execution.accept_report`). Never printed by the CLI.
|
|
27
|
+
- `error`: a step failed; `after`, `state`, and `history` are as they were before it, so a
|
|
28
|
+
`submit` with no answer retries it.
|
|
29
|
+
- `done`: the end was reached; `state` is the end step's inputs.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
from dataclasses import dataclass, field
|
|
35
|
+
from typing import Any, Dict, List
|
|
36
|
+
|
|
37
|
+
from aip.model.procedure import Procedure
|
|
38
|
+
from aip.model.steps import Decision, Execution, describe_next, threshold
|
|
39
|
+
from aip.model.types import (
|
|
40
|
+
JSON, InputValidationError, OutputValidationError, StepError, project, validate_input, validate_output,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# The error kinds of the error object (`docs/cli-json.md`); anything else is reported as `server`.
|
|
44
|
+
ERROR_KINDS = ("script_failed", "invalid_input", "invalid_output", "requires_unmet", "timeout", "server")
|
|
45
|
+
|
|
46
|
+
PAUSED = ("client_task", "decision")
|
|
47
|
+
|
|
48
|
+
# Keys of a pause block that are for the client program, not the agent: the CLI never prints them.
|
|
49
|
+
PRIVATE = ("thresholds", "history", "resolution")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass
|
|
53
|
+
class Cursor:
|
|
54
|
+
after: str | None = None
|
|
55
|
+
state: JSON = field(default_factory=dict)
|
|
56
|
+
history: List[JSON] = field(default_factory=list)
|
|
57
|
+
pause: JSON | None = None
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def status(self) -> str:
|
|
61
|
+
"""The run's status: `paused`, `failed`, `done`, or `running` (nothing pending)."""
|
|
62
|
+
kind = (self.pause or {}).get("kind")
|
|
63
|
+
return "paused" if kind in PAUSED else "failed" if kind == "error" else "done" if kind == "done" else "running"
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@dataclass
|
|
67
|
+
class Advance:
|
|
68
|
+
"""What one `start` or `submit` did.
|
|
69
|
+
|
|
70
|
+
cursor: where the run is now; `None` when nothing is worth keeping (the start input was
|
|
71
|
+
rejected before any step ran)
|
|
72
|
+
entries: the history entries this call added, in order (also at the end of `cursor.history`)
|
|
73
|
+
lines: the `--progress` line of every step this call completed, in order
|
|
74
|
+
error: the error object when the call failed; `kept` says the run did not move (an answer
|
|
75
|
+
that does not fit its pause: answer it again)
|
|
76
|
+
failure: the history entry recording a step that failed while running (the server's ledger)
|
|
77
|
+
exc: the exception behind `error`, for `--debug`
|
|
78
|
+
"""
|
|
79
|
+
cursor: Cursor | None
|
|
80
|
+
entries: List[JSON] = field(default_factory=list)
|
|
81
|
+
lines: List[JSON] = field(default_factory=list)
|
|
82
|
+
error: JSON | None = None
|
|
83
|
+
kept: bool = False
|
|
84
|
+
failure: JSON | None = None
|
|
85
|
+
exc: BaseException | None = None
|
|
86
|
+
|
|
87
|
+
@property
|
|
88
|
+
def resumable(self) -> bool:
|
|
89
|
+
"""Whether there is a run to come back to: the pause that still stands, or the retry point."""
|
|
90
|
+
return self.kept or self.cursor is not None
|
|
91
|
+
|
|
92
|
+
def outcome(self) -> JSON:
|
|
93
|
+
"""The paused, done, or error object, without `run_id` and `run_file` (the caller adds them)."""
|
|
94
|
+
if self.error is not None:
|
|
95
|
+
return dict(self.error)
|
|
96
|
+
pause = self.cursor.pause
|
|
97
|
+
if pause["kind"] == "done":
|
|
98
|
+
return {"done": True, "state": pause["state"]}
|
|
99
|
+
return {"paused": pause["kind"], **{k: v for k, v in pause.items() if k != "kind"}}
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
# ---------------------------------------------------------------------------- errors
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def error_object(exc: BaseException) -> JSON:
|
|
106
|
+
"""The error object's kind, step, message and per-kind detail for a step that raised."""
|
|
107
|
+
if isinstance(exc, StepError):
|
|
108
|
+
kind = exc.kind if exc.kind in ERROR_KINDS else "server"
|
|
109
|
+
return {"error": kind, "step": exc.step, "message": str(exc), **exc.fields()}
|
|
110
|
+
return {"error": "server", "step": None, "message": f"{type(exc).__name__}: {exc}"}
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _answer_error(error: JSON) -> bool:
|
|
114
|
+
"""An answer to a pause that does not fit, as opposed to a step that failed while running."""
|
|
115
|
+
return error["error"] in ("invalid_input", "invalid_output") and "script" not in error
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
# ----------------------------------------------------------------------------- lines
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def step_line(entry: JSON) -> JSON:
|
|
122
|
+
"""The `--progress` line for one completed step, from its history entry."""
|
|
123
|
+
line: JSON = {"event": "step", "step": entry["step"], "kind": entry["kind"]}
|
|
124
|
+
if entry["kind"] == "router":
|
|
125
|
+
line["to"] = entry["result"]["to"]
|
|
126
|
+
elif entry["kind"] == "decision":
|
|
127
|
+
line["resolver"] = (entry.get("attribution") or {}).get("resolver", "manual")
|
|
128
|
+
elif entry["kind"] == "execution" and "seconds" in entry:
|
|
129
|
+
line["seconds"] = entry["seconds"]
|
|
130
|
+
return line
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def settled_line(pause: JSON) -> JSON | None:
|
|
134
|
+
"""The line for a paused step, printed once its answer is accepted."""
|
|
135
|
+
if pause["kind"] == "client_task":
|
|
136
|
+
return {"event": "step", "step": pause["step"], "kind": "client_task"}
|
|
137
|
+
return None
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
# ---------------------------------------------------------------------------- pauses
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def pause_of(response: JSON) -> JSON | None:
|
|
144
|
+
"""The pause a step response asks for: a client task. Its `state` is the step's projected input."""
|
|
145
|
+
if response["next"] is None or response["kind"] != "client_task":
|
|
146
|
+
return None
|
|
147
|
+
entry, result = response["history"][-1], response["result"]
|
|
148
|
+
return {"kind": "client_task", "step": response["ran"], "task": result["task"], "state": entry["input"],
|
|
149
|
+
"references": result["references"], "answer_with": result["expects"]}
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def thresholds_of(step: Decision) -> Dict[str, float]:
|
|
153
|
+
"""Every question's threshold as the author set it in SKILL.md, the type's default otherwise."""
|
|
154
|
+
return {name: threshold(q.type, step.thresholds, name) for name, q in step.questions.items()}
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def decision_pause(step: Decision, state: JSON, history: List[JSON]) -> JSON:
|
|
158
|
+
"""The pause at a decision: what the decision model is given (`questions`, `state`, and `history`
|
|
159
|
+
when the step asks for it), and the thresholds the client's resolver applies."""
|
|
160
|
+
pause = {"kind": "decision", "step": step.name, "questions": describe_next(step)["questions"],
|
|
161
|
+
"state": project(state, step.inputs), "thresholds": thresholds_of(step)}
|
|
162
|
+
if step.history:
|
|
163
|
+
pause["history"] = history
|
|
164
|
+
return pause
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
# ------------------------------------------------------------------------------ loop
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def start(procedure: Procedure, payload: JSON, scripts: bool = True) -> Advance:
|
|
171
|
+
"""Open a run on the start input and step it until it must stop. With `scripts` false the run
|
|
172
|
+
stops at each execution step (`execute`) instead of running its script here."""
|
|
173
|
+
return _drive(procedure, scripts, None, payload, [])
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def submit(procedure: Procedure, cursor: Cursor, answer: JSON | None, scripts: bool = True,
|
|
177
|
+
attribution: JSON | None = None) -> Advance:
|
|
178
|
+
"""Carry one thing to a run: the answer to its pause (at a decision, with the `attribution` of
|
|
179
|
+
whoever resolved it; None is a manual answer), the report of a script the client ran, or
|
|
180
|
+
(`None`, at a failed step) a retry. A retry may carry keys too; they are merged over the
|
|
181
|
+
state before the step. An answer that does not fit leaves the run where it was (`kept`)."""
|
|
182
|
+
pause = cursor.pause or {}
|
|
183
|
+
kind = pause.get("kind")
|
|
184
|
+
if kind == "done":
|
|
185
|
+
return Advance(cursor, kept=True, error={
|
|
186
|
+
"error": "server", "step": None, "message": "the run is done; there is nothing to answer"})
|
|
187
|
+
if kind == "error":
|
|
188
|
+
return _drive(procedure, scripts, cursor.after, {**cursor.state, **(answer or {})}, cursor.history)
|
|
189
|
+
if kind == "execute":
|
|
190
|
+
if not _is_report(answer):
|
|
191
|
+
return Advance(cursor, kept=True, error={
|
|
192
|
+
"error": "invalid_output", "step": pause["step"],
|
|
193
|
+
"message": f"step {pause['step']!r} runs on the client: post the report of running its script, "
|
|
194
|
+
'{"output": {...}} or {"error": "script_failed"|"timeout"|"requires_unmet", ...}',
|
|
195
|
+
"missing": ["output"], "invalid": []})
|
|
196
|
+
return _drive(procedure, scripts, cursor.after, cursor.state, cursor.history, report=answer)
|
|
197
|
+
if kind not in PAUSED:
|
|
198
|
+
return Advance(cursor, kept=True, error={
|
|
199
|
+
"error": "server", "step": None, "message": f"the run is not paused (status {cursor.status})"})
|
|
200
|
+
if answer is None:
|
|
201
|
+
keys = list(pause["questions"] if kind == "decision" else pause.get("answer_with", {}))
|
|
202
|
+
return Advance(cursor, kept=True, error={
|
|
203
|
+
"error": "invalid_output", "step": pause["step"],
|
|
204
|
+
"message": f"resume needs an answer for the paused {kind} step {pause['step']!r} (--input <answer.json>)",
|
|
205
|
+
"missing": keys, "invalid": []})
|
|
206
|
+
if kind == "decision":
|
|
207
|
+
return _drive(procedure, scripts, cursor.after, cursor.state, cursor.history,
|
|
208
|
+
answering=pause, answers=(answer, attribution))
|
|
209
|
+
try:
|
|
210
|
+
validate_output(pause["step"], pause["answer_with"], answer, strict=False)
|
|
211
|
+
except OutputValidationError as exc:
|
|
212
|
+
return Advance(cursor, kept=True, error=error_object(exc), exc=exc)
|
|
213
|
+
# the client task's entry is written now, like a decision's: the task it was given and the answer
|
|
214
|
+
outputs = {k: answer[k] for k in pause["answer_with"]}
|
|
215
|
+
entry = {"step": pause["step"], "kind": "client_task", "input": pause["state"],
|
|
216
|
+
"result": {"task": pause["task"], "references": pause["references"], "answer": outputs}}
|
|
217
|
+
return _drive(procedure, scripts, cursor.after, {**cursor.state, **outputs}, cursor.history,
|
|
218
|
+
answering=pause, answered=entry)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _is_report(answer: JSON | None) -> bool:
|
|
222
|
+
"""A client's report of running a script: its output, or a failure of a known kind."""
|
|
223
|
+
if not isinstance(answer, dict):
|
|
224
|
+
return False
|
|
225
|
+
if "error" in answer:
|
|
226
|
+
return answer["error"] in ("script_failed", "timeout", "requires_unmet")
|
|
227
|
+
return isinstance(answer.get("output"), dict)
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def _drive(procedure: Procedure, scripts: bool, after: str | None, payload: JSON,
|
|
231
|
+
history: List[JSON], answering: JSON | None = None, answers: tuple[JSON, JSON | None] | None = None,
|
|
232
|
+
report: JSON | None = None, answered: JSON | None = None) -> Advance:
|
|
233
|
+
"""Step until a pause, the end, or a failure. `answering` is the pause this call answers: a bad
|
|
234
|
+
answer leaves it in place. `answers` (the answers and their attribution) answers a decision
|
|
235
|
+
first, `report` an execution step the client ran, and `answered` is the history entry of the
|
|
236
|
+
client task this call answers."""
|
|
237
|
+
carried = len(history)
|
|
238
|
+
if answered is not None:
|
|
239
|
+
history = [*history, answered]
|
|
240
|
+
lines: List[JSON] = []
|
|
241
|
+
|
|
242
|
+
def settle() -> None:
|
|
243
|
+
nonlocal answering
|
|
244
|
+
line = settled_line(answering) if answering is not None else None
|
|
245
|
+
if line is not None:
|
|
246
|
+
lines.append(line)
|
|
247
|
+
answering = None
|
|
248
|
+
|
|
249
|
+
def stop(pause: JSON) -> Advance:
|
|
250
|
+
return Advance(Cursor(after, payload, history, pause), entries=history[carried:], lines=lines)
|
|
251
|
+
|
|
252
|
+
while True:
|
|
253
|
+
node = None
|
|
254
|
+
try:
|
|
255
|
+
node, routed = procedure.resolve(after, payload)
|
|
256
|
+
if answers is not None:
|
|
257
|
+
if not isinstance(node, Decision):
|
|
258
|
+
raise KeyError(f"the step after {after!r} is not a decision")
|
|
259
|
+
response = node.accept_answers(payload, [*history, *routed], *answers).to_dict()
|
|
260
|
+
answers = None
|
|
261
|
+
elif report is not None:
|
|
262
|
+
if not isinstance(node, Execution):
|
|
263
|
+
raise KeyError(f"the step after {after!r} is not an execution step")
|
|
264
|
+
response = node.accept_report(payload, [*history, *routed], report).to_dict()
|
|
265
|
+
report = None
|
|
266
|
+
elif isinstance(node, Decision):
|
|
267
|
+
validate_input(node.name, node.inputs, payload) # before asking anyone
|
|
268
|
+
settle()
|
|
269
|
+
return stop(decision_pause(node, payload, [*history, *routed]))
|
|
270
|
+
elif isinstance(node, Execution) and not scripts:
|
|
271
|
+
request = node.request(payload)
|
|
272
|
+
settle()
|
|
273
|
+
return stop(request)
|
|
274
|
+
else:
|
|
275
|
+
response = procedure.run(after, payload, history).to_dict()
|
|
276
|
+
except Exception as exc:
|
|
277
|
+
return _failed(exc, node, after, payload, history, carried, lines, keep=answering is not None)
|
|
278
|
+
settle()
|
|
279
|
+
pause = pause_of(response)
|
|
280
|
+
if pause is not None: # its entry is written when it is answered
|
|
281
|
+
response["history"] = response["history"][:-1]
|
|
282
|
+
for entry in response["history"][len(history):]:
|
|
283
|
+
if entry["kind"] != "end":
|
|
284
|
+
lines.append(step_line(entry))
|
|
285
|
+
after, payload, history = response["ran"], response["suggested"], response["history"]
|
|
286
|
+
if response["next"] is None:
|
|
287
|
+
payload = response["result"]
|
|
288
|
+
return stop({"kind": "done", "state": response["result"]})
|
|
289
|
+
if pause is not None:
|
|
290
|
+
return stop(pause)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _failed(exc: BaseException, node: Any, after: str | None, state: JSON, history: List[JSON], carried: int,
|
|
294
|
+
lines: List[JSON], keep: bool) -> Advance:
|
|
295
|
+
"""A step failed. The run waits at the state before it, to be retried, unless the failure is a
|
|
296
|
+
bad answer to a pause (`keep`: the pause stands, answer it again) or the start input was
|
|
297
|
+
rejected before any step ran (start again)."""
|
|
298
|
+
error = error_object(exc)
|
|
299
|
+
if keep and _answer_error(error):
|
|
300
|
+
return Advance(None, error=error, kept=True, exc=exc)
|
|
301
|
+
if after is None and not history and isinstance(exc, InputValidationError):
|
|
302
|
+
return Advance(None, error=error, exc=exc)
|
|
303
|
+
detail = exc.fields() if isinstance(exc, StepError) else {}
|
|
304
|
+
if isinstance(getattr(exc, "host", None), str):
|
|
305
|
+
detail["host"] = exc.host # the machine that reported a script's failure
|
|
306
|
+
failure = {"step": getattr(node, "name", error["step"]), "kind": "error", "step_kind": getattr(node, "kind", None),
|
|
307
|
+
"input": state, "result": {"error": f"{type(exc).__name__}: {exc}", **detail}}
|
|
308
|
+
pause = {"kind": "error", "step": error["step"], "error": error["error"]}
|
|
309
|
+
return Advance(Cursor(after, state, history, pause), entries=history[carried:], lines=lines,
|
|
310
|
+
error=error, failure=failure, exc=exc)
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
__all__ = ["Advance", "Cursor", "ERROR_KINDS", "PAUSED", "PRIVATE", "decision_pause", "error_object", "pause_of",
|
|
314
|
+
"settled_line", "start", "step_line", "submit", "thresholds_of"]
|