bellbook (Python)

Python bindings for Bellbook: validate tamper-evident, replay-verifiable records of agent activity offline, from Python.

This is a thin PyO3 wrapper over the Rust bellbook crate, which stays the single source of truth for canonicalization, verification, and the conformance vectors. It is not a reimplementation. (The independent from-scratch validator under conformance/python/ in the repository is a separate thing: a deliberate second implementation that exists to cross-check the specification.)

Status

Validation, reading, and writing (issue #13).

Validate

validate(bytes) -> Report reaches the same Clean / Tainted / Invalid decision as the bellbook validate CLI, over the same core.

import bellbook

report = bellbook.validate(open("receipt.json", "rb").read())

print(report.status)          # "clean" | "tainted" | "invalid"
print(report.spec_version)    # "0.3"
print(report.record_count)
print(report.head_hash)       # lowercase hex; compare against an anchored head
print(report.rules_hash)      # compare against rules you trust
print(report.retracted, report.tainted)
print(report.standing)        # {"compromised": [...], "unsound": [...], "restorations": {...}}
print(report)                 # the full human-readable report (same as the CLI)

Validation never raises for a bad receipt: an unparseable or failing receipt returns a Report with status == "invalid" and a problem or reason set. As with the CLI, Clean is relative to the rules embedded in the receipt - compare rules_hash against a rule set you trust.

Read

read(bytes) -> Receipt parses a receipt for inspection. Reading does not verify - call validate for the decision.

import json

receipt = bellbook.read(open("receipt.json", "rb").read())

print(receipt.spec_version, len(receipt))
for r in receipt.records:
    print(r.kind, r.time, r.author_id, r.author_type, r.evidence)
    for ref in r.refs:
        print("  ", ref["type"], "->", ref["target"])
    payload = json.loads(r.payload_json)

A Record exposes id, kind, time, author_id, author_type, signed, evidence, schema, refs, and payload_json. The enum-valued fields (kind, author_type, evidence, and each ref's type) are the record's Rust variant names, e.g. "Candidate", "Provider", "Reported", "Use". read raises ValueError on bytes that are not a parseable receipt.

Write

Writer(log_dir, rules) records evolution to a persistent, single-writer log. It holds the same exclusive lock and runs the same replay-on-commit the Rust LogWriter does. rules is a JSON string: the verifier rules the log is committed under, the same object a receipt embeds under rules.

import bellbook

w = bellbook.Writer("./mylog", rules_json)

c0 = w.candidate(author="agent", git_tree="a1b2...")            # a Root candidate
e0 = w.evaluate(author="agent", candidate=c0.id, criterion="builds", passed=True)
s0 = w.select(author="agent", objective="ship it",
              consider=[c0.id], choose=[c0.id], uses_eval=[e0.id])

print(c0.id, c0.accepted, c0.reason)   # each commit returns a Commit

# Export and verify in the same process:
report = bellbook.validate(w.receipt())
assert report.status == "clean"

Each of candidate, evaluate, and select commits one record and returns a Commit (id, accepted, result, reason). A record is durably committed whether accepted or rejected - a rejected record is evidence a proposal was refused - so accepted may be False without an exception. Statically-knowable payload violations (an unregistered author, a score scale above 12, an upgrade whose tree differs from its target) raise ValueError before anything is written.

  • candidate(author, git_tree, *, git_commit=None, algo="sha1", note=None, continues=None, parent=None, derives_from=None, upgrades=None, manifest=None)
    • basis is exactly one of continues (with parent), derives_from, or upgrades; omit all three for a Root. manifest (a directory path) binds the source by a canonical manifest hash instead of a reported tree.
  • evaluate(author, candidate, criterion, *, passed=False, failed=False, score=None, scale=None, procedure=None, uses=None) - exactly one of passed, failed, or a score (with scale, a decimal exponent 0-12).
  • select(author, objective, consider, *, choose=None, uses_eval=None, none=False, replaces=None, rationale=None) - exactly one of choose (with uses_eval) or none=True; replaces reaffirms a prior selection.

The writer is deliberately single-writer (SPEC 5.1): it holds an exclusive lock for the log directory, so a second Writer on the same directory raises. Other useful members: w.head (current head, hex), w.records (the committed records, as Records), len(w), and w.receipt() (portable receipt bytes).

Build from source

pip install maturin
maturin develop            # build and install into the current venv
pytest bindings/python/tests

Wheels are built and published in CI (later stages); this is for local development.

Licensed under MIT OR Apache-2.0.

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cristianducu from gravatar.com cristianducu

Credits

Author: Bellbook AI

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.9

Tags

audit tamper-evident provenance agent verification

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bellbook-0.3.0.tar.gz (19.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

bellbook-0.3.0-cp39-abi3-win_amd64.whl (692.1 kB view details)

Uploaded CPython 3.9+Windows x86-64

bellbook-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (862.4 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

bellbook-0.3.0-cp39-abi3-macosx_11_0_arm64.whl (757.8 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file bellbook-0.3.0.tar.gz.

File metadata

  • Download URL: bellbook-0.3.0.tar.gz
  • Upload date:
  • Size: 19.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bellbook-0.3.0.tar.gz
Algorithm Hash digest
SHA256 480fea8c0c1d165a9838e68176adcdc2c17708205d08cb7cb2fc6bb48fed4698
MD5 76ac630a77a23b917bcd6a183b2aa793
BLAKE2b-256 ea60d832418053abc479016aa93b59bb7a40f2f61d9475e2077d1299908744d1

See more details on using hashes here.

Provenance

The following attestation bundles were made for bellbook-0.3.0.tar.gz:

Publisher: publish-pypi.yml on bellbook-ai/bellbook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bellbook-0.3.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: bellbook-0.3.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 692.1 kB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bellbook-0.3.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3cf8d75e06ba0f4b1cad5e00431489932516aedd3718d2994dd9cc75a675999a
MD5 0fc22e378e4fd2b0683c92f74485ab66
BLAKE2b-256 72ce79b7c11c8103b17f42414511dc3f7f4c6d52df35ed6c120ca55a4d2787ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for bellbook-0.3.0-cp39-abi3-win_amd64.whl:

Publisher: publish-pypi.yml on bellbook-ai/bellbook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bellbook-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for bellbook-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e37f0884cdb33d879d0f53292f43cf827f518c3d945c3ce3080086865142587c
MD5 f3a7ccdc38583cbdfd25d9335f9acf10
BLAKE2b-256 eb3e1c32140dfee34aead6b8c640d77c9ed2af6f89562cdc9bf94ffca4740115

See more details on using hashes here.

Provenance

The following attestation bundles were made for bellbook-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on bellbook-ai/bellbook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bellbook-0.3.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for bellbook-0.3.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b488765fcb59f586c1cdc58e155a6f44bd96c45d04bc4a047db50049ef4c4c43
MD5 666b4dbcad3e679a4deee4a9e439189c
BLAKE2b-256 e79f96e7f3262afc539748f6de8fc97900811a73c569e6c77239fe1003728fcc

See more details on using hashes here.

Provenance

The following attestation bundles were made for bellbook-0.3.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish-pypi.yml on bellbook-ai/bellbook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page