Skip to content

valgebra-planning

Plans of tool calls for agents, proven well-typed for every output the tool contracts admit.

A plan is a program of calls and type tests on values, in the sense of strong planning under nondeterministic outcomes: it is accepted only where each value it passes to a tool is proven inside that tool's argument, whatever values inside their output schemas the tools return. A program proposed elsewhere, by hand or by a language model, is verified the same way, link by link. valgebra-jsonschema reads each tool's MCP inputSchema and outputSchema into valgebra's sets, and valgebra decides every inclusion a program rests on.

from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique


def tool(name, takes, returns):
    """Return the contract of a tool listed with these properties, every one required."""
    return read_contract(
        {
            "name": name,
            "inputSchema": {"type": "object", "properties": takes, "required": [*takes]},
            "outputSchema": {"type": "object", "properties": returns, "required": [*returns]},
        }
    )


ORDER = {"type": "string", "pattern": "^ord_[0-9]+$"}
REFUND = {"type": "string", "pattern": "^rfd_[0-9]+$"}
tools = {
    "find_order": tool("find_order", {"order_id": ORDER}, {"status": {"enum": ["open", "paid"]}}),
    "refund": tool(
        "refund", {"order_id": ORDER, "status": {"const": "paid"}}, {"refund_id": REFUND}
    ),
}
task = read_task("refund an order", {"order_id": ORDER}, REFUND)

# A program a model proposed: it refunds whatever order the lookup returns.
checked = critique(
    "c1 = find_order(order_id=order_id)\n"
    "c2 = refund(order_id=order_id, status=c1.status)\n"
    "return c2.refund_id\n",
    tools,
    task,
)
print(checked.accepted)
print(checked.notes[0])
False
refuted: c1.status <= refund.status; 'open' lies outside; test `if c1.status in refund.status:` and make the call in that branch
pip install valgebra-planning            # Python 3.11 or later
pip install "valgebra-planning[mcp]"     # with a live MCP server's tools, and the proxy

Every inclusion a program rests on is a link, and each reads proven, refuted, with a value that breaks it where one is found, or undecided where valgebra cannot tell, which never counts as proven. A program is accepted when every link is proven and no path stops. How it works builds this from a tool's contract up, with a diagram for each step.

Start with the command line, a model's program checked or the recipes; the method is what every answer means.

The site serves llms.txt, a manifest of its pages, and llms-full.txt, their full text, for a reader that is not a browser. The developer pages under docs/dev/ are not published: how a version reaches PyPI, and the rules for every text.