Overview#

JAX Privacy provides robust, scalable, pure-JAX implementations of the building blocks necessary to develop DP mechanisms for machine learning applications, alongside high-level training APIs (training and the Keras API) and worked examples. For a high-level summary of what is in and out of scope for the library, see Scope and Design Philosophy in the repository README and the accompanying paper.

The key building blocks that constitute a DP Mechanism include:

  1. (Gradient) Clipping (jax_privacy.clipping): Compute bounded-sensitivity aggregations over a batch of examples (usually minibatch gradients).

  2. Noise Addition (jax_privacy.noise_addition): Add (possibly correlated or adaptive) noise to clipped minibatch gradients, providing formal guarantees for the output.

  3. Batch Selection (jax_privacy.batch_selection): Construct a (usually non-deterministic) sequence of example batches to apply gradient clipping and noise addition to.

  4. Accounting (jax_privacy.accounting): To compute the privacy budget required to run a given mechanism or calibrate the mechanism parameters (like noise multiplier) to achieve a given privacy target.

  5. Auditing (jax_privacy.auditing): To provide empirical measures of the privacy of a model, usually used in conjunction with canary insertion (either at the example level or the gradient level).

The design of the JAX Privacy core library aims to make these different building blocks work together seamlessly, while allowing the user to pick and choose which ones they need for their application. While end-to-end DP mechanisms generally need to be concerned with at least the first four building blocks, there are some cases when one might want to bypass some of our utilities:

  • When doing convex optimization over Lipschitz-continuous losses, the gradient already has bounded sensitivity, and so gradient clipping could in principle be bypassed.

  • When doing research, it is common practice to read the data in a deterministic or shuffled order, rather than adhering to the exact batch selection strategy required to obtain the desired formal DP guarantees. While we don’t recommend doing this, our batch selection strategies can be ignored in such cases.


API Tiers#

JAX Privacy provides three levels of API, each trading flexibility for stronger built-in DP assurance. Each tier builds on the one below it: the higher-level tiers compose the building blocks for you, so that privacy-critical coupling decisions are made once in the library rather than once per user.

Tip

Design principle: You should not be able to configure any individual JAX Privacy utility in a way that breaks its stated guarantees. If you can, that is a bug. We attempt to enforce this at the API level, even when it sacrifices some flexibility.

Tier 1: End-to-end training loops#

These consume a DPExecutionPlan and write the entire training loop for you — batch selection, gradient computation, noise addition, parameter updates, and privacy accounting. The resulting training satisfies the stated DP guarantee unconditionally. It is a design goal of JAX Privacy that you should not need to reason about how the components interact; the library handles this for you.

Currently, the Keras API supports DP-SGD with internally Poisson-sampled batches built from random-access per-example arrays (with accounting done using the same Poisson-sampling assumption); arbitrary DP ExecutionPlans are not yet supported.

Tier 2: DPExecutionPlan#

A single config object bundles batch selection, clipped gradient computation, noise addition, and the corresponding DpEvent into a verified DPExecutionPlan. When you use the plan’s components as documented to write your own training loop, the resulting loop inherits the stated DP guarantee by construction. See dp_sgd_transformer.py and dp_logistic_regression.py for examples.

Tier 3: Core API (low-level building blocks)#

Users compose the individual modules directly. Any BatchSelectionStrategy can be used, any noise addition scheme can be composed, and any DpEvent can be used for privacy analysis — including Monte Carlo accounting via monte_carlo for combinations where PLD/RDP accounting is not available. Each individual component is designed so that you should not be able to configure it in a way that breaks its own local formal guarantees — and if you can, that is a bug. Importantly, these local guarantees are not DP guarantees: individual components do not satisfy DP by themselves. They are properties like sensitivity bounds and per-example isolation that serve as the building blocks for proving DP for the higher-level compositions. The risk at this tier is in composition: wiring components together incorrectly (e.g., calibrating noise to the wrong sensitivity, or using an accounting method that does not match the batch selection strategy). See jax_api_example.py and balls_in_bins_accounting.py for examples.

Your responsibilities at each tier#

Which parts of DP correctness you own depends on the tier you build on:

  • Tier 1 (end-to-end training loops): Nothing, as far as component composition goes. Configure the mechanism and the library handles batch selection, clipping, noise, and accounting so the training loop satisfies the stated guarantee.

  • Tier 2 (DPExecutionPlan): Use the plan’s components as documented. The privacy-critical pieces are already coupled consistently; your job is to wire them into your training loop as described.

  • Tier 3 (Core API): You own composition. You are responsible for calibrating noise to the right sensitivity and using an accounting method that matches your batch selection. The components are designed so that assembling a basic DP-SGD loop is straightforward; going beyond that (e.g., custom mechanisms or accounting) requires genuine DP expertise, and that is a deliberate, acceptable trade-off for the flexibility this tier provides.

This is a direct consequence of JAX Privacy’s flat, auditable design: privacy-critical logic is not buried across nested abstraction layers. Each component (clipping, noise addition, batch selection, accounting) stands alone and can be understood, tested, and audited in isolation; coupling happens only at the higher-level API layer, where the joint guarantees are stated explicitly. See the Common Pitfalls page for how each pitfall interacts with the tier system.

Important

What JAX Privacy can and cannot control. JAX Privacy governs what it computes: the sensitivity of a gradient, the noise added, the accounting of a mechanism. It cannot govern what you release. It will not stop you from logging a PRNG seed, or checkpointing raw training state to unencrypted storage. You must always reason about what leaves your trust boundary, and to whom. This is a property of your deployment, not of the library.