nvflare.fuel.flare_api.flare_api module

class Session(username: str | None = None, startup_path: str | None = None, secure_mode: bool = True, debug: bool = False)

Bases: SessionSpec

Initializes a session with the NVFLARE system.

Parameters:

• username (str) – string of username to log in with

• startup_path (str) – path to the provisioned startup kit, which contains endpoint of the system

• secure_mode (bool) – whether to run in secure mode or not

abort_job(job_id: str)

Abort the specified job.

Parameters:

job_id (str) – job to be aborted

Returns: dict of (status, info)

If the job is already done, no effect; If job is not started yet, it will be cancelled and won’t be scheduled. If the job is being executed, it will be aborted.

cat_target(target: str, options: str | None = None, file: str | None = None) → str

Run the “cat” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “cat” command

• file – the file that the “cat” command will run against

Returns: result of “cat” command

clone_job(job_id: str) → str

Create a new job by cloning a specified job.

Parameters:

job_id – job to be cloned

Returns: ID of the new job

close()

Close the session.

delete_job(job_id: str)

Delete the specified job completely from the system.

Parameters:

job_id (str) – job to be deleted

Returns: None

The job will be deleted from the job store if the job is not currently running.

do_app_command(job_id: str, topic: str, cmd_data) → dict

Ask a running job to execute an app command

Parameters:

• job_id – the ID of the running job

• topic – topic of the command

• cmd_data – the data of the command. Must be JSON serializable.

Returns: result of the app command

If the job is not currently running, an exception will occur. User must make sure that the job is running when calling this method.

download_job_result(job_id: str) → str

Download result of the job.

Parameters:

job_id (str) – ID of the job

Returns: folder path to the location of the job result

If the job size is smaller than the maximum size set on the server, the job will download to the download_dir set in Session through the admin config, and the path to the downloaded result will be returned. If the size of the job is larger than the maximum size, the location to download the job will be returned.

get_active_sp() → dict

Get the current active service provider (SP).

Returns: a dict that describes the current active SP. If no SP is available currently, the ‘name’ attribute of the result is empty.

get_available_apps_to_upload()

Get defined FLARE app folders from the upload folder on the machine the FLARE API is running.

Returns: a list of app folders

get_client_env(client_names=None)

Get running environment values for specified clients. The env includes values of client name, workspace directory, root url of the FL server, and secure mode or not.

These values can be used for 3rd-party system configuration (e.g. CellPipe to connect to the FLARE system).

Parameters:

client_names – clients to get env from. None means all clients.

Returns: list of env info for specified clients.

Raises: InvalidTarget exception, if no clients are connected or an invalid client name is specified

get_client_job_status(client_names: List[str] | None = None) → List[dict]

Get job status info of specified FL clients.

Parameters:

client_names (List[str]) – names of the clients to get status info

Returns: A list of jobs running on the clients. Each job is described by a dict of: id, app name and status. If there are multiple jobs running on one client, the list contains one entry for each job for that client. If no FL clients are connected or the server failed to communicate to them, this method returns None.

get_connected_client_list() → List[ClientInfo]

Get the list of connected clients.

Returns: a list of ClientInfo objects

get_job_meta(job_id: str) → dict

Get the meta info of the specified job.

Parameters:

job_id – ID of the job

Returns: a dict of job metadata

get_system_info()

Get general system information.

Returns: a SystemInfo object

get_working_directory(target: str) → str

Get the working directory of the specified target.

Parameters:

target (str) – the target (server of a client name)

Returns: current working directory of the specified target

grep_target(target: str, options: str | None = None, pattern: str | None = None, file: str | None = None) → str

Run the “grep” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “grep” command

• pattern – the grep pattern

• file – the file that the “grep” command will run against

Returns: result of “grep” command

head_target(target: str, options: str | None = None, file: str | None = None) → str

Run the “head” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “head” command

• file – the file that the “head” command will run against

Returns: result of “head” command

head_target_log(target: str, options: str | None = None) → str

Run the “head log.txt” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “head” command

Returns: result of “head” command

list_jobs(detailed: bool = False, limit: int | None = None, id_prefix: str | None = None, name_prefix: str | None = None, reverse: bool = False) → List[dict]

Get the job info from the server.

Parameters:

• detailed (bool) – True to get the detailed information for each job, False by default

• limit (int, optional) – maximum number of jobs to show, with 0 or None to show all (defaults to None to show all)

• id_prefix (str) – if included, only return jobs with the beginning of the job ID matching the id_prefix

• name_prefix (str) – if included, only return jobs with the beginning of the job name matching the name_prefix

• reverse (bool) – if specified, list jobs in the reverse order of submission times

Returns: a list of job metadata

list_sp() → dict

List available service providers.

Returns: a dict that contains information about the primary SP and others

ls_target(target: str, options: str | None = None, path: str | None = None) → str

Run the “ls” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “ls” command

• path – the optional file path

Returns: result of “ls” command

