Client API Usage

The FLARE Client API provides an easy way for users to convert their centralized, local training code into federated learning code with the following benefits:

Only requires a few lines of code changes, without the need to restructure the code or implement a new class
Reduces the number of new FLARE specific concepts exposed to users
Easy adaptation from existing local training code using different frameworks (PyTorch, PyTorch Lightning, HuggingFace)

Core concept

The general structure of the popular federated learning (FL) workflow, “FedAvg” is as follows:

FL server initializes an initial model
For each round (global iteration):
1. FL server sends the global model to clients
2. Each FL client starts with this global model and trains on their own data
3. Each FL client sends back their trained model
4. FL server aggregates all the models and produces a new global model

On the client side, the training workflow is as follows:

Receive the model from the FL server
Perform local training on the received global model and/or evaluate the received global model for model selection
Send the new model back to the FL server

To convert a centralized training code to federated learning, we need to adapt the code to do the following steps:

Obtain the required information from received FLModel
Run local training
Put the results in a new FLModel to be sent back

For a general use case, there are three essential methods for the Client API:

init(): Initializes NVFlare Client API environment.
receive(): Receives model from NVFlare side.
send(): Sends the model to NVFlare side.

Users can use the Client API to change their centralized training code to federated learning, for example:

import nvflare.client as flare

flare.init() # 1. Initializes NVFlare Client API environment.
input_model = flare.receive() # 2. Receives model from NVFlare side.
params = input_model.params # 3. Obtain the required information from received FLModel

# original local training code begins
new_params = local_train(params)
# original local training code ends

output_model = flare.FLModel(params=new_params) # 4. Put the results in a new FLModel
flare.send(output_model) # 5. Sends the model to NVFlare side.

With 5 lines of code changes, we convert the centralized training code to a federated learning setting.

Defining and Running the FL Job

After modifying your training script with the Client API, you need to create a job.py file to define how the job runs:

# job.py - Define and run the FL job
from nvflare.app_common.np.recipes.fedavg import NumpyFedAvgRecipe
from nvflare.recipe import SimEnv

recipe = NumpyFedAvgRecipe(
    name="my-fl-job",
    min_clients=2,
    num_rounds=3,
    # Model can be class instance, array, or dict config
    # For pre-trained weights: initial_ckpt="/server/path/to/model.npy"
    model=[[1, 2, 3], [4, 5, 6]],
    train_script="client.py",  # Points to your Client API script
)

env = SimEnv(num_clients=2)
run = recipe.execute(env)

Then run your federated learning job:

python job.py

That’s it! Your training script (with Client API) and job definition work together to run federated learning.

See the Learn More section at the bottom for detailed guides and resources.

Client API Reference

Below is a table overview of key Client APIs.

Client API
API	Description	API Doc Link
init	Initializes NVFlare Client API environment.	`init`
receive	Receives model from NVFlare side.	`receive`
send	Sends the model to NVFlare side.	`send`
system_info	Gets NVFlare system information.	`system_info`
get_job_id	Gets job id.	`get_job_id`
get_site_name	Gets site name.	`get_site_name`
is_running	Returns whether the NVFlare system is up and running.	`is_running`
is_train	Returns whether the current task is a training task.	`is_train`
is_evaluate	Returns whether the current task is an evaluation task.	`is_evaluate`
is_submit_model	Returns whether the current task is a submit_model task.	`is_submit_model`

Lightning APIs
API	Description	API Doc Link
patch	Patches the PyTorch Lightning Trainer for usage with FLARE.	`patch`

Metrics Logger
API	Description	API Doc Link
SummaryWriter	SummaryWriter mimics the usage of Tensorboard’s SummaryWriter.	`SummaryWriter`
WandBWriter	WandBWriter mimics the usage of weights and biases.	`WandBWriter`
MLflowWriter	MLflowWriter mimics the usage of MLflow.	`MLflowWriter`

Working Examples

For complete working examples across different frameworks:

PyTorch: hello-pt
NumPy: hello-numpy
PyTorch Lightning: hello-lightning
TensorFlow: hello-tf

Each example shows both the Client API training script (client.py) and Job Recipe definition (job.py).

Learn More

NVFlare Job Recipe - How to define and run FL jobs with your training script
Client API - Programming Guide with detailed examples and technical details
nvflare.client.api - Complete API reference documentation
nvflare.app_opt.lightning.api - PyTorch Lightning integration