nvflare.fuel.flare_api.api_spec module

exception AuthenticationError(message='', auth_code=None)[source]

Bases: Exception

exception AuthorizationError[source]

Bases: Exception

class ClientInfo(name: str, last_connect_time)[source]

Bases: object

exception ClientsStillRunning[source]

Bases: Exception

exception CommandError(error_code: str, message: str = '', hint: str = '', exit_code: int = 1)[source]

Bases: Exception

exception InternalError[source]

Bases: Exception

exception InvalidArgumentError[source]

Bases: Exception

exception InvalidJobDefinition[source]

Bases: Exception

exception InvalidTarget[source]

Bases: Exception

class JobInfo(job_id: str, app_name: str)[source]

Bases: object

exception JobNotDone[source]

Bases: Exception

exception JobNotFound[source]

Bases: Exception

exception JobNotRunning[source]

Bases: Exception

exception JobTimeout[source]

Bases: Exception

class MonitorReturnCode(value)[source]

Bases: int, Enum

An enumeration.

ENDED_BY_CB = 2
JOB_FINISHED = 0
TIMEOUT = 1
exception NoClientsAvailable[source]

Bases: Exception

exception NoConnection[source]

Bases: ConnectionError

exception NoReply[source]

Bases: Exception

class ServerInfo(status, start_time)[source]

Bases: object

exception SessionClosed[source]

Bases: Exception

class SessionSpec[source]

Bases: ABC

abstract abort_job(job_id: str)[source]

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 add_study_site(study: str, sites: List[str] | None = None, site_orgs: List[str] | None = None) → dict[source]

Add sites to an existing study.

Exactly one of sites or site_orgs must be provided; passing both raises InvalidArgumentError.

Parameters:

  • study – study name

  • sites – flat site list for org_admin callers; mutually exclusive with site_orgs

  • site_orgs – repeatable “org:s1,s2,…” groups for project_admin callers; mutually exclusive with sites

Returns: study payload dict with added/already_enrolled lists

abstract add_study_user(study: str, user: str) → dict[source]

Add a user to the study admins list.

Parameters:

  • study – study name

  • user – user name to add

Returns: study payload dict

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

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 check_status(target_type: str, targets=None) → dict[source]

Report status for the server and/or clients.

Parameters:

  • target_type – server, client, or all

  • targets – optional client names when target_type is client

Returns: status information keyed by site name.

abstract clone_job(job_id: str) → str[source]

Create a new job by cloning a specified job

Parameters:

job_id – job to be cloned

Returns: ID of the new job

abstract close()[source]

Close the session

Returns:

abstract configure_job_log(job_id: str, config, target: str = 'all') → None[source]

Configure logging for a running job.

Parameters:

  • job_id – ID of the running job

  • config – log level, log mode, file path, or dictConfig payload

  • target – all, server, or a client site name

Returns: None

abstract configure_site_log(config, target: str = 'all') → None[source]

Configure site-level logging.

Parameters:

  • config – log level or built-in log mode

  • target – all, server, or a client site name

Returns: None

abstract delete_job(job_id: str)[source]

Delete the specified job completely from the system

Parameters:

job_id – job to be deleted

Returns: delete result metadata, including the number of submit-token records marked deleted.

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 disable_client(client_name: str) → dict[source]

Disable a client from reconnecting to the system.

Parameters:

client_name – name of the client to disable

Returns: command result dictionary

abstract download_job_components(job_id: str) → str[source]

Download additional job components (e.g., ERRORLOG_site-1) for a specified job.

Parameters:

job_id (str) – ID of the job

Returns: folder path to the location of the downloaded additional job components

abstract download_job_result(job_id: str, destination: str | None = None) → str[source]

Download result of the job

Parameters:

  • job_id – ID of the job

  • destination – optional directory to move the downloaded result into.

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 enable_client(client_name: str) → dict[source]

Enable a disabled client to reconnect to the system.

Parameters:

client_name – name of the client to enable

Returns: command result dictionary

abstract get_available_apps_to_upload()[source]

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][source]

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][source]

Get the list of connected clients

Returns: a list of ClientInfo objects

abstract get_job_logs(job_id: str, target: str = 'server', tail_lines: int | None = None, grep_pattern: str | None = None, log_file_name: str = 'log.txt') → dict[source]

Retrieve logs for the specified job.

Parameters:

  • job_id – ID of the job

  • target – server, all, or a client site name

  • tail_lines – deprecated compatibility option to return the last N lines

  • grep_pattern – deprecated compatibility option to return matching lines

  • log_file_name – internal log file selector. Defaults to log.txt.

Returns: dict with logs mapping site names to log content, and

optional unavailable mapping site names to reasons.

abstract get_job_meta(job_id: str) → dict[source]

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[source]

Get general info of the FLARE system

abstract get_working_directory(target: str) → str[source]

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[source]

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[source]

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[source]

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_job_components(job_id: str) → List[str][source]

Get the list of additional job components for the specified job.

Parameters:

job_id (str) – ID of the job

Returns: a list of the additional job components

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

Get the job info from the server

Parameters:

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

  • limit – maximum number of jobs to show, with 0 or None to show all

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

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

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

  • submit_token – optional retry-safe submit token to resolve the submitted job

  • **kwargs – deprecated legacy aliases accepted for compatibility

