Skip to main content

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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valgebra-planning 0.0.2
File Size Uploaded Provenance Actions
valgebra_planning-0.0.2.tar.gz 146.6 kB With provenance Details for valgebra_planning-0.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valgebra-planning 0.0.2
File Interpreter ABI Platform Actions
valgebra_planning-0.0.2-py3-none-any.whl Python 3 none any Details for valgebra_planning-0.0.2-py3-none-any.whl

Total release size: 215.7 kB

Release files / valgebra_planning-0.0.2.tar.gz

Download URL valgebra_planning-0.0.2.tar.gz
Size 146.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4f125f8da9ba9a2149f7529b33ed63a0b604ee3502af128709b3cb0916699d2a
BLAKE2b-256 checksum
How to use checksums
bc61749bc4ef868fb62265b2f63fd575aa416c075377526308c5ad698ac5f8df
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 log

Release files / valgebra_planning-0.0.2-py3-none-any.whl

Download URL valgebra_planning-0.0.2-py3-none-any.whl
Size 69.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e2d2a9ee98c71c7d2520e7ef3e17a6685c92c88aacfe8296103f4f87edaaccc
BLAKE2b-256 checksum
How to use checksums
0885176614e851e8a6990829d11a5a37e7cb7a6313a95b5966eaacb5b173874c
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 log

Security for valgebra-planning 0.0.2

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.

Select from 2 files

Attestation for valgebra_planning-0.0.2.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page