pyboltzmann 0.1.0__py3-none-any.whl

boltzmann/__init__.py

@@ -0,0 +1,160 @@
+"""Boltzmann: an SDK for the Boltzmann Protocol.
+
+The brain conserves, validates, and retrieves knowledge. An external LLM processes, contextualizes,
+and uses it.
+
+Knowledge is stored as typed, content-addressed blocks organized into five memory modules --
+canonical, episodic, semantic, procedural, and provenance. Each module bundles its blocks, a Merkle
+DAG that pins the exact composition of a version, and the indices needed to query it.
+
+**This package is a protocol SDK, not a brain.** It provides three things:
+
+1. **Identity and verification**, implemented, because every conforming client must compute the same
+   values: the canonical serialization, ``block_id``, the Merkle root, inclusion proofs.
+2. **The types the protocol exchanges**, implemented, because they are wire formats: block schemas,
+   ``ProcessingTask``, ``boltzmann.candidates/v1``, ``EvidenceBundle``, ``Query``, the OCI manifest.
+3. **The interfaces an implementation satisfies**, declared: ``BrainReader``, ``BrainWriter``,
+   ``BrainRetention``, ``BrainDistribution``, plus ``BlockStore``, ``Index``, ``QueryPlanner``,
+   ``Validator``, ``CandidateProposer``, ``RegistryClient``, ``MerkleLayout``,
+   ``NormalizationPipeline``.
+
+Ingestion, query, retention, and distribution are **not implemented here**. Where the paper leaves
+something to the implementation -- ranking, fusion, index engines, cascade depth, retention
+thresholds -- so does this SDK.
+
+It embeds no language model. Interpretation enters through ``CandidateProposer`` and nowhere else.
+
+Reference: *Boltzmann Brain: A Versioned, Distributable, and Model-Agnostic Knowledge Architecture*
+(Gaussia, 2026).
+"""
+
+from boltzmann.blocks import (
+    Actor,
+    ActorKind,
+    Block,
+    CanonicalBlock,
+    EpisodicBlock,
+    MemoryType,
+    NormalizedView,
+    ProceduralBlock,
+    Producer,
+    ProvenanceBlock,
+    Relation,
+    RemovalMechanism,
+    SemanticBlock,
+    SemanticKind,
+    Step,
+)
+from boltzmann.brain import Brain, BrainState
+from boltzmann.exceptions import BoltzmannError
+from boltzmann.identity import BlockId, MerkleRoot, OciDigest
+from boltzmann.identity.time import utc_timestamp
+from boltzmann.indices import Index, IndexKind
+from boltzmann.ingest import (
+    Candidate,
+    CandidateProposer,
+    CandidateSet,
+    CommitResult,
+    ProcessingTask,
+    RegistrationRequest,
+    RegistrationResult,
+    ValidationReport,
+    ValidationStatus,
+    Validator,
+)
+from boltzmann.merkle import InclusionProof, MerkleLayout, MerkleTree
+from boltzmann.module import Composition, Ledger, Module, ModuleRef, Snapshot
+from boltzmann.protocol import (
+    PROTOCOL_VERSION,
+    BoltzmannProtocol,
+    BrainDistribution,
+    BrainReader,
+    BrainRetention,
+    BrainWriter,
+)
+from boltzmann.query import EvidenceBundle, Match, Query, QueryFilters, QueryHints, QueryPlanner, RetrievalMode
+from boltzmann.retention import (
+    CascadePlan,
+    DropRequest,
+    DropResult,
+    ProducerDropRequest,
+    PruneReport,
+    RedactionResult,
+    ResolvabilityReport,
+    RetentionPolicy,
+    SupersessionResult,
+)
+from boltzmann.store import BlockStore, MemoryBlockStore, OciLayoutStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "Actor",
+    "ActorKind",
+    "Block",
+    "BlockId",
+    "BlockStore",
+    "BoltzmannError",
+    "BoltzmannProtocol",
+    "Brain",
+    "BrainDistribution",
+    "BrainReader",
+    "BrainRetention",
+    "BrainState",
+    "BrainWriter",
+    "Candidate",
+    "CascadePlan",
+    "CandidateProposer",
+    "CandidateSet",
+    "CanonicalBlock",
+    "CommitResult",
+    "Composition",
+    "DropRequest",
+    "DropResult",
+    "ProducerDropRequest",
+    "PruneReport",
+    "RedactionResult",
+    "ResolvabilityReport",
+    "SupersessionResult",
+    "EpisodicBlock",
+    "EvidenceBundle",
+    "InclusionProof",
+    "Ledger",
+    "Index",
+    "IndexKind",
+    "Match",
+    "MemoryBlockStore",
+    "MemoryType",
+    "MerkleLayout",
+    "MerkleRoot",
+    "MerkleTree",
+    "Module",
+    "ModuleRef",
+    "NormalizedView",
+    "OciDigest",
+    "OciLayoutStore",
+    "ProceduralBlock",
+    "ProcessingTask",
+    "Producer",
+    "ProvenanceBlock",
+    "Query",
+    "QueryFilters",
+    "QueryHints",
+    "QueryPlanner",
+    "RegistrationRequest",
+    "RegistrationResult",
+    "Relation",
+    "RemovalMechanism",
+    "RetentionPolicy",
+    "RetrievalMode",
+    "SemanticBlock",
+    "SemanticKind",
+    "Snapshot",
+    "Step",
+    "ValidationReport",
+    "ValidationStatus",
+    "Validator",
+    "__version__",
+    "utc_timestamp",
+]

