idea156-kappabridge-privacy-safe/AGENTS.md

AGENTS.md

Architecture

This repository implements KappaBridge as a Python package under src/idea156_kappabridge_privacy_safe.

Core modules:

• contracts.py: canonical contract models for Object, SharedSignal, PlanDelta, DatasetSchema, AccessPolicy, and audit/reproducibility records.
• storage.py: SQLite persistence with SQLAlchemy, including the contract table and tamper-evident governance ledger.
• registry.py: graph-of-contracts registry backed by networkx.
• attestation.py: Ed25519-based cryptographic attestations for contract use.
• sync.py: deterministic delta sync envelopes for offline-first reconnection.
• adapters.py: lab/data-format adapters for climate, epidemiology, genomics, ecology, and image datasets.
• optimizer.py: lightweight deterministic federated planner for joint experiment requests.
• harness.py: conformance harness for adapter validation.

Tech Stack

• Python 3.11+
• Pydantic for contract validation
• SQLAlchemy + SQLite for durable persistence
• Cryptography for attestations
• NetworkX for the contract graph
• Pandas, Pillow, and NumPy for adapter support

Testing

• Run bash test.sh to build the package and execute the full test suite.
• The script must continue to pass after any change to contracts, ledger hashing, or sync behavior.

Rules

• Keep contract hashing canonical and deterministic.
• Do not mutate stored contracts; append new records instead.
• Preserve ledger ordering and hash chaining.
• When adding adapters, ensure they produce stable, validated manifests.
• Prefer the smallest correct change that keeps offline sync and governance auditable.