Using valgebra-planning¶
How to plan the tasks of a tool library, or check a program written for one, from the command line. What each answer means is the method's.
A library¶
A library is a directory (valgebra_planning/library.py reads it):
| file | holds |
|---|---|
tools.json |
a server's tools/list result: {"tools": [...]}, each tool its name, inputSchema, and the outputSchema and annotations it declares; "trusted": true where the server's annotations are trusted |
tasks.json |
{"tasks": [...]}, each task a name, the JSON Schema of each value the agent starts with in inputs, the JSON Schema of the goal, and the rules it is held to: errors (any tool may fail), policies and flows by name, types, the file of observed calls its semantic types are mined from |
policies.json |
{"policies": [...]}, each an automaton over calls (valgebra_planning/policy.py): initial, the bad states no path may reach, the pending states no path may end in, and the transitions |
flows.json |
{"flows": [...]}, each a flow rule (valgebra_planning/flows.py) |
a file types names |
{"calls": [...]}, each an observed call: tool, arguments, result; a tool listed without an outputSchema gets one shaped from its results there, an assumption every binding resting on it names |
A tool without an outputSchema can be called, and nothing it returns can fill another call's
argument: its result is a set no argument is proven to hold. examples/parcels is a library
holding every file.
Plan¶
prints the program for each task (every task when no --task is given; --task repeats), whether
it is strong or weak, how many of its links valgebra proves, each link not proven, each value a
weak program's stops leave uncovered, and each binding resting on a mined type. With --json it
prints one JSON document, a list holding a row per task. The exit status is 1 when a task gets no
program.
Critique a program written elsewhere¶
reads program.py, the Python an agent writes against typed tool APIs (valgebra_planning/critic.py
states what it reads), verifies every link under the rules the task names, and prints each link not
proven with the value that refutes it and what to change: the test that makes a call safe, the call
a policy needs first, the source a flow rule trusts, the error block a call needs. A binding crossing
two types the task's observed calls tell apart is a note, and decides nothing. The exit status is 0 when the program is
accepted, 1 when it is not, and 2 when the reader refuses its text.
Stubs for a model¶
prints the library's tools as Python stubs, after a preamble stating the language a program
uses: one function a tool, every argument by name, its docstring holding the tool's input and
output schemas. Hand them to a model to write a program against, then critique it; in Python,
valgebra_planning.codemode.repair runs that loop with any callable as the model.
Check a library¶
lists every specification in the library that holds vacuously, as the method defines them: a goal no value or every value meets, a policy transition that never fires, a policy that can never be violated, a flow rule that lets nothing or everything through, a rule no task is held to. A finding valgebra leaves undecided is marked so. The exit status is 1 when it finds one.
Compare two privilege policies¶
reads two privilege policies in Progent's format, {"tool": [[priority, effect, condition,
fallback], ...]}, and prints for each tool the new one names whether it narrows the old one,
expands it, with a call it newly allows, or is left undecided. The exit status is 0 only when
every tool narrows. In Python, valgebra_planning.privilege.as_policy turns a policy into one the
planner, the verifier and the runner hold a program to.
A live server¶
With the mcp extra (uv sync --extra mcp, or pip install "valgebra-planning[mcp]"), --server
reads the tools from a live MCP server instead of tools.json: a URL connects over Streamable
HTTP, anything else is a command starting a server over stdio. The command is split as a POSIX
shell splits it, on Windows as well: a backslash escapes the character after it, so a path
holding one, or a space, goes in single quotes, as shlex.quote writes it.
uv run valgebra-planning plan examples/parcels --task "return a parcel" \
--server "uv run python tests/parcel_server.py"
uv run valgebra-planning run examples/parcels --task "settle a parcel" \
--inputs '{"tracking": "AB123456789IT"}' --server "uv run python tests/parcel_server.py"
run plans the task over the server's tools and runs the program against the server
(valgebra_planning/servers.py): each call is a tools/call, its structuredContent the value
it returns, an isError result, a protocol error or a request for input a tool error, and the run
fails closed on any argument record, policy step or result outside its contract. It prints how the run ended, and the cause of a break (the
server, an assumption, or the program), and exits 1 unless it returned a value with no break.
tests/parcel_server.py serves the example's tools over stdio.
A proxy in front of a server¶
uv run valgebra-planning proxy --server "uv run python tests/parcel_server.py" --library examples/parcels
serves an MCP server over stdio, in front of --server, that lists its tools as they are and
answers a call only after holding it to the tool's contract, to every policy and flow rule the
library defines, and, the call made, its result to the output schema
(valgebra_planning/proxy.py). A broken check answers the call with a tool error naming it, and
the call never reaches the server, or its result the agent. The error names each failure's path
and code, as run_id: string_pattern_mismatch, and never the value: a key the tool's schemas do
not declare is written *, so no part of a refused result reaches the agent through the error.
A refused call leaves every policy
where it was. A flow rule reads provenance from values: an argument equal to a value a source
tool returned is taken as that tool's, an assumption. Under only an argument equal to no value
its sources returned is refused, and so is a value from a task input, since a proxy sees no
task. A call the server answers by asking for input is answered with a tool error, and the
request is not forwarded. An agent connects to the proxy as to any stdio server, and no agent
changes.
Limits¶
- With
--server, the tasks, policies, flow rules and observed calls are still the library's files.