FLARE API¶

FLARE API is the FLAdminAPI redesigned for a better user experience in version 2.3. It is a wrapper for admin commands that can be issued to the FL server like the FLAdminAPI, and you can use a provisioned admin client’s certs and keys to initialize a Session to use the commands of the API.

Initialization and Usage¶

Initialize the FLARE API with new_secure_session by providing the username and the path to the startup kit folder of the provisioned user containing the startup folder with the admin client’s certs and keys:

from nvflare.fuel.flare_api.flare_api import new_secure_session

sess = new_secure_session(
    "super@nvidia.com",
    "/workspace/example_project/prod_00/super@nvidia.com"
)

Logging in is automatically handled, and commands can be executed with the session object returned (sess in the preceding code block).

Using the FLARE API should be similar to the previous FLAdminAPI but simpler. The return structure is no longer an object with a status and a dictionary of details, but can be a string or even nothing depending on the command. Instead of having a status with an error, FLARE API now will raise an exception, and the handling of these exceptions will be the responsibility of the code using the FLARE API.

There should now be no need to have wrappers around the commands since what is being returned is much simpler, for example, submit_job now returns the job id as a string if the job is accepted by the system. See the details of what each command returns in the docstrings at: FLARE API.

Implementation Notes¶

Like with FLAdminAPI previously, AdminAPI is used to connect and submit commands to the server.

There is no more logout(), instead, use close() to end the session. One common pattern of usage may be to have the code using the session to execute commands inside a try block and then close the session in a finally clause:

.. code-block:: python

try:
print(sess.get_system_info()) job_id = sess.submit_job(“/workspace/locataion_of_jobs/job1”) print(job_id + “ was submitted”) # monitor_job() waits until the job is done, see the section about it below for details sess.monitor_job(job_id) print(“job done!”)

finally:
sess.close()

Note

The session monitor may take a bit of time to close when close() is called.

Additional and Complex Commands¶

With a job_id for example after submit_job in the code block above, here are some examples of other commands that can be run:

.. code-block:: python

# get job meta dictionary with job info job_meta_dict = sess.get_job_meta(job_id)

# submit a copy of an existing job with clone_job new_job_id = sess.clone_job(job_id) print(new_job_id + “ was submitted as a clone of “ + job_id)

Monitor Job¶

By default, like in the most basic usage above in Implementation Notes, monitor_job() waits until the job specified as the first argument is finished, but it can be used in more custom ways by providing additional args including your own callback with custom code to be called after each status poll. The following is the API spec for monitor_job:

def monitor_job(
    self, 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

    Args:
        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.

    """

Only the first argument is required, but with additional args, you can customize monitor_job() to do almost anything you want to do. The following is an example where you can see the usage of a sample_cb and cb_kwargs. This callback always returns True, keeping the default behavior of monitor_job() of waiting until the job specified as the first argument is finished, but you can customize this to behave as you want.

def sample_cb(
    session: Session, job_id: str, job_meta, *cb_args, **cb_kwargs
) -> bool:
    if job_meta["status"] == "RUNNING":
        if cb_kwargs["cb_run_counter"]["count"] < 3:
            print(job_meta)
            print(cb_kwargs["cb_run_counter"])
        else:
            print(".", end="")
    else:
        print("\n" + str(job_meta))

    cb_kwargs["cb_run_counter"]["count"] += 1
    return True

# Calling monitor_job with the sample_cb above and a cb_kwarg
sess.monitor_job(job_id, cb=sample_cb, cb_run_counter={"count":0})