38 lines
1.6 KiB
Markdown
38 lines
1.6 KiB
Markdown
# 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.
|