pyboltzmann
An SDK for the Boltzmann Protocol: portable, verifiable, model-agnostic knowledge.
The brain conserves, validates, and retrieves knowledge. An external LLM processes, contextualizes, and uses it.
Reference: Boltzmann Brain: A Versioned, Distributable, and Model-Agnostic Knowledge Architecture (Gaussia, 2026).
What this is
A client for a Boltzmann brain. You open a directory, call methods, and they
work against an OCI artifact. Brain implements the complete protocol, including
hierarchical catalog navigation.
brain = Brain.open("./my-brain", actor=curator)
brain.ingest(pdf, request, my_llm) # register → delegate → validate → commit
brain.search(Query(text="Fourier")) # filter, resolve, verify
brain.drop(DropRequest(...)) # rebuild the Merkle DAG, cascade, record
await brain.push(client, "ghcr.io/org/brain", "v1")
The line it draws: the SDK does whatever the protocol defines mechanically; the
implementer supplies whatever the paper assigns elsewhere. Identity, the wire
formats, the four operation paths and a conformance suite are here; the model, the
ranking, the index engines and any CLI or MCP server are yours. No language model is
embedded — interpretation enters through CandidateProposer and nowhere else.
Installation
pip install pyboltzmann # the distribution
pip install 'pyboltzmann[oci]' # plus the network registry transport
import boltzmann # the import package
The two names differ because boltzmann on PyPI belongs to an unrelated package —
the same split as pygaussia providing gaussia.
Python >= 3.11. The core needs only pydantic and rfc8785; [oci] adds the
network registry transport.
Usage
The whole lifecycle of Section 11, against a real OCI layout:
from boltzmann import Actor, Brain, MemoryType, Producer, Query
from boltzmann.blocks import ActorKind, ProducerKind
from boltzmann.ingest import Candidate, CandidateSet, RegistrationRequest
curator = Actor(id="curator@example.org", kind=ActorKind.HUMAN)
brain = Brain.open("./my-brain", actor=curator)
# You supply the model. The SDK embeds none: what knowledge a source yields is its
# judgment, and what gets stored is the protocol's.
def my_llm(task, source):
# task.output_schema names the schema; brain.candidates_schema(task) *is* it, with the
# payload resolved per memory type. Hand it to the model as structured output.
return CandidateSet(
producer=Producer(kind=ProducerKind.MODEL, id="claude-opus-5", version="2026-07"),
candidates=[
Candidate(
memory_type=MemoryType.SEMANTIC,
evidence=[task.source],
locator="p.147",
payload={
"kind": "formula",
"label": "Fourier series",
"statement": "decomposes a periodic function into sines",
"subject": "signals",
},
)
],
)
request = RegistrationRequest(media_type="application/pdf", actor=curator, license="CC-BY-4.0")
pdf = b"%PDF-1.7 lecture 07: Fourier analysis"
# Register, delegate, validate, commit. Registering the same source twice is a no-op.
commit = brain.ingest(pdf, request, my_llm)
# Data with its provenance, never prose, every match verified against the snapshot.
bundle = brain.search(Query(text="periodic function"))
assert bundle.all_verified
assert bundle.matches[0].sources[0].locator == "p.147"
# Membership is provable in O(log n), without holding the rest of the module.
block_id = commit.committed[0]
assert brain.prove(block_id, MemoryType.SEMANTIC).verify(brain.root_of(MemoryType.SEMANTIC))
assert brain.verify()
Documentation
The docs/ directory
is the source of truth, and it is published as the Boltzmann SDK section of the
Gaussia docs.
| Quickstart | Ingest, query, prove, publish, remove — in one file |
| Architecture | Blocks, compositions, modules, snapshots |
| Memory types | The five typed blocks and the rules each obeys |
| Identity | JCS, the three levels of hashes, the values a payload refuses |
| Merkle DAGs | RFC 9162 over sorted leaves, and inclusion proofs |
| Catalog | Hierarchical classes and virtual paths over canonical sources |
| Interfaces | The protocol surface, and the things you plug in |
| Ingestion | Preserve the source, delegate the interpretation, validate |
| Query | Evidence Bundles, filters, and supplying a planner |
| Retention | Drop, supersede, demote, prune, redact |
| Distribution | Pack, push, pull, and selective installs |
| Conformance | Golden vectors, and the suites you inherit |
Development
uv sync
uv run pre-commit install && uv run pre-commit install --hook-type commit-msg
uv run ruff check . && uv run ruff format .
uv run mypy src
uv run pytest
Commits follow Conventional Commits — use
uv run cz commit for the interactive prompt. Releases are cut by
python-semantic-release from the commit history.
License
MIT — see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for pyboltzmann 0.9.1
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 | |
|---|---|---|---|---|
| pyboltzmann-0.9.1.tar.gz | 331.3 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyboltzmann-0.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 730.1 kB
Release files / pyboltzmann-0.9.1.tar.gz
| Download URL | pyboltzmann-0.9.1.tar.gz |
|---|---|
| Size | 331.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6a0d93dcc32bf43f528e17ef54168b14449c83645cf94a681a28753271bbe67b
|
|
BLAKE2b-256 checksum How to use checksums |
6c398d0445b4de7c52e387b731d590be6e5af0a36f06fb6e4990b4c1a24939e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 7, 2026.
Transparency logRelease files / pyboltzmann-0.9.1-py3-none-any.whl
| Download URL | pyboltzmann-0.9.1-py3-none-any.whl |
|---|---|
| Size | 398.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
277964511e63c547e93f09022f274a3e7a0b1090da67e82f5687b8b1fee15342
|
|
BLAKE2b-256 checksum How to use checksums |
62f89ae23ba1b84ce01285a55681817c005398cdae7cdb8b046bc2bbd0178ae0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 7, 2026.
Transparency logSecurity for pyboltzmann 0.9.1
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
All 2 files in this release have been uploaded with provenance metadata.
Attestation for pyboltzmann-0.9.1.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 Sep 7, 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.