boltzmann/blocks/__init__.py

@@ -0,0 +1,50 @@
+"""Typed knowledge blocks: the durable unit of the protocol."""
+
+from boltzmann.blocks.base import ENVELOPE_KEYS, Block
+from boltzmann.blocks.canonical import CanonicalBlock, NormalizedView
+from boltzmann.blocks.episodic import EpisodicBlock
+from boltzmann.blocks.memory_type import MemoryType
+from boltzmann.blocks.procedural import ProceduralBlock, Step
+from boltzmann.blocks.provenance import (
+    Actor,
+    ActorKind,
+    DemotionRecord,
+    DerivationRecord,
+    NormalizationRecord,
+    Producer,
+    ProducerKind,
+    ProvenanceBlock,
+    ProvenanceEntry,
+    RegistrationRecord,
+    RemovalMechanism,
+    RemovalRecord,
+    SupersessionRecord,
+)
+from boltzmann.blocks.semantic import Relation, SemanticBlock, SemanticKind
+
+__all__ = [
+    "ENVELOPE_KEYS",
+    "Actor",
+    "ActorKind",
+    "Block",
+    "CanonicalBlock",
+    "DemotionRecord",
+    "DerivationRecord",
+    "EpisodicBlock",
+    "MemoryType",
+    "NormalizationRecord",
+    "NormalizedView",
+    "ProceduralBlock",
+    "Producer",
+    "ProducerKind",
+    "ProvenanceBlock",
+    "ProvenanceEntry",
+    "RegistrationRecord",
+    "Relation",
+    "RemovalMechanism",
+    "RemovalRecord",
+    "SemanticBlock",
+    "SemanticKind",
+    "Step",
+    "SupersessionRecord",
+]

boltzmann/blocks/base.py

