Skip to content

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

uv run valgebra-planning plan examples/parcels --task "return a parcel"

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

uv run valgebra-planning critique examples/parcels --task "return a parcel" program.py

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

uv run valgebra-planning stubs examples/parcels

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

uv run valgebra-planning check examples/parcels

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

uv run valgebra-planning privileges old.json new.json

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.