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/model/steps.py
ADDED
|
@@ -0,0 +1,607 @@
|
|
|
1
|
+
"""Step model: state, meta, nodes, and the accept flow."""
|
|
2
|
+
|
|
3
|
+
from abc import ABC, abstractmethod
|
|
4
|
+
from dataclasses import dataclass, field
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any, ClassVar, Dict, List, TypeAlias
|
|
7
|
+
import copy
|
|
8
|
+
import json
|
|
9
|
+
import os
|
|
10
|
+
import subprocess
|
|
11
|
+
import sys
|
|
12
|
+
import time
|
|
13
|
+
|
|
14
|
+
from typesafe_sdk import Choice, Noul, Score, SystemOneResponse, TypeSafeClient
|
|
15
|
+
|
|
16
|
+
from aip.model.environment import PYTHON, Requires, RequiresUnmet
|
|
17
|
+
from aip.model.resources import Asset, Reference, ResourceLoader, Script
|
|
18
|
+
from aip.model.types import (
|
|
19
|
+
JSON, DataType, InputValidationError, Inputs, OutputValidationError, ScriptFailed, ScriptTimeout,
|
|
20
|
+
describe_inputs, project, validate_input, validate_output,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
DecisionQuestion: TypeAlias = Noul | Choice | Score
|
|
24
|
+
|
|
25
|
+
# Default decision thresholds. Noul: flag when |p - 0.5| < margin.
|
|
26
|
+
# Choice / Score: flag when the model's confidence < min_confidence.
|
|
27
|
+
DEFAULT_NOUL_MARGIN = 0.15
|
|
28
|
+
DEFAULT_MIN_CONFIDENCE = 0.6
|
|
29
|
+
|
|
30
|
+
@dataclass
|
|
31
|
+
class State:
|
|
32
|
+
"""
|
|
33
|
+
What one step sees: the state projected to the step's declared `inputs`, plus the
|
|
34
|
+
history the client carried in. Built by `accept()`, never persisted server-side.
|
|
35
|
+
"""
|
|
36
|
+
currentState: JSON = field(default_factory=dict)
|
|
37
|
+
history: List[JSON] = field(default_factory=list)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass
|
|
41
|
+
class Meta:
|
|
42
|
+
"""Package metadata, owned by the Procedure."""
|
|
43
|
+
name: str
|
|
44
|
+
description: str = ""
|
|
45
|
+
version: str = "0.1.0"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class StepResponse:
|
|
50
|
+
"""
|
|
51
|
+
What the server returns after running a step.
|
|
52
|
+
|
|
53
|
+
ran: name of the step that ran
|
|
54
|
+
kind: "decision" | "client_task" | "execution" | "end"
|
|
55
|
+
result: raw output of the step
|
|
56
|
+
suggested: the full state after this step: the posted state plus the keys this step
|
|
57
|
+
produced. The client posts it as the next input (answers merged over it)
|
|
58
|
+
review: items the client should look at before accepting `suggested`
|
|
59
|
+
(e.g. low-confidence decision answers); empty means safe to pass through
|
|
60
|
+
next: description of what comes next (see `describe_next`); None at the end
|
|
61
|
+
history: the carried-in history plus this step's entry
|
|
62
|
+
"""
|
|
63
|
+
ran: str
|
|
64
|
+
kind: str
|
|
65
|
+
result: JSON
|
|
66
|
+
suggested: JSON
|
|
67
|
+
review: List[JSON]
|
|
68
|
+
next: JSON | None
|
|
69
|
+
history: List[JSON]
|
|
70
|
+
|
|
71
|
+
def to_dict(self) -> JSON:
|
|
72
|
+
return {
|
|
73
|
+
"ran": self.ran, "kind": self.kind, "result": self.result, "suggested": self.suggested,
|
|
74
|
+
"review": self.review, "next": self.next, "history": self.history,
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@dataclass(kw_only=True)
|
|
79
|
+
class EndStep:
|
|
80
|
+
"""Terminal node. `inputs` is the shape of the final state the client receives."""
|
|
81
|
+
kind: ClassVar[str] = "end"
|
|
82
|
+
name: str = "end"
|
|
83
|
+
inputs: Inputs = field(default_factory=dict)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def branch_key(value: Any) -> str:
|
|
87
|
+
"""Branch keys are YAML strings; collapsed answers are typed. `true`/`false` for a
|
|
88
|
+
noul, the label for a choice, the level number for a score."""
|
|
89
|
+
if isinstance(value, bool):
|
|
90
|
+
return "true" if value else "false"
|
|
91
|
+
return str(value)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@dataclass(kw_only=True)
|
|
95
|
+
class Router:
|
|
96
|
+
"""
|
|
97
|
+
Dumb router: maps the value the client posted under `branch_on` to the next node.
|
|
98
|
+
Calls no model, has no endpoint. The server walks routers internally after the
|
|
99
|
+
client's input arrives; the client only sees the branches for schema purposes.
|
|
100
|
+
|
|
101
|
+
branch_on: key in the posted input whose value selects the branch
|
|
102
|
+
branches: branch value -> node; needs two or more
|
|
103
|
+
"""
|
|
104
|
+
kind: ClassVar[str] = "router"
|
|
105
|
+
name: str
|
|
106
|
+
branch_on: str
|
|
107
|
+
branches: Dict[str, "Node"]
|
|
108
|
+
|
|
109
|
+
def route(self, payload: JSON) -> "Node":
|
|
110
|
+
if self.branch_on not in payload:
|
|
111
|
+
raise InputValidationError(self.name, [f"missing routing key {self.branch_on!r}"], missing=[self.branch_on])
|
|
112
|
+
value = payload[self.branch_on]
|
|
113
|
+
key = branch_key(value)
|
|
114
|
+
if key not in self.branches:
|
|
115
|
+
raise InputValidationError(
|
|
116
|
+
self.name, [f"{self.branch_on}={value!r} has no branch; options: {list(self.branches)}"],
|
|
117
|
+
invalid=[self.branch_on])
|
|
118
|
+
return self.branches[key]
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
@dataclass(kw_only=True)
|
|
122
|
+
class BaseStep(ABC):
|
|
123
|
+
"""
|
|
124
|
+
A node the server runs. Steps are configuration; run state flows through `accept`.
|
|
125
|
+
|
|
126
|
+
name: unique within the procedure; endpoints and history refer to it
|
|
127
|
+
inputs: the keys this step reads; validated on accept, and the only keys it sees
|
|
128
|
+
outputs: the keys this step adds to the state; its result is validated against them
|
|
129
|
+
inputsTo: the node that receives this step's output (a step, a router, or the end)
|
|
130
|
+
"""
|
|
131
|
+
kind: ClassVar[str] = "step"
|
|
132
|
+
name: str
|
|
133
|
+
inputs: Inputs = field(default_factory=dict)
|
|
134
|
+
outputs: Inputs = field(default_factory=dict)
|
|
135
|
+
inputsTo: "Node | None" = None
|
|
136
|
+
loader: ResourceLoader | None = None
|
|
137
|
+
meta: Meta | None = None
|
|
138
|
+
|
|
139
|
+
@abstractmethod
|
|
140
|
+
def _invoke(self, state: State) -> JSON:
|
|
141
|
+
"""Run the step against the accepted state and return its raw result."""
|
|
142
|
+
|
|
143
|
+
def output_types(self) -> Inputs:
|
|
144
|
+
"""The keys this step adds to the state, with their types."""
|
|
145
|
+
return dict(self.outputs)
|
|
146
|
+
|
|
147
|
+
def produced(self, result: JSON) -> JSON:
|
|
148
|
+
"""The keys this step's result adds to the state. By default the (validated) result itself."""
|
|
149
|
+
return dict(result)
|
|
150
|
+
|
|
151
|
+
def review(self, result: JSON) -> List[JSON]:
|
|
152
|
+
"""Items the client should look at before passing `suggested` through."""
|
|
153
|
+
return []
|
|
154
|
+
|
|
155
|
+
def accept(self, payload: JSON, history: List[JSON]) -> StepResponse:
|
|
156
|
+
"""
|
|
157
|
+
Validate the posted state against the declared inputs, run the step on just those
|
|
158
|
+
keys, and merge what it produced back into the full state.
|
|
159
|
+
"""
|
|
160
|
+
validate_input(self.name, self.inputs, payload)
|
|
161
|
+
state = State(currentState=project(payload, self.inputs), history=copy.deepcopy(history))
|
|
162
|
+
began = time.monotonic()
|
|
163
|
+
result = self._invoke(state)
|
|
164
|
+
entry = {"step": self.name, "kind": self.kind, "input": state.currentState, "result": result}
|
|
165
|
+
if isinstance(self, Execution):
|
|
166
|
+
entry["seconds"] = round(time.monotonic() - began, 3)
|
|
167
|
+
return StepResponse(
|
|
168
|
+
ran=self.name,
|
|
169
|
+
kind=self.kind,
|
|
170
|
+
result=result,
|
|
171
|
+
suggested={**payload, **self.produced(result)},
|
|
172
|
+
review=self.review(result),
|
|
173
|
+
next=describe_next(self.inputsTo),
|
|
174
|
+
history=[*history, entry],
|
|
175
|
+
)
|
|
176
|
+
|
|
177
|
+
def _require_loader(self) -> ResourceLoader:
|
|
178
|
+
if self.loader is None:
|
|
179
|
+
raise RuntimeError(f"{type(self).__name__} {self.name!r} needs a ResourceLoader to resolve resources")
|
|
180
|
+
return self.loader
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
Node: TypeAlias = BaseStep | Router | EndStep
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def describe_next(node: Node | None) -> JSON | None:
|
|
187
|
+
"""
|
|
188
|
+
Client-facing description of the node that receives the next input. Routers are
|
|
189
|
+
expanded into their branches so the client can see every possible input shape,
|
|
190
|
+
but the client never resolves them; the server does on the next call.
|
|
191
|
+
"""
|
|
192
|
+
if node is None:
|
|
193
|
+
return None
|
|
194
|
+
if isinstance(node, Router):
|
|
195
|
+
return {
|
|
196
|
+
"step": node.name, "kind": node.kind, "branch_on": node.branch_on,
|
|
197
|
+
"branches": {value: describe_next(target) for value, target in node.branches.items()},
|
|
198
|
+
}
|
|
199
|
+
described: JSON = {"step": node.name, "kind": node.kind, "inputs": describe_inputs(node.inputs)}
|
|
200
|
+
if isinstance(node, Decision):
|
|
201
|
+
described["questions"] = {name: q.model_dump(exclude_none=True) for name, q in node.questions.items()}
|
|
202
|
+
return described
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
@dataclass(kw_only=True)
|
|
206
|
+
class Decision(BaseStep):
|
|
207
|
+
"""
|
|
208
|
+
Runs a SystemOne (TypeSafe / Jev) decision and hands the typed result to the client.
|
|
209
|
+
|
|
210
|
+
The declared inputs are the content being evaluated; the criteria live in each
|
|
211
|
+
question's `instructions`, written by the author. No assets and no framing are injected.
|
|
212
|
+
|
|
213
|
+
questions: keyed by name; answers come back under the same names and, after
|
|
214
|
+
collapse, become state keys of the same name: a decision's outputs
|
|
215
|
+
history: send the run history to the decision model too; off unless the author asks
|
|
216
|
+
thresholds: per-question, the author's, and the only ones applied. Noul: margin around 0.5.
|
|
217
|
+
Choice / Score: minimum confidence. Unset questions use the type's default.
|
|
218
|
+
client: optional injected TypeSafe client (tests, connection reuse); otherwise one
|
|
219
|
+
is opened per invoke using TYPESAFE_API_KEY from the environment
|
|
220
|
+
"""
|
|
221
|
+
kind: ClassVar[str] = "decision"
|
|
222
|
+
questions: Dict[str, DecisionQuestion] = field(default_factory=dict)
|
|
223
|
+
thresholds: Dict[str, float] = field(default_factory=dict)
|
|
224
|
+
history: bool = False
|
|
225
|
+
client: TypeSafeClient | None = None
|
|
226
|
+
|
|
227
|
+
ANSWER_TYPES: ClassVar[Dict[str, DataType]] = {
|
|
228
|
+
"noul": DataType.BOOLEAN, "choice": DataType.STRING, "score": DataType.INTEGER}
|
|
229
|
+
|
|
230
|
+
def render(self, state: State) -> JSON:
|
|
231
|
+
"""Pure projection of state into the JSON `state` sent to Jev: the declared inputs,
|
|
232
|
+
and the history only when the step asks for it."""
|
|
233
|
+
payload: JSON = {"state": state.currentState}
|
|
234
|
+
if self.history and state.history:
|
|
235
|
+
payload["history"] = state.history
|
|
236
|
+
return payload
|
|
237
|
+
|
|
238
|
+
def output_types(self) -> Inputs:
|
|
239
|
+
"""One key per question, typed by what its answer collapses to."""
|
|
240
|
+
return {name: self.ANSWER_TYPES[q.type] for name, q in self.questions.items()}
|
|
241
|
+
|
|
242
|
+
def _invoke(self, state: State) -> JSON:
|
|
243
|
+
"""
|
|
244
|
+
Returns the TypeSafe result as a JSON dict:
|
|
245
|
+
{"model": str,
|
|
246
|
+
"usage": {"input_tokens", "output_tokens"},
|
|
247
|
+
"answers": {name: {"type": "noul"|"choice"|"score", ...}}}
|
|
248
|
+
"""
|
|
249
|
+
if not self.questions:
|
|
250
|
+
raise ValueError(f"Decision {self.name!r} has no questions to ask")
|
|
251
|
+
payload = self.render(state)
|
|
252
|
+
if self.client is not None:
|
|
253
|
+
result: SystemOneResponse = self.client.system_one(state=payload, questions=self.questions)
|
|
254
|
+
else:
|
|
255
|
+
with TypeSafeClient() as client:
|
|
256
|
+
result = client.system_one(state=payload, questions=self.questions)
|
|
257
|
+
return result.model_dump(mode="json")
|
|
258
|
+
|
|
259
|
+
def accept_answers(self, payload: JSON, history: List[JSON], answers: JSON,
|
|
260
|
+
attribution: JSON | None = None) -> StepResponse:
|
|
261
|
+
"""
|
|
262
|
+
The client resolved the decision: `answers` holds one collapsed value per question (bool
|
|
263
|
+
for noul, label for choice, int level for score), and `attribution` says how it got them,
|
|
264
|
+
`{"resolver": "typesafe"|"manual", "model", "confidence": {question: float}|None,
|
|
265
|
+
"reviewed"}`, plus `proposed` (the model's answers before review) when reviewed. None is
|
|
266
|
+
a manual answer. Both are checked and recorded in the history entry.
|
|
267
|
+
"""
|
|
268
|
+
validate_input(self.name, self.inputs, payload)
|
|
269
|
+
missing = [q for q in self.questions if q not in answers]
|
|
270
|
+
if missing:
|
|
271
|
+
raise OutputValidationError(self.name, [f"missing answers for {missing}"], missing=missing)
|
|
272
|
+
self.check_answers(answers)
|
|
273
|
+
attribution = manual() if attribution is None else self.check_attribution(attribution)
|
|
274
|
+
result = {"answers": {name: answers[name] for name in self.questions}}
|
|
275
|
+
entry = {"step": self.name, "kind": self.kind, "input": project(payload, self.inputs),
|
|
276
|
+
"result": result, "attribution": attribution}
|
|
277
|
+
return StepResponse(
|
|
278
|
+
ran=self.name, kind=self.kind, result=result,
|
|
279
|
+
suggested={**payload, **result["answers"]},
|
|
280
|
+
review=[], next=describe_next(self.inputsTo), history=[*history, entry],
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
def check_attribution(self, attribution: JSON) -> JSON:
|
|
284
|
+
"""The attribution as recorded: a known resolver, a model name, a confidence in 0..1 for
|
|
285
|
+
questions of this step, whether the answers were reviewed, and what was proposed before."""
|
|
286
|
+
errors: List[str] = []
|
|
287
|
+
if not isinstance(attribution, dict):
|
|
288
|
+
raise OutputValidationError(self.name, ["attribution must be an object"], invalid=["attribution"])
|
|
289
|
+
resolver = attribution.get("resolver")
|
|
290
|
+
if resolver not in RESOLVERS:
|
|
291
|
+
errors.append(f"attribution.resolver must be one of {list(RESOLVERS)}, got {resolver!r}")
|
|
292
|
+
model = attribution.get("model")
|
|
293
|
+
if model is not None and not isinstance(model, str):
|
|
294
|
+
errors.append("attribution.model must be a string or null")
|
|
295
|
+
scores = attribution.get("confidence")
|
|
296
|
+
if scores is not None and not (isinstance(scores, dict) and all(
|
|
297
|
+
k in self.questions and isinstance(v, (int, float)) and not isinstance(v, bool) and 0 <= v <= 1
|
|
298
|
+
for k, v in scores.items())):
|
|
299
|
+
errors.append("attribution.confidence must map this step's questions to numbers in 0..1")
|
|
300
|
+
reviewed = attribution.get("reviewed", False)
|
|
301
|
+
if not isinstance(reviewed, bool):
|
|
302
|
+
errors.append("attribution.reviewed must be true or false")
|
|
303
|
+
proposed = attribution.get("proposed")
|
|
304
|
+
if proposed is not None:
|
|
305
|
+
if not isinstance(proposed, dict) or set(proposed) != set(self.questions):
|
|
306
|
+
errors.append("attribution.proposed must answer every question of this step")
|
|
307
|
+
else:
|
|
308
|
+
try:
|
|
309
|
+
self.check_answers(proposed)
|
|
310
|
+
except OutputValidationError as exc:
|
|
311
|
+
errors += [f"attribution.proposed: {e}" for e in exc.errors]
|
|
312
|
+
if resolver == "manual" and (model is not None or scores is not None or proposed is not None):
|
|
313
|
+
errors.append("a manual answer has no model, confidence, or proposed answers")
|
|
314
|
+
if errors:
|
|
315
|
+
raise OutputValidationError(self.name, errors, invalid=["attribution"])
|
|
316
|
+
out = {"resolver": resolver, "model": model, "confidence": scores, "reviewed": reviewed}
|
|
317
|
+
if proposed is not None:
|
|
318
|
+
out["proposed"] = proposed
|
|
319
|
+
return out
|
|
320
|
+
|
|
321
|
+
def check_answers(self, answers: JSON) -> None:
|
|
322
|
+
"""Collapsed answers must name only this step's questions and fit each question's type."""
|
|
323
|
+
validate_output(self.name, self.output_types(), {k: v for k, v in answers.items() if k in self.questions},
|
|
324
|
+
strict=False)
|
|
325
|
+
invalid = [key for key in answers if key not in self.questions]
|
|
326
|
+
errors = [f"undeclared output {key!r} (not a question of this step)" for key in invalid]
|
|
327
|
+
for name, q in self.questions.items():
|
|
328
|
+
value = answers[name]
|
|
329
|
+
if q.type == "choice" and value not in q.criteria:
|
|
330
|
+
errors.append(f"{name}: {value!r} is not one of {list(q.criteria)}")
|
|
331
|
+
invalid.append(name)
|
|
332
|
+
if q.type == "score" and isinstance(value, int) and not 0 <= value < len(q.criteria):
|
|
333
|
+
errors.append(f"{name}: level {value} is outside 0..{len(q.criteria) - 1}")
|
|
334
|
+
invalid.append(name)
|
|
335
|
+
if errors:
|
|
336
|
+
raise OutputValidationError(self.name, errors, invalid=invalid)
|
|
337
|
+
|
|
338
|
+
@staticmethod
|
|
339
|
+
def collapse(answer: JSON) -> Any:
|
|
340
|
+
"""Discrete value for one answer: noul -> bool, choice -> label, score -> argmax level."""
|
|
341
|
+
match answer["type"]:
|
|
342
|
+
case "noul":
|
|
343
|
+
return answer["noul"] >= 0.5
|
|
344
|
+
case "choice":
|
|
345
|
+
return answer["choice"]
|
|
346
|
+
case "score":
|
|
347
|
+
return int(max(answer["probabilities"], key=answer["probabilities"].get))
|
|
348
|
+
raise ValueError(f"unknown answer type {answer['type']!r}")
|
|
349
|
+
|
|
350
|
+
def produced(self, result: JSON) -> JSON:
|
|
351
|
+
"""Each answer collapsed to a discrete value under its question name."""
|
|
352
|
+
missing = [name for name in self.questions if name not in result["answers"]]
|
|
353
|
+
if missing:
|
|
354
|
+
raise OutputValidationError(self.name, [f"no answer for {missing}"])
|
|
355
|
+
return {name: self.collapse(result["answers"][name]) for name in self.questions}
|
|
356
|
+
|
|
357
|
+
def review(self, result: JSON) -> List[JSON]:
|
|
358
|
+
"""Answers whose uncertainty crosses the threshold, with what the client needs to decide."""
|
|
359
|
+
return flag(result["answers"], self.thresholds)
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
def threshold(question_type: str, thresholds: Dict[str, float], name: str) -> float:
|
|
363
|
+
"""A question's threshold: the author's, else its type's default."""
|
|
364
|
+
return thresholds.get(name, DEFAULT_NOUL_MARGIN if question_type == "noul" else DEFAULT_MIN_CONFIDENCE)
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
def flag(answers: JSON, thresholds: Dict[str, float]) -> List[JSON]:
|
|
368
|
+
"""The model's answers (`{name: {"type", ...}}`) whose uncertainty crosses their threshold: a noul
|
|
369
|
+
within its margin of 0.5, a choice or score under its minimum confidence."""
|
|
370
|
+
flagged: List[JSON] = []
|
|
371
|
+
for name, answer in answers.items():
|
|
372
|
+
limit = threshold(answer["type"], thresholds, name)
|
|
373
|
+
if answer["type"] == "noul":
|
|
374
|
+
if abs(answer["noul"] - 0.5) < limit:
|
|
375
|
+
flagged.append({"question": name, "type": "noul", "noul": answer["noul"],
|
|
376
|
+
"reason": f"within {limit} of 0.5"})
|
|
377
|
+
elif answer["confidence"] < limit:
|
|
378
|
+
flagged.append({"question": name, "type": answer["type"], "confidence": answer["confidence"],
|
|
379
|
+
"probabilities": answer["probabilities"], "reason": f"confidence below {limit}"})
|
|
380
|
+
return flagged
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def confidence(answer: JSON) -> float:
|
|
384
|
+
"""How sure the model is of its collapsed answer: a noul's probability of the side it chose, a
|
|
385
|
+
choice's or score's own confidence."""
|
|
386
|
+
if answer["type"] == "noul":
|
|
387
|
+
return round(max(answer["noul"], 1 - answer["noul"]), 4)
|
|
388
|
+
return answer["confidence"]
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
RESOLVERS = ("typesafe", "manual")
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def manual() -> JSON:
|
|
395
|
+
"""The attribution of a decision answered with no model: by the client, or the agent at a pause."""
|
|
396
|
+
return {"resolver": "manual", "model": None, "confidence": None, "reviewed": False}
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
class _SafeMap(dict):
|
|
400
|
+
"""format_map helper: unknown placeholders are left intact instead of raising."""
|
|
401
|
+
def __missing__(self, key: str) -> str:
|
|
402
|
+
return "{" + key + "}"
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
@dataclass(kw_only=True)
|
|
406
|
+
class ClientTask(BaseStep):
|
|
407
|
+
"""
|
|
408
|
+
A step the client performs itself (text generation, synthesis, reasoning). Fallback
|
|
409
|
+
for anything not expressible as a Decision or Execution.
|
|
410
|
+
|
|
411
|
+
The template is the whole task: prose rendered at invoke time with `{key}`
|
|
412
|
+
placeholders drawn from the step's declared inputs, plus `{assets[name]}` and
|
|
413
|
+
`{meta.name}`. Nothing is prepended to it. The client does the task and answers with
|
|
414
|
+
the step's `outputs`.
|
|
415
|
+
|
|
416
|
+
template: the asset holding the task template
|
|
417
|
+
assets: extra eager resources available to the template as {assets[name]}
|
|
418
|
+
references: lazy resources; only uri + description are handed to the client
|
|
419
|
+
"""
|
|
420
|
+
kind: ClassVar[str] = "client_task"
|
|
421
|
+
template: Asset
|
|
422
|
+
assets: List[Asset] = field(default_factory=list)
|
|
423
|
+
references: List[Reference] = field(default_factory=list)
|
|
424
|
+
|
|
425
|
+
def render(self, state: State) -> str:
|
|
426
|
+
"""Pure projection of the template over state, assets, and meta."""
|
|
427
|
+
loader = self._require_loader()
|
|
428
|
+
mapping = _SafeMap(state.currentState)
|
|
429
|
+
mapping["assets"] = loader.load_all(self.assets)
|
|
430
|
+
mapping["meta"] = self.meta
|
|
431
|
+
return loader.load(self.template).format_map(mapping)
|
|
432
|
+
|
|
433
|
+
def _invoke(self, state: State) -> JSON:
|
|
434
|
+
"""Hands the rendered task, the reference index, and the keys to answer with to the client."""
|
|
435
|
+
return {"task": self.render(state), "references": [r.summary() for r in self.references],
|
|
436
|
+
"expects": describe_inputs(self.outputs)}
|
|
437
|
+
|
|
438
|
+
def produced(self, result: JSON) -> JSON:
|
|
439
|
+
"""Nothing yet: the client's answer adds the outputs, checked when it is posted."""
|
|
440
|
+
return {}
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
WORKDIR = "AIP_WORKDIR"
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def run_script(step: str, script: str, argv: List[str], stdin: JSON, cwd: Path, timeout: float | None,
|
|
447
|
+
workdir: Path | None = None) -> JSON:
|
|
448
|
+
"""Run one script under the stdin/stdout contract and return the JSON object it printed.
|
|
449
|
+
|
|
450
|
+
The script runs from `cwd` (its own folder) with `AIP_WORKDIR` set to `workdir`, the run's
|
|
451
|
+
working directory, where it reads and writes the run's files. Raises `ScriptTimeout`, or
|
|
452
|
+
`ScriptFailed` for a non-zero exit or stdout that is not one JSON object. The result is not
|
|
453
|
+
checked against the step's outputs here; `Execution.check` does that.
|
|
454
|
+
"""
|
|
455
|
+
env = {**os.environ, WORKDIR: str(Path(workdir or Path.cwd()).resolve())}
|
|
456
|
+
try:
|
|
457
|
+
proc = subprocess.run(argv, input=json.dumps(stdin), capture_output=True, text=True, cwd=cwd,
|
|
458
|
+
timeout=timeout, env=env)
|
|
459
|
+
except subprocess.TimeoutExpired as err:
|
|
460
|
+
raise ScriptTimeout(step, script, timeout) from err
|
|
461
|
+
stderr = proc.stderr.strip()
|
|
462
|
+
if proc.returncode != 0:
|
|
463
|
+
raise ScriptFailed(step, script, proc.returncode, stderr, failed_message(script, proc.returncode, stderr))
|
|
464
|
+
|
|
465
|
+
out = proc.stdout.strip()
|
|
466
|
+
if not out:
|
|
467
|
+
return {}
|
|
468
|
+
try:
|
|
469
|
+
result = json.loads(out)
|
|
470
|
+
except json.JSONDecodeError as err:
|
|
471
|
+
raise ScriptFailed(step, script, 0, stderr,
|
|
472
|
+
f"Script {script} did not write JSON to stdout: {err}\n{out[:500]}") from err
|
|
473
|
+
if not isinstance(result, dict):
|
|
474
|
+
raise ScriptFailed(step, script, 0, stderr,
|
|
475
|
+
f"Script {script} must write a JSON object, got {type(result).__name__}")
|
|
476
|
+
return result
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def failed_message(script: str, exit_code: int, stderr: str) -> str:
|
|
480
|
+
return f"Script {script} exited with {exit_code}:\n{stderr}"
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
def launch(command: List[str] | None, path: Path, python: Path | str | None = None) -> List[str]:
|
|
484
|
+
"""The argument list for a script at `path`: `command`, or `python` on the script. A leading
|
|
485
|
+
`python` is `python` (default: this process's own interpreter)."""
|
|
486
|
+
python = str(python or sys.executable)
|
|
487
|
+
if command is None:
|
|
488
|
+
return [python, str(path)]
|
|
489
|
+
return [python if arg == PYTHON and i == 0 else arg for i, arg in enumerate(command)]
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
@dataclass(kw_only=True)
|
|
493
|
+
class Execution(BaseStep):
|
|
494
|
+
"""
|
|
495
|
+
Executes an action rather than making a decision. Analogous to a tool call. For now
|
|
496
|
+
a script in the package; MCP and endpoints can be added later.
|
|
497
|
+
|
|
498
|
+
Script contract:
|
|
499
|
+
stdin one JSON object: {"state": <the declared inputs only>, "assets": {name: content},
|
|
500
|
+
"expects": <describe_next of the node after this one>}
|
|
501
|
+
(`currentState` carries the same object for one version, for older scripts)
|
|
502
|
+
stdout one JSON object holding exactly the declared `outputs` (empty stdout is {});
|
|
503
|
+
a missing, mistyped, or undeclared key fails the step
|
|
504
|
+
stderr diagnostics; carried in the `script_failed` error when the exit code is non-zero
|
|
505
|
+
env `AIP_WORKDIR`: the run's working directory, where the run's files are
|
|
506
|
+
The script runs from its folder with `command` when the step declares one, otherwise
|
|
507
|
+
`python <script>`. Before it runs, the skill's `requires` block is checked against the
|
|
508
|
+
machine that runs it (`requires_unmet` names what is missing).
|
|
509
|
+
|
|
510
|
+
The script runs on the client. A run that cannot run it in this process (the server's)
|
|
511
|
+
stops at the step with `request()`, what the client needs to run it, and continues with
|
|
512
|
+
`accept_report()` when the client posts what happened. `_invoke` runs it in-process.
|
|
513
|
+
|
|
514
|
+
script: the Script resource to run
|
|
515
|
+
command: the argument list that launches the script, from its folder; None is `python <script>`
|
|
516
|
+
requires: the skill's environment declaration, shared by every Execution of the procedure
|
|
517
|
+
assets: constant inputs the script always receives, e.g. a JSON config. Re-read from
|
|
518
|
+
disk on every invoke so edits are picked up.
|
|
519
|
+
timeout: seconds before the script is killed; None waits forever
|
|
520
|
+
python: the interpreter for a `python` launcher in-process; None is this process's own
|
|
521
|
+
"""
|
|
522
|
+
kind: ClassVar[str] = "execution"
|
|
523
|
+
script: Script
|
|
524
|
+
assets: List[Asset] = field(default_factory=list)
|
|
525
|
+
timeout: float | None = 60.0
|
|
526
|
+
command: List[str] | None = None
|
|
527
|
+
requires: Requires | None = None
|
|
528
|
+
python: Path | None = None
|
|
529
|
+
|
|
530
|
+
@property
|
|
531
|
+
def script_path(self) -> str:
|
|
532
|
+
"""The script as the SKILL.md names it, relative to the skill root: `scripts/x.py`."""
|
|
533
|
+
return Path(*self.script.uri.parts[1:]).as_posix()
|
|
534
|
+
|
|
535
|
+
def render(self, state: State) -> JSON:
|
|
536
|
+
"""Pure projection of the declared inputs + assets into the script's stdin payload."""
|
|
537
|
+
payload: JSON = {"state": state.currentState, "currentState": state.currentState}
|
|
538
|
+
if self.assets:
|
|
539
|
+
payload["assets"] = self._require_loader().load_all(self.assets, fresh=True)
|
|
540
|
+
payload["expects"] = describe_next(self.inputsTo)
|
|
541
|
+
return payload
|
|
542
|
+
|
|
543
|
+
def argv(self, path: Path) -> List[str]:
|
|
544
|
+
"""The launch command: the step's `command`, or `python` on the script."""
|
|
545
|
+
return launch(self.command, path, self.python)
|
|
546
|
+
|
|
547
|
+
def request(self, payload: JSON) -> JSON:
|
|
548
|
+
"""What a client needs to run this step itself on `payload` (the full state, checked against
|
|
549
|
+
the declared inputs): the script, its launch command, the rendered stdin, the timeout,
|
|
550
|
+
and the skill's `requires`. The stop the server's run waits at (kind `execute`)."""
|
|
551
|
+
validate_input(self.name, self.inputs, payload)
|
|
552
|
+
r = self.requires
|
|
553
|
+
return {"kind": "execute", "step": self.name, "script": self.script_path, "command": self.command,
|
|
554
|
+
"stdin": self.render(State(currentState=project(payload, self.inputs))), "timeout": self.timeout,
|
|
555
|
+
"requires": None if r is None else {"interpreter": r.interpreter, "version": r.version,
|
|
556
|
+
"packages": list(r.packages), "tools": list(r.tools)}}
|
|
557
|
+
|
|
558
|
+
def check(self, result: JSON) -> JSON:
|
|
559
|
+
"""The script's result, checked against the declared outputs."""
|
|
560
|
+
try:
|
|
561
|
+
validate_output(self.name, self.outputs, result)
|
|
562
|
+
except OutputValidationError as err:
|
|
563
|
+
err.script = self.script_path
|
|
564
|
+
raise
|
|
565
|
+
return result
|
|
566
|
+
|
|
567
|
+
def accept_report(self, payload: JSON, history: List[JSON], report: JSON) -> StepResponse:
|
|
568
|
+
"""Continue after the client ran the script: `report` is `{"output": {...}, "seconds"}`, or
|
|
569
|
+
a failure `{"error": "script_failed"|"timeout"|"requires_unmet", ...}` with its detail
|
|
570
|
+
(exit code and stderr, the timeout, the missing items), raised here as that error so the
|
|
571
|
+
run records it like a failure in-process."""
|
|
572
|
+
validate_input(self.name, self.inputs, payload)
|
|
573
|
+
if "error" in report:
|
|
574
|
+
raise self.reported_error(report)
|
|
575
|
+
result = self.check(report["output"])
|
|
576
|
+
entry = {"step": self.name, "kind": self.kind, "input": project(payload, self.inputs), "result": result}
|
|
577
|
+
if isinstance(report.get("seconds"), (int, float)):
|
|
578
|
+
entry["seconds"] = round(float(report["seconds"]), 3)
|
|
579
|
+
if isinstance(report.get("host"), str):
|
|
580
|
+
entry["host"] = report["host"]
|
|
581
|
+
return StepResponse(ran=self.name, kind=self.kind, result=result, suggested={**payload, **result},
|
|
582
|
+
review=[], next=describe_next(self.inputsTo), history=[*history, entry])
|
|
583
|
+
|
|
584
|
+
def reported_error(self, report: JSON) -> Exception:
|
|
585
|
+
"""The error a client's failure report stands for; `host` is the machine that reported it."""
|
|
586
|
+
kind, script = report["error"], self.script_path
|
|
587
|
+
if kind == "timeout":
|
|
588
|
+
exc: Exception = ScriptTimeout(self.name, script, report.get("seconds", self.timeout))
|
|
589
|
+
elif kind == "requires_unmet":
|
|
590
|
+
exc = RequiresUnmet(self.name, [str(m) for m in report.get("missing") or []])
|
|
591
|
+
else:
|
|
592
|
+
exit_code, stderr = int(report.get("exit_code", 0) or 0), str(report.get("stderr", ""))
|
|
593
|
+
exc = ScriptFailed(self.name, script, exit_code, stderr,
|
|
594
|
+
report.get("message") or failed_message(script, exit_code, stderr))
|
|
595
|
+
if isinstance(report.get("host"), str):
|
|
596
|
+
exc.host = report["host"]
|
|
597
|
+
return exc
|
|
598
|
+
|
|
599
|
+
def _invoke(self, state: State) -> JSON:
|
|
600
|
+
if self.requires is not None:
|
|
601
|
+
self.requires.ensure(self.name, self.python)
|
|
602
|
+
loader = self._require_loader()
|
|
603
|
+
path = loader.path(self.script.uri)
|
|
604
|
+
if not path.is_file():
|
|
605
|
+
raise FileNotFoundError(f"Script {self.script.uri!s} not found at {path}")
|
|
606
|
+
return self.check(run_script(self.name, self.script_path, self.argv(path), self.render(state), path.parent,
|
|
607
|
+
self.timeout))
|