idea151-aidmesh-federated-privacy/AGENTS.md

AidMesh – Architecture & Agent Protocols

• Goal: A privacy-preserving, offline-first disaster-relief orchestration framework that federates local planning using a canonical contract model.

• Core concepts (GoC): LocalProblem (Objects), SharedSignals / DualVariables (Morphisms), PlanDelta, AuditLog, PrivacyBudget, and Time Rounds for delta-sync.

• Tech Stack (production-ready): Python 3.8+, FastAPI optional, SQLite or in-memory storage, cryptographic tagging for messages, and a lightweight ADMM-lite solver for cross-organization coordination.

• Repository structure:

  • src/idea151_aidmesh_federated_privacy/: package
  • tests/: unit tests for core primitives
  • AGENTS.md: this file
  • README.md: product overview and how to contribute

• Testing & tooling:

  • test.sh: runs pytest, builds the package to verify packaging metadata.
  • The build step uses python3 -m build and stores artifacts in dist/.

• Conventions:

  • Use dataclasses for data models. Immutable where possible.
  • Keep adapters pluggable via small interface; adapters communicate via TLS-like envelopes (simulated in tests).
  • Deterministic replay: delta logs can be replayed; no non-deterministic dependencies in tests.

• Collaboration model:

  • Phase-based rollout as described in the MVP blueprint.
  • Adapters (starter set): SupplyDepotController, FieldDistributionPlanner.

• Governance & privacy:

  • Per-message crypto-tags, tamper-evident logs, optional differential privacy budgets, and short-lived identities.

• Tests & quality gates:

  • At least one basic test in tests/ ensuring core primitives function end-to-end.
  • test.sh should succeed, including a packaging build check.