Trumpet-FL-core

A Federated Learning platform to test and evaluate different Privacy Enhancing Technologies. This repository contains resources for building, deploying, and testing Docker images for the FL Core, which includes the Aggregator (Agg) and Data Owner (DO) components.

Building and Running FL images

Aggregator

To get started, firts, clone this repository.

$ git clone https://github.com/gradiant/Trumpet-FL-core.git
$ cd Trumpet-FL-core

The Aggregator image can be built and optionally started using Docker Compose or Docker directly.

• Using Docker Compose:

  $ docker compose -f docker-compose.agg.yml build

• Using Dockerfile:

  $ docker build -t grad-fl-agg:latest -f Dockerfile.agg .

We provided an example docker compose file for deploying this service:

$ docker compose -f docker-compose.agg.yml up

Data Owner

The Data Owner image can also be built in the same way and optionally started using Docker Compose.

• Using Docker Compose:

  $ docker compose -f docker-compose.do.yml build

• Using Dockerfile:

  $ docker build -t grad-fl-do:latest -f Dockerfile.do .

For the Data Owner, we also provided an example docker compose for deploying this service:

$ docker compose -f docker-compose.do.yml up

Test FL Core

To run unit tests, execute:

pytest

To test the fl-core with a 3 domain owners / one aggregator scenario, first deploy using docker compose:

$ docker compose -f docker-compose.yaml up

Under deploy folder, there are all the files needed for testing the FL core. In order to do that, follow these steps on separate terminals:

$ python3 backend_receiver.py
$ python3 start_train_tvs_version.py 

---

Export FL images

• After succesfully build and test the FL images locally, you can export them:

  $ docker save grad-fl-agg:latest grad-fl-do:latest | gzip > grad-fl-images.tar.gz

• Those images can be loaded back again on other computer:

  $ docker load < grad-fl-images.tar.gz

Note on Network Configuration :

• The network configuration provided in this repository is intended as an example and may need to be adjusted based on your specific environment and requirements.

• This applies to both the aggregator (agg) and the data owner (do) components. Ensure that the network settings are properly aligned with your infrastructure to avoid conflicts or connectivity issues.

Project Structure

The project is organized into several key directories and files, each serving a distinct role in the implementation of Federated Learning. At the top level, there are four main directories: aggregation, api, communicator, node, and utils:

• The aggregation directory contains various strategies for secure aggregations using privacy-enhancing technologies.
• The api directory is split into two subdirectories, aggregator and do (Domain Owners), each containing the necessary endpoints and main files to handle API requests. This APIs, both in the Agg and DO, invoke the FL functionalities implemented in the library.
• The communicator directory houses classes responsible for communication between nodes, such as HTTPCommunicator. Ideally the classes implementing this behaviour should be interchangeable.
• The node directory defines the abstract and concrete classes for both the aggregator and the domain owners. This components are responsible for orchestrating the entire FL process.
• The utils directory includes utility scripts and machine learning models essential for the FL process.

API Documentation

Endpoints

Aggregator

Method	Endpoint	Description
POST	/setup	Endpoint to send the setup data

Domain Owner

Method	Endpoint	Description
POST	/upload_data	Endpoint to upload data
POST	/setup	Endpoint to send the setup data

Study Agreement

In the context of federated learning, a Study Agreement refers to a configuration or contract that defines the rules, parameters, and settings for conducting a study or experiment involving multiple nodes. This agreement ensures that all participants or components in the federated learning setup align with the same operational expectations. For this case, the FL Core defines a reduced or simplified version of the actual study agreement. This agreement can be sent to FL Core through the /setup endpoint in a JSON format, and defines the following fields:

• name: Name of the study.
• study_id: Id of the study.
• coordinator: Public IP of the aggregator FL core.
• model: Selected model to train (provided inside FL core).
• pet: Privacy Enhancing Techonology to use during aggregations.
• webhook_url: Endpoint where DOs can notify the backend about the progress of the FL training and send the final results.
• participants: List with the DO FL core endpoints.
• pet_config: List of the paramaters of the selected PET function and its values.

For convenience, an example JSON config is provided:

{
    "name": "Study 1",
    "study_id": "4b3c4477-fccc-4e13-bffd-d4d0c34b2507",
    "coordinator": "172.19.0.2:8080",
    "model": "NN_FHIR",
    "pet": "None",
    "pet_config" : {},
    "rounds": "3",
    "webhook_url": "http://172.19.0.1:9000/",
    "participants": ["http://172.19.0.3:8080/","http://172.19.0.4:8080/","http://172.19.0.5:8080/"],
}

Aggregation

Aggregation strategies play a pivotal role in combining the locally trained model updates from multiple nodes into a unified global model. These strategies are designed to ensure efficient, accurate, and secure integration of diverse contributions while preserving data privacy. Common aggregation approaches like FedAVG leverage weighted averaging of parameters, effectively balancing contributions based on the size of local datasets. Advanced methods such as CDC_DP incorporate differential privacy and coded distributed computing mechanisms to safeguard sensitive information, while strategies like ThHE utilize homomorphic encryption to ensure secure computations. Note that these techniques extend FedAVG by adding extra protection to the aggregation mechanism. The choice of aggregation method directly impacts the overall performance, scalability, and privacy guarantees of the federated system, making it a critical aspect of designing robust federated learning workflows.

FedAVG

Specifying this option in the study will run Federated Averaging algorithm without any parameter-protection.

{
  "name": "Study 1",
  "study_id": "4b3c4477-fccc-4e13-bffd-d4d0c34b2507",
  "coordinator": "172.19.0.2:8080",
  "model": "NN",
  "pet": "None",
  "rounds": "3",
  "webhook_url": "http://172.19.0.1:9000/",
  "participants": ["http://172.19.0.3:8080/","http://172.19.0.4:8080/","http://172.19.0.5:8080/"],
  "pet_config": {},
}

