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