@@ -0,0 +1,215 @@
+"""The block envelope and the computation of ``block_id`` (paper Section 6.1).
+
+A block is a logical unit of knowledge with a deterministic serialization:
+
+.. math::
+
+    block\\_id = SHA\\text{-}256(canonical\\_serialization(block))
+
+What gets hashed is the **envelope**, not the payload alone, so that the memory
+type and the schema version are bound into the identity:
+
+.. code-block:: json
+
+    {
+      "boltzmann": 1,
+      "memory_type": "semantic",
+      "payload": {},
+      "schema_version": 1,
+      "serialization": "jcs/1"
+    }
+
+Everything derived or mutable stays outside: physical location, index state, and
+the time a block happened to be registered are not part of what the block *is*.
+
+Two conventions keep identity unambiguous:
+
+* An absent optional field is dropped from the payload rather than serialized as
+  ``null``, so ``{"a": 1}`` and ``{"a": 1, "b": null}`` are the same block.
+  Optional collections therefore default to ``None``, never to ``[]``.
+* Blocks are frozen. Correcting a block means creating a new one; the previous
+  one may be kept for history, audit, or rollback.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC
+from typing import Any, ClassVar, Self
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from boltzmann.blocks.memory_type import MemoryType
+from boltzmann.constants import PROTOCOL_VERSION
+from boltzmann.exceptions import BlockIntegrityError, BlockSchemaError
+from boltzmann.identity.digest import BlockId
+from boltzmann.identity.serialization import SERIALIZATION_ID, canonicalize, reject_non_deterministic
+
+ENVELOPE_KEYS = frozenset({"boltzmann", "memory_type", "payload", "schema_version", "serialization"})
+"""The exact set of keys a block envelope carries."""
+
+_REGISTRY: dict[tuple[MemoryType, int], type[Block]] = {}
+
+
+class Block(BaseModel, ABC):
+    """
+    Base class for the five typed knowledge blocks.
+
+    A subclass declares its memory type and schema version as class variables and
+    its fields as the payload. Identity, serialization, and decoding come for free.
+
+    Attributes:
+        MEMORY_TYPE (MemoryType): Which memory module this block belongs to.
+        SCHEMA_VERSION (int): Version of this block's payload schema.
+        SERIALIZATION (str): Canonical serialization used to compute ``block_id``.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    MEMORY_TYPE: ClassVar[MemoryType]
+    SCHEMA_VERSION: ClassVar[int] = 1
+    SERIALIZATION: ClassVar[str] = SERIALIZATION_ID
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Register concrete subclasses so stored bytes can be decoded back."""
+        super().__init_subclass__(**kwargs)
+        memory_type = getattr(cls, "MEMORY_TYPE", None)
+        if memory_type is None or ABC in cls.__bases__:
+            return
+        key = (memory_type, cls.SCHEMA_VERSION)
+        registered = _REGISTRY.get(key)
+        if registered is not None and registered is not cls:
+            raise BlockSchemaError(
+                f"{cls.__name__} claims ({memory_type}, schema_version={cls.SCHEMA_VERSION}), "
+                f"already held by {registered.__name__}"
+            )
+        _REGISTRY[key] = cls
+
+    @model_validator(mode="after")
+    def _reject_non_deterministic_payload(self) -> Self:
+        """Fail at construction, not at hashing, when a value has no canonical form."""
+        reject_non_deterministic(self.payload())
+        return self
+
+    # --- Identity -------------------------------------------------------------
+
+    def payload(self) -> dict[str, Any]:
+        """
+        The block's payload as a JSON-shaped mapping.
+
+        Returns:
+            dict[str, Any]: The payload, with absent optional fields dropped.
+        """
+        return self.model_dump(mode="json", exclude_none=True)
+
+    def envelope(self) -> dict[str, Any]:
+        """
+        The full envelope that ``block_id`` is computed over.
+
+        Returns:
+            dict[str, Any]: The envelope mapping.
+        """
+        return {
+            "boltzmann": PROTOCOL_VERSION,
+            "memory_type": self.MEMORY_TYPE.value,
+            "payload": self.payload(),
+            "schema_version": self.SCHEMA_VERSION,
+            "serialization": self.SERIALIZATION,
+        }
+
+    def canonical_bytes(self) -> bytes:
+        """
+        The exact bytes that are hashed and stored.
+
+        Returns:
+            bytes: The canonically serialized envelope.
+        """
+        return canonicalize(self.envelope(), self.SERIALIZATION)
+
+    @property
+    def block_id(self) -> BlockId:
+        """The block's content-addressed identity."""
+        return BlockId.of(self.canonical_bytes())
+
+    # --- Decoding -------------------------------------------------------------
+
+    @staticmethod
+    def decode(data: bytes) -> Block:
+        """
+        Decode stored bytes back into a typed block.
+
+        Beyond parsing, this checks that ``data`` is already in canonical form: if
+        re-serializing the decoded block does not reproduce ``data`` byte for byte,
+        the stored bytes would hash to a different ``block_id`` than they claim, so
+        they are rejected rather than silently normalized.
+
+        Args:
+            data (bytes): Canonically serialized envelope bytes.
+
+        Returns:
+            Block: The decoded block.
+
+        Raises:
+            BlockSchemaError: If the envelope is malformed or its type is unknown.
+            BlockIntegrityError: If ``data`` is not in canonical form.
+        """
+        try:
+            envelope = json.loads(data)
+        except json.JSONDecodeError as error:
+            raise BlockSchemaError(f"block envelope is not valid JSON: {error}") from error
+
+        if not isinstance(envelope, dict):
+            raise BlockSchemaError(f"block envelope must be an object, got {type(envelope).__name__}")
+
+        missing = ENVELOPE_KEYS - envelope.keys()
+        unexpected = envelope.keys() - ENVELOPE_KEYS
+        if missing or unexpected:
+            details = []
+            if missing:
+                details.append(f"missing {sorted(missing)}")
+            if unexpected:
+                details.append(f"unexpected {sorted(unexpected)}")
+            raise BlockSchemaError(f"malformed block envelope: {', '.join(details)}")
+
+        if envelope["boltzmann"] != PROTOCOL_VERSION:
+            raise BlockSchemaError(
+                f"block declares protocol version {envelope['boltzmann']!r}, this client implements {PROTOCOL_VERSION}"
+            )
+
+        try:
+            memory_type = MemoryType(envelope["memory_type"])
+        except ValueError as error:
+            raise BlockSchemaError(f"unknown memory type {envelope['memory_type']!r}") from error
+
+        schema_version = envelope["schema_version"]
+        block_class = _REGISTRY.get((memory_type, schema_version))
+        if block_class is None:
+            known = sorted(version for kind, version in _REGISTRY if kind is memory_type)
+            raise BlockSchemaError(
+                f"no schema registered for {memory_type} version {schema_version!r}; this client knows {known}"
+            )
+
+        if envelope["serialization"] != block_class.SERIALIZATION:
+            raise BlockSchemaError(
+                f"block declares serialization {envelope['serialization']!r}, "
+                f"{block_class.__name__} uses {block_class.SERIALIZATION!r}"
+            )
+
+        block = block_class.model_validate(envelope["payload"])
+        if block.canonical_bytes() != data:
+            raise BlockIntegrityError(
+                f"stored bytes for a {memory_type} block are not in canonical "
+                f"{block_class.SERIALIZATION} form, so they do not hash to the block_id they claim"
+            )
+        return block
+
+    @staticmethod
+    def registry() -> dict[tuple[MemoryType, int], type[Block]]:
+        """
+        The registered block schemas.
+
+        Returns:
+            dict[tuple[MemoryType, int], type[Block]]: Map of memory type and
+            schema version to the class that implements it.
+        """
+        return dict(_REGISTRY)

