.. _apiclient-label:

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.

.. code-block:: bash
   
   $ 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:

.. code-block:: python

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

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

.. code-block:: bash

   $ export SCALEOUT_AUTH_TOKEN=<access-token>

Then passing a token as an argument is not required. 

.. code-block:: python

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

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


**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`.  
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 <https://github.com/scaleoutsystems/scaleout-client/tree/main/scaleout-client-python/examples/api-tutorials>`_  .


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