Metadata-Version: 2.5
Name: pyboltzmann
Version: 0.4.0b1
Summary: An SDK for the Boltzmann Protocol: portable, verifiable, model-agnostic knowledge
Project-URL: Homepage, https://github.com/gaussia-labs/pyboltzmann
Project-URL: Repository, https://github.com/gaussia-labs/pyboltzmann.git
Project-URL: Bug Tracker, https://github.com/gaussia-labs/pyboltzmann/issues
Project-URL: Changelog, https://github.com/gaussia-labs/pyboltzmann/releases
Author: Gaussia Labs
Maintainer-email: Alex Fiorenza <alexfiorenza2012@gmail.com>
License: MIT
License-File: LICENSE
Keywords: content-addressing,knowledge-representation,llm,memory-systems,merkle-dag,oci-artifacts,protocol,provenance,retrieval-augmented-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: rfc8785>=0.1.4
Provides-Extra: conformance
Requires-Dist: pytest>=8.0.0; extra == 'conformance'
Provides-Extra: oci
Requires-Dist: oras>=0.2.42; extra == 'oci'
Description-Content-Type: text/markdown

# 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*](https://github.com/gaussia-labs/papers) (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.

```python
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

```bash
pip install pyboltzmann          # the distribution
pip install 'pyboltzmann[oci]'   # plus the network registry transport
```

```python
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:

```python
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/`](https://github.com/gaussia-labs/pyboltzmann/tree/master/docs) directory
is the source of truth, and it is published as the Boltzmann SDK section of the
[Gaussia docs](https://github.com/gaussia-labs/docs).

<!-- Absolute URLs: this file is also the PyPI long description, where a relative link
     resolves against pypi.org and 404s. -->

| | |
|---|---|
| [Quickstart](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/quickstart.mdx) | Ingest, query, prove, publish, remove — in one file |
| [Architecture](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/concepts/architecture.mdx) | Blocks, compositions, modules, snapshots |
| [Memory types](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/concepts/memory-types.mdx) | The five typed blocks and the rules each obeys |
| [Identity](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/concepts/identity.mdx) | JCS, the three levels of hashes, the values a payload refuses |
| [Merkle DAGs](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/concepts/merkle.mdx) | RFC 9162 over sorted leaves, and inclusion proofs |
| [Interfaces](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/concepts/interfaces.mdx) | The protocol surface, and the four things you plug in |
| [Ingestion](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/guides/ingestion.mdx) | Preserve the source, delegate the interpretation, validate |
| [Query](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/guides/query.mdx) | Evidence Bundles, filters, and supplying a planner |
| [Retention](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/guides/retention.mdx) | Drop, supersede, demote, prune, redact |
| [Distribution](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/guides/distribution.mdx) | Pack, push, pull, and selective installs |
| [Conformance](https://github.com/gaussia-labs/pyboltzmann/blob/master/docs/guides/conformance.mdx) | Golden vectors, and the suites you inherit |

## Development

```bash
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](https://www.conventionalcommits.org/) — use
`uv run cz commit` for the interactive prompt. Releases are cut by
`python-semantic-release` from the commit history.

## License

MIT — see [LICENSE](https://github.com/gaussia-labs/pyboltzmann/blob/master/LICENSE).