boltzmann/blocks/canonical.py

@@ -0,0 +1,76 @@
+"""Canonical memory: what material was observed (paper Section 5).
+
+The canonical module preserves observed evidence, not truth claims. A canonical
+block asserts that a source was incorporated and that it *contains* certain
+bytes; it does not declare those bytes correct. Because every semantic and
+procedural interpretation cites canonical evidence through provenance, this
+module is the root of re-derivation.
+
+**A canonical block is a pure statement about observed bytes.** Its identity
+depends on nothing else, which is what makes re-registering an identical original
+a genuine no-op: two actors ingesting the same PDF compute the same ``block_id``
+and the second registration adds no block. Everything historical or
+actor-dependent -- who incorporated it, when, from where, under what license or
+retention policy, and which earlier edition it supersedes -- is recorded as a
+provenance edge instead. See :mod:`boltzmann.blocks.provenance`.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from boltzmann.blocks.base import Block
+from boltzmann.blocks.memory_type import MemoryType
+from boltzmann.identity.digest import OciDigest
+
+
+class NormalizedView(BaseModel):
+    """
+    A deterministic transform of an original blob.
+
+    A normalized view is plain text, Markdown, or a structured extract produced by
+    a named deterministic pipeline whose identity is recorded in provenance.
+    Normalized views live in canonical rather than semantic memory because they are
+    still evidence for ingestion, not consolidated knowledge.
+
+    Attributes:
+        blob (OciDigest): Content address of the normalized bytes.
+        media_type (str): IANA media type of the normalized bytes.
+        size (int): Length of the normalized bytes in bytes.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    blob: OciDigest
+    media_type: str = Field(min_length=1)
+    size: int = Field(ge=0)
+
+
+class CanonicalBlock(Block):
+    """
+    Evidence that a source was incorporated and preserved.
+
+    Note which level of identity ``blob`` carries. The observed bytes of a source
+    are a transportable file, not a unit of knowledge, so they are addressed by an
+    :class:`~boltzmann.identity.digest.OciDigest`; the ``block_id`` of this block is
+    the knowledge-level statement *about* those bytes. Read together with
+    ``media_type`` and ``size``, this block is an OCI descriptor over the evidence
+    plus an optional normalized view of it -- which is why publishing a brain is a
+    copy rather than a conversion.
+
+    Attributes:
+        blob (OciDigest): Content address of the original bytes as observed.
+        media_type (str): IANA media type of the original.
+        size (int): Length of the original in bytes.
+        normalized_view (NormalizedView | None): Optional deterministic transform
+            of the original, addressed by its own hash.
+    """
+
+    MEMORY_TYPE: ClassVar[MemoryType] = MemoryType.CANONICAL
+
+    blob: OciDigest
+    media_type: str = Field(min_length=1)
+    size: int = Field(ge=0)
+    normalized_view: NormalizedView | None = None

