.. _apiclient-label:

Using the API Client
====================

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

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.

.. code-block:: bash
   
   $ pip install scaleout

**Connecting to the API**

To initialize the connection to the Scaleout Edge API, create an instance of the ``Scaleout`` class with your deployment URL and an **API key**.

API keys are the recommended credential for programmatic and CI/CD use — they are long-lived and do not need to be refreshed. You can create one from the **Settings** tab in the Dashboard.

.. code-block:: python

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

For scripts and automation, the API key can be supplied via an environment variable instead of hardcoding it:

.. code-block:: bash

   $ export SCALEOUT_AUTH_TOKEN=<api-key>

.. code-block:: python

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

We are now ready to work with the API.

Uploading a Model
-----------------

Before starting training, an initial global model must be uploaded to the Control Plane.
Use ``set_active_model`` to upload a local model file and register it as the active model.

Supported file formats are ``.npz`` (NumPy) and ``.bin`` (binary):

.. code-block:: python

   >>> result = client.set_active_model("path/to/initial_model.npz")
   >>> print(result)
   {'committed_at': '...', 'id': '...', 'key': 'models', 'model': '...', ...}

The method detects the file format from the extension and sets the matching helper (``numpyhelper`` for ``.npz``, ``binaryhelper`` for ``.bin``) automatically.

Orchestrating Sessions
---------------------- 

The most common task is automating the training lifecycle.

**Starting a session**

You can initiate a training run with a specific configuration.

.. code:: python

   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.

.. code:: python

   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

Validating a Model
------------------

You can trigger a validation of a specific model within a session.

.. code-block:: python

   >>> client.start_validation(session_id="<session-id>", model_id="<model-id>")

Managing Combiners
------------------

For deployments where a combiner must be reachable at a specific public address, you can set it.
Give 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 portnumber
which is normally not exposed directly.
For IPv6, use ``[address]:port``.

.. code-block:: python

   >>> client.set_public_hostname(id="<combiner-id>", public_hostname="combiner.example.com:443")


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

.. code-block:: python
   
   >>> sessions = client.get_sessions()

To get a specific session:

.. code-block:: python
   
   >>> session = client.get_session(id="session_id")

For more information on how to use the ``Scaleout`` client, see the :py:mod:`scaleoututil.api.client`.


.. meta::
   :description lang=en:
      Scaleout Edge comes with a Python client class called Scaleout that can be used to interact with Scaleout Edge programmatically.
   :keywords: Federated Learning, Scaleout, Federated Learning Framework, Federated Learning Platform, FEDn, Scaleout Systems, Scaleout Edge