Scaleout Edge API Client

This section documents the Scaleout Edge API Client, the high-level interface used by external applications, orchestration layers, and tools to interact with a running Scaleout Edge network. The API Client provides convenient methods for:

querying network state
managing clients, attributes, and sessions
submitting models and retrieving results
interacting with controllers, combiners, and server functions

It acts as the primary Python entry point for programmatic communication with the Scaleout Edge backend.

class scaleout.Scaleout(host: str, port: int = None, secure: bool | None = None, verify: bool = True, token: str = None, auth_scheme: str = None, token_endpoint: str = None, access_token_provider: Callable[[], str | None] | None = None)[source]

Bases: object

Python client for interacting with the statestore and controller.

Parameters:

host (str) – The host of the api server.
port (int) – The port of the api server.
secure (bool) – Whether to use https.
verify (bool) – Whether to verify the server certificate.

__init__(host: str, port: int = None, secure: bool | None = None, verify: bool = True, token: str = None, auth_scheme: str = None, token_endpoint: str = None, access_token_provider: Callable[[], str | None] | None = None)[source]

Initialize the Scaleout client.

Parameters:

host (str) – The host of the api server.
port (int) – The port of the api server.
secure (bool) – Whether to use https.
verify (bool) – Whether to verify the server SSL certificate (default: True). Set to False for development with self-signed certificates.
token (str) – Refresh token for automatic token management. Can also be set via SCALEOUT_AUTH_TOKEN env var.
auth_scheme (str) – Authorization scheme (e.g., ‘Bearer’). Defaults to ‘Bearer’.
token_endpoint (str) – Token refresh endpoint URL. If not provided, will be constructed from host.

add_attributes(attribute: dict) → dict[source]

Add or update node attributes via the controller API.

Parameters:: attribute – A dict matching AttributeDTO.schema, e.g.:

{
    "key": "charging",
    "value": "true",
    "sender": {
        "name": "",
        "role": "",
        "client_id": "abc123"    # or "combiner_id": "abc123"
    }
}

Returns:: Parsed JSON response from the server.
Return type:: dict

add_status(status: dict) → dict[source]

Submit a status entry to the controller API.

Parameters:

status –

A dict matching StatusDTO.schema, e.g.:

{
    "type": "MODEL_UPDATE",
    "log_level": "INFO",
    "status": "Training complete",
    "sender": {
        "client_id": "abc-123"
    }
}

Returns:

Parsed JSON response from the server.

Return type:

dict

continue_session(session_id: str, rounds: int = 5, round_timeout: int = 180)[source]

Continue a session.

Parameters:

session_id (str) – The id of the session to continue.
rounds (int) – The number of rounds to perform.
round_timeout (int) – The round timeout to use in seconds.

Returns:

A dict with success or failure message and session config.

Return type:

dict

download_model(id: str, path: str)[source]

Download the model with id id.

Parameters:

id (str) – The id (or model property) of the model to download.
path (str) – The path to download the model to.

Returns:

Message with success or failure.

Return type:

dict

download_package(path: str)[source]

Download the compute package.

Parameters:: path (str) – The path to download the compute package to.
Returns:: Message with success or failure.
Return type:: dict

get_active_clients(combiner_id: str = None, n_max: int = None)[source]

Get active clients from the statestore.

Parameters:

combiner_id (str) – The combiner id to get active clients for.
n_max (int) – The maximum number of clients to get (If none all will be fetched).

Returns:

Active clients.

Return type:

dict

get_active_model()[source]

Get the latest model from the statestore.

Returns:: The latest model.
Return type:: dict

get_active_package()[source]

Get the (active) compute package from the statestore.

Returns:: Package.
Return type:: dict

get_attribute_trail(node_id: str)[source]

Get the full attribute history for a given node.

Parameters:: node_id (str) – The node_id (client or combiner) to fetch attributes for
Returns:: All matching attributes for the node
Return type:: dict

get_client(id: str)[source]

Get a client from the statestore.

Parameters:: id (str) – The client id to get.
Returns:: Client.
Return type:: dict

get_client_config(checksum=True)[source]

Get client config from controller. Optionally include the checksum. The config is used for clients to connect to the controller and ask for combiner assignment.