boltzmann/blocks/episodic.py

@@ -0,0 +1,52 @@
+"""Episodic memory: what happened in a concrete context (paper Section 5).
+
+Records events and experiences with time, context, participants, outcome, and
+evidence. This is the only module that stays append-only: corrections generate new
+episodes or supersession relations rather than drops that rewrite the past.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Self
+
+from pydantic import Field, model_validator
+
+from boltzmann.blocks.base import Block
+from boltzmann.blocks.memory_type import MemoryType
+from boltzmann.identity.digest import BlockId
+from boltzmann.identity.time import Timestamp, parse_timestamp
+
+
+class EpisodicBlock(Block):
+    """
+    A concrete experience, situated in time.
+
+    Attributes:
+        summary (str): What happened, in one statement.
+        occurred_at (Timestamp): When the episode happened, in canonical UTC form.
+        ended_at (Timestamp | None): When it finished, for episodes with duration.
+        context (str | None): The setting the episode belongs to, such as a course,
+            a project, or a conversation.
+        participants (list[str] | None): Who took part.
+        outcome (str | None): How it resolved.
+        evidence (list[BlockId] | None): Canonical blocks that attest to the episode.
+        tags (list[str] | None): Free-form labels for filtering.
+    """
+
+    MEMORY_TYPE: ClassVar[MemoryType] = MemoryType.EPISODIC
+
+    summary: str = Field(min_length=1)
+    occurred_at: Timestamp
+    ended_at: Timestamp | None = None
+    context: str | None = None
+    participants: list[str] | None = None
+    outcome: str | None = None
+    evidence: list[BlockId] | None = None
+    tags: list[str] | None = None
+
+    @model_validator(mode="after")
+    def _check_interval(self) -> Self:
+        """An episode cannot end before it started."""
+        if self.ended_at is not None and parse_timestamp(self.ended_at) < parse_timestamp(self.occurred_at):
+            raise ValueError(f"ended_at {self.ended_at} precedes occurred_at {self.occurred_at}")
+        return self

boltzmann/blocks/memory_type.py

@@ -0,0 +1,53 @@
+"""The five memory modules (paper Section 5).
+
+Each module is named by the question it answers:
+
+============  ==========================================================
+canonical     What material was observed?
+episodic      What happened in a concrete context?
+semantic      What general knowledge was consolidated?
+procedural    How is a task performed?
+provenance    Where did it come from and how was it transformed?
+============  ==========================================================
+
+The enum lives in the kernel rather than in the module layer because a block's
+memory type sits inside the hashed envelope: it is part of that block's identity,
+not a property of where the block happens to be stored.
+"""
+
+from enum import StrEnum
+
+
+class MemoryType(StrEnum):
+    """A memory module, and therefore the type of a knowledge block."""
+
+    CANONICAL = "canonical"
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+    PROVENANCE = "provenance"
+
+    @property
+    def is_append_only(self) -> bool:
+        """
+        Whether the module refuses ``drop``.
+
+        The episodic module is a chronological record of what happened, so
+        corrections append new episodes or supersession relations rather than
+        rewriting the past (paper Section 10.3).
+        """
+        return self is MemoryType.EPISODIC
+
+    @property
+    def is_droppable(self) -> bool:
+        """Whether blocks may be excluded from this module's composition."""
+        return not self.is_append_only
+
+    @property
+    def is_derived(self) -> bool:
+        """
+        Whether blocks of this type are interpretations that cite canonical evidence.
+
+        Derived blocks are what a canonical drop cascades to (paper Section 10.3).
+        """
+        return self in {MemoryType.SEMANTIC, MemoryType.PROCEDURAL}

