nvflare.job_config.api module

class ClientApp

Bases: FedApp

Wrapper around ClientAppConfig.

add_executor(executor: Executor, tasks=None)

class FedApp(app_config: ClientAppConfig | ServerAppConfig)

Bases: object

FedApp handles ClientAppConfig and ServerAppConfig and allows setting task result or task data filters.

add_component(component, comp_id=None)

add_external_dir(ext_dir: str)

Register external folder to include them in custom directory.

Parameters:

ext_dir – external folder that need to be deployed to the client/server.

add_external_script(ext_script: str)

Register external script to include them in custom directory.

Parameters:

ext_script – List of external scripts that need to be deployed to the client/server.

add_file_source(src_path: str, dest_dir=None, app_folder_type=None)

add_params(args: Dict[str, any])

Add additional system configuration parameters to be included in the generated JSON configs.

Parameters:

args – Dictionary of system configuration parameters (e.g., {“timeout”: 600, “max_retries”: 3})

add_resources(resources: List[str])

Add resources to the job. To be used by job component programmer.

Parameters:

resources

Returns:

add_task_data_filter(tasks: List[str], task_filter: Filter)

add_task_result_filter(tasks: List[str], task_filter: Filter)

generate_tracked_id(id: str = '') → str

get_app_config()

class FedJob(name: str = 'fed_job', min_clients: int = 1, mandatory_clients: List[str] | None = None, meta_props: Dict[str, Any] | None = None)

Bases: object

FedJob allows users to generate job configurations in a Pythonic way. The to() routine allows users to send different components to either the server or clients.

Parameters:

• name – the name of the NVFlare job

• min_clients – the minimum number of clients for the job

• mandatory_clients – mandatory clients to run the job (optional)

add_component(comp_id: str, obj: Any, ctx: JobCtx)

Add a component to the job. To be used by job component programmer.

Parameters:

• comp_id – component id

• obj – component to be added to job.

• ctx – JobCtx for contextual information.

Returns:

final id assigned to component.

add_controller(obj: Controller, ctx: JobCtx)

Add a Controller object to the job. To be used by controller programmer.

Parameters:

• obj – Controller to be added to job.

• ctx – JobCtx for contextual information.

Returns:

add_executor(obj: Executor, tasks: List[str], ctx: JobCtx)

Add an executor to the job. To be used by executor programmer.

Parameters:

• obj – Executor to be added to job.

• tasks – List of tasks that should be handled. If None, all tasks will be handled using [*].

• ctx – JobCtx for contextual information.

Returns:

add_file_source(src_path: str, dest_dir, app_folder_type, ctx: JobCtx)

Add a file source to the job. To be used by job component programmer.

Parameters:

• src_path – path to the source to be added to job.

• dest_dir – destination path for the source

• app_folder_type – type of app folder to place the files

• ctx – JobCtx for contextual information.

Returns:

add_file_to(src_path: str, target: str, dest_dir=None, app_folder_type=None)

Add a file to a specific target’s app directory.

Parameters:

• src_path – Local path to the file to be bundled into the job.

• target – Target site name (e.g., “server”, “site-1”, or ALL_SITES for all clients).

• dest_dir – Optional subdirectory within the target folder to place the file.

• app_folder_type – Type of app folder to place the file. Valid values: “custom”, “config”. If not specified, defaults to “custom”.

add_file_to_clients(src_path: str, dest_dir=None, app_folder_type=None)

Add a file to all client apps’ directory.

Parameters:

• src_path – Local path to the file to be bundled into the job.

• dest_dir – Optional subdirectory within the target folder to place the file.

• app_folder_type – Type of app folder to place the file. Valid values: “custom”, “config”. If not specified, defaults to “custom”.

add_file_to_server(src_path: str, dest_dir=None, app_folder_type=None)

Add a file to the server app directory.

Parameters:

• src_path – Local path to the file to be bundled into the job.

• dest_dir – Optional subdirectory within the target folder to place the file.

• app_folder_type – Type of app folder to place the file. Valid values: “custom”, “config”. If not specified, defaults to “custom”.

add_filter(obj: Filter, filter_type: str, tasks, ctx: JobCtx)

Add a filter to the job. To be used by filter programmer.

Parameters:

• obj – Filter to be added to job.

• filter_type – The type of filter used. Either FilterType.TASK_RESULT or FilterType.TASK_DATA.

