valgebra-planning 0.0.1__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.
- valgebra_planning/__init__.py +10 -0
- valgebra_planning/_valgebra.py +65 -0
- valgebra_planning/cells.py +312 -0
- valgebra_planning/cli.py +312 -0
- valgebra_planning/codemode.py +132 -0
- valgebra_planning/contracts.py +265 -0
- valgebra_planning/critic.py +377 -0
- valgebra_planning/flows.py +75 -0
- valgebra_planning/library.py +103 -0
- valgebra_planning/mining.py +165 -0
- valgebra_planning/planner.py +703 -0
- valgebra_planning/policy.py +193 -0
- valgebra_planning/privilege.py +180 -0
- valgebra_planning/program.py +236 -0
- valgebra_planning/proxy.py +164 -0
- valgebra_planning/py.typed +0 -0
- valgebra_planning/run.py +268 -0
- valgebra_planning/servers.py +94 -0
- valgebra_planning/vacuity.py +186 -0
- valgebra_planning/verify.py +484 -0
- valgebra_planning-0.0.1.dist-info/METADATA +92 -0
- valgebra_planning-0.0.1.dist-info/RECORD +26 -0
- valgebra_planning-0.0.1.dist-info/WHEEL +4 -0
- valgebra_planning-0.0.1.dist-info/entry_points.txt +2 -0
- valgebra_planning-0.0.1.dist-info/licenses/LICENSE-APACHE +202 -0
- valgebra_planning-0.0.1.dist-info/licenses/LICENSE-MIT +21 -0
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Plans of tool calls proven well-typed for every output the tool contracts admit.
|
|
2
|
+
|
|
3
|
+
A tool's contract is a pair of sets valgebra decides inclusion over. A program of calls and
|
|
4
|
+
type tests is accepted only where every value it passes on is proven inside the argument it
|
|
5
|
+
fills, whatever values inside their output schemas the tools return.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
__all__: list[str] = []
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""The boundary: every name this package takes from valgebra and valgebra-jsonschema.
|
|
2
|
+
|
|
3
|
+
No other module imports either package, so a rename upstream is one edit here, and
|
|
4
|
+
`tests/test_boundaries.py` holds that line.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from valgebra import (
|
|
10
|
+
Validator,
|
|
11
|
+
anything,
|
|
12
|
+
complement,
|
|
13
|
+
intersection,
|
|
14
|
+
nothing,
|
|
15
|
+
union,
|
|
16
|
+
)
|
|
17
|
+
from valgebra_jsonschema import (
|
|
18
|
+
ANNOTATIONS,
|
|
19
|
+
ARRAY,
|
|
20
|
+
BOOLEAN,
|
|
21
|
+
INTEGER,
|
|
22
|
+
JSON,
|
|
23
|
+
NULL,
|
|
24
|
+
NUMBER,
|
|
25
|
+
OBJECT,
|
|
26
|
+
STRING,
|
|
27
|
+
Compiler,
|
|
28
|
+
Tool,
|
|
29
|
+
Unsupported,
|
|
30
|
+
compile_schema,
|
|
31
|
+
finite,
|
|
32
|
+
json_key,
|
|
33
|
+
older,
|
|
34
|
+
read_tool,
|
|
35
|
+
upgrade,
|
|
36
|
+
)
|
|
37
|
+
from valgebra_jsonschema.sample import Sampler
|
|
38
|
+
|
|
39
|
+
__all__ = [
|
|
40
|
+
"ANNOTATIONS",
|
|
41
|
+
"ARRAY",
|
|
42
|
+
"BOOLEAN",
|
|
43
|
+
"INTEGER",
|
|
44
|
+
"JSON",
|
|
45
|
+
"NULL",
|
|
46
|
+
"NUMBER",
|
|
47
|
+
"OBJECT",
|
|
48
|
+
"STRING",
|
|
49
|
+
"Compiler",
|
|
50
|
+
"Sampler",
|
|
51
|
+
"Tool",
|
|
52
|
+
"Unsupported",
|
|
53
|
+
"Validator",
|
|
54
|
+
"anything",
|
|
55
|
+
"compile_schema",
|
|
56
|
+
"complement",
|
|
57
|
+
"finite",
|
|
58
|
+
"intersection",
|
|
59
|
+
"json_key",
|
|
60
|
+
"nothing",
|
|
61
|
+
"older",
|
|
62
|
+
"read_tool",
|
|
63
|
+
"union",
|
|
64
|
+
"upgrade",
|
|
65
|
+
]
|
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
"""The cells: the minterms of every set a plan reads, within each kind of JSON value.
|
|
2
|
+
|
|
3
|
+
Every slot, input and goal is a predicate on JSON values. Each predicate taken inside or
|
|
4
|
+
outside cuts the values into cells, and each predicate is exactly a union of cells, so an
|
|
5
|
+
inclusion between two predicates' cells implies the inclusion between the predicates
|
|
6
|
+
(Graf and Saidi 1997; the minterms of an effective Boolean algebra, D'Antoni and Veanes
|
|
7
|
+
2017). The values split first into seven disjoint kinds, and a predicate cuts only the
|
|
8
|
+
cells of the kinds it meets.
|
|
9
|
+
|
|
10
|
+
A part of a cell is dropped only where valgebra proves it empty. It is inhabited where a
|
|
11
|
+
concrete value lies in it, or where valgebra refutes its emptiness. Every other part is
|
|
12
|
+
kept as undecided, so it can cost a plan, never admit a wrong one. Most cuts are settled by
|
|
13
|
+
relations between two predicates, each asked of valgebra once: a cell inside a predicate
|
|
14
|
+
disjoint from the new one lies outside it, a cell inside a predicate below the new one lies
|
|
15
|
+
inside it, and a cell outside a predicate above it lies outside it.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import itertools
|
|
21
|
+
import json
|
|
22
|
+
import random
|
|
23
|
+
from collections.abc import Iterable, Sequence
|
|
24
|
+
from dataclasses import dataclass, field
|
|
25
|
+
from typing import Any, Literal
|
|
26
|
+
|
|
27
|
+
from valgebra_planning._valgebra import (
|
|
28
|
+
ARRAY,
|
|
29
|
+
BOOLEAN,
|
|
30
|
+
INTEGER,
|
|
31
|
+
NULL,
|
|
32
|
+
NUMBER,
|
|
33
|
+
OBJECT,
|
|
34
|
+
STRING,
|
|
35
|
+
Sampler,
|
|
36
|
+
Unsupported,
|
|
37
|
+
Validator,
|
|
38
|
+
complement,
|
|
39
|
+
finite,
|
|
40
|
+
intersection,
|
|
41
|
+
nothing,
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
__all__ = ["Abstraction", "Cell", "Predicate", "Status", "abstract", "gather"]
|
|
45
|
+
|
|
46
|
+
#: The seven kinds of JSON value, which partition every value `json.loads` returns that holds
|
|
47
|
+
#: no NaN: JSON has none (RFC 8259 §6), and valgebra-jsonschema compiles no set holding one.
|
|
48
|
+
KINDS: dict[str, Validator[Any]] = {
|
|
49
|
+
"null": NULL,
|
|
50
|
+
"boolean": BOOLEAN,
|
|
51
|
+
"integer": INTEGER,
|
|
52
|
+
"fraction": intersection(NUMBER, complement(INTEGER)),
|
|
53
|
+
"string": STRING,
|
|
54
|
+
"array": ARRAY,
|
|
55
|
+
"object": OBJECT,
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
#: Values at the edges of common bounds, tried in every cell before any draw.
|
|
59
|
+
EDGES: tuple[Any, ...] = (
|
|
60
|
+
None,
|
|
61
|
+
True,
|
|
62
|
+
False,
|
|
63
|
+
0,
|
|
64
|
+
1,
|
|
65
|
+
-1,
|
|
66
|
+
2,
|
|
67
|
+
100,
|
|
68
|
+
1000,
|
|
69
|
+
0.5,
|
|
70
|
+
-0.5,
|
|
71
|
+
1.5,
|
|
72
|
+
float("inf"),
|
|
73
|
+
"",
|
|
74
|
+
"a",
|
|
75
|
+
"0",
|
|
76
|
+
[],
|
|
77
|
+
[None],
|
|
78
|
+
{},
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
#: How many values are drawn from each predicate's schema.
|
|
82
|
+
DRAWS = 24
|
|
83
|
+
|
|
84
|
+
#: How many objects of each schema's draws are merged with every other schema's.
|
|
85
|
+
MERGED = 2
|
|
86
|
+
|
|
87
|
+
#: How many seeded merges of a random subset of the object schemas are tried.
|
|
88
|
+
SUBSETS = 64
|
|
89
|
+
|
|
90
|
+
Status = Literal["inhabited", "undecided"]
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@dataclass(frozen=True, slots=True)
|
|
94
|
+
class Predicate:
|
|
95
|
+
"""A set a plan reads, with the schema it compiles from and the names standing for it."""
|
|
96
|
+
|
|
97
|
+
names: tuple[str, ...]
|
|
98
|
+
values: Validator[Any]
|
|
99
|
+
schema: object
|
|
100
|
+
root: object
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
@dataclass(frozen=True, slots=True)
|
|
104
|
+
class Cell:
|
|
105
|
+
"""One minterm: a kind, the predicates it lies inside, and whether it holds a value.
|
|
106
|
+
|
|
107
|
+
The cell lies outside every predicate of its kind not in ``inside``. ``witness`` holds
|
|
108
|
+
a member where one is known; an inhabited cell without one was proven non-empty.
|
|
109
|
+
"""
|
|
110
|
+
|
|
111
|
+
kind: str
|
|
112
|
+
inside: frozenset[int]
|
|
113
|
+
values: Validator[Any]
|
|
114
|
+
status: Status
|
|
115
|
+
witness: tuple[Any, ...] = ()
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
@dataclass(slots=True)
|
|
119
|
+
class _Split:
|
|
120
|
+
kind: str
|
|
121
|
+
inside: set[int]
|
|
122
|
+
outside: set[int]
|
|
123
|
+
values: Validator[Any]
|
|
124
|
+
witnesses: list[Any]
|
|
125
|
+
proven: bool = False
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass(slots=True)
|
|
129
|
+
class Abstraction:
|
|
130
|
+
"""The predicates of a plan and the cells they cut the JSON values into."""
|
|
131
|
+
|
|
132
|
+
predicates: tuple[Predicate, ...]
|
|
133
|
+
cells: tuple[Cell, ...]
|
|
134
|
+
asked: int = 0
|
|
135
|
+
_members: dict[int, frozenset[int]] = field(default_factory=dict)
|
|
136
|
+
|
|
137
|
+
def index(self, name: str) -> int:
|
|
138
|
+
"""Return the predicate a name stands for, or raise `KeyError`."""
|
|
139
|
+
for i, predicate in enumerate(self.predicates):
|
|
140
|
+
if name in predicate.names:
|
|
141
|
+
return i
|
|
142
|
+
raise KeyError(name)
|
|
143
|
+
|
|
144
|
+
def cells_of(self, predicate: int) -> frozenset[int]:
|
|
145
|
+
"""Return the cells lying inside a predicate."""
|
|
146
|
+
if predicate not in self._members:
|
|
147
|
+
self._members[predicate] = frozenset(
|
|
148
|
+
i for i, cell in enumerate(self.cells) if predicate in cell.inside
|
|
149
|
+
)
|
|
150
|
+
return self._members[predicate]
|
|
151
|
+
|
|
152
|
+
def members(self, cell: int) -> tuple[Any, ...]:
|
|
153
|
+
"""Return the values a cell holds where a predicate it lies inside lists them all.
|
|
154
|
+
|
|
155
|
+
Elsewhere, the member found for it, if any.
|
|
156
|
+
"""
|
|
157
|
+
held = self.cells[cell]
|
|
158
|
+
for i in sorted(held.inside):
|
|
159
|
+
predicate = self.predicates[i]
|
|
160
|
+
listed = finite(predicate.schema, predicate.root)
|
|
161
|
+
if listed is not None:
|
|
162
|
+
return tuple(v for v in listed if held.values.is_valid(v))
|
|
163
|
+
return held.witness
|
|
164
|
+
|
|
165
|
+
def undecided(self, cells: Iterable[int]) -> int:
|
|
166
|
+
"""Return how many of ``cells`` may be empty."""
|
|
167
|
+
return sum(self.cells[i].status == "undecided" for i in cells)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _key(schema: object, root: object) -> str:
|
|
171
|
+
text = json.dumps(schema, sort_keys=True, default=repr)
|
|
172
|
+
# A reference reads against its document, so the same text under two roots is two sets.
|
|
173
|
+
if "$ref" in text:
|
|
174
|
+
text += json.dumps(root, sort_keys=True, default=repr)
|
|
175
|
+
return text
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def gather(entries: Iterable[tuple[str, Validator[Any], object, object]]) -> list[Predicate]:
|
|
179
|
+
"""Merge named sets with the same schema text into one predicate each, keeping order."""
|
|
180
|
+
merged: dict[str, Predicate] = {}
|
|
181
|
+
for name, values, schema, root in entries:
|
|
182
|
+
key = _key(schema, root)
|
|
183
|
+
if key in merged:
|
|
184
|
+
held = merged[key]
|
|
185
|
+
merged[key] = Predicate((*held.names, name), held.values, held.schema, held.root)
|
|
186
|
+
else:
|
|
187
|
+
merged[key] = Predicate((name,), values, schema, root)
|
|
188
|
+
return list(merged.values())
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
class _Relations:
|
|
192
|
+
"""Relations between two predicates, each asked of valgebra at most once."""
|
|
193
|
+
|
|
194
|
+
def __init__(self, predicates: Sequence[Predicate]) -> None:
|
|
195
|
+
self.predicates = predicates
|
|
196
|
+
self.below: dict[tuple[int, int], bool] = {}
|
|
197
|
+
self.apart: dict[tuple[int, int], bool] = {}
|
|
198
|
+
self.asked = 0
|
|
199
|
+
|
|
200
|
+
def is_below(self, i: int, j: int) -> bool:
|
|
201
|
+
"""Return whether predicate ``i`` is proven inside ``j``."""
|
|
202
|
+
if (i, j) not in self.below:
|
|
203
|
+
self.asked += 1
|
|
204
|
+
answer = self.predicates[i].values.relation_to(self.predicates[j].values)
|
|
205
|
+
self.below[i, j] = answer == "subset"
|
|
206
|
+
return self.below[i, j]
|
|
207
|
+
|
|
208
|
+
def are_apart(self, i: int, j: int) -> bool:
|
|
209
|
+
"""Return whether the two predicates are proven to share no value."""
|
|
210
|
+
key = (min(i, j), max(i, j))
|
|
211
|
+
if key not in self.apart:
|
|
212
|
+
self.asked += 1
|
|
213
|
+
meet = intersection(self.predicates[i].values, self.predicates[j].values)
|
|
214
|
+
self.apart[key] = meet.relation_to(nothing) == "subset"
|
|
215
|
+
return self.apart[key]
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _pool(predicates: Sequence[Predicate], rng: random.Random) -> list[Any]:
|
|
219
|
+
"""Return candidate members: the edges, every listed value, and draws from each schema.
|
|
220
|
+
|
|
221
|
+
An open record meets another wherever a value carries both their keys, which no draw from
|
|
222
|
+
one schema does, so the objects drawn are also merged: every pair, and seeded subsets of
|
|
223
|
+
up to every one. Membership alone judges each candidate.
|
|
224
|
+
"""
|
|
225
|
+
pool = list(EDGES)
|
|
226
|
+
objects: list[list[dict[str, Any]]] = []
|
|
227
|
+
for predicate in predicates:
|
|
228
|
+
listed = finite(predicate.schema, predicate.root)
|
|
229
|
+
if listed:
|
|
230
|
+
pool.extend(listed)
|
|
231
|
+
try:
|
|
232
|
+
drawn = Sampler(predicate.root, rng).draw(predicate.schema, DRAWS)
|
|
233
|
+
except (Unsupported, RecursionError):
|
|
234
|
+
continue
|
|
235
|
+
pool.extend(drawn)
|
|
236
|
+
records = [value for value in drawn if isinstance(value, dict)][:MERGED]
|
|
237
|
+
if records:
|
|
238
|
+
objects.append(records)
|
|
239
|
+
for first, second in itertools.combinations(objects, 2):
|
|
240
|
+
pool.extend({**a, **b} for a in first for b in second)
|
|
241
|
+
for _ in range(SUBSETS):
|
|
242
|
+
chosen = rng.sample(objects, rng.randint(2, len(objects))) if len(objects) > 1 else []
|
|
243
|
+
merged: dict[str, Any] = {}
|
|
244
|
+
for records in chosen:
|
|
245
|
+
merged.update(rng.choice(records))
|
|
246
|
+
if merged:
|
|
247
|
+
pool.append(merged)
|
|
248
|
+
return pool
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _emptiness(values: Validator[Any]) -> Literal["empty", "inhabited", "undecided"]:
|
|
252
|
+
answer = values.relation_to(nothing)
|
|
253
|
+
if answer == "subset":
|
|
254
|
+
return "empty"
|
|
255
|
+
return "inhabited" if answer == "not_subset" else "undecided"
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def _cut(split: _Split, i: int, predicate: Predicate, relations: _Relations) -> list[_Split]:
|
|
259
|
+
"""Cut one cell by one predicate, keeping each part that may hold a value."""
|
|
260
|
+
if any(relations.are_apart(i, j) for j in split.inside) or any(
|
|
261
|
+
relations.is_below(i, j) for j in split.outside
|
|
262
|
+
):
|
|
263
|
+
split.outside.add(i)
|
|
264
|
+
return [split]
|
|
265
|
+
if any(relations.is_below(j, i) for j in split.inside):
|
|
266
|
+
split.inside.add(i)
|
|
267
|
+
return [split]
|
|
268
|
+
parts = []
|
|
269
|
+
for inside in (True, False):
|
|
270
|
+
values = intersection(
|
|
271
|
+
split.values, predicate.values if inside else complement(predicate.values)
|
|
272
|
+
)
|
|
273
|
+
witnesses = [v for v in split.witnesses if predicate.values.is_valid(v) == inside]
|
|
274
|
+
proven = bool(witnesses)
|
|
275
|
+
if not witnesses:
|
|
276
|
+
emptiness = _emptiness(values)
|
|
277
|
+
if emptiness == "empty":
|
|
278
|
+
continue
|
|
279
|
+
proven = emptiness == "inhabited"
|
|
280
|
+
held = split.inside | {i} if inside else set(split.inside)
|
|
281
|
+
out = set(split.outside) if inside else split.outside | {i}
|
|
282
|
+
parts.append(_Split(split.kind, held, out, values, witnesses, proven))
|
|
283
|
+
return parts
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def abstract(predicates: Sequence[Predicate], *, seed: int = 0) -> Abstraction:
|
|
287
|
+
"""Cut the JSON values into the cells of ``predicates``."""
|
|
288
|
+
rng = random.Random(seed)
|
|
289
|
+
relations = _Relations(predicates)
|
|
290
|
+
pool = _pool(predicates, rng)
|
|
291
|
+
cells: list[Cell] = []
|
|
292
|
+
for kind, kind_values in KINDS.items():
|
|
293
|
+
meets = [
|
|
294
|
+
i
|
|
295
|
+
for i, predicate in enumerate(predicates)
|
|
296
|
+
if _emptiness(intersection(kind_values, predicate.values)) != "empty"
|
|
297
|
+
]
|
|
298
|
+
members = [v for v in pool if kind_values.is_valid(v)]
|
|
299
|
+
splits = [_Split(kind, set(), set(), kind_values, members, proven=bool(members))]
|
|
300
|
+
for i in meets:
|
|
301
|
+
splits = [part for split in splits for part in _cut(split, i, predicates[i], relations)]
|
|
302
|
+
cells.extend(
|
|
303
|
+
Cell(
|
|
304
|
+
kind=split.kind,
|
|
305
|
+
inside=frozenset(split.inside),
|
|
306
|
+
values=split.values,
|
|
307
|
+
status="inhabited" if split.proven else "undecided",
|
|
308
|
+
witness=tuple(split.witnesses[:1]),
|
|
309
|
+
)
|
|
310
|
+
for split in splits
|
|
311
|
+
)
|
|
312
|
+
return Abstraction(tuple(predicates), tuple(cells), asked=relations.asked)
|
valgebra_planning/cli.py
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
"""The command line: plan a library's tasks, or critique a program written for one.
|
|
2
|
+
|
|
3
|
+
valgebra-planning plan LIBRARY [--task NAME] [--server SERVER] [--json]
|
|
4
|
+
valgebra-planning critique LIBRARY --task NAME PROGRAM [--server SERVER] [--json]
|
|
5
|
+
valgebra-planning run LIBRARY --task NAME --inputs JSON --server SERVER [--json]
|
|
6
|
+
valgebra-planning check LIBRARY [--server SERVER] [--json]
|
|
7
|
+
valgebra-planning privileges OLD NEW [--json]
|
|
8
|
+
valgebra-planning stubs LIBRARY [--server SERVER]
|
|
9
|
+
valgebra-planning proxy --server SERVER [--library LIBRARY]
|
|
10
|
+
|
|
11
|
+
``LIBRARY`` is a directory `valgebra_planning.library.read_library` reads. ``plan`` prints each
|
|
12
|
+
task's program and its verification; it exits 1 when a task gets no program. ``critique`` reads a
|
|
13
|
+
program written in Python, verifies it under the task's rules and prints what is not proven; it
|
|
14
|
+
exits 1 when the program is not accepted. ``run`` plans a task and runs the program against a
|
|
15
|
+
live server, failing closed; it exits 1 when the run does not return a value inside the goal.
|
|
16
|
+
``check`` lists every specification that holds vacuously and exits 1 when it finds one.
|
|
17
|
+
``privileges`` compares two privilege policies in Progent's format and exits 1 unless the new one
|
|
18
|
+
narrows the old for every tool it names. ``proxy`` serves an MCP server over stdio in front of
|
|
19
|
+
``SERVER``, holding every call to the contracts and to the library's policies and flow rules.
|
|
20
|
+
``stubs`` prints the tools as typed Python stubs, their schemas in their docstrings, for a model
|
|
21
|
+
to write a program against.
|
|
22
|
+
``SERVER`` is a URL or a command starting a stdio server; its tools replace ``tools.json``, and
|
|
23
|
+
it needs the ``mcp`` extra. With ``--json`` each prints one JSON document.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
import argparse
|
|
29
|
+
import asyncio
|
|
30
|
+
import json
|
|
31
|
+
import sys
|
|
32
|
+
from collections.abc import Mapping, Sequence
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
from typing import Any
|
|
35
|
+
|
|
36
|
+
from valgebra_planning.codemode import stubs
|
|
37
|
+
from valgebra_planning.contracts import Contract
|
|
38
|
+
from valgebra_planning.critic import ProgramError, critique
|
|
39
|
+
from valgebra_planning.library import Library, Problem, read_library
|
|
40
|
+
from valgebra_planning.planner import Plan, plan
|
|
41
|
+
from valgebra_planning.privilege import describe, read_privileges, updates
|
|
42
|
+
from valgebra_planning.program import render
|
|
43
|
+
from valgebra_planning.run import blame
|
|
44
|
+
from valgebra_planning.vacuity import vacuities
|
|
45
|
+
from valgebra_planning.verify import Verification, verify
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _links(checked: Verification) -> list[dict[str, Any]]:
|
|
49
|
+
return [
|
|
50
|
+
{
|
|
51
|
+
"where": link.where,
|
|
52
|
+
"claim": link.claim,
|
|
53
|
+
"verdict": link.verdict,
|
|
54
|
+
"counterexample": list(link.counterexample),
|
|
55
|
+
"assumed": list(link.assumed),
|
|
56
|
+
}
|
|
57
|
+
for link in checked.links
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _planned(library: Library, problem: Problem) -> tuple[dict[str, Any], Plan]:
|
|
62
|
+
"""Return a problem's row, its program verified, and the plan the row reads."""
|
|
63
|
+
found = plan(
|
|
64
|
+
library.tools,
|
|
65
|
+
problem.task,
|
|
66
|
+
errors=problem.errors,
|
|
67
|
+
policies=problem.policies,
|
|
68
|
+
flows=problem.flows,
|
|
69
|
+
types=problem.types,
|
|
70
|
+
)
|
|
71
|
+
row: dict[str, Any] = {"task": problem.task.name, "program": None}
|
|
72
|
+
if found.program is None:
|
|
73
|
+
return row, found
|
|
74
|
+
checked = verify(
|
|
75
|
+
found.program,
|
|
76
|
+
library.tools,
|
|
77
|
+
problem.task,
|
|
78
|
+
errors=problem.errors,
|
|
79
|
+
policies=problem.policies,
|
|
80
|
+
flows=problem.flows,
|
|
81
|
+
)
|
|
82
|
+
return row | {
|
|
83
|
+
"program": render(found.program),
|
|
84
|
+
"strong": found.strong,
|
|
85
|
+
"proven": checked.proven,
|
|
86
|
+
"links": _links(checked),
|
|
87
|
+
"uncovered": [
|
|
88
|
+
{"where": u.where, "ref": u.ref, "examples": list(u.examples)} for u in found.uncovered
|
|
89
|
+
],
|
|
90
|
+
"assumed": list(found.assumed),
|
|
91
|
+
}, found
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _text(row: dict[str, Any]) -> str:
|
|
95
|
+
lines = [f"## {row['task']}", ""]
|
|
96
|
+
if row["program"] is None:
|
|
97
|
+
return "\n".join([*lines, "no program"])
|
|
98
|
+
proven = sum(link["verdict"] == "proven" for link in row["links"])
|
|
99
|
+
kind = "strong" if row["strong"] else "weak"
|
|
100
|
+
lines += [row["program"], "", f"{kind}; {proven} of {len(row['links'])} links proven"]
|
|
101
|
+
lines += [
|
|
102
|
+
f"{link['verdict']}: {link['claim']}" + (f" (at {link['where']})" if link["where"] else "")
|
|
103
|
+
for link in row["links"]
|
|
104
|
+
if link["verdict"] != "proven"
|
|
105
|
+
]
|
|
106
|
+
lines += [
|
|
107
|
+
f"uncovered at {u['where'] or 'top'}: {u['ref']}, {u['examples']}" for u in row["uncovered"]
|
|
108
|
+
]
|
|
109
|
+
lines += [f"assumed from the observed calls: {binding}" for binding in row["assumed"]]
|
|
110
|
+
return "\n".join(lines)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _plan(library: Library, names: Sequence[str], *, as_json: bool) -> int:
|
|
114
|
+
problems = [library.problem(name) for name in names] if names else list(library.problems)
|
|
115
|
+
rows = [_planned(library, problem)[0] for problem in problems]
|
|
116
|
+
print(json.dumps(rows, indent=2) if as_json else "\n\n".join(map(_text, rows)))
|
|
117
|
+
return 0 if all(row["program"] is not None for row in rows) else 1
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _critique(library: Library, name: str, source: Path, *, as_json: bool) -> int:
|
|
121
|
+
problem = library.problem(name)
|
|
122
|
+
try:
|
|
123
|
+
checked = critique(
|
|
124
|
+
source.read_text(encoding="utf-8"),
|
|
125
|
+
library.tools,
|
|
126
|
+
problem.task,
|
|
127
|
+
errors=problem.errors,
|
|
128
|
+
policies=problem.policies,
|
|
129
|
+
flows=problem.flows,
|
|
130
|
+
types=problem.types,
|
|
131
|
+
)
|
|
132
|
+
except ProgramError as error:
|
|
133
|
+
print(f"{source}: {error}", file=sys.stderr)
|
|
134
|
+
return 2
|
|
135
|
+
if as_json:
|
|
136
|
+
print(
|
|
137
|
+
json.dumps(
|
|
138
|
+
{
|
|
139
|
+
"task": name,
|
|
140
|
+
"accepted": checked.accepted,
|
|
141
|
+
"links": _links(checked.verification),
|
|
142
|
+
"notes": list(checked.notes),
|
|
143
|
+
},
|
|
144
|
+
indent=2,
|
|
145
|
+
)
|
|
146
|
+
)
|
|
147
|
+
else:
|
|
148
|
+
proven = checked.verification.count("proven")
|
|
149
|
+
print(f"{name}: {proven} of {len(checked.verification.links)} links proven")
|
|
150
|
+
print("\n".join(checked.notes) if checked.notes else "accepted")
|
|
151
|
+
return 0 if checked.accepted else 1
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _served(server: str) -> Mapping[str, Contract]:
|
|
155
|
+
"""Return the contracts of a live server's tools."""
|
|
156
|
+
from valgebra_planning.servers import connect, read_server # noqa: PLC0415 - the mcp extra
|
|
157
|
+
|
|
158
|
+
async def listed() -> dict[str, Contract]:
|
|
159
|
+
async with connect(server) as client:
|
|
160
|
+
return await read_server(client)
|
|
161
|
+
|
|
162
|
+
return asyncio.run(listed())
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def _run(directory: Path, name: str, inputs: dict[str, Any], server: str, *, as_json: bool) -> int:
|
|
166
|
+
"""Plan a task over a live server's tools and run the program against it, in one session."""
|
|
167
|
+
from valgebra_planning.servers import connect, read_server, run_on_server # noqa: PLC0415
|
|
168
|
+
|
|
169
|
+
async def ran() -> dict[str, Any]:
|
|
170
|
+
async with connect(server) as client:
|
|
171
|
+
library = read_library(directory, await read_server(client))
|
|
172
|
+
problem = library.problem(name)
|
|
173
|
+
row, found = _planned(library, problem)
|
|
174
|
+
if found.program is None:
|
|
175
|
+
return row
|
|
176
|
+
result = await run_on_server(
|
|
177
|
+
found.program,
|
|
178
|
+
library.tools,
|
|
179
|
+
problem.task,
|
|
180
|
+
inputs,
|
|
181
|
+
client,
|
|
182
|
+
policies=problem.policies,
|
|
183
|
+
)
|
|
184
|
+
return row | {
|
|
185
|
+
"value": result.value,
|
|
186
|
+
"stopped": result.stopped,
|
|
187
|
+
"refused": result.refused,
|
|
188
|
+
"broken": list(result.broken),
|
|
189
|
+
"blame": blame(result, library.tools, proven=row["proven"]),
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
row = asyncio.run(ran())
|
|
193
|
+
returned = row["program"] is not None and row["stopped"] is None and row["refused"] is None
|
|
194
|
+
if as_json:
|
|
195
|
+
print(json.dumps(row, indent=2))
|
|
196
|
+
elif row["program"] is None:
|
|
197
|
+
print(_text(row))
|
|
198
|
+
else:
|
|
199
|
+
ended = (
|
|
200
|
+
f"refused: {row['refused']}"
|
|
201
|
+
if row["refused"]
|
|
202
|
+
else (
|
|
203
|
+
f"stopped on {row['stopped']}" if row["stopped"] else f"returned {row['value']!r}"
|
|
204
|
+
)
|
|
205
|
+
)
|
|
206
|
+
cause = [f"cause: {row['blame']}"] if row["blame"] else []
|
|
207
|
+
print("\n".join([_text(row), "", ended, *row["broken"], *cause]))
|
|
208
|
+
return 0 if returned and not row["broken"] else 1
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _check(library: Library, *, as_json: bool) -> int:
|
|
212
|
+
found = vacuities(library)
|
|
213
|
+
if as_json:
|
|
214
|
+
print(
|
|
215
|
+
json.dumps(
|
|
216
|
+
[{"where": f.where, "finding": f.finding, "certainty": f.certainty} for f in found],
|
|
217
|
+
indent=2,
|
|
218
|
+
)
|
|
219
|
+
)
|
|
220
|
+
else:
|
|
221
|
+
lines = [
|
|
222
|
+
f"{f.where}: {f.finding}" + ("" if f.certainty == "proven" else " (undecided)")
|
|
223
|
+
for f in found
|
|
224
|
+
]
|
|
225
|
+
print("\n".join(lines) if lines else "no specification holds vacuously")
|
|
226
|
+
return 1 if found else 0
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _privileges(old: Path, new: Path, *, as_json: bool) -> int:
|
|
230
|
+
"""Compare two privilege policies in Progent's format, tool by tool."""
|
|
231
|
+
found = updates(
|
|
232
|
+
read_privileges(json.loads(old.read_text(encoding="utf-8"))),
|
|
233
|
+
read_privileges(json.loads(new.read_text(encoding="utf-8"))),
|
|
234
|
+
)
|
|
235
|
+
if as_json:
|
|
236
|
+
rows = [{"tool": u.tool, "change": u.change, "witness": list(u.witness)} for u in found]
|
|
237
|
+
print(json.dumps(rows, indent=2))
|
|
238
|
+
else:
|
|
239
|
+
print("\n".join(map(describe, found)))
|
|
240
|
+
return 0 if all(u.change == "narrowing" for u in found) else 1
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def _proxy(server: str, directory: Path | None) -> int:
|
|
244
|
+
"""Serve a proxy over stdio in front of a server, holding calls to a library's rules."""
|
|
245
|
+
from valgebra_planning.proxy import serve # noqa: PLC0415 - the mcp extra
|
|
246
|
+
from valgebra_planning.servers import connect # noqa: PLC0415
|
|
247
|
+
|
|
248
|
+
library = None if directory is None else read_library(directory)
|
|
249
|
+
policies = () if library is None else tuple(library.policies.values())
|
|
250
|
+
flows = () if library is None else tuple(library.flows.values())
|
|
251
|
+
|
|
252
|
+
async def served() -> None:
|
|
253
|
+
async with connect(server) as upstream:
|
|
254
|
+
await serve(upstream, policies=policies, flows=flows)
|
|
255
|
+
|
|
256
|
+
asyncio.run(served())
|
|
257
|
+
return 0
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
261
|
+
"""Run the command the arguments name and return its exit status."""
|
|
262
|
+
parser = argparse.ArgumentParser(prog="valgebra-planning", description=__doc__.splitlines()[0])
|
|
263
|
+
commands = parser.add_subparsers(dest="command", required=True)
|
|
264
|
+
planning = commands.add_parser("plan", help="plan and verify a library's tasks")
|
|
265
|
+
planning.add_argument("library", type=Path)
|
|
266
|
+
planning.add_argument("--task", action="append", default=[], help="a task by name; repeatable")
|
|
267
|
+
planning.add_argument("--json", action="store_true")
|
|
268
|
+
critic = commands.add_parser("critique", help="verify a program written for one task")
|
|
269
|
+
critic.add_argument("library", type=Path)
|
|
270
|
+
critic.add_argument("--task", required=True)
|
|
271
|
+
critic.add_argument("program", type=Path)
|
|
272
|
+
critic.add_argument("--json", action="store_true")
|
|
273
|
+
running = commands.add_parser("run", help="plan a task and run it against a live server")
|
|
274
|
+
running.add_argument("library", type=Path)
|
|
275
|
+
running.add_argument("--task", required=True)
|
|
276
|
+
running.add_argument("--inputs", required=True, type=json.loads, help="a JSON object")
|
|
277
|
+
running.add_argument("--json", action="store_true")
|
|
278
|
+
checking = commands.add_parser("check", help="find specifications that hold vacuously")
|
|
279
|
+
checking.add_argument("library", type=Path)
|
|
280
|
+
checking.add_argument("--json", action="store_true")
|
|
281
|
+
privileged = commands.add_parser("privileges", help="compare two Progent privilege policies")
|
|
282
|
+
privileged.add_argument("old", type=Path)
|
|
283
|
+
privileged.add_argument("new", type=Path)
|
|
284
|
+
privileged.add_argument("--json", action="store_true")
|
|
285
|
+
stubbed = commands.add_parser("stubs", help="print typed Python stubs of a library's tools")
|
|
286
|
+
stubbed.add_argument("library", type=Path)
|
|
287
|
+
proxied = commands.add_parser("proxy", help="serve an MCP proxy holding calls to the rules")
|
|
288
|
+
proxied.add_argument("--library", type=Path, help="a library whose policies and flows hold")
|
|
289
|
+
for command in (planning, critic, running, checking, stubbed, proxied):
|
|
290
|
+
required = command in (running, proxied)
|
|
291
|
+
command.add_argument("--server", required=required, help="a URL or a command")
|
|
292
|
+
args = parser.parse_args(argv)
|
|
293
|
+
if args.command == "privileges":
|
|
294
|
+
return _privileges(args.old, args.new, as_json=args.json)
|
|
295
|
+
if args.command == "proxy":
|
|
296
|
+
return _proxy(args.server, args.library)
|
|
297
|
+
try:
|
|
298
|
+
if args.command == "run":
|
|
299
|
+
return _run(args.library, args.task, args.inputs, args.server, as_json=args.json)
|
|
300
|
+
tools = None if args.server is None else _served(args.server)
|
|
301
|
+
library = read_library(args.library, tools)
|
|
302
|
+
if args.command == "plan":
|
|
303
|
+
return _plan(library, args.task, as_json=args.json)
|
|
304
|
+
if args.command == "check":
|
|
305
|
+
return _check(library, as_json=args.json)
|
|
306
|
+
if args.command == "stubs":
|
|
307
|
+
print(stubs(library.tools))
|
|
308
|
+
return 0
|
|
309
|
+
return _critique(library, args.task, args.program, as_json=args.json)
|
|
310
|
+
except KeyError as missing:
|
|
311
|
+
print(f"{args.library}: no task named {missing}", file=sys.stderr)
|
|
312
|
+
return 2
|