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/executor.py
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
"""The client runs every execution step: next to the data, in this process's machine.
|
|
2
|
+
|
|
3
|
+
A run's loop (`aip.model.engine`, on the server or in this process) stops at an execution step
|
|
4
|
+
with a request: the script as the SKILL.md names it, its launch command, the rendered stdin,
|
|
5
|
+
the timeout, and the skill's `requires`. `Executor.perform` checks `requires` against this
|
|
6
|
+
machine (once per run of the client), runs the script from its folder under the skill root
|
|
7
|
+
with `AIP_WORKDIR` set to the run's working directory, and returns the report the loop
|
|
8
|
+
continues with: `{"output": {...}, "seconds"}`, or a failure with its detail
|
|
9
|
+
(`script_failed` with exit code and stderr, `timeout`, `requires_unmet` with what is missing),
|
|
10
|
+
each with `host`, this machine's name, which the run's history records beside the result.
|
|
11
|
+
The loop checks the output against the step's declared outputs.
|
|
12
|
+
|
|
13
|
+
For a skill folder the skill root is the folder. For a served run it is the revision's
|
|
14
|
+
`scripts/` and `assets/`, fetched once into `~/.aip/cache/<name>@<revision>/` (`AIP_HOME`
|
|
15
|
+
moves it) and verified file by file against the server's manifest; `SKILL.md` is never
|
|
16
|
+
fetched: the client needs the files the scripts use, not the graph.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import hashlib
|
|
22
|
+
import json
|
|
23
|
+
import shutil
|
|
24
|
+
import socket
|
|
25
|
+
import tempfile
|
|
26
|
+
import time
|
|
27
|
+
from pathlib import Path
|
|
28
|
+
from typing import Any, Dict, List
|
|
29
|
+
|
|
30
|
+
from aip.model.environment import Requires
|
|
31
|
+
from aip.model.steps import launch, run_script
|
|
32
|
+
from aip.model.types import StepError
|
|
33
|
+
|
|
34
|
+
JSON = Dict[str, Any]
|
|
35
|
+
|
|
36
|
+
# The folders of a revision a client fetches to run its scripts.
|
|
37
|
+
FETCHED = ("scripts", "assets")
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class Executor:
|
|
41
|
+
"""Runs execution requests for one run. `root` is the skill root the request's `script` is
|
|
42
|
+
relative to; `workdir` is the run's working directory; `python` runs a `python` launcher
|
|
43
|
+
(default this process's own interpreter)."""
|
|
44
|
+
|
|
45
|
+
def __init__(self, root: Path, workdir: Path, python: Path | None = None):
|
|
46
|
+
self.root = Path(root).resolve()
|
|
47
|
+
self.workdir = Path(workdir)
|
|
48
|
+
self.python = python
|
|
49
|
+
self._met: set[str] = set()
|
|
50
|
+
|
|
51
|
+
def perform(self, request: JSON) -> JSON:
|
|
52
|
+
"""Run one execution request and report what happened, and where."""
|
|
53
|
+
return {**self._perform(request), "host": socket.gethostname()}
|
|
54
|
+
|
|
55
|
+
def _perform(self, request: JSON) -> JSON:
|
|
56
|
+
step, script = request["step"], request["script"]
|
|
57
|
+
try:
|
|
58
|
+
self._check(step, request.get("requires"))
|
|
59
|
+
path = (self.root / script).resolve()
|
|
60
|
+
if self.root not in path.parents or not path.is_file():
|
|
61
|
+
raise FileNotFoundError(f"script {script} not found under {self.root}")
|
|
62
|
+
began = time.monotonic()
|
|
63
|
+
output = run_script(step, script, launch(request.get("command"), path, self.python), request["stdin"],
|
|
64
|
+
path.parent, request.get("timeout"), self.workdir)
|
|
65
|
+
except StepError as exc:
|
|
66
|
+
return {"error": exc.kind, "message": str(exc), **exc.fields()}
|
|
67
|
+
except OSError as exc:
|
|
68
|
+
return {"error": "script_failed", "message": f"{type(exc).__name__}: {exc}", "script": script,
|
|
69
|
+
"exit_code": -1, "stderr": str(exc)}
|
|
70
|
+
return {"output": output, "seconds": round(time.monotonic() - began, 3)}
|
|
71
|
+
|
|
72
|
+
def _check(self, step: str, declared: JSON | None) -> None:
|
|
73
|
+
"""`requires` against this machine; a passing check is not repeated."""
|
|
74
|
+
if not declared:
|
|
75
|
+
return
|
|
76
|
+
key = json.dumps(declared, sort_keys=True)
|
|
77
|
+
if key in self._met:
|
|
78
|
+
return
|
|
79
|
+
Requires(interpreter=declared["interpreter"], version=declared.get("version"),
|
|
80
|
+
packages=list(declared.get("packages") or []),
|
|
81
|
+
tools=list(declared.get("tools") or [])).ensure(step, self.python)
|
|
82
|
+
self._met.add(key)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
# ----------------------------------------------------------------------------- cache
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def cache_dir(name: str, revision: str) -> Path:
|
|
89
|
+
"""Where a served revision's `scripts/` and `assets/` are kept on this machine."""
|
|
90
|
+
from aip.client.runner import aip_home
|
|
91
|
+
|
|
92
|
+
return aip_home() / "cache" / f"{name}@{revision}"
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def fetch(server: Any, name: str, revision: str) -> Path:
|
|
96
|
+
"""The revision's `scripts/` and `assets/` on this machine, fetched once and verified.
|
|
97
|
+
|
|
98
|
+
The server's manifest names every file with its sha256 and mode; the client fetches only
|
|
99
|
+
the files under `scripts/` and `assets/`, checks each hash (the first mismatch aborts, naming
|
|
100
|
+
the file), and moves the folder into place in one step. A cached copy is re-verified against
|
|
101
|
+
the manifest on every call and fetched again if anything differs."""
|
|
102
|
+
from aip.client.server import ServerError
|
|
103
|
+
|
|
104
|
+
ref = f"{name}@{revision}"
|
|
105
|
+
wanted = [e for e in server.get(f"/catalog/{ref}/files") if e["path"].split("/", 1)[0] in FETCHED]
|
|
106
|
+
target = cache_dir(name, revision)
|
|
107
|
+
if target.is_dir() and _matches(target, wanted):
|
|
108
|
+
return target
|
|
109
|
+
|
|
110
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
111
|
+
tmp = Path(tempfile.mkdtemp(prefix=f".{ref}-", dir=target.parent))
|
|
112
|
+
try:
|
|
113
|
+
for entry in wanted:
|
|
114
|
+
data = server.file(ref, entry["path"])
|
|
115
|
+
digest = hashlib.sha256(data).hexdigest()
|
|
116
|
+
if digest != entry["sha256"]:
|
|
117
|
+
raise ServerError(0, "hash_mismatch", f"{ref}/{entry['path']}: sha256 {digest[:12]}… does not "
|
|
118
|
+
f"match the manifest's {entry['sha256'][:12]}…",
|
|
119
|
+
location=entry["path"])
|
|
120
|
+
path = tmp / entry["path"]
|
|
121
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
122
|
+
path.write_bytes(data)
|
|
123
|
+
path.chmod(int(entry["mode"]) & 0o777)
|
|
124
|
+
shutil.rmtree(target, ignore_errors=True)
|
|
125
|
+
tmp.rename(target)
|
|
126
|
+
finally:
|
|
127
|
+
shutil.rmtree(tmp, ignore_errors=True)
|
|
128
|
+
return target
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def _matches(folder: Path, entries: List[JSON]) -> bool:
|
|
132
|
+
for entry in entries:
|
|
133
|
+
path = folder / entry["path"]
|
|
134
|
+
if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != entry["sha256"]:
|
|
135
|
+
return False
|
|
136
|
+
return True
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
__all__ = ["Executor", "FETCHED", "cache_dir", "fetch"]
|
aip/client/resolver.py
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""The client resolves decisions: with its own decision model, next to the agent, not on the server.
|
|
2
|
+
|
|
3
|
+
A run's loop (`aip.model.engine`, on the server or in this process) stops at every decision
|
|
4
|
+
with a pause: the questions, the step's declared inputs as `state` (and the run's `history`
|
|
5
|
+
when the step asks for it), and the author's `thresholds`. When a TypeSafe key is configured
|
|
6
|
+
on this client (`TYPESAFE_API_KEY`, else `aip config --decision-model KEY`), `Resolver.resolve`
|
|
7
|
+
asks the model and either answers the decision, every question clear of its threshold, or
|
|
8
|
+
returns a `review` pause for the agent: the model's `proposed_answers` and the questions under
|
|
9
|
+
their thresholds. The agent answers a review with overrides only (`{}` accepts), and
|
|
10
|
+
`Resolver.reviewed` turns that into the final answers. With no key the decision pause is
|
|
11
|
+
printed as it is and the agent answers it in the model's place.
|
|
12
|
+
|
|
13
|
+
Every answer goes back to the loop with its attribution, which the history records:
|
|
14
|
+
`{"resolver": "typesafe"|"manual", "model", "confidence": {question: float}|None, "reviewed"}`,
|
|
15
|
+
plus `proposed` (the model's answers) when a review was answered.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import os
|
|
21
|
+
from typing import Annotated, Any, Dict, Union
|
|
22
|
+
|
|
23
|
+
from pydantic import Field, TypeAdapter
|
|
24
|
+
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
|
|
25
|
+
|
|
26
|
+
from aip.model.steps import Decision, confidence, flag, manual
|
|
27
|
+
from aip.model.types import OutputValidationError
|
|
28
|
+
|
|
29
|
+
JSON = Dict[str, Any]
|
|
30
|
+
|
|
31
|
+
KEY_ENV = "TYPESAFE_API_KEY"
|
|
32
|
+
|
|
33
|
+
_QUESTION = TypeAdapter(Annotated[Union[Noul, Choice, Score], Field(discriminator="type")])
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def configured_key() -> str | None:
|
|
37
|
+
"""The decision model's key on this client: `TYPESAFE_API_KEY`, else the config file's."""
|
|
38
|
+
from aip.client.server import load_config
|
|
39
|
+
|
|
40
|
+
return os.environ.get(KEY_ENV) or (load_config().get("decision_model") or {}).get("api_key") or None
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def status() -> str:
|
|
44
|
+
"""One line for `aip config`: which model resolves decisions on this client, or that none does."""
|
|
45
|
+
from aip.client.server import config_path
|
|
46
|
+
|
|
47
|
+
if os.environ.get(KEY_ENV):
|
|
48
|
+
return f"decision model: TypeSafe (from {KEY_ENV})"
|
|
49
|
+
if configured_key():
|
|
50
|
+
return f"decision model: TypeSafe (from {config_path()})"
|
|
51
|
+
return "decision model: none; every decision pauses for you to answer (`aip config --decision-model KEY`)"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class Resolver:
|
|
55
|
+
"""Answers decision pauses with TypeSafe. `client` is an injected TypeSafe client (tests,
|
|
56
|
+
connection reuse); otherwise one is opened per decision with `api_key`."""
|
|
57
|
+
|
|
58
|
+
def __init__(self, client: Any = None, api_key: str | None = None):
|
|
59
|
+
self.client = client
|
|
60
|
+
self.api_key = api_key
|
|
61
|
+
|
|
62
|
+
@classmethod
|
|
63
|
+
def configured(cls, client: Any = None) -> "Resolver | None":
|
|
64
|
+
"""A resolver when this client has a decision model (an injected client or a key), else None."""
|
|
65
|
+
if client is not None:
|
|
66
|
+
return cls(client)
|
|
67
|
+
key = configured_key()
|
|
68
|
+
return cls(api_key=key) if key else None
|
|
69
|
+
|
|
70
|
+
def ask(self, pause: JSON) -> JSON:
|
|
71
|
+
"""The model's raw response to a decision pause, as JSON."""
|
|
72
|
+
questions = {name: _QUESTION.validate_python(q) for name, q in pause["questions"].items()}
|
|
73
|
+
payload: JSON = {"state": pause["state"]}
|
|
74
|
+
if pause.get("history"):
|
|
75
|
+
payload["history"] = pause["history"]
|
|
76
|
+
if self.client is not None:
|
|
77
|
+
result = self.client.system_one(state=payload, questions=questions)
|
|
78
|
+
else:
|
|
79
|
+
with TypeSafeClient(api_key=self.api_key) as client:
|
|
80
|
+
result = client.system_one(state=payload, questions=questions)
|
|
81
|
+
return result.model_dump(mode="json")
|
|
82
|
+
|
|
83
|
+
def resolve(self, pause: JSON) -> JSON:
|
|
84
|
+
"""`{"answer", "attribution"}` when every question cleared its threshold, else the review pause
|
|
85
|
+
(`{"kind": "review", ...}`), which keeps the model's attribution under `resolution`."""
|
|
86
|
+
result = self.ask(pause)
|
|
87
|
+
answers = result["answers"]
|
|
88
|
+
missing = [q for q in pause["questions"] if q not in answers]
|
|
89
|
+
if missing:
|
|
90
|
+
raise OutputValidationError(pause["step"], [f"the decision model gave no answer for {missing}"],
|
|
91
|
+
missing=missing)
|
|
92
|
+
proposed = {name: Decision.collapse(answers[name]) for name in pause["questions"]}
|
|
93
|
+
attribution = {"resolver": "typesafe", "model": result.get("model"),
|
|
94
|
+
"confidence": {name: confidence(answers[name]) for name in pause["questions"]},
|
|
95
|
+
"reviewed": False}
|
|
96
|
+
flagged = flag({name: answers[name] for name in pause["questions"]}, pause.get("thresholds") or {})
|
|
97
|
+
if not flagged:
|
|
98
|
+
return {"answer": proposed, "attribution": attribution}
|
|
99
|
+
return {"kind": "review", "step": pause["step"], "state": pause["state"], "proposed_answers": proposed,
|
|
100
|
+
"review": flagged, "resolution": attribution}
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def reviewed(pause: JSON, overrides: JSON | None) -> JSON:
|
|
104
|
+
"""The final answers to a review pause and their attribution: the proposed answers with the
|
|
105
|
+
agent's overrides over them. Raises `OutputValidationError` for an answer that overrides
|
|
106
|
+
anything but the step's questions (the pause stands)."""
|
|
107
|
+
if overrides is None:
|
|
108
|
+
raise OutputValidationError(pause["step"], [
|
|
109
|
+
f"resume needs an answer for the paused review step {pause['step']!r} (--input <answer.json>; "
|
|
110
|
+
"{} accepts the proposed answers)"], missing=list(pause["proposed_answers"]))
|
|
111
|
+
proposed = pause["proposed_answers"]
|
|
112
|
+
unknown = [k for k in overrides if k not in proposed]
|
|
113
|
+
if unknown:
|
|
114
|
+
raise OutputValidationError(pause["step"], [f"not questions of step {pause['step']!r}: {unknown}; "
|
|
115
|
+
f"override only {list(proposed)}"], invalid=unknown)
|
|
116
|
+
attribution = {**pause["resolution"], "reviewed": True, "proposed": dict(proposed)}
|
|
117
|
+
return {"answer": {**proposed, **overrides}, "attribution": attribution}
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
__all__ = ["KEY_ENV", "Resolver", "configured_key", "manual", "reviewed", "status"]
|
aip/client/runner.py
ADDED
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
"""Drive a procedure from the command line: run, pause, resume.
|
|
2
|
+
|
|
3
|
+
A run stops one of three ways, and the runner prints one JSON object for each; the shapes
|
|
4
|
+
are a contract, documented in `docs/cli-json.md`:
|
|
5
|
+
|
|
6
|
+
- **paused**: the client must answer. `client_task` (do the step's work), `decision` (no
|
|
7
|
+
decision model on this client: answer the questions), `review` (this client's decision model
|
|
8
|
+
answered a question under its threshold: confirm or override). Each pause carries only the paused step's declared inputs
|
|
9
|
+
as `state`; the answer is merged over the state the run file holds.
|
|
10
|
+
- **done**: the end step was reached; `state` is the end step's inputs.
|
|
11
|
+
- **error**: a step failed. The run file keeps the state before the failing step, and
|
|
12
|
+
`resume` with no input retries it. A bad answer to a pause leaves the pause in place.
|
|
13
|
+
|
|
14
|
+
The loop itself is `aip.model.engine`, run by the backend: in this process for a skill folder,
|
|
15
|
+
on the server for a published name. The SDK's `Driver` (`aip.sdk`) turns each stop into a
|
|
16
|
+
result and writes the run file; the runner prints it, and in interactive mode answers pauses
|
|
17
|
+
from the terminal.
|
|
18
|
+
|
|
19
|
+
Every outcome but an error before anything ran writes the run file. A local run's file holds
|
|
20
|
+
the whole run, and at done the whole history, its ledger; a served run's holds only the run
|
|
21
|
+
id, server, revision, version and pending pause, since the server holds the rest. Run files
|
|
22
|
+
live under the user's home, at `~/.aip/runs/<run-id>.json` (`AIP_HOME` moves it), so
|
|
23
|
+
`aip resume <run-id>` works from any directory; a served run is keyed by the id the server
|
|
24
|
+
assigned, a local run by a generated one. With `progress`, one JSON line per completed step
|
|
25
|
+
is printed before the final object. In interactive mode a pause becomes prompts instead.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
import json
|
|
29
|
+
import os
|
|
30
|
+
import re
|
|
31
|
+
import sys
|
|
32
|
+
import time
|
|
33
|
+
import traceback
|
|
34
|
+
import uuid
|
|
35
|
+
from dataclasses import asdict, dataclass, field
|
|
36
|
+
from pathlib import Path
|
|
37
|
+
from typing import Any, Callable, ClassVar, Dict, List
|
|
38
|
+
|
|
39
|
+
from aip.client.backend import Backend
|
|
40
|
+
from aip.model.engine import ERROR_KINDS
|
|
41
|
+
|
|
42
|
+
JSON = Dict[str, Any]
|
|
43
|
+
|
|
44
|
+
EXIT_DONE = 0
|
|
45
|
+
EXIT_PAUSED = 0
|
|
46
|
+
EXIT_ERROR = 1
|
|
47
|
+
|
|
48
|
+
RUN_ID = re.compile(r"[A-Za-z0-9_-]+")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def aip_home() -> Path:
|
|
52
|
+
"""`AIP_HOME`, else `~/.aip`: where run files live."""
|
|
53
|
+
override = os.environ.get("AIP_HOME")
|
|
54
|
+
return Path(override).expanduser() if override else Path.home() / ".aip"
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def run_path(run_id: str) -> Path:
|
|
58
|
+
"""The run file of `run_id` under `aip_home()`."""
|
|
59
|
+
if not RUN_ID.fullmatch(run_id):
|
|
60
|
+
raise ValueError(f"not a run id: {run_id!r}")
|
|
61
|
+
return aip_home() / "runs" / f"{run_id}.json"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def new_run_id() -> str:
|
|
65
|
+
"""A local run's id, the same shape the server's run backends assign."""
|
|
66
|
+
return uuid.uuid4().hex[:16]
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@dataclass
|
|
70
|
+
class RunFile:
|
|
71
|
+
"""Everything needed to continue a run. A local run's file holds the whole run (`skill_dir`,
|
|
72
|
+
`after`, `state`, `history`); a served run's only a handle (`server`, `name`, `revision`,
|
|
73
|
+
`version`): the server holds the rest. Both hold `run_id`, the run's working directory
|
|
74
|
+
(`workdir`, where its scripts read and write files), and the pending `pause`
|
|
75
|
+
(`{"kind": "client_task"|"review"|"decision"|"error"|"done", "step", ...}`). Unset fields
|
|
76
|
+
are left out of the file."""
|
|
77
|
+
pause: JSON
|
|
78
|
+
run_id: str | None = None
|
|
79
|
+
skill_dir: str | None = None
|
|
80
|
+
after: str | None = None # the step whose output the next input answers (None = start)
|
|
81
|
+
state: JSON | None = None # the run's full state; an answer is merged over it
|
|
82
|
+
history: List[JSON] | None = None
|
|
83
|
+
server: str | None = None
|
|
84
|
+
name: str | None = None
|
|
85
|
+
revision: str | None = None
|
|
86
|
+
version: int | None = None # the server's version of the run, sent back with the answer
|
|
87
|
+
workdir: str | None = None # where the run's scripts read and write files (AIP_WORKDIR)
|
|
88
|
+
created: float = field(default_factory=time.time)
|
|
89
|
+
|
|
90
|
+
LOCAL: ClassVar = ("skill_dir", "after", "state", "history")
|
|
91
|
+
|
|
92
|
+
def save(self, path: Path) -> Path:
|
|
93
|
+
data = {k: v for k, v in asdict(self).items()
|
|
94
|
+
if v is not None or (k in self.LOCAL and self.server is None)}
|
|
95
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
96
|
+
path.write_text(json.dumps(data, indent=2) + "\n")
|
|
97
|
+
return path
|
|
98
|
+
|
|
99
|
+
@classmethod
|
|
100
|
+
def load(cls, path: Path) -> "RunFile":
|
|
101
|
+
data = json.loads(Path(path).read_text())
|
|
102
|
+
if "suggested" in data: # written before 0.6a0
|
|
103
|
+
data["state"] = data.pop("suggested")
|
|
104
|
+
data.pop("thresholds", None) # before B1: thresholds are the author's alone now
|
|
105
|
+
return cls(**data)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def backend_for(run: RunFile, token: str | None = None, session: Any = None, client: Any = None) -> Backend:
|
|
109
|
+
"""The backend a run file was written against: the server it names, else the local folder.
|
|
110
|
+
`client` is an injected decision-model client (tests); otherwise the configured key decides."""
|
|
111
|
+
if run.server:
|
|
112
|
+
from aip.client.backend import HttpBackend
|
|
113
|
+
|
|
114
|
+
return HttpBackend(run.server, token, f"{run.name}@{run.revision}", session=session, workdir=run.workdir,
|
|
115
|
+
client=client)
|
|
116
|
+
from aip.client.backend import LocalBackend
|
|
117
|
+
|
|
118
|
+
return LocalBackend(Path(run.skill_dir), client=client, workdir=run.workdir)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
@dataclass
|
|
122
|
+
class Outcome:
|
|
123
|
+
code: int
|
|
124
|
+
payload: JSON # final state when done, the pause block when paused, the error object
|
|
125
|
+
run_file: Path | None = None
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
Prompter = Callable[[str], str]
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def error_object(exc: BaseException) -> JSON:
|
|
132
|
+
"""The error object's kind, step, message and per-kind detail, for a local or a server failure."""
|
|
133
|
+
from aip.client.server import ServerError
|
|
134
|
+
from aip.model.engine import error_object as step_error
|
|
135
|
+
|
|
136
|
+
if isinstance(exc, ServerError):
|
|
137
|
+
if exc.kind in ERROR_KINDS:
|
|
138
|
+
detail = {k: v for k, v in exc.extra.items() if k not in ("run_id", "errors", "resumable")}
|
|
139
|
+
return {"error": exc.kind, "step": exc.location, "message": exc.message, **detail}
|
|
140
|
+
return {"error": "server", "step": exc.location, "message": str(exc), "status": exc.status}
|
|
141
|
+
return step_error(exc)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class Runner:
|
|
145
|
+
"""The CLI's face on a run: prints what the SDK's `Driver` returns (`docs/cli-json.md`), and in
|
|
146
|
+
interactive mode answers each pause on the terminal instead."""
|
|
147
|
+
|
|
148
|
+
def __init__(self, backend: Backend | None, run_file: Path | None = None,
|
|
149
|
+
interactive: bool = False, prompter: Prompter = input, out=None,
|
|
150
|
+
progress: bool = False, debug: bool = False, run_id: str | None = None):
|
|
151
|
+
"""`run_file` is an explicit path; without one the run file is `run_path(<run id>)`.
|
|
152
|
+
`run_id` is a resumed run's id. `backend` may be None when only `show` is used."""
|
|
153
|
+
self.backend = backend
|
|
154
|
+
self.run_file = run_file
|
|
155
|
+
self.run_id = run_id
|
|
156
|
+
self.interactive = interactive
|
|
157
|
+
self.prompt = prompter
|
|
158
|
+
self.out = out or sys.stdout
|
|
159
|
+
self.progress = progress
|
|
160
|
+
self.debug = debug
|
|
161
|
+
|
|
162
|
+
# ------------------------------------------------------------------ entry points
|
|
163
|
+
|
|
164
|
+
def start(self, payload: JSON | None) -> Outcome:
|
|
165
|
+
from aip.sdk import Driver
|
|
166
|
+
|
|
167
|
+
def go(on_step, on_pause):
|
|
168
|
+
driver = Driver(self.backend, self.run_file, on_step, on_pause)
|
|
169
|
+
return driver.start(self.start_input(driver.start_step()) if payload is None and self.interactive
|
|
170
|
+
else payload)
|
|
171
|
+
return self.show(go)
|
|
172
|
+
|
|
173
|
+
def resume(self, run: RunFile, payload: JSON | None) -> Outcome:
|
|
174
|
+
from aip.sdk import Driver
|
|
175
|
+
|
|
176
|
+
if payload is None and self.interactive and run.pause["kind"] not in ("error", "done"):
|
|
177
|
+
payload = self.ask(run.pause)
|
|
178
|
+
return self.show(lambda on_step, on_pause: Driver(self.backend, self.run_file, on_step, on_pause,
|
|
179
|
+
run_id=run.run_id).resume(run, payload))
|
|
180
|
+
|
|
181
|
+
def start_input(self, start: JSON) -> JSON:
|
|
182
|
+
"""The start input, prompted on the terminal from the start step's description."""
|
|
183
|
+
return self._prompt_inputs(start["inputs"])
|
|
184
|
+
|
|
185
|
+
def show(self, call: Callable[[Callable, Callable | None], Any]) -> Outcome:
|
|
186
|
+
"""Run `call(on_step, on_pause)`, an SDK call that returns a `Paused` or `Done` or raises
|
|
187
|
+
a `RunError`, and print what it stopped at: one object, after the `--progress` lines."""
|
|
188
|
+
from aip.sdk import Done, RunError
|
|
189
|
+
|
|
190
|
+
try:
|
|
191
|
+
result = call(self._line, (lambda paused: self.ask(paused.to_json())) if self.interactive else None)
|
|
192
|
+
except RunError as exc:
|
|
193
|
+
if exc.cause is not None and self.debug:
|
|
194
|
+
traceback.print_exception(exc.cause, file=sys.stderr)
|
|
195
|
+
block = exc.to_json()
|
|
196
|
+
self._print(block)
|
|
197
|
+
return Outcome(EXIT_ERROR, block, exc.run_file)
|
|
198
|
+
if isinstance(result, Done):
|
|
199
|
+
self._print(result.to_json())
|
|
200
|
+
return Outcome(EXIT_DONE, result.state, result.run_file)
|
|
201
|
+
block = result.to_json()
|
|
202
|
+
if not self.interactive:
|
|
203
|
+
self._print(block)
|
|
204
|
+
return Outcome(EXIT_PAUSED, block, result.run_file)
|
|
205
|
+
|
|
206
|
+
def _print(self, obj: JSON) -> None:
|
|
207
|
+
self.out.write((json.dumps(obj) if self.progress else json.dumps(obj, indent=2)) + "\n")
|
|
208
|
+
|
|
209
|
+
def _line(self, line: JSON) -> None:
|
|
210
|
+
if self.progress:
|
|
211
|
+
self.out.write(json.dumps(line) + "\n")
|
|
212
|
+
|
|
213
|
+
# ------------------------------------------------------------------- interactive
|
|
214
|
+
|
|
215
|
+
def ask(self, pause: JSON) -> JSON:
|
|
216
|
+
"""The answer to a pause (a run file's, or the printed object), from the terminal."""
|
|
217
|
+
kind = pause.get("kind") or pause.get("paused")
|
|
218
|
+
if kind == "decision":
|
|
219
|
+
return self._prompt_answers(pause["questions"])
|
|
220
|
+
if kind == "client_task":
|
|
221
|
+
self.out.write("\n" + pause["task"] + "\n\n")
|
|
222
|
+
return self._prompt_inputs(pause["answer_with"])
|
|
223
|
+
return self._prompt_review(pause["review"], pause["proposed_answers"])
|
|
224
|
+
|
|
225
|
+
def _prompt_inputs(self, expects: JSON) -> JSON:
|
|
226
|
+
"""One prompt per declared key, typed from the vocabulary."""
|
|
227
|
+
result: JSON = {}
|
|
228
|
+
for name, dtype in expects.items():
|
|
229
|
+
while True:
|
|
230
|
+
raw = self.prompt(f"{name} ({dtype}): ").strip()
|
|
231
|
+
try:
|
|
232
|
+
result[name] = _coerce(raw, dtype)
|
|
233
|
+
break
|
|
234
|
+
except ValueError as exc:
|
|
235
|
+
self.out.write(f" {exc}\n")
|
|
236
|
+
return result
|
|
237
|
+
|
|
238
|
+
def _prompt_answers(self, questions: JSON) -> JSON:
|
|
239
|
+
answers: JSON = {}
|
|
240
|
+
for name, q in questions.items():
|
|
241
|
+
self.out.write(f"\n{name}: {q.get('instructions', '')}\n")
|
|
242
|
+
if q["type"] == "noul":
|
|
243
|
+
if q.get("criteria"):
|
|
244
|
+
self.out.write(f" yes: {q['criteria'].get('true', '')}\n no: {q['criteria'].get('false', '')}\n")
|
|
245
|
+
answers[name] = _coerce(self.prompt(" yes/no: "), "boolean")
|
|
246
|
+
elif q["type"] == "choice":
|
|
247
|
+
for label, desc in q["criteria"].items():
|
|
248
|
+
self.out.write(f" {label}: {desc or ''}\n")
|
|
249
|
+
while (label := self.prompt(" choice: ").strip()) not in q["criteria"]:
|
|
250
|
+
self.out.write(f" pick one of {list(q['criteria'])}\n")
|
|
251
|
+
answers[name] = label
|
|
252
|
+
else:
|
|
253
|
+
for i, desc in enumerate(q["criteria"]):
|
|
254
|
+
self.out.write(f" {i}: {desc}\n")
|
|
255
|
+
while True:
|
|
256
|
+
level = int(_coerce(self.prompt(" level: "), "integer"))
|
|
257
|
+
if 0 <= level < len(q["criteria"]):
|
|
258
|
+
break
|
|
259
|
+
self.out.write(f" pick 0..{len(q['criteria']) - 1}\n")
|
|
260
|
+
answers[name] = level
|
|
261
|
+
return answers
|
|
262
|
+
|
|
263
|
+
def _prompt_review(self, review: List[JSON], proposed: JSON) -> JSON:
|
|
264
|
+
"""Only the overrides: an empty answer keeps the model's."""
|
|
265
|
+
overrides: JSON = {}
|
|
266
|
+
for item in review:
|
|
267
|
+
name = item["question"]
|
|
268
|
+
self.out.write(f"\n{name}: {item['reason']} (model says {json.dumps(proposed.get(name))})\n")
|
|
269
|
+
if "probabilities" in item:
|
|
270
|
+
self.out.write(" " + json.dumps(item["probabilities"]) + "\n")
|
|
271
|
+
raw = self.prompt(f" keep {json.dumps(proposed.get(name))}? enter to keep, or a new value: ").strip()
|
|
272
|
+
if raw:
|
|
273
|
+
current = proposed.get(name)
|
|
274
|
+
dtype = "boolean" if isinstance(current, bool) else "integer" if isinstance(current, int) else "string"
|
|
275
|
+
overrides[name] = _coerce(raw, dtype)
|
|
276
|
+
return overrides
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def _coerce(raw: str, dtype: str) -> Any:
|
|
280
|
+
raw = raw.strip()
|
|
281
|
+
match dtype:
|
|
282
|
+
case "string":
|
|
283
|
+
return raw
|
|
284
|
+
case "integer":
|
|
285
|
+
try:
|
|
286
|
+
return int(raw)
|
|
287
|
+
except ValueError:
|
|
288
|
+
raise ValueError(f"expected an integer, got {raw!r}") from None
|
|
289
|
+
case "float":
|
|
290
|
+
try:
|
|
291
|
+
return float(raw)
|
|
292
|
+
except ValueError:
|
|
293
|
+
raise ValueError(f"expected a number, got {raw!r}") from None
|
|
294
|
+
case "boolean":
|
|
295
|
+
if raw.lower() in ("y", "yes", "true", "1"):
|
|
296
|
+
return True
|
|
297
|
+
if raw.lower() in ("n", "no", "false", "0"):
|
|
298
|
+
return False
|
|
299
|
+
raise ValueError(f"expected yes/no, got {raw!r}")
|
|
300
|
+
case _:
|
|
301
|
+
try:
|
|
302
|
+
return json.loads(raw)
|
|
303
|
+
except json.JSONDecodeError:
|
|
304
|
+
raise ValueError(f"expected JSON for {dtype}, got {raw!r}") from None
|