monitor_job(job_id: str, timeout: float = 0.0, poll_interval: float = 2.0, cb=None, *cb_args, **cb_kwargs) → MonitorReturnCode

Monitor the job progress.

Monitors until one of the conditions occurs:

• job is done

• timeout

• the status_cb returns False

Parameters:

• job_id (str) – the job to be monitored

• timeout (float) – how long to monitor. If 0, never time out.

• poll_interval (float) – how often to poll job status

• cb – if provided, callback to be called after each status poll

Returns: a MonitorReturnCode

Every time the cb is called, it must return a bool indicating whether the monitor should continue. If False, this method ends.

promote_sp(sp_end_point: str)

Promote the specified endpoint to become the active SP.

Parameters:

sp_end_point – the endpoint of the SP. It’s string in this format: <url>:<server_port>:<admin_port>

Returns: None

reset_errors(job_id: str)

Clear errors for all system targets for the specified job.

Parameters:

job_id (str) – ID of the job

Returns: None

restart(target_type: str, client_names: List[str] | None = None) → dict

Restart specified system target(s).

Parameters:

• target_type (str) – what system target (server, client, or all) to restart

• client_names (List[str]) – clients to be restarted if target_type is client. If not specified, all clients.

Returns: a dict that contains detailed info about the restart request:

status - the overall status of the result. server_status - whether the server is restarted successfully - only if target_type is “all” or “server”. client_status - a dict (keyed on client name) that specifies status of each client - only if target_type is “all” or “client”.

set_timeout(value: float)

Set a session-specific command timeout.

This is the amount of time the server will wait for responses after sending commands to FL clients.

Note that this value is only effective for the current API session.

Parameters:

value (float) – a positive float number for the timeout in seconds

Returns: None

show_errors(job_id: str, target_type: str, targets: List[str] | None = None) → dict

Show processing errors of specified job on specified targets.

Parameters:

• job_id (str) – ID of the job

• target_type (str) – type of target (server or client)

• targets – list of client names if target type is “client”. All clients if not specified.

Returns: a dict that contains job errors (if any) on specified targets. The key of the dict is target name. The value is a dict of errors reported by different system components (ServerRunner or ClientRunner).

show_stats(job_id: str, target_type: str, targets: List[str] | None = None) → dict

Show processing stats of specified job on specified targets.

Parameters:

• job_id (str) – ID of the job

• target_type (str) – type of target (server or client)

• targets – list of client names if target type is “client”. All clients if not specified.

Returns: a dict that contains job stats on specified targets. The key of the dict is target name. The value is a dict of stats reported by different system components (ServerRunner or ClientRunner).

shutdown(target_type: TargetType, client_names: List[str] | None = None)

Shut down specified system target(s).

Parameters:

• target_type – what system target (server, client, or all) to shut down

• client_names – clients to be shut down if target_type is client. If not specified, all clients.

Returns: None

shutdown_system()

Shutdown the whole NVFLARE system including the overseer, FL server(s), and all FL clients.

Returns: None

Note: the user must be a Project Admin to use this method; otherwise the NOT_AUTHORIZED exception will be raised.

submit_job(job_definition_path: str) → str

Submit a predefined job to the NVFLARE system.

Parameters:

job_definition_path – path to the folder that defines a NVFLARE job

Returns: the job id if accepted by the system

If the submission fails, an exception will be raised.

tail_target(target: str, options: str | None = None, file: str | None = None) → str

Run the “tail” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “tail” command

• file – the file that the “tail” command will run against

Returns: result of “tail” command

tail_target_log(target: str, options: str | None = None) → str

Run the “tail log.txt” command on the specified target and return the result.

Parameters:

• target – the target (server or a client name) the command will be run on

• options – options of the “tail” command

Returns: result of “tail” command

try_connect(timeout)

unset_timeout()

Unset the session-specific command timeout.

Once unset, the FL Admin Server’s default timeout will be used.

Returns: None

basic_cb_with_print(session: Session, job_id: str, job_meta, *cb_args, **cb_kwargs) → bool

This is a sample callback to use with monitor_job.

This demonstrates how a custom callback can be used.

new_insecure_session(startup_kit_location: str, debug: bool = False, timeout: float = 10.0) → Session

Create a new insecure FLARE API session with the NVFLARE system.

Parameters:

• startup_kit_location (str) – path to the provisioned startup folder

• debug (bool) – enable debug mode

• timeout (float) – how long to try to establish the session, in seconds

Returns: a Session object

The username for insecure session is always “admin”.

new_secure_session(username: str, startup_kit_location: str, debug: bool = False, timeout: float = 10.0) → Session

Create a new secure FLARE API session with the NVFLARE system.

Parameters:

• username (str) – username assigned to the user

• startup_kit_location (str) – path to the provisioned startup folder, the root admin dir containing the startup folder

• debug (bool) – enable debug mode

• timeout (float) – how long to try to establish the session, in seconds

Returns: a Session object