nvflare.fuel.flare_api.api_spec module

exception AuthenticationError

Bases: Exception

exception AuthorizationError

Bases: Exception

class ClientInfo(name: str, last_connect_time)

Bases: object

exception ClientsStillRunning

Bases: Exception

exception InternalError

Bases: Exception

exception InvalidArgumentError

Bases: Exception

exception InvalidJobDefinition

Bases: Exception

exception InvalidTarget

Bases: Exception

class JobInfo(job_id: str, app_name: str)

Bases: object

exception JobNotDone

Bases: Exception

exception JobNotFound

Bases: Exception

exception JobNotRunning

Bases: Exception

class MonitorReturnCode(value)

Bases: int, Enum

An enumeration.

ENDED_BY_CB = 2

JOB_FINISHED = 0

TIMEOUT = 1

exception NoClientsAvailable

Bases: Exception

exception NoConnection

Bases: Exception

class ServerInfo(status, start_time)

Bases: object

exception SessionClosed

Bases: Exception

class SessionSpec

Bases: ABC

abstract abort_job(job_id: str)

Abort the specified job

Parameters:

job_id – job to be aborted

Returns: None

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

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

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

Parameters:

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

• options – options of the “cat” command

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

Returns: result of “cat” command

abstract 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

abstract close()

Close the session

Returns:

abstract delete_job(job_id: str)

Delete the specified job completely from the system

Parameters:

job_id – job to be deleted

Returns: None

If the job is being executed, the job will be stopped first. Everything of the job will be deleted from the job store, as well as workspaces on the FL server and clients.

abstract download_job_result(job_id: str) → str

Download result of the job

Parameters:

job_id – 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.

abstract 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.

abstract 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

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

Get job status info of specified FL clients

Parameters:

client_names – 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.

abstract get_connected_client_list() → List[ClientInfo]

Get the list of connected clients

Returns: a list of ClientInfo objects

abstract 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

abstract get_system_info() → SystemInfo

Get general info of the FLARE system

abstract get_working_directory(target: str) → str

Get the working directory of the specified target

Parameters:

target – the target (server of a client name)

Returns: current working directory of the specified target

abstract 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 result

Parameters:

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

• 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

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

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

Parameters:

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

• options – options of the “head” command

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

Returns: result of “head” command

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

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

Parameters:

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

• options – options of the “head” command

Returns: result of “head” command

abstract list_jobs(detailed: bool = False, all: bool = False) → List[dict]

Get the job info from the server

Parameters:

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

• all – True to get jobs submitted by all users (default is to only list jobs submitted by the same user)

Returns: a list of job metadata

abstract list_sp() → dict

List available service providers

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

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

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

Parameters:

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

• options – options of the “ls” command

• path – the optional file path

Returns: result of “ls” command

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

Monitor the job progress until one of the conditions occurs:

• job is done

• timeout

• the status_cb returns False

Parameters:

• job_id – the job to be monitored

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

• poll_interval – how often to poll job status

• cb – if provided, callback to be called after each 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.

abstract 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

abstract reset_errors(job_id: str)

Clear errors for all system targets for the specified job

Parameters:

job_id – ID of the job

Returns: None

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

Restart specified system target(s)

Parameters:

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

• client_names – 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”.

abstract 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 – a positive float number

Returns: None

abstract 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 – ID of the job

• target_type – 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).

abstract 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 – ID of the job

• target_type – 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).

abstract 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

abstract shutdown_system()

Shut down 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 raise.

abstract 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, exception will be raised:

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

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

Parameters:

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

• options – options of the “tail” command

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

Returns: result of “tail” command

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

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

Parameters:

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

• options – options of the “tail” command

Returns: result of “tail” command

abstract unset_timeout()

Unset the session-specific command timeout. Once unset, the FL Admin Server’s default will be used.

Returns: None

class SystemInfo(server_info: ServerInfo, client_info: List[ClientInfo], job_info: List[JobInfo])

Bases: object

class TargetType

Bases: object

ALL = 'all'

CLIENT = 'client'

SERVER = 'server'

job_monitor_cb_signature(session: SessionSpec, job_id: str, job_mea: dict, *args, **kwargs) → bool

Parameters:

• session – the session

• job_id – ID of the job being monitored

• job_mea – meta info of the job

• *args –

• **kwargs –

Returns: