python-sdk-pets

Privacy-enhancing technologies (PETs) for FLAME: reviewed building blocks to call from an analysis instead of hand-writing privacy code. It complements python-sdk (the node runtime) and python-sdk-patterns (the analysis shape).

Install

pip install git+https://github.com/PrivateAIM/python-sdk-pets.git

Requires Python ≥ 3.10; depends on numpy and opendp. The optional synth (smartnoise-synth) and training (Opacus) extras enable synthetic data and model training.

Example

from flame_pets import Bounds, ProvenanceRecorder, stats

bounds = Bounds(0.0, 120.0)   # from domain knowledge, never from the data
recorder = ProvenanceRecorder(analysis_id="my-analysis")

release = stats.dp_mean(ages, bounds, epsilon=0.5, recorder=recorder)

release.value        # the noisy mean
release.guarantee    # DifferentialPrivacy(epsilon=0.5, delta=0.0)
release.to_dict()    # JSON-safe, ready to submit as a result

A federated analyzer/aggregator example is in examples/dp_mean_star_analysis.py.

Modules

Module	PETs	Guarantee
stats	dp_count/sum/mean, central_dp_*, combine_*	(ε)-differential privacy (OpenDP Laplace)
suppression	safe_count/mean/quantile, crosstab, pool_*	minimum group size k (k-anonymity-family threshold)
synth	DPSynthesizer (smartnoise-synth wrapper)	(ε, δ)-DP at fit time; sampling is free
training	DPTrainer (Opacus DP-SGD), federated_average	(ε, δ)-DP per node
provenance, hub	ProvenanceRecorder, HubMonitoringSink	audit trail of every PET call

Design

• Privacy parameters (bounds, thresholds, category domains) are declared explicitly from domain knowledge, never derived from the data.
• Every output is a Release carrying an explicit guarantee: differential privacy (with an epsilon) or a minimum group size (with a k). These are different kinds of statements — DP bounds inference, a group-size threshold constrains the released output — and they are never conflated.
• Withheld values are the SUPPRESSED sentinel, never None or 0.
• Both trust models are supported throughout: node-protected (protection applied before anything leaves the node) and aggregator-protected (a trusted aggregator protects pooled true values).
• The DP statistics are tested against adversarial neighbouring datasets.

Non-goals

Not a replacement for the hub's policy framework, not a general-purpose DP library (it wraps OpenDP, smartnoise-synth, and Opacus for the FLAME patterns), and no defence against a malicious aggregator beyond what the chosen trust model provides.

License

Apache-2.0