scaleout 1.0.0b2
A client library for the Scaleout Edge
Requires Python: <3.14,>=3.11

|pic1| |pic2| |pic3|

.. |pic1| image:: https://github.com/scaleoutsystems/fedn/actions/workflows/integration-tests.yaml/badge.svg
   :target: https://github.com/scaleoutsystems/fedn/actions/workflows/integration-tests.yaml

.. |pic2| image:: https://badgen.net/badge/icon/discord?icon=discord&label
   :target: https://discord.gg/KMg4VwszAd

.. |pic3| image:: https://readthedocs.org/projects/fedn/badge/?version=latest&style=flat
   :target: https://scaleout.readthedocs.io

Scaleout Edge: An enterprise-ready Edge AI framework
----------------------------------------------------

Our goal is to provide an Edge AI framework that is both secure, scalable, easy-to-use and that supports Federated Learning. We believe that that minimal code change should be needed to progress from early proof-of-concepts to production. This is reflected in our core design: 

-  **Minimal server-side complexity for the end-user**. Running a proper distributed FL deployment is hard. With FEDn Studio we seek to handle all server-side complexity and provide a UI, REST API and a Python interface to help users manage FL experiments and track metrics in real time.

-  **Secure by design.** FL clients do not need to open any ingress ports. Industry-standard communication protocols (gRPC) and token-based authentication and RBAC (Jason Web Tokens) provides flexible integration in a range of production environments.  

-  **ML-framework agnostic**. A black-box client-side architecture lets data scientists interface with their framework of choice. 

-  **Cloud native.** By following cloud native design principles, we ensure a wide range of deployment options including private cloud and on-premise infrastructure. 

-  **Scalability and resilience.** Multiple aggregation servers (combiners) can share the workload. FEDn seamlessly recover from failures in all critical components and manages intermittent client-connections. 

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

Scaleout Edge is free forever for academic and personal use / small projects. Sign up for a `Scaleout account <https://scaleout.scaleoutsystems.com/signup>`__  and take the `Quickstart tutorial <https://scaleout.readthedocs.io/en/stable/quickstart.html>`__ to get started with Scaleout Edge. 

Features
========

Federated learning: 

- Tiered federated learning architecture enabling massive scalability and resilience. 
- Support for any ML framework (examples for PyTorch, Tensforflow/Keras and Scikit-learn)
- Extendable via a plug-in architecture (aggregators, load balancers, object storage backends, databases  etc.)
- Built-in federated algorithms (FedAvg, FedAdam, FedYogi, FedAdaGrad, etc.)
- UI, CLI and Python API.
- Implement clients in any language (Python, C++, Kotlin etc.)
- No open ports needed client-side.

Edge ModelOps features:
-  Secure client model deployment and update management for models used by inference applications.
-  Add client-side logic or server-side logic with to handle multiple models for different use cases, or to implement custom logic for model deployment, update and rollback.
-  Client health monitoring and status reporting.
-  Logging and distributed tracing for monitoring and troubleshooting.


From development to FL in production: 

-  Secure deployment of server-side / control-plane on Kubernetes.
-  UI with dashboards for orchestrating FL experiments and for visualizing results
-  Team features - collaborate with other users in shared project workspaces. 
-  Features for the trusted-third party: Manage access to the FL network, FL clients and training progress.
-  REST API for handling experiments/jobs. 
-  View and export logging and tracing information. 
-  Public cloud, dedicated cloud and on-premise deployment options.

Available client APIs:

- Python client (this package)
- C++ client (`Scaleout C++ client <https://github.com/scaleoutsystems/fedn-cpp-client>`__)
- Android Kotlin client (`Scaleout Kotlin client <https://github.com/scaleoutsystems/fedn-android-client>`__)


Getting started
===============

Get started with FEDn in two steps:  

1. Register for a `FEDn Studio account <https://scaleout.scaleoutsystems.com/signup>`__
2. Take the `Quickstart tutorial <https://scaleout.readthedocs.io/en/stable/quickstart.html>`__

Use of our multi-tenant, managed deployment of FEDn Studio (SaaS) is free forever for academic research and personal development/testing purposes.
For users and teams requiring additional resources, more storage and cpu, dedicated support, and other hosting options (private cloud, on-premise), `explore our plans <https://www.scaleoutsystems.com/start#pricing>`__.  

Documentation
=============

More details about the architecture, deployment, and how to develop your own application and framework extensions are found in the documentation:

-  `Documentation <https://scaleout.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.

- `Scaleout Edge + PyTorch <https://github.com/scaleoutsystems/fedn/tree/master/examples/mnist-pytorch>`__
- `Scaleout Edge + Tensforflow/Keras <https://github.com/scaleoutsystems/fedn/tree/master/examples/mnist-keras>`__
- `Scaleout Edge + MONAI <https://github.com/scaleoutsystems/fedn/tree/master/examples/monai-2D-mednist>`__
- `Scaleout Edge + Hugging Face <https://github.com/scaleoutsystems/fedn/tree/master/examples/huggingface>`__
- `Scaleout Edge + Flower <https://github.com/scaleoutsystems/fedn/tree/master/examples/flower-client>`__
- `Scaleout Edge + Self-supervised learning <https://github.com/scaleoutsystems/fedn/tree/master/examples/FedSimSiam>`__

Scaleout Edge Deployment options
================================

Several hosting options are available to suit different project settings.

-  `Public cloud (multi-tenant) <https://scaleout.scaleoutsystems.com>`__: Managed multi-tenant deployment in public cloud. 
-   Dedicated cloud (single-tenant): Managed, dedicated deployment in a cloud region of your choice (AWS, GCP, Azure, managed Kubernetes) 
-   Self-managed: Set up a self-managed deployment in your VPC or on-premise Kubernets cluster using Helm Chart and container images provided by Scaleout. 

Contact the Scaleout team for information.

Support
=======

Community support is available in our `Discord
server <https://discord.gg/KMg4VwszAd>`__.

Options are available for `Dedicated/custom support <https://www.scaleoutsystems.com/start#pricing>`__.

Making contributions
====================

All pull requests will be considered and are much appreciated. For
more details please refer to our `contribution
guidelines <https://github.com/scaleoutsystems/fedn/blob/master/CONTRIBUTING.md>`__.

Citation
========

If you use Scaleout Edge in your research, please cite:

::

   @article{ekmefjord2021scalable,
     title={Scalable federated machine learning with FEDn},
     author={Ekmefjord, Morgan and Ait-Mlouk, Addi and Alawadi, Sadi and {\\AA}kesson, Mattias and Stoyanova, Desislava and Spjuth, Ola and Toor, Salman and Hellander, Andreas},
     journal={arXiv preprint arXiv:2103.00148},
     year={2021}
   }


License
=======

Scaleout Edge python client is licensed under Apache-2.0 (see `LICENSE <LICENSE>`__ file for
full information).

Use of Scaleout Edge Studio is subject to the `Terms of Use <https://www.scaleoutsystems.com/terms>`__.