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.
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