valgebra-planning
Plans of tool calls for agents, proven well-typed for every output the tool contracts admit. A plan here 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.
📖 Documentation: https://ppigazzini.github.io/valgebra-planning/
🤖 For AI assistants and coding agents: the documentation is also published as
llms.txt (a curated manifest)
and llms-full.txt (the
full text, including the API reference) per the llmstxt.org
convention.
It is part of the valgebra ecosystem.
valgebra-jsonschema reads each tool's
contract, the MCP inputSchema and outputSchema, into valgebra's sets, and valgebra decides
every inclusion a program rests on. Nothing here reads JSON Schema itself.
Status: pre-alpha.
pip install valgebra-planning # Python 3.11 or later
pip install "valgebra-planning[mcp]" # with a live MCP server's tools, and the proxy
What it does
| step | module |
|---|---|
| read each tool's contract as argument and result slots | valgebra_planning/contracts.py |
| cut the JSON values into the cells of every slot, input and goal | valgebra_planning/cells.py |
| search a strong program, or a weak one whose stops name what they leave | valgebra_planning/planner.py |
| verify every link of a program with valgebra alone | valgebra_planning/verify.py |
| read a program written in Python, verify it and critique it | valgebra_planning/critic.py |
| hold a program to tool errors, policies, flow rules and mined types | planner.py, policy.py, flows.py, mining.py |
| run a program, failing closed on every contract and policy | valgebra_planning/run.py |
| plan a library's tasks or critique a program from the command line | valgebra_planning/cli.py |
read a live MCP server's tools and run a program against it (mcp extra) |
valgebra_planning/servers.py |
| find the specifications of a library that hold vacuously | valgebra_planning/vacuity.py |
| read Progent's privilege policies as sets: narrowing, expansion, a program held to one | valgebra_planning/privilege.py |
| serve an MCP proxy holding every call to the contracts, policies and flow rules | valgebra_planning/proxy.py |
| give a model typed stubs, and repair its program with the critique | valgebra_planning/codemode.py |
The guide has the command line, the Python names each module promises, how a model's program is proven before it runs, tasks done end to end in Python, a policy, a flow rule and a privilege update among them, the method and its limits, and the studies: on a parcel-returns library of ten tools, eight tasks get programs whose every link valgebra proves, from 3 of 3 to 24 of 24.
Prior work
The method starts from valplan (doi:10.5281/zenodo.23686600), predicate abstraction over a Boolean algebra of JSON Schema sets with strong planning over the cells. This package is written anew on the valgebra ecosystem and shares no code with it.
License
MIT OR Apache-2.0, at your option. See
LICENSE-MIT and
LICENSE-APACHE.
Metadata
Release files for valgebra-planning 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| valgebra_planning-0.0.3.tar.gz | 147.4 kB | With provenance | Details for valgebra_planning-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| valgebra_planning-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for valgebra_planning-0.0.3-py3-none-any.whl |
Total release size: 216.7 kB
Release files / valgebra_planning-0.0.3.tar.gz
| Download URL | valgebra_planning-0.0.3.tar.gz |
|---|---|
| Size | 147.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
25fa50738ba1b3b79f6cb6da048db44d86123685c1b17ddb1eec322dc8d1f807
|
|
BLAKE2b-256 checksum How to use checksums |
8d5a54d316f836bbabe640cb33079dafdbd9ddbf0f354ff2d21e1d7465141973
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / valgebra_planning-0.0.3-py3-none-any.whl
| Download URL | valgebra_planning-0.0.3-py3-none-any.whl |
|---|---|
| Size | 69.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b42be12380c11a16847d05d1612e7db39787d892e4a795e27718c1f8443753fc
|
|
BLAKE2b-256 checksum How to use checksums |
866ac68cc88dc2a20088db34ea9ae852e073b29765f0f3196e3ea07ad3a052e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for valgebra-planning 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for valgebra_planning-0.0.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.