boltzmann/blocks/procedural.py

@@ -0,0 +1,62 @@
+"""Procedural memory: how a task is performed (paper Section 5).
+
+Represents action sequences, conditions, decisions, alternative paths, and success
+criteria -- for example how to obtain the Fourier coefficients of a given function.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from boltzmann.blocks.base import Block
+from boltzmann.blocks.memory_type import MemoryType
+from boltzmann.identity.digest import BlockId
+
+
+class Step(BaseModel):
+    """
+    One action in a procedure.
+
+    Attributes:
+        action (str): What to do.
+        condition (str | None): When this step applies, for branching procedures.
+        alternatives (list[str] | None): Other ways to accomplish the same step.
+        uses (list[BlockId] | None): Semantic blocks the step relies on, such as the
+            formula it applies.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    action: str = Field(min_length=1)
+    condition: str | None = None
+    alternatives: list[str] | None = None
+    uses: list[BlockId] | None = None
+
+
+class ProceduralBlock(Block):
+    """
+    A way of performing a task.
+
+    Attributes:
+        label (str): Short name of the procedure.
+        goal (str): What the procedure accomplishes.
+        steps (list[Step]): The ordered actions. Order is significant, so it is part
+            of the block's identity.
+        preconditions (list[str] | None): What must hold before starting.
+        success_criteria (list[str] | None): How to tell the procedure worked.
+        subject (str | None): Domain the procedure belongs to, for filtering.
+        evidence (list[BlockId] | None): Canonical blocks this procedure cites.
+            A canonical drop cascades to every block that lists it here.
+    """
+
+    MEMORY_TYPE: ClassVar[MemoryType] = MemoryType.PROCEDURAL
+
+    label: str = Field(min_length=1)
+    goal: str = Field(min_length=1)
+    steps: list[Step] = Field(min_length=1)
+    preconditions: list[str] | None = None
+    success_criteria: list[str] | None = None
+    subject: str | None = None
+    evidence: list[BlockId] | None = None