pyboltzmann 0.1.0__tar.gz

pyboltzmann-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+.DS_Store
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+.env
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Distribution / packaging
+*.gz
+*.whl
+
+# Logs
+*.log
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb_checkpoints/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+Thumbs.db
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Hypothesis
+.hypothesis/

pyboltzmann-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gaussia Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyboltzmann-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: pyboltzmann
+Version: 0.1.0
+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: 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=alex)
+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.** So 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.
+
+It embeds no language model. Interpretation enters through `CandidateProposer` and
+nowhere else.
+
+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.
+
+## 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. It is the same split as
+`pygaussia` providing `gaussia`.
+
+The core needs **`pydantic` and `rfc8785`**. Everything else is optional: `[oci]`
+adds a network registry transport, and moving a brain between OCI layouts on disk
+needs nothing at all.
+
+Python >= 3.11.
+
+## 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
+
+alex = Actor(id="alex", kind=ActorKind.HUMAN)
+brain = Brain.open("./my-brain", actor=alex)
+
+# 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=alex, 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()
+```
+
+Removing knowledge cascades through provenance, publishing is a copy rather than a
+conversion, and an implementation in any language can prove it conforms against the
+golden vectors that ship in the wheel. Each of those has a guide.
+
+## 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 6962 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).

pyboltzmann-0.1.0/README.md

@@ -0,0 +1,153 @@
+# 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=alex)
+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.** So 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.
+
+It embeds no language model. Interpretation enters through `CandidateProposer` and
+nowhere else.
+
+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.
+
+## 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. It is the same split as
+`pygaussia` providing `gaussia`.
+
+The core needs **`pydantic` and `rfc8785`**. Everything else is optional: `[oci]`
+adds a network registry transport, and moving a brain between OCI layouts on disk
+needs nothing at all.
+
+Python >= 3.11.
+
+## 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
+
+alex = Actor(id="alex", kind=ActorKind.HUMAN)
+brain = Brain.open("./my-brain", actor=alex)
+
+# 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=alex, 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()
+```
+
+Removing knowledge cascades through provenance, publishing is a copy rather than a
+conversion, and an implementation in any language can prove it conforms against the
+golden vectors that ship in the wheel. Each of those has a guide.
+
+## 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 6962 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).