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 whole protocol — 23 of 23 operations across the four contracts.

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", 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.

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.