Metadata-Version: 2.4
Name: cathedral-constraint-field
Version: 0.3.1
Summary: A deliberate framework for modeling elegant constraint fields in complex systems
Project-URL: Homepage, https://github.com/AILIFE1/Cathedral-Constraint-Field
Project-URL: Repository, https://github.com/AILIFE1/Cathedral-Constraint-Field
Project-URL: Issues, https://github.com/AILIFE1/Cathedral-Constraint-Field/issues
Author-email: AILIFE1 <ailife1@example.com>
License: MIT
License-File: LICENSE
Keywords: ai-alignment,cathedral,constraint-satisfaction,constraints,mathematical-modeling,optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.0
Requires-Dist: scipy>=1.13
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Description-Content-Type: text/markdown

# 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.

```python
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](https://cathedral-ai.com), so identity and completeness proofs survive across sessions.

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

```bash
pip install cathedral-constraint-field
```

```python
from cathedral_constraint_field import ConstraintField, RefusalLedger, CathedralBridge
```

See [`examples/`](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

```bash
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](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*