Parameters:: checksum (bool) – Whether to include the checksum of the package.
Returns:: The client configuration.
Return type:: dict

get_clients(n_max: int = None)[source]

Get clients from the statestore.

Parameters:: n_max (int) – The maximum number of clients to get (If none all will be fetched).
Returns:: Clients.
Return type:: dict

get_clients_count(only_active: bool = False)[source]

Get the number of clients in the statestore.

Returns:: The number of clients.
Return type:: dict

get_combiner(id: str)[source]

Get a combiner from the statestore.

Parameters:: id (str) – The combiner id to get.
Returns:: Combiner.
Return type:: dict

get_combiners(n_max: int = None)[source]

Get combiners in the network.

Parameters:: n_max (int) – The maximum number of combiners to get (If none all will be fetched).
Returns:: Combiners.
Return type:: dict

get_combiners_count()[source]

Get the number of combiners in the statestore.

Returns:: The number of combiners.
Return type:: dict

get_controller_status()[source]

Get the status of the controller.

Returns:: The status of the controller.
Return type:: dict

get_current_attributes(node_list)[source]

Get the current attributes of the node(s).

Parameters:: node_list (list|str) – The list of nodes to get the attributes for or a single node_id (client_id or combiner_id)
Raises:: ValueError – If node_list is not a list or empty.
Returns:: The current attributes of the nodes.
Return type:: dict

get_model(id: str)[source]

Get a model from the statestore.

Parameters:: id (str) – The id (or model property) of the model to get.
Returns:: Model.
Return type:: dict

get_model_trail(id: str = None, include_self: bool = True, reverse: bool = True, n_max: int = None)[source]

Get the model trail.

Parameters:

id (str) – The id (or model property) of the model to start the trail from. (optional)
n_max (int) – The maximum number of models to get (If none all will be fetched).

Returns:

Models.

Return type:

dict

get_models(session_id: str = None, n_max: int = None)[source]

Get models from the statestore.

Parameters:

session_id (str) – The session id to get models for. (optional)
n_max (int) – The maximum number of models to get (If none all will be fetched).

Returns:

Models.

Return type:

dict

get_models_count()[source]

Get the number of models in the statestore.

Returns:: The number of models.
Return type:: dict

get_package(id: str)[source]

Get a compute package from the statestore.

Parameters:: id (str) – The id of the compute package to get.
Returns:: Package.
Return type:: dict

get_package_checksum()[source]

Get the checksum of the compute package.

Returns:: The checksum.
Return type:: dict

get_packages(n_max: int = None)[source]

Get compute packages from the statestore.

Parameters:: n_max (int) – The maximum number of packages to get (If none all will be fetched).
Returns:: Packages.
Return type:: dict

get_packages_count()[source]

Get the number of compute packages in the statestore.

Returns:: The number of packages.
Return type:: dict

get_predictions(model_id: str = None, correlation_id: str = None, client_id: str = None, n_max: int = None)[source]

Get predictions from the statestore. Filter by input parameters.

Parameters:

model_id (str) – The model id to get predictions for.
correlation_id (str) – The correlation id to get predictions for.
client_id (str) – The client id to get predictions for.
n_max (int) – The maximum number of predictions to get (If none all will be fetched).

Returns:

Predictions.

Return type:

dict

get_round(id: str)[source]

Get a round from the statestore.

Parameters:: round_id (str) – The round id to get.
Returns:: Round (config and metrics).
Return type:: dict

get_rounds(n_max: int = None, filter: Dict = None)[source]

Get all rounds from the statestore.

Parameters:: n_max (int) – The maximum number of rounds to get (If none all will be fetched).
Returns:: Rounds.
Return type:: dict

get_rounds_count()[source]

Get the number of rounds in the statestore.

Returns:: The number of rounds.
Return type:: dict

get_session(id: str = None, name: str = None)[source]

Get a session from the statestore.

Parameters:

id (str) – The session id to get.
name (str) – The session name to get.

Returns:

Session.

Return type:

dict

get_session_status(id: str)[source]

Get the status of a session.

Parameters:: id (str) – The id of the session to get.
Returns:: The status of the session.
Return type:: str

get_sessions(n_max: int = None, name: str = None)[source]

Get sessions from the statestore.

Parameters:

n_max (int) – The maximum number of sessions to get (If none all will be fetched).
name (str) – The session name to get.