CDC_DP

Coded Distributed Computing with Differential Privacy (CDC_DP) combines advanced coding techniques, such as Lagrange Coded Computing (LCC), with Differential Privacy (DP) to ensure secure and efficient aggregation of local model updates in federated learning. This approach protects sensitive data by encoding inputs to achieve information-theoretic privacy while introducing calibrated noise for additional privacy guarantees in the aggregated model.

This aggregation mechanism can be configured using the following pet parameters:

• eval_points: Evaluation points of the Lagrange interpolating polynomial. It is an array composed of equidistant points.
• eps1: Selects the the noise to be added to the models parameters in order to check if those parameters are candidates to be released.
• eps3: Parameter for dinamically select the noise to add in the weights that have been choosed.
• epochs: Number of epochs the model got. Right now should remain to a fixed value of 1.
• release_proportion: Proportion of model parameters released.
• eps2: Parameter to calculate the noise that is added to the threshold to choose candidates.
• gamma: The sensitivity is used to calibrate the noise added to each update.
• tau: Threshold for choosing parameter candidates.

Below we provided an example configuration:

{
  "name": "Study 1",
  "study_id": "4b3c4477-fccc-4e13-bffd-d4d0c34b2507",
  "coordinator": "172.19.0.2:8080",
  "model": "NN",
  "pet": "CDC_DP",
  "rounds": "3",
  "webhook_url": "http://172.19.0.1:9000/",
  "participants": ["http://172.19.0.3:8080/","http://172.19.0.4:8080/","http://172.19.0.5:8080/"],
  "pet_config": {
      "eval_points": [0.001, 0.002, 0.003],
      "eps1": 0.5,
      "eps3": 10,
      "epochs": 1,
      "release_proportion": 0.3,
      "eps2": 0.5,
      "gamma": 1,
      "tau": 1e-10,
  },
}

ThHE

The technique Threshold Homomorphic Encryption enables secure aggregation of encrypted data in federated learning, ensuring that intermediate computations remain private and can only be decrypted collectively by authorized parties.

In this implementation, the PET is distributed as a compiled shared library (thhe.so). This binary is built from the Lattigo library, which provides the underlying lattice-based homomorphic encryption primitives used by the system.

This aggregation mechanism can be configured using the following pet parameters:

• logn: Logarithm of N. Basically defines the input parameter size of the model.
• plaintext_mod: Specifies the modulus t for the plaintext space, meaning that plaintext values are integers in the range [0,t−1]. A larger value allows encoding larger numbers or more precise data representations, however, a larger t may require a larger q to ensure computations remain valid. Right now cannot be configurable.
• log_q: Refers to the logarithm of the modulus q, which is the modulus of the ciphertext space. A larger value allows more computations, but increases the computational cost. Critical to controll the noise budget.
• log_p: Logarithm of modulus p, used in the rescaling process, which is a key operation for maintaining precision in approximate arithmetic.
• scale: Refers to a multiplicative factor used to encode real (or complex) numbers as integers for encryption. This process is necessary because lattice-based cryptography operates over integers.

Below we provided an example configuration:

{
  "name": "Study 1",
  "study_id": "4b3c4477-fccc-4e13-bffd-d4d0c34b2507",
  "coordinator": "172.19.0.2:8080",
  "model": "NN",
  "pet": "ThHE",
  "rounds": "3",
  "webhook_url": "http://172.19.0.1:9000/",
  "participants": ["http://172.19.0.3:8080/","http://172.19.0.4:8080/","http://172.19.0.5:8080/"],
  "pet_config": {
      "logn": 16,
      "plaintext_mod": 0,
      "log_q": [58, 56, 55, 55],
      "log_p": [56, 55],
      "scale": 16,
  },
}

Replication of experiments

The Deploy folder contains the three following scripts used to start the training. Note that train_mnist_with_contributions.py and train_mnist_without_contributions.py are intended solely for testing purposes.

• start_train_tvs_version.py: In this script, training is set up and executed using HAPI FHIR JSON data. The script configures the training parameters and supports the integration of privacy-enhancing technologies (PETs) such as CDC_DP or ThHE. It uploads datasets and orchestrates the training process with the defined settings.

• train_mnist_with_contributions.py: This script trains using the MNIST dataset with participant contributions explicitly factored into the aggregation process. Each participant's dataset size is taken into account to proportionally influence the global model updates during training.

• train_mnist_without_contributions.py: This script trains using the MNIST dataset without considering participant contributions. All participants are assumed to have contributed equally, and their data is given equal weight in the aggregation process.

Licensing

This repository contains components under different licenses.

Source Code (AGPLv3)

All source code in this repository is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

You can find the full license text in the LICENSE file of this repository or at: https://www.gnu.org/licenses/agpl-3.0.html

Binary Component (Apache 2.0)

The binary file grad_fl/aggregation/pet/thhe.so is licensed under the Apache License, Version 2.0.

You can find the full license text in the grad_fl/aggregation/pet/thhe-LICENSE file or at: https://www.apache.org/licenses/LICENSE-2.0

Notes

• The binary component is distributed under Apache 2.0 and may be used, modified, and redistributed under its terms.
• The source code is distributed under AGPLv3, which imposes copyleft requirements, especially when the software is used over a network.
• Each component must be used in compliance with its respective license.

If you redistribute this repository or build upon it, ensure that you comply with the obligations of both licenses.

Acknowledgment

Funded by the European Union

Trumpet project has received funding from a Research and Innovation action activity under Horizon Europe Framework Programme with Grant Agreement No.101070038