flip.nvflare.components

FLIP Components module containing reusable FL components.

Components include event handlers, model locators, JSON generators, and persistence utilities.

Exports:

• ClientEventHandler: Client-side event handler

• ServerEventHandler: Server-side event handler

• PTModelLocator: PyTorch model locator

• InitialPTModelLocator: PyTorch model locator for initial models with safehouse fallback

• EvaluationPTModelLocator: PyTorch model locator for evaluation workflows

• ValidationJsonGenerator: Validation results JSON generator

• EvaluationJsonGenerator: Evaluation results JSON generator

• PersistToS3AndCleanup: S3 persistence and cleanup component

• PercentilePrivacy: Percentile-based privacy filter

• StagePercentilePrivacy: Stage-aware percentile-based privacy filter

• CleanupImages: Image cleanup executor

Submodules

• flip.nvflare.components.cleanup
• flip.nvflare.components.custom_percentile_privacy
• flip.nvflare.components.evaluation_json_generator
• flip.nvflare.components.flip_client_event_handler
• flip.nvflare.components.flip_server_event_handler
• flip.nvflare.components.persist_and_cleanup
• flip.nvflare.components.pt_model_locator
• flip.nvflare.components.stage_percentile_privacy
• flip.nvflare.components.validation_json_generator

Classes

CleanupImages	CleanupImages takes place at the start and end of the run.
PercentilePrivacy	Implementation of "largest percentile to share" privacy preserving policy.
EvaluationJsonGenerator	Handles EVALUATION_RESULT_RECEIVED event and generates a results.json containing accuracy of each
ClientEventHandler	ClientEventHandler is a generic component that handles system events triggered by nvflare
ServerEventHandler	ServerEventHandler is a generic component that handles system events triggered by nvflare
PersistToS3AndCleanup	The component that is executed post training and is a part of the FLIP training model
EvaluationPTModelLocator
InitialPTModelLocator
PTModelLocator
StagePercentilePrivacy	Implementation of "largest percentile to share" privacy preserving policy.
ValidationJsonGenerator	Handles VALIDATION_RESULT_RECEIVED event and generates a results.json containing accuracy of each

Package Contents

class flip.nvflare.components.CleanupImages

Bases: nvflare.apis.executor.Executor

CleanupImages takes place at the start and end of the run. All the images used for the training are deleted to prevent the build-up of unnecessary files on the storage space. Executing at the start of a run ensures that any training code is executed with a clean slate.

Args:

Raises:

execute(task_name: str, shareable: nvflare.apis.shareable.Shareable, fl_ctx: nvflare.apis.fl_context.FLContext, abort_signal: nvflare.apis.signal.Signal)

class flip.nvflare.components.PercentilePrivacy(percentile=10, gamma=0.01, data_kinds: List[str] | None = None, off: bool = False)

Bases: nvflare.apis.dxo_filter.DXOFilter

Implementation of “largest percentile to share” privacy preserving policy.

Shokri and Shmatikov, Privacy-preserving deep learning, CCS ‘15

Parameters:

• percentile (int, optional) – Only abs diff greater than this percentile is updated. Allowed range 0..100. Defaults to 10.

• gamma (float, optional) – The upper limit to truncate abs values of weight diff. Defaults to 0.01.

• 0. (Any weight diff with abs<gamma will become)

• data_kinds – kinds of DXO to filter

• off (bool, optional) – If True, the filter is turned off. Defaults to False.

percentile = 10

gamma = 0.01

off = False

process_dxo(dxo: nvflare.apis.dxo.DXO, shareable: nvflare.apis.shareable.Shareable, fl_ctx: nvflare.apis.fl_context.FLContext) → None | nvflare.apis.dxo.DXO

Compute the percentile on the abs delta_W.

Only share the params where absolute delta_W greater than the percentile value

Parameters:

• dxo – information from client

• shareable – that the dxo belongs to

• fl_ctx – context provided by workflow

Returns: filtered dxo

class flip.nvflare.components.EvaluationJsonGenerator(results_dir=PTConstants.EvalDir, json_file_name=PTConstants.EvalResultsFilename)

Bases: nvflare.apis.fl_component.FLComponent

Handles EVALUATION_RESULT_RECEIVED event and generates a results.json containing accuracy of each validated model.

Parameters:

• results_dir (str, optional) – Name of the results directory. Defaults to cross_site_eval

• json_file_name (str, optional) – Name of the json file. Defaults to evaluation_results.json

handle_evaluation_events(event_type: str, fl_ctx: nvflare.apis.fl_context.FLContext)

class flip.nvflare.components.ClientEventHandler

Bases: nvflare.apis.fl_component.FLComponent

ClientEventHandler is a generic component that handles system events triggered by nvflare or custom flip events. It executes logic inside its own event handler but may also call other component’s event handlers directly to help overcome the non-deterministic order in which nvflare handles events.

Args:

Raises:

handle_event(event_type: str, fl_ctx: nvflare.apis.fl_context.FLContext)

class flip.nvflare.components.ServerEventHandler(model_id: str = '', validation_json_generator_id: str = 'json_generator', persist_and_cleanup_id: str = 'persist_and_cleanup', flip: flip.FLIP = FLIP())

