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",
    "entity_id": "client_123",
}

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:

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:

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:

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:

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(entity_id: str)[source]

Get the full attribute history for a given node.

Parameters:: entity_id (str) – The entity_id (client or combiner) to fetch attributes for
Returns:: All matching attributes for the entity
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_command(id: str)[source]

Get a command from the statestore.

Parameters:: id (str) – The command id to get.
Returns:: Command.
Return type:: dict

get_commands(n_max: int = None, parent_correlation_id: str = None)[source]

Get commands in the network.

Parameters:

n_max (int) – The maximum number of commands to get (If none all will be fetched).
parent_correlation_id (str) – The parent correlation id to get commands for.

Returns:

Commands.

Return type:

get_commands_count()[source]

Get the number of commands in the statestore.

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

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

Get root commands (commands without parent) in the network.

Parameters:: n_max (int) – The maximum number of root commands to get (If none all will be fetched).
Returns:: Root commands.
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(entity_list)[source]

Get the current attributes of the entity(ies).

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

get_metrics(*, session_id: str = None, model_id: str = None, round_id: str = None, key: str = None, sender_name: str = None, sender_role: str = None, sender_client_id: str = None, n_max: int = None)[source]

Get metrics logged with EdgeClient.log_metric from the statestore. Filter by input parameters.

Parameters:

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

Returns:

Metrics.

Return type:

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

Get the number of metrics in the statestore.

Returns:: The number of metrics.
Return type:: int

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:

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:

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_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:

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:

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:

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, synchronous: 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.
Raises:: RuntimeError – If the file type is unsupported (only .npz and .bin are supported), or if the server responds with a non-success status code.
Returns:: A dict with success or failure message.
Return type:: dict

set_active_package(path: str, helper: str, name: str, description: str = '', restart_clients: bool = False)[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.
restart_clients (bool) – Push the new package to connected clients and restart them.

Returns:

A dict with success or failure message.

Return type:

set_public_hostname(id: str, public_hostname: str)[source]

Set the public hostname of a combiner.

Parameters:

id (str) – The combiner id to update.
public_hostname (str) – The hostname and port, as hostname:port, of the endpoint that accepts the edge clients’ gRPC connections, such as a configured ingress or load balancer. Without a port, edge clients connect on the combiner’s own port.

Raises:

RuntimeError – If the server responds with a non-success status code.

Returns:

The server response (a success message).

Return type:

stage_model(model_id: str, client_ids: list = None)[source]

Stage a model to clients.

Parameters:

model_id (str) – The id of the model to stage.
client_ids (list) – The list of client ids to stage the model to (if None all clients will be staged).

Returns:

A dict with success or failure message.

Return type:

start_inference(model_id: str, synchronous: bool = True, timeout: int = None, client_ids: list = None, parameters: dict = None)[source]

Start an inference trail for a model.

Parameters:

model_id (str) – The id of the model to start inference for.
parameters (dict) – The parameters for the inference.
client_ids (list) – The list of client ids to start inference on (if None all clients will be started).
timeout (int) – The timeout for the inference session in seconds, -1 for infinite (default: 180).
synchronous – Whether to run the inference synchronously (in order) or asynchronously (default: True).

Returns:

A dict with success or failure message.

Return type:

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:

start_validation(session_id: str, model_id: str)[source]

Start a validation for a given session and model.

Parameters:

session_id (str) – The id of the session to validate.
model_id (str) – The id of the model to validate.

Returns:

A dict with success or failure message.

Return type:

step_command(correlation_id: str)[source]

Skip a synchronization barrier in a session control for a specific correlation id.

Parameters:: correlation_id (str) – The correlation id of the command to step.
Returns:: A dict with success or failure message.
Return type:: dict

step_current_command()[source]

Skip a synchronization barrier in 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_command(correlation_id: str)[source]

Stop a session control for a specific correlation id.

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

stop_current_command()[source]

Stop a session control.

Parameters:: session_id (str) – The id of the session to stop.
Raises:: RuntimeError – If the server responds with a non-success status code.
Returns:: A dict with success or failure message.
Return type:: dict