Using the API Client

The Scaleout Edge API Client is the primary programmatic interface for interacting with the Control Plane.

While the UI is excellent for monitoring, the API Client allows you to automate your MLOps workflows, integrate with CI/CD pipelines, and build custom dashboards.

Installation

The client is available as a standard Python package.

$ pip install scaleout

Connecting to the Control Plane

To initialize the connection to the Scaleout Edge Control Plane, we need to create an instance of the Scaleout class. This requires the host URL of the control plane and an admin access token for authentication:

>>> from scaleout import Scaleout
>>> client = Scaleout(host="<API-URL>", token="<ACCESS-TOKEN>")

Alternatively, the access token can be sourced from an environment variable.

$ export SCALEOUT_AUTH_TOKEN=<access-token>

Then passing a token as an argument is not required.

>>> from scaleout import Scaleout
>>> client = Scaleout(host="<API-URL>")

We are now ready to work with the API.

Orchestrating Sessions

The most common task is automating the training lifecycle.

Starting a session

You can initiate a training run with a specific configuration.

session_config = {
 "name": "nightly-retrain-v2",
 "rounds": 5,
 "min_clients": 10,
 "aggregator": "fedopt",
 "aggregator_kwargs": {
     "learning_rate": 0.01
   }
}

session = client.start_session(**session_config)
print(f"Session started: {session['id']}")

Monitoring Progress

You can poll the session status to wait for completion.

import time

while True:
    status = client.get_controller_status()
    if status == 'idle':
        print("Training complete.")
        break
    time.sleep(60)  # Wait for 1 minute before checking again

List data

Other than orchestrating sessions, the Scaleout client can be used to retrieve information about various entities from the network, such as sessions, models, etc. All entities are represented, and they all work in a similar fashion.

get_*() - (plural) list all entities of a specific type
get_*(id=<id-of-entity>) - get a specific entity

Entities represented in the Scaleout client are:

clients
combiners
models
packages
rounds
sessions
statuses
validations

To list all sessions:

>>> sessions = client.get_sessions()

To get a specific session:

>>> session = client.get_session(id="session_id")

For more information on how to use the Scaleout client, see the scaleoututil.api.client. There is also a collection of Jupyter Notebooks showcasing more advanced use of the API, including how to work with other built-in aggregators and how to automate hyperparameter tuning:

API Example .