Boltzmann Python SDK

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

curator = Actor(id="curator@example.org", kind=ActorKind.HUMAN)

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 brain conserves, validates, and retrieves knowledge. An external LLM processes, contextualizes, and uses it. The SDK embeds no model — interpretation enters through one interface and nowhere else.

The line this SDK draws

The SDK does whatever the protocol defines mechanically; the implementer supplies whatever the paper assigns elsewhere.

The SDK does	Because
Identity: canonical serialization, `block_id`, Merkle roots, inclusion proofs	Two clients that disagree on these do not share a brain at all
The wire formats, and their JSON Schema	Two clients that disagree cannot hand work to the same model
Ingestion, query, retention, distribution	You should not have to write hashing, cascades and mark-and-sweep yourself
Authenticity: SSHSIG signatures, the trust root, positional revocation	Whose brain this is must be checkable mechanically, offline, by anyone
A conformance suite and golden vectors	So an implementation can prove it conforms, in any language

You supply	Because
`CandidateProposer`	What knowledge a source yields is the external model’s judgment
`QueryPlanner`	Ranking and index selection are explicitly implementation-defined
`Index` engines	Which engine backs an index is the implementation’s choice
An MCP server or CLI	Exposure layers, not protocol — build them on top

There are no NotImplementedError stubs, and a test enforces it. An unimplemented function is worse than an interface: it looks callable and is not. Nothing is declared and unreachable either — every type, enum member and constant is produced by something, and a test enforces that too.

Where to go next

Installation

The distribution is pyboltzmann; the import package is boltzmann.

Quickstart

The whole lifecycle against a real OCI layout, in one file.

Architecture

Blocks, modules, compositions, snapshots.

Interfaces

The protocol surface, and the four things you plug in.

Reference

Boltzmann Brain: A Versioned, Distributable, and Model-Agnostic Knowledge Architecture (Gaussia, 2026).

Getting started

Core concepts

Guides

Boltzmann Python SDK

The line this SDK draws

Where to go next

Installation

Quickstart

Architecture

Interfaces

Reference

​The line this SDK draws

​Where to go next

Installation

Quickstart

Architecture

Interfaces

​Reference

The line this SDK draws

Where to go next

Reference