• tasks – List of tasks that Filter applies to.

• ctx – JobCtx for contextual information.

Returns:

add_params(args: Dict[str, any], ctx: JobCtx)

Add additional system configuration parameters to the job. To be used by job component programmer.

Parameters:

• args – Dictionary of configuration parameters (e.g., {“timeout”: 600, “max_retries”: 3})

• ctx – JobCtx for contextual information.

Returns:

add_resources(resources: List[str], ctx: JobCtx)

Add resources to the job. To be used by job component programmer.

Parameters:

• resources – List of filenames or directories to be added to job.

• ctx – JobCtx for contextual information.

Returns:

as_id(obj: Any) → str

Generate and return uuid for obj. For end users. If this id is referenced by another added object, this obj will also be added as a component.

static check_kwargs(args_to_check: dict, args_expected: dict)

Check kwargs for arguments. Raise Error if required arg is missing, or unexpected arg is given.

Parameters:

• args_to_check (dict) – kwargs dictionary to check.

• args_expected (dict) – dictionary of argument name to boolean of whether argument is required (True) or optional (False).

export_job(job_root: str)

Export job config to job_root directory with name self.name. For end users.

Parameters:

job_root – directory to export job configuration.

Returns:

set_app_packages(app_packages: List[str])

Set app packages. When generating job config, code from these packages will not be included into “custom” folder.

Parameters:

app_packages – app packages to be set

Returns: None

set_up_client(target: str)

Setup routine called by FedJob when first sending object to a client target.

Parameters:

target – the target to perform setup.

Returns:

simulator_run(workspace: str, n_clients: int | None = None, clients: List[str] | None = None, threads: int | None = None, gpu: str | None = None, log_config: str | None = None)

Run the job with the simulator with the workspace using clients and threads. For end users.

Parameters:

• workspace – workspace directory for job.

• n_clients – number of clients.

• clients – client names.

• threads – number of threads.

• gpu – gpu assignments for simulating clients, comma separated

• log_config – log config mode (‘concise’, ‘msg_only’, ‘full’, ‘verbose’), filepath, or level

Returns:

to(obj: Any, target: str, id=None, **kwargs) → Any

Assign an object to the target. For end users.

Parameters:

• obj – the object to be assigned

• target – the target that the object is assigned to

• id – the id of the object

• **kwargs – additional args to be passed to the object’s add_to_fed_job method.

If the obj provides the add_to_fed_job method, it will be called with the kwargs. This method must follow this signature:

add_to_fed_job(job, ctx, …)

job: this is the job (self) ctx: this is the JobCtx that keeps contextual info of this call.

The add_to_fed_job function is usually implemented in FL component classes. When implementing this function, you should not use anything in the ctx; instead, you should use the “add_xxx” methods of the “job” object: add_component, add_resources, add_filter, add_executor, etc.

Returns:

result of add_to_job_method if called, or id of added component

to_clients(obj: Any, id=None, **kwargs)

assign an object to all clients. For end users.

Parameters:

• obj (Any) – Object to be deployed.

• id – Optional user-defined id for the object. Defaults to None and ID will automatically be assigned.

• **kwargs – additional args to be passed to the object’s add_to_fed_job method.

Returns:

result of add_to_job_method if called, or id of added component

to_server(obj: Any, id=None, **kwargs)

assign an object to the server. For end users.

Parameters:

• obj – The object to be assigned. The obj will be given a default id if none is provided based on its type.

• id – Optional user-defined id for the object. Defaults to None and ID will automatically be assigned.

• **kwargs – additional args to be passed to the object’s add_to_fed_job method.

Returns:

result of add_to_job_method if called, or id of added component

class JobCtx(obj: Any, target: str, comp_id: str)

Bases: object

class ServerApp

Bases: FedApp

Wrapper around ServerAppConfig.

FedApp handles ClientAppConfig and ServerAppConfig and allows setting task result or task data filters.

add_controller(controller: Controller, id=None)

has_add_to_job_method(obj: Any) → bool

validate_object_for_job(name, obj, obj_type)

Check whether the specified object is valid for job. The object must either have the add_to_fed_job method or is valid object type.

Parameters:

• name – name of the object

• obj – the object to be checked

• obj_type – the object type that the object should be, if it doesn’t have the add_to_fed_job method.

Returns: None