Returns:

Sessions.

Return type:

dict

get_sessions_count()[source]

Get the number of sessions in the statestore.

Returns:: The number of sessions.
Return type:: dict

get_status(id: str)[source]

Get a status object (event) from the statestore.

Parameters:: id (str) – The id of the status to get.
Returns:: Status.
Return type:: dict

get_statuses(session_id: str = None, event_type: str = None, sender_name: str = None, sender_role: str = None, n_max: int = None)[source]

Get statuses from the statestore. Filter by input parameters

Parameters:

session_id (str) – The session id to get statuses for.
event_type (str) – The event type to get.
sender_name (str) – The sender name to get.
sender_role (str) – The sender role to get.
n_max (int) – The maximum number of statuses to get (If none all will be fetched).

Returns:

Statuses

get_statuses_count()[source]

Get the number of statuses in the statestore.

Returns:: The number of statuses.
Return type:: dict

get_validation(id: str)[source]

Get a validation from the statestore.

Parameters:: id (str) – The id of the validation to get.
Returns:: Validation.
Return type:: dict

get_validations(session_id: str = None, model_id: str = None, correlation_id: str = None, sender_name: str = None, sender_role: str = None, sender_client_id: str = None, n_max: int = None)[source]

Get validations from the statestore. Filter by input parameters.

Parameters:

session_id (str) – The session id to get validations for.
model_id (str) – The model id to get validations for.
correlation_id (str) – The correlation id to get validations for.
sender_name (str) – The sender name to get validations for.
sender_role (str) – The sender role to get validations for.
sender_client_id (str) – The sender client id to get validations for.
n_max (int) – The maximum number of validations to get (If none all will be fetched).

Returns:

Validations.

Return type:

dict

get_validations_count(session_id: str = None)[source]

Get the number of validations in the statestore.

Returns:: The number of validations.
Return type:: dict

run_custom_command(command_type: str, blocking: bool = False, timeout: int = None, client_ids: list = None, parameters: dict = None)[source]

session_is_finished(id: str)[source]

Check if a session with id has finished.

Parameters:: id (str) – The id of the session to get.
Returns:: True if session is finished, otherwise false.
Return type:: bool

set_active_model(path)[source]

Set the initial model in the statestore and upload to model repository.

Parameters:: path (str) – The file path of the initial model to set.
Returns:: A dict with success or failure message.
Return type:: dict

set_active_package(path: str, helper: str, name: str, description: str = '')[source]

Set the compute package in the statestore.

Parameters:

path (str) – The file path of the compute package to set.
helper (str) – The helper type to use.

Returns:

A dict with success or failure message.

Return type:

dict

start_predictions(prediction_id: str = None, model_id: str = None)[source]

Start predictions for a model.

Parameters:

model_id (str) – The model id to start predictions for.
data (dict) – The data to predict.

Returns:

A dict with success or failure message.

Return type:

dict

start_session(name: str = None, aggregator: str = 'fedavg', aggregator_kwargs: dict = None, model_id: str = None, round_timeout: int = 180, rounds: int = 5, round_buffer_size: int = -1, delete_models: bool = True, validate: bool = True, helper: str = None, min_clients: int = 1, requested_clients: int = 8, server_functions: ServerFunctionsBase = None)[source]

Start a new session.

Parameters:

name (str) – The name of the session
aggregator (str) – The aggregator plugin to use.
model_id (str) – The id of the initial model.
round_timeout (int) – The round timeout to use in seconds.
rounds (int) – The number of rounds to perform.
round_buffer_size (int) – The round buffer size to use.
delete_models (bool) – Whether to delete models after each round at combiner (save storage).
validate (bool) – Whether to validate the model after each round.
helper (str) – The helper type to use.
min_clients (int) – The minimum number of clients required.
requested_clients (int) – The requested number of clients.

Returns:

A dict with success or failure message and session config.

Return type:

dict

step_current_session()[source]

Continue a session control.

Parameters:: session_id (str) – The id of the session to continue.
Returns:: A dict with success or failure message.
Return type:: dict

stop_current_session()[source]

Stop a session control.

Parameters:: session_id (str) – The id of the session to stop.
Returns:: A dict with success or failure message.
Return type:: dict