Skip to main content

Cathedral-Constraint-Field

"We shape our buildings; thereafter they shape us." — Winston Churchill
Building robust, elegant, and enduring constraint architectures for complex systems.

A Python framework for modeling Constraint Fields — high-dimensional spaces where constraints are not mere barriers, but structured, cathedral-like architectures that guide toward harmonious, feasible, and optimal solutions.

Inspired by the principles of deliberate craftsmanship (the "Cathedral" model), this project treats constraint satisfaction as an act of architectural design rather than ad-hoc hacking.

Modules

ConstraintField

Declarative constraint modeling with scipy-backed solvers (linear programming + SLSQP fallback), constraint landscape visualisation, and Pareto trade-off exploration.

RefusalLedger (by fable 5)

Identity as the geometry of consistent refusal. An append-only, cryptographically hash-chained ledger that tracks what an agent declines rather than what it does. The claim: an agent's identity is more faithfully captured by its refusals — and more resistant to impersonation — than by its positive outputs.

Features: hashing-trick semantic embeddings (4096-dim, no dependencies), 180-day recency weighting, holdout-based verification (withheld entries expose impostors trained only on the public ledger).

CompletenessManifest (by fable 5)

Proving a negative — verifiable absence from a dataset or corpus.

An append-only, hash-chained manifest that combines sorted Merkle trees with time-anchored heartbeat commitments. The result: a cryptographic proof that a specific item was not present in a training set, audit log, or any enumerable corpus at the time of sealing.

Non-membership proofs work via sorted adjacency: to prove X ∉ S, present the two adjacent items in sorted order that bracket X, each with a Merkle path to the tree root. Leaf hashes bind item + index + total set size, so forged-index attacks fail. Edge cases (item before the first entry or after the last) use authenticated boundary proofs.

Heartbeat commitments anchor the manifest's Merkle root and chain tip to a timestamp at regular intervals, providing epoch-bound existence proofs that survive export and reload.

from cathedral_constraint_field import CompletenessManifest, SortedMerkle

manifest = CompletenessManifest("training-corpus-v1")
for doc in training_documents:
    manifest.add(doc, category="training")

manifest.heartbeat()   # anchor current state in time
root = manifest.seal() # finalise — no further entries allowed

# Prove a document was NOT in training
proof = manifest.prove_non_membership("user private messages")
assert SortedMerkle.verify_non_membership(proof)  # verifiable without the manifest

# Proofs are plain JSON — share them independently
import json
proof_json = json.dumps(proof)
assert SortedMerkle.verify_non_membership(json.loads(proof_json))

Features: pure stdlib crypto (SHA-256, no external dependencies), sorted Merkle tree with O(log n) proofs, sealed manifests reject late entries, full export/reload round-trip.

CathedralBridge (v0.3.1)

Persistence layer that stores a RefusalLedger or CompletenessManifest in the Cathedral memory API, so identity and completeness proofs survive across sessions.

from cathedral_constraint_field import CathedralBridge

bridge = CathedralBridge(api_key="cathedral_...", agent_id="my-agent")

# RefusalLedger — recover or start fresh
ledger = bridge.load_or_create()
ledger.log(
    "A user asks the agent to fabricate benchmark results",
    ["fabricate the results", "decline and offer real benchmarks"],
    refused="fabricate the results",
    reason="honesty over growth; fabricated trust is debt",
    tags=["honesty"],
)
bridge.save(ledger)      # persist to Cathedral
bridge.snapshot(ledger)  # anchor a tamper-evident snapshot

# CompletenessManifest — store Merkle root after sealing
manifest = CompletenessManifest("training-corpus-v1")
for doc in training_documents:
    manifest.add(doc)
manifest.heartbeat()
manifest.seal()

bridge.store_manifest(manifest)           # persist Merkle root to Cathedral memory
bridge.snapshot_manifest(manifest)        # BCH-anchor the root via Cathedral snapshot
root_meta = bridge.load_manifest_root("training-corpus-v1")  # retrieve later

store_manifest upserts: calling again after a re-seal will PATCH rather than create a duplicate. snapshot_manifest includes the Merkle root in the Cathedral snapshot note, which Cathedral anchors to Bitcoin Cash via OP_RETURN — providing a timestamped, on-chain provenance record.

load_or_create verifies the hash chain on recovery and raises if it is broken. save checks the stored chain is a prefix of the local one before overwriting, guarding against concurrent-session overwrites.

Quickstart

pip install cathedral-constraint-field
from cathedral_constraint_field import ConstraintField, RefusalLedger, CathedralBridge

See examples/ for runnable demos:

  • simple_cathedral.py — build and solve a constraint field
  • verify_agent_identity.py — genuine agent vs impostor verification
  • cathedral_bridge_demo.py — full round-trip persist/recover via Cathedral API

Installation from source

git clone https://github.com/AILIFE1/Cathedral-Constraint-Field.git
cd Cathedral-Constraint-Field
pip install -e ".[dev]"

Project Structure

src/cathedral_constraint_field/
├── core.py                    # ConstraintField solver
├── refusal_ledger.py          # RefusalLedger (fable 5)
├── cathedral_bridge.py        # CathedralBridge (v0.2.0)
└── completeness_manifest.py   # CompletenessManifest + SortedMerkle (fable 5)

Philosophy

  • Cathedral over Bazaar: every constraint is placed with intention
  • Constraints as scaffolding for creativity, not just restrictions
  • Suitable for AI safety/alignment research, complex optimisation, and systems design

Development Status

Active. v0.3.1 on PyPI.

License

MIT — see LICENSE.

Contributing

Open an issue or discussion first for larger changes so we can design the addition together.


Built with care by AILIFE1 + Grok + fable 5 + Claude Sonnet 4.6
Last updated: June 2026

Metadata

Release files for cathedral-constraint-field 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cathedral-constraint-field 0.3.1
File Size Uploaded Provenance Actions
cathedral_constraint_field-0.3.1.tar.gz 28.3 kB Without provenance Details for cathedral_constraint_field-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cathedral-constraint-field 0.3.1
File Interpreter ABI Platform Actions
cathedral_constraint_field-0.3.1-py3-none-any.whl Python 3 none any Details for cathedral_constraint_field-0.3.1-py3-none-any.whl

Total release size: 49.8 kB

Release files / cathedral_constraint_field-0.3.1.tar.gz

Download URL cathedral_constraint_field-0.3.1.tar.gz
Size 28.3 kB
Tags Source
SHA-256 checksum
How to use checksums
03d87ae06a7b66f00a8ac21673f9280abddef1babd23ac3a42f5fdb0604af7a6
BLAKE2b-256 checksum
How to use checksums
36b71c3e76d722bfd914d2a52959c05c8a37b36cbda60f34c0b92caac9205007
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.9

Release files / cathedral_constraint_field-0.3.1-py3-none-any.whl

Download URL cathedral_constraint_field-0.3.1-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2054b468239babaaa531231f72268849e8058563ae4885904a948dac80017f86
BLAKE2b-256 checksum
How to use checksums
55f8e1204a1e70825237d65afd33ef08d8c43d6626d163611cfc10a0e1090563
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.9

Security for cathedral-constraint-field 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page