Bases: nvflare.apis.fl_component.FLComponent

ServerEventHandler is a generic component that handles system events triggered by nvflare or custom flip events. It executes logic inside its own event handler but may also call other component’s event handlers directly to overcome the non-deterministic order in which nvflare handles events i.e handling ValidationJsonGenerator component events.

Parameters:

• model_id (string, not required)

• validation_json_generator_id (string, not required)

• persist_and_cleanup_id (string, not required)

• flip (object, not required)

Raises:

ValueError – when model ID is not a valid UUID

model_id = ''

validation_json_generator_id = 'json_generator'

validation_json_generator = None

persist_and_cleanup_id = 'persist_and_cleanup'

persist_and_cleanup = None

flip

fatal_error = False

final_status = None

handle_event(event_type: str, fl_ctx: nvflare.apis.fl_context.FLContext)

class flip.nvflare.components.PersistToS3AndCleanup(model_id: str, persistor_id: str = AppConstants.DEFAULT_PERSISTOR_ID, flip: flip.FLIP = FLIP())

Bases: nvflare.apis.fl_component.FLComponent

The component that is executed post training and is a part of the FLIP training model

The PersistToS3AndCleanup workflow saves the aggregated model (once training has finished) to an S3 bucket, and then deletes files created as part of the run

Parameters:

• model_id (str) – ID of the model that the training is being performed under.

• persistor_id (str, optional) – ID of the persistor component. Defaults to “persistor”.

Raises:

ValueError –

• when the model ID is not a valid UUID.

FileNotFoundError: boto3 error for when the zip file does not exist.

model_id

persistor_id: str

model_persistor: nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor | None = None

model_inventory: dict

model_dir: str = ''

bucket_name: str = ''

flip

execute(fl_ctx: nvflare.apis.fl_context.FLContext)

upload_results_to_s3_bucket(fl_ctx: nvflare.apis.fl_context.FLContext)

Uploads the final aggregated model and reports to an S3 bucket as a zip file.

cleanup(fl_ctx: nvflare.apis.fl_context.FLContext)

Cleans up the workspace by deleting the transfer and save directories for the model ID.

class flip.nvflare.components.EvaluationPTModelLocator(exclude_vars=None)

Bases: nvflare.app_common.abstract.model_locator.ModelLocator

models = None

exclude_vars = None

locate_model(fl_ctx: nvflare.apis.fl_context.FLContext) → nvflare.apis.dxo.DXO | None

class flip.nvflare.components.InitialPTModelLocator(exclude_vars=None, model=None)

Bases: nvflare.app_common.abstract.model_locator.ModelLocator

model = None

exclude_vars = None

get_model_names(fl_ctx: nvflare.apis.fl_context.FLContext) → List[str]

locate_model(model_name, fl_ctx: nvflare.apis.fl_context.FLContext) → nvflare.apis.dxo.DXO | None

class flip.nvflare.components.PTModelLocator(exclude_vars=None, model=None)

Bases: nvflare.app_common.abstract.model_locator.ModelLocator

model = None

exclude_vars = None

get_model_names(fl_ctx: nvflare.apis.fl_context.FLContext) → List[str]

locate_model(model_name, fl_ctx: nvflare.apis.fl_context.FLContext) → nvflare.apis.dxo.DXO | None

class flip.nvflare.components.StagePercentilePrivacy(percentile=10, gamma=0.01, data_kinds: List[str] = None, off: bool = False)

Bases: nvflare.apis.dxo_filter.DXOFilter

Implementation of “largest percentile to share” privacy preserving policy.

Shokri and Shmatikov, Privacy-preserving deep learning, CCS ‘15

Parameters:

• percentile (int, optional) – Only abs diff greater than this percentile is updated. Allowed range 0..100. Defaults to 10.

• gamma (float, optional) – The upper limit to truncate abs values of weight diff. Defaults to 0.01.

• 0. (Any weight diff with abs<gamma will become)

• data_kinds – kinds of DXO to filter

• off (bool, optional) – If True, the filter is turned off. Defaults to False.

percentile = 10

gamma = 0.01

off = False

process_dxo(dxo: nvflare.apis.dxo.DXO, shareable: nvflare.apis.shareable.Shareable, fl_ctx: nvflare.apis.fl_context.FLContext) → None | nvflare.apis.dxo.DXO

Compute the percentile on the abs delta_W.

Only share the params where absolute delta_W greater than the percentile value

Parameters:

• dxo – information from client

• shareable – that the dxo belongs to

• fl_ctx – context provided by workflow

Returns: filtered dxo

class flip.nvflare.components.ValidationJsonGenerator(results_dir=AppConstants.CROSS_VAL_DIR, json_file_name=PTConstants.CrossValResultsJsonFilename)

Bases: nvflare.apis.fl_component.FLComponent

Handles VALIDATION_RESULT_RECEIVED event and generates a results.json containing accuracy of each validated model.

Parameters:

• results_dir (str, optional) – Name of the results directory. Defaults to cross_site_val

• json_file_name (str, optional) – Name of the json file. Defaults to cross_val_results.json

handle_evaluation_events(event_type: str, fl_ctx: nvflare.apis.fl_context.FLContext)