Returns: a list of job metadata

abstract list_studies() → dict[source]

List studies visible to the caller.

Returns: dict with studies list

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

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

monitor_job(job_id: str, timeout: int = 0, poll_interval: float = 2.0, cb=None, *cb_args, **cb_kwargs) → MonitorReturnCode[source]
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: MonitorReturnCode

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

abstract monitor_job_and_return_job_meta(job_id: str, timeout: float = 0.0, poll_interval: float = 2.0, cb=None, *cb_args, **cb_kwargs) -> (<enum 'MonitorReturnCode'>, typing.Optional[dict])[source]
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 tuple of (MonitorReturnCode, job meta)

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

abstract register_study(study: str, sites: List[str] | None = None, site_orgs: List[str] | None = None) → dict[source]

Create or merge a study in the server registry.

Exactly one of sites or site_orgs must be provided; passing both raises InvalidArgumentError. Use sites for org_admin callers (own-org sites only) and site_orgs for project_admin callers (cross-org enrollment).

Parameters:

  • study – study name

  • sites – flat site list for org_admin callers; mutually exclusive with site_orgs

  • site_orgs – repeatable “org:s1,s2,…” groups for project_admin callers; mutually exclusive with sites

Returns: study payload dict

abstract remove_client(client_name: str) → None[source]

Release a connected client’s active token.

Parameters:

client_name – name of the client whose active token should be released

Returns: None

Note

This does not stop the client, revoke credentials, or prevent reconnect. Use disable_client to prevent a client from reconnecting.

abstract remove_study(study: str) → dict[source]

Remove a study and all its registry entries.

Parameters:

study – study name

Returns: study payload dict

abstract remove_study_site(study: str, sites: List[str] | None = None, site_orgs: List[str] | None = None) → dict[source]

Remove sites from an existing study.

Exactly one of sites or site_orgs must be provided; passing both raises InvalidArgumentError.

Parameters:

  • study – study name

  • sites – flat site list for org_admin callers; mutually exclusive with site_orgs

  • site_orgs – repeatable “org:s1,s2,…” groups for project_admin callers; mutually exclusive with sites

Returns: study payload dict with removed/not_enrolled lists

abstract remove_study_user(study: str, user: str) → dict[source]

Remove a user from the study admins list.

Parameters:

  • study – study name

  • user – user name to remove

Returns: study payload dict

abstract report_resources(target_type: str, targets=None) → dict[source]

Report resource information for the server and/or clients.

Parameters:

  • target_type – server, client, or all

  • targets – optional client names when target_type is client

Returns: resource information keyed by site name.

abstract report_version(target_type: str, targets: List[str] | None = None) → dict[source]

Report NVFlare version for specified system target(s).

Parameters:

  • target_type – type of target (server, client, or all)

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

Returns: a dict with version information per site

abstract reset_errors(job_id: str)[source]

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, wait: bool = True, timeout: float = 30.0) → dict[source]

Restart the FL server.

Parameters:

  • target_type – must be server

  • client_names – unused; retained for signature compatibility

  • wait – whether to wait for the restart to complete before returning

  • timeout – maximum seconds to wait for completion

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.

abstract set_timeout(value: float)[source]

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[source]

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[source]

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 show_study(study: str) → dict[source]

Show details for a single study.

Parameters:

study – study name

Returns: study payload dict

abstract shutdown(target_type: TargetType, client_names: List[str] | None = None, wait: bool = True, timeout: float = 30.0) → dict[source]

Shut down the FL server.

Parameters:

  • target_type – must be server

  • client_names – unused; retained for signature compatibility

  • wait – whether to wait for shutdown completion before returning

  • timeout – maximum seconds to wait for completion

Returns: a dict that contains detailed info about the shutdown request.

abstract shutdown_system()[source]

Shut down the whole NVFLARE system including the FL server 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, submit_token: str | None = None) → str[source]

Submit a predefined job to the NVFLARE system

Parameters:

  • job_definition_path – path to the folder that defines a NVFLARE job

  • submit_token – optional retry-safe submit token scoped by study and submitter

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[source]

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[source]

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()[source]

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

Returns: None

abstract wait_for_job(job_id: str, timeout: float = 0.0, poll_interval: float = 2.0) → dict[source]

Wait until the specified job reaches a terminal state.

Parameters:

  • job_id – ID of the job

  • timeout – maximum seconds to wait, or 0 to wait indefinitely

  • poll_interval – seconds between status polls

Returns: terminal job metadata/status information.

exception SubmitTokenConflict(message: str, existing_job_id: str | None = None)[source]

Bases: Exception

exception SubmitTokenJobDeleted(message: str, job_id: str | None = None, state: str | None = None, deleted_time: str | None = None)[source]

Bases: Exception

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

Bases: object

class TargetType[source]

Bases: object

ALL = 'all'
CLIENT = 'client'
SERVER = 'server'
job_monitor_cb_signature(session: SessionSpec, job_id: str, job_meta: dict, *args, **kwargs) → bool[source]
Parameters:

  • session – the session

  • job_id – ID of the job being monitored

  • job_meta – meta info of the job

  • *args

  • **kwargs

Returns: