opengrowth-privacy-preserving-federated-/AGENTS.md

OpenGrowth Agents — Architecture & Contribution Guide

Overview

• A lightweight, privacy-preserving federated experimentation MVP intended for startup growth insights.
• Core stack is Python-based with a clean, testable API surface suitable for gradual expansion.

Tech Stack

• Language: Python 3.8+
• Components:
  • SchemaRegistry: stores schemas and templates for experiments and metrics
  • ExperimentTemplate: lightweight representation of experiments
  • Adapters: GA4Adapter, SegmentAdapter to map analytics metrics into the canonical representation
  • SecureAggregator: simple, privacy-preserving aggregation (mean + 95% CI)
  • CloudLedger: simple, auditable, cloud-anchored ledger simulation
  • Governance: AccessControl and Policy scaffold

Testing & Quality

• Tests are written with pytest and must pass locally before publishing
• test.sh orchestrates tests plus a packaging build check

Running Tests

• bash test.sh

• Extending the MVP

• Implemented a minimal production-friendly registry extension on GraphOfContracts: list_contracts and unregister_contract for better introspection and lifecycle management.

• Added unit tests (pytest) covering core primitives: LocalExperiment, SharedSignals, PlanDelta, and GraphOfContracts workflows.

• Plan to add REST/MQTT adapters and a secure aggregation backend in follow-up iterations; groundwork in this patch focuses on strengthening the contract model and making it testable.

Notes for contributors:

• The repo now includes tests/test_contracts.py validating core primitives. Run tests with bash test.sh.
• If you extend contracts or add new primitives, add tests accordingly.
• Add more adapters (e.g., Amplitude) with a consistent interface
• Expand governance with versioned templates and access controls
• Implement a more robust secure aggregation (secure multi-party computation or differential privacy knobs in practice)
• Build an initial REST/MQTT adapter to connect analytics stacks to the federation layer

Contribution Rules

• Keep changes small and incrementally testable
• Add tests for any new public API
• Update AGENTS.md if the architecture evolves or new agents are introduced