Merge remote-tracking branch 'origin/master' into feature/SK-811

.github/workflows/branch-name-check.yaml

@@ -7,7 +7,7 @@ on:
       - master
 
 env:
-  BRANCH_REGEX: '^((feature|github|dependabot|hotfix|bugfix|fix|bug|docs|refactor)\/.+)|(release\/v((([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?))$'
+  BRANCH_REGEX: '(?i)^((feature|github|dependabot|hotfix|bugfix|fix|bug|docs|refactor)\/.+)|(release\/v((([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?))$'
 
 jobs:
   branch-name-check:

Dockerfile

@@ -41,7 +41,7 @@ RUN mkdir -p /app \
   # Install FEDn and requirements
   && python -m venv /venv \
   && /venv/bin/pip install --upgrade pip \
-  && /venv/bin/pip install --no-cache-dir setuptools>=65 \
+  && /venv/bin/pip install --no-cache-dir 'setuptools>=65' \
   && /venv/bin/pip install --no-cache-dir -e . \
   && if [[ ! -z "$REQUIREMENTS" ]]; then \
   /venv/bin/pip install --no-cache-dir -r /app/config/requirements.txt; \

README.rst

@@ -26,7 +26,7 @@ Our goal is to provide a federated learning framework that is both secure, scala
 
 -  **Developer and DevOps friendly.** Extensive event logging and distributed tracing enables developers to monitor the sytem in real-time, simplifying troubleshooting and auditing. Extensions and integrations are facilitated by a flexible plug-in architecture.  
 
-We provide a fully managed deployment for testing, academic, and personal use. Sign up for a `FEDn Studio account <https://fedn.scaleoutsystems.com/signup>`__  and take the `Quickstart tutorial <https://fedn.readthedocs.io/en/stable/quickstart.html>`__ to get started with FEDn. 
+FEDn is free forever for academic and personal use / small projects. Sign up for a `FEDn Studio account <https://fedn.scaleoutsystems.com/signup>`__  and take the `Quickstart tutorial <https://fedn.readthedocs.io/en/stable/quickstart.html>`__ to get started with FEDn. 
 
 Features
 =========
@@ -77,6 +77,18 @@ More details about the architecture, deployment, and how to develop your own app
 
 -  `Documentation <https://fedn.readthedocs.io>`__
 
+FEDn Project Examples
+=====================
+
+Our example projects demonstrate different use case scenarios of FEDn 
+and its integration with popular machine learning frameworks like PyTorch and TensorFlow.
+
+- `FEDn + PyTorch <https://github.com/scaleoutsystems/fedn/tree/master/examples/mnist-pytorch>`__
+- `FEDn + Tensforflow/Keras <https://github.com/scaleoutsystems/fedn/tree/master/examples/mnist-keras>`__
+- `FEDn + MONAI <https://github.com/scaleoutsystems/fedn/tree/master/examples/monai-2D-mednist>`__
+- `FEDn + Hugging Face <https://github.com/scaleoutsystems/fedn/tree/master/examples/huggingface>`__
+- `FEDn + Flower <https://github.com/scaleoutsystems/fedn/tree/master/examples/flower-client>`__
+- `FEDN + Self-supervised learning <https://github.com/scaleoutsystems/fedn/tree/master/examples/FedSimSiam>`__
 
 FEDn Studio Deployment options
 ==============================

docs/apiclient.rst

@@ -1,9 +1,13 @@
 .. _apiclient-label:
 
-APIClient
-=========
+Using the Python API
+====================
 
 FEDn comes with an *APIClient* - a Python3 library that can be used to interact with FEDn programmatically. 
+In this tutorial we show how to use the APIClient to initialize the server-side with the compute package and seed models, 
+run and control training sessions, use different aggregators, and to retrieve models and metrics. 
+
+We assume a basic understanding of the FEDn framework, i.e. that the user have taken the Getting Started tutorial: :ref:`quickstart-label`
 
 **Installation**
 
@@ -13,39 +17,87 @@ The APIClient is available as a Python package on PyPI, and can be installed usi
    
    $ pip install fedn
 
-**Initialize the APIClient**
+**Initialize the APIClient to a FEDn Studio project**
 
 The FEDn REST API is available at <controller-host>/api/v1/. To access this API you need the url to the controller-host, as well as an admin API token. The controller host can be found in the project dashboard (top right corner).
 To obtain an admin API token, navigate to the "Settings" tab in your Studio project and click on the "Generate token" button. Copy the 'access' token and use it to access the API using the instructions below. 
 
-
 .. code-block:: python
 
    >>> from fedn import APIClient
    >>> client = APIClient(host="<controller-host>", token="<access-token>", secure=True, verify=True)
 
+Alternatively, the access token can be sourced from an environment variable. 
 
-**Set active package and seed model**
+.. code-block:: bash
+   $ export FEDN_AUTH_TOKEN=<access-token>
 
-The active package can be set using the following code snippet:
+Then passing a token as an argument is not required. 
 
 .. code-block:: python
-   
-   client.set_active_package(path="path/to/package.tgz", helper="numpyhelper")
 
-To set the initial seed model, you can use the following code snippet:
+   >>> from fedn import APIClient
+   >>> client = APIClient(host="<controller-host>", secure=True, verify=True)
 
-.. code-block:: python
-   
-   client.set_active_model(path="path/to/seed.npz")
+**Set the active compute package and seed model**
+
+To set the active compute package in the FEDn Studio Project:
+
+.. code:: python
+
+   >>> from fedn import APIClient
+   >>> client = APIClient(host="<controller-host>", token="<access-token>", secure=True, verify=True)
+   >>> client.set_active_package("package.tgz", helper="numpyhelper")
+   >>> client.set_active_model("seed.npz")
 
 **Start a training session**
 
-Once the active package and seed model are set, you can connect clients to the network and start training models. The following code snippet starts a traing session:
+Once the active package and seed model are set, you can connect clients to the network and start training models. To run a training session
+using the default aggregator (FedAvg):
+
+.. code:: python
+
+   >>> ...
+   >>> client.start_session(id="test-session", rounds=3)
+   # Wait for training to complete, when controller is idle:
+   >>> client.get_controller_status()
+   # Show model trail:
+   >>> models = client.get_model_trail()
+   # Show performance of latest global model:
+   >>> model_id = models[-1]['model']
+   >>> validations = client.get_validations(model_id=model_id)
+
+To run a session using the FedAdam aggregator using custom hyperparamters: 
 
 .. code-block:: python
-   
-   session = client.start_session(id="session_name")
+
+   >>> session_id = "experiment_fedadam"
+
+   >>> session_config = {
+                     "helper": "numpyhelper",
+                     "id": session_id,
+                     "aggregator": "fedopt",
+                     "aggregator_kwargs": {
+                           "serveropt": "adam",
+                           "learning_rate": 1e-2,
+                           "beta1": 0.9,
+                           "beta2": 0.99,
+                           "tau": 1e-4
+                           },
+                     "model_id": seed_model['model'],
+                     "rounds": 10
+                  }
+
+   >>> result_fedadam = client.start_session(**session_config)
+
+**Download a global model**
+
+To download a global model and write it to file:
+
+.. code:: python
+
+   >>> ...
+   >>> client.download_model("<model-id>", path="model.npz")
 
 **List data**
 
@@ -65,17 +117,17 @@ Entities represented in the APIClient are:
 * statuses
 * validations
 
-The following code snippet shows how to list all sessions:
-
+To list all sessions: 
 .. code-block:: python
    
-   sessions = client.get_sessions()
+   >>> sessions = client.get_sessions()
 
-And the following code snippet shows how to get a specific session:
+To get a specific session:
 
 .. code-block:: python
    
-   session = client.get_session(id="session_name")
-
+   >>> session = client.get_session(id="session_name")
 
-For more information on how to use the APIClient, see the :py:mod:`fedn.network.api.client`, and the example `Notebooks <https://github.com/scaleoutsystems/fedn/blob/master/examples/mnist-pytorch/API_Example.ipynb>`_. 
+For more information on how to use the APIClient, see the :py:mod:`fedn.network.api.client`, and the collection of example Jupyter Notebooks:
+
+- `API Example <https://github.com/scaleoutsystems/fedn/tree/master/examples/notebooks>`_  . 

docs/conf.py

@@ -12,7 +12,7 @@
 author = "Scaleout Systems AB"
 
 # The full version, including alpha/beta/rc tags
-release = "0.11.1"
+release = "0.12.1"
 
 # Add any Sphinx extension module names here, as strings
 extensions = [
@@ -25,6 +25,7 @@
     "sphinx.ext.viewcode",
     "sphinx_rtd_theme",
     "sphinx_code_tabs",
+    "sphinx_design",
 ]
 
 # The master toctree document.
@@ -97,7 +98,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, "fedn", "FEDn Documentation", author, "fedn", "One line description of project.", "Miscellaneous"),
+    (master_doc, "fedn", "FEDn Documentation", author, "fedn",
+     "One line description of project.", "Miscellaneous"),
 ]
 
 # Bibliographic Dublin Core info.