refactor(examples): Migrate examples to hub/apps & update links

.github/CODEOWNERS

@@ -18,6 +18,9 @@ README.md @jafermarq @tanertopal @danieljanes
 # Flower Examples
 /examples @yan-gao-GY @panh99 @chongshenng @jafermarq @tanertopal @danieljanes
 
+# Flower Hub
+/hub @yan-gao-GY @panh99 @chongshenng @jafermarq @tanertopal @danieljanes
+
 # Flower Intelligence
 /intelligence/dev @charlesbvll @tanertopal @danieljanes
 /intelligence/docs @charlesbvll @tanertopal @danieljanes

.github/workflows/framework-e2e.yml

@@ -342,7 +342,7 @@ jobs:
           python -m pip install "flwr[simulation] @ ${WHEEL_URL}"
       - name: Install project dependencies
         if: ${{ needs.changes.outputs.framework == 'true' }}
-        working-directory: examples/${{ matrix.example }}
+        working-directory: hub/apps/${{ matrix.example }}
         run: |
           sed -i 's/"flwr\[[^]]*\][^"]*", *//g' pyproject.toml
           # Replace tensorflow with tensorflow-cpu to avoid GPU warnings in CI
@@ -351,7 +351,7 @@ jobs:
           pip install .  --extra-index-url https://download.pytorch.org/whl/cpu
       - name: Run project
         if: ${{ needs.changes.outputs.framework == 'true' }}
-        working-directory: examples/${{ matrix.example }}
+        working-directory: hub/apps/${{ matrix.example }}
         run: |
           flwr run --run-config num-server-rounds=1 --stream 2>&1 | tee flwr_output.log 
           output=$(flwr ls --format=json)

.github/workflows/framework-test.yml

@@ -38,7 +38,7 @@ jobs:
               - 'dev/uv.lock'
               - '.github/workflows/framework-test.yml'
             ex_bench:
-              - 'examples/**/*'
+              - 'hub/apps/**/*'
               - 'benchmarks/**/*'
               - 'dev/test.sh'
               - '.github/workflows/framework-test.yml'

.gitignore

@@ -10,9 +10,9 @@ flwr_logs
 # Node.js
 node_modules
 
-# Flower Examples
-examples/**/dataset/**
-#examples/**/dev/*.sh
+# Flower Apps
+hub/apps/**/dataset/**
+#hub/apps/**/dev/*.sh
 
 # Flower Baselines
 baselines/datasets/leaf

README.md

@@ -111,34 +111,33 @@ Several code examples show different usage scenarios of Flower (in combination w
 
 Quickstart examples:
 
-- [Quickstart (TensorFlow)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-tensorflow)
-- [Quickstart (PyTorch)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pytorch)
-- [Quickstart (Hugging Face)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-huggingface)
-- [Quickstart (PyTorch Lightning)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pytorch-lightning)
-- [Quickstart (fastai)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-fastai)
-- [Quickstart (Pandas)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pandas)
-- [Quickstart (JAX)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-jax)
-- [Quickstart (MONAI)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-monai)
-- [Quickstart (scikit-learn)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-sklearn)
-- [Quickstart (Android [TFLite])](https://github.com/flwrlabs/flower/tree/main/examples/android)
-- [Quickstart (iOS [CoreML])](https://github.com/flwrlabs/flower/tree/main/examples/ios)
-- [Quickstart (MLX)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-mlx)
-- [Quickstart (XGBoost)](https://github.com/flwrlabs/flower/tree/main/examples/xgboost-quickstart)
-- [Quickstart (CatBoost)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-catboost)
-
-Other [examples](https://github.com/flwrlabs/flower/tree/main/examples):
-
-- [Raspberry Pi & Nvidia Jetson Tutorial](https://github.com/flwrlabs/flower/tree/main/examples/embedded-devices)
-- [PyTorch: From Centralized to Federated](https://github.com/flwrlabs/flower/tree/main/examples/pytorch-from-centralized-to-federated)
-- [Vertical FL](https://github.com/flwrlabs/flower/tree/main/examples/vertical-fl)
-- [Federated Finetuning of OpenAI's Whisper](https://github.com/flwrlabs/flower/tree/main/examples/whisper-federated-finetuning)
-- [Federated Finetuning of Large Language Model](https://github.com/flwrlabs/flower/tree/main/examples/flowertune-llm)
-- [Federated Finetuning of a Vision Transformer](https://github.com/flwrlabs/flower/tree/main/examples/flowertune-vit)
-- [Advanced Flower with PyTorch](https://github.com/flwrlabs/flower/tree/main/examples/advanced-pytorch)
-- [Comprehensive Flower+XGBoost](https://github.com/flwrlabs/flower/tree/main/examples/xgboost-comprehensive)
-- [Flower with KaplanMeierFitter from the lifelines library](https://github.com/flwrlabs/flower/tree/main/examples/federated-kaplan-meier-fitter)
-- [Sample Level Privacy with Opacus](https://github.com/flwrlabs/flower/tree/main/examples/opacus)
-- [Flower with a Tabular Dataset](https://github.com/flwrlabs/flower/tree/main/examples/fl-tabular)
+- [Quickstart (TensorFlow)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-tensorflow)
+- [Quickstart (PyTorch)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pytorch)
+- [Quickstart (Hugging Face)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-huggingface)
+- [Quickstart (PyTorch Lightning)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pytorch-lightning)
+- [Quickstart (fastai)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-fastai)
+- [Quickstart (Pandas)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pandas)
+- [Quickstart (JAX)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-jax)
+- [Quickstart (MONAI)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-monai)
+- [Quickstart (scikit-learn)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-sklearn)
+- [Quickstart (Android [TFLite])](https://github.com/flwrlabs/flower/tree/main/hub/apps/android)
+- [Quickstart (iOS [CoreML])](https://github.com/flwrlabs/flower/tree/main/hub/apps/ios)
+- [Quickstart (MLX)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-mlx)
+- [Quickstart (XGBoost)](https://github.com/flwrlabs/flower/tree/main/hub/apps/xgboost-quickstart)
+- [Quickstart (CatBoost)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-catboost)
+
+Other [examples](https://github.com/flwrlabs/flower/tree/main/hub/apps):
+
+- [Raspberry Pi & Nvidia Jetson Tutorial](https://github.com/flwrlabs/flower/tree/main/hub/apps/embedded-devices)
+- [Vertical FL](https://github.com/flwrlabs/flower/tree/main/hub/apps/vertical-fl)
+- [Federated Finetuning of OpenAI's Whisper](https://github.com/flwrlabs/flower/tree/main/hub/apps/whisper-federated-finetuning)
+- [Federated Finetuning of Large Language Model](https://github.com/flwrlabs/flower/tree/main/hub/apps/flowertune-llm)
+- [Federated Finetuning of a Vision Transformer](https://github.com/flwrlabs/flower/tree/main/hub/apps/flowertune-vit)
+- [Advanced Flower with PyTorch](https://github.com/flwrlabs/flower/tree/main/hub/apps/advanced-pytorch)
+- [Comprehensive Flower+XGBoost](https://github.com/flwrlabs/flower/tree/main/hub/apps/xgboost-comprehensive)
+- [Flower with KaplanMeierFitter from the lifelines library](https://github.com/flwrlabs/flower/tree/main/hub/apps/federated-kaplan-meier-fitter)
+- [Sample Level Privacy with Opacus](https://github.com/flwrlabs/flower/tree/main/hub/apps/opacus)
+- [Flower with a Tabular Dataset](https://github.com/flwrlabs/flower/tree/main/hub/apps/fl-tabular)
 
 ## Community
 

datasets/README.md

@@ -10,7 +10,7 @@ Flower Datasets (`flwr-datasets`) is a library to quickly and easily create data
 
 
 > [!TIP]
-> For complete documentation that includes API docs, how-to guides and tutorials, please visit the [Flower Datasets Documentation](https://flower.ai/docs/datasets/) and for full FL example see the [Flower Examples page](https://github.com/flwrlabs/flower/tree/main/examples).
+> For complete documentation that includes API docs, how-to guides and tutorials, please visit the [Flower Datasets Documentation](https://flower.ai/docs/datasets/) and for full FL example see the [Flower Examples page](https://github.com/flwrlabs/flower/tree/main/hub/apps).
 
 ## Installation
 

datasets/docs/source/recommended-fl-datasets.rst

@@ -5,7 +5,7 @@ This page lists the recommended datasets for federated learning research, which
 used with Flower Datasets ``flwr-datasets``. To learn about the library, see the
 `quickstart tutorial <https://flower.ai/docs/datasets/tutorial-quickstart.html>`_ . To
 see the full FL example with Flower and Flower Datasets open the `quickstart-pytorch
-<https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pytorch>`_.
+<https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pytorch>`_.
 
 .. note::
 

dev/devtool/build_example_docs.py

@@ -195,7 +195,7 @@ def _copy_markdown_files(example: str) -> None:
 def _add_gh_button(example: str) -> None:
     gh_text = (
         '[<img src="_static/view-gh.png" alt="View on GitHub" width="200"/>]'
-        f"(https://github.com/flwrlabs/flower/blob/main/examples/{example})"
+        f"(https://github.com/flwrlabs/flower/blob/main/hub/apps/{example})"
     )
     readme_file = os.path.join(str(ROOT), "examples", "docs", "source", example + ".md")
     with open(readme_file, "r+", encoding="utf-8") as f:
@@ -221,7 +221,7 @@ def _copy_images(example: str) -> None:
 
 
 def _add_all_entries() -> None:
-    examples_dir = os.path.join(ROOT, "examples")
+    examples_dir = os.path.join(ROOT, "hub", "apps")
     for example in sorted(os.listdir(examples_dir)):
         example_path = os.path.join(examples_dir, example)
         if os.path.isdir(example_path) and example != "docs":
@@ -237,7 +237,7 @@ def _main() -> None:
     with INDEX.open("w", encoding="utf-8") as index_file:
         index_file.write(INITIAL_TEXT)
 
-    examples_dir = os.path.join(ROOT, "examples")
+    examples_dir = os.path.join(ROOT, "hub", "apps")
     for example in sorted(os.listdir(examples_dir)):
         example_path = os.path.join(examples_dir, example)
         if os.path.isdir(example_path) and example != "docs":

dev/format.sh

@@ -5,15 +5,15 @@ cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"/
 
 taplo fmt
 
-# Examples
-# Iterate over all example directories
-for dir in ../examples/*/; do
+# Apps
+# Iterate over all app directories
+for dir in ../hub/apps/*/; do
     src_args=$(find "$dir" -maxdepth 1 -type d | sed 's/^/--src /' | tr '\n' ' ')
     python -m isort $dir $src_args --settings-path . &
 done
 wait
-python -m black -q ../examples
-python -m docformatter -i -r ../examples
+python -m black -q ../hub
+python -m docformatter -i -r ../hub
 
 # Benchmarks
 python -m isort ../benchmarks
@@ -22,7 +22,7 @@ python -m docformatter -i -r ../benchmarks
 
 # Notebooks
 KEYS="metadata.celltoolbar metadata.language_info metadata.toc metadata.notify_time metadata.varInspector metadata.accelerator metadata.vscode cell.metadata.id cell.metadata.heading_collapsed cell.metadata.hidden cell.metadata.code_folding cell.metadata.tags cell.metadata.init_cell cell.metadata.vscode cell.metadata.pycharm"
-python -m nbstripout ../examples/*/*.ipynb --extra-keys "$KEYS"
+python -m nbstripout ../hub/apps/*/*.ipynb --extra-keys "$KEYS"
 
 # Markdown
-python -m mdformat --number ../examples
+python -m mdformat --number ../hub

dev/test.sh

@@ -9,7 +9,7 @@ echo "- Start Python checks"
 
 echo "- isort: start"
 pids=()
-for dir in ../examples/*/; do
+for dir in ../hub/apps/*/; do
     src_args=$(find "$dir" -maxdepth 1 -type d | sed 's/^/--src /' | tr '\n' ' ')
     python -m isort --check-only $dir $src_args --settings-path . &
     pids+=($!)
@@ -23,23 +23,23 @@ python -m isort --check-only ../benchmarks
 echo "- isort: done"
 
 echo "- black: start"
-python -m black --check ../benchmarks ../examples
+python -m black --check ../benchmarks ../hub
 echo "- black: done"
 
 echo "- All Python checks passed"
 
 echo "- Start Markdown checks"
 
 echo "- mdformat: start"
-python -m mdformat --check --number ../examples
+python -m mdformat --check --number ../hub
 echo "- mdformat: done"
 
 echo "- All Markdown checks passed"
 
 echo "- Start TOML checks"
 
 echo "- taplo: start"
-taplo fmt --check ../benchmarks ../examples
+taplo fmt --check ../benchmarks ../hub
 echo "- taplo: done"
 
 echo "- All TOML checks passed"

framework/README.md

@@ -113,33 +113,32 @@ Several code examples show different usage scenarios of Flower (in combination w
 
 Quickstart examples:
 
-- [Quickstart (TensorFlow)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-tensorflow)
-- [Quickstart (PyTorch)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pytorch)
-- [Quickstart (Hugging Face)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-huggingface)
-- [Quickstart (PyTorch Lightning)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pytorch-lightning)
-- [Quickstart (fastai)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-fastai)
-- [Quickstart (Pandas)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-pandas)
-- [Quickstart (JAX)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-jax)
-- [Quickstart (MONAI)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-monai)
-- [Quickstart (scikit-learn)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-sklearn)
-- [Quickstart (Android [TFLite])](https://github.com/flwrlabs/flower/tree/main/examples/android)
-- [Quickstart (iOS [CoreML])](https://github.com/flwrlabs/flower/tree/main/examples/ios)
-- [Quickstart (MLX)](https://github.com/flwrlabs/flower/tree/main/examples/quickstart-mlx)
-- [Quickstart (XGBoost)](https://github.com/flwrlabs/flower/tree/main/examples/xgboost-quickstart)
-
-Other [examples](https://github.com/flwrlabs/flower/tree/main/examples):
-
-- [Raspberry Pi & Nvidia Jetson Tutorial](https://github.com/flwrlabs/flower/tree/main/examples/embedded-devices)
-- [PyTorch: From Centralized to Federated](https://github.com/flwrlabs/flower/tree/main/examples/pytorch-from-centralized-to-federated)
-- [Vertical FL](https://github.com/flwrlabs/flower/tree/main/examples/vertical-fl)
-- [Federated Finetuning of OpenAI's Whisper](https://github.com/flwrlabs/flower/tree/main/examples/whisper-federated-finetuning)
-- [Federated Finetuning of Large Language Model](https://github.com/flwrlabs/flower/tree/main/examples/flowertune-llm)
-- [Federated Finetuning of a Vision Transformer](https://github.com/flwrlabs/flower/tree/main/examples/flowertune-vit)
-- [Advanced Flower with PyTorch](https://github.com/flwrlabs/flower/tree/main/examples/advanced-pytorch)
-- [Comprehensive Flower+XGBoost](https://github.com/flwrlabs/flower/tree/main/examples/xgboost-comprehensive)
-- [Flower with KaplanMeierFitter from the lifelines library](https://github.com/flwrlabs/flower/tree/main/examples/federated-kaplan-meier-fitter)
-- [Sample Level Privacy with Opacus](https://github.com/flwrlabs/flower/tree/main/examples/opacus)
-- [Flower with a Tabular Dataset](https://github.com/flwrlabs/flower/tree/main/examples/fl-tabular)
+- [Quickstart (TensorFlow)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-tensorflow)
+- [Quickstart (PyTorch)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pytorch)
+- [Quickstart (Hugging Face)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-huggingface)
+- [Quickstart (PyTorch Lightning)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pytorch-lightning)
+- [Quickstart (fastai)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-fastai)
+- [Quickstart (Pandas)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-pandas)
+- [Quickstart (JAX)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-jax)
+- [Quickstart (MONAI)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-monai)
+- [Quickstart (scikit-learn)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-sklearn)
+- [Quickstart (Android [TFLite])](https://github.com/flwrlabs/flower/tree/main/hub/apps/android)
+- [Quickstart (iOS [CoreML])](https://github.com/flwrlabs/flower/tree/main/hub/apps/ios)
+- [Quickstart (MLX)](https://github.com/flwrlabs/flower/tree/main/hub/apps/quickstart-mlx)
+- [Quickstart (XGBoost)](https://github.com/flwrlabs/flower/tree/main/hub/apps/xgboost-quickstart)
+
+Other [examples](https://github.com/flwrlabs/flower/tree/main/hub/apps):
+
+- [Raspberry Pi & Nvidia Jetson Tutorial](https://github.com/flwrlabs/flower/tree/main/hub/apps/embedded-devices)
+- [Vertical FL](https://github.com/flwrlabs/flower/tree/main/hub/apps/vertical-fl)
+- [Federated Finetuning of OpenAI's Whisper](https://github.com/flwrlabs/flower/tree/main/hub/apps/whisper-federated-finetuning)
+- [Federated Finetuning of Large Language Model](https://github.com/flwrlabs/flower/tree/main/hub/apps/flowertune-llm)
+- [Federated Finetuning of a Vision Transformer](https://github.com/flwrlabs/flower/tree/main/hub/apps/flowertune-vit)
+- [Advanced Flower with PyTorch](https://github.com/flwrlabs/flower/tree/main/hub/apps/advanced-pytorch)
+- [Comprehensive Flower+XGBoost](https://github.com/flwrlabs/flower/tree/main/hub/apps/xgboost-comprehensive)
+- [Flower with KaplanMeierFitter from the lifelines library](https://github.com/flwrlabs/flower/tree/main/hub/apps/federated-kaplan-meier-fitter)
+- [Sample Level Privacy with Opacus](https://github.com/flwrlabs/flower/tree/main/hub/apps/opacus)
+- [Flower with a Tabular Dataset](https://github.com/flwrlabs/flower/tree/main/hub/apps/fl-tabular)
 
 ## Community
 

framework/dev/update_version.py

@@ -24,7 +24,7 @@
 }
 
 EXAMPLES = {
-    "examples/**/pyproject.toml": [
+    "hub/apps/**/pyproject.toml": [
         "flwr[simulation]>={version}",
         "flwr[simulation]=={version}",
         "flwr>={version}",

framework/docs/source/contributor-how-to-set-up-a-virtual-env.rst

@@ -25,8 +25,8 @@ Flower requires at least `Python 3.10 <https://docs.python.org/3.10/>`_.
 
 One of the recommended virtual environment is `pyenv
 <https://github.com/pyenv/pyenv>`_/`virtualenv
-<https://github.com/pyenv/pyenv-virtualenv>`_. Please see `Flower examples
-<https://github.com/flwrlabs/flower/tree/main/examples/>`_ for details.
+<https://github.com/pyenv/pyenv-virtualenv>`_. Please see `Flower apps
+<https://github.com/flwrlabs/flower/tree/main/hub/apps/>`_ for details.
 
 Once Pyenv is set up, you can use it to install `Python Version 3.10
 <https://docs.python.org/3.10/>`_ or above:

framework/docs/source/docker/run-quickstart-examples-docker-compose.rst

@@ -7,7 +7,7 @@
 ####################################################
 
 Flower provides a set of `quickstart examples
-<https://github.com/flwrlabs/flower/tree/main/examples>`_ to help you get started with
+<https://github.com/flwrlabs/flower/tree/main/hub/apps>`_ to help you get started with
 the framework. These examples are designed to demonstrate the capabilities of Flower and
 by default run using the Simulation Runtime. This guide demonstrates how to run them
 using Flower's Deployment Runtime via Docker Compose.
@@ -36,7 +36,7 @@ Before you start, make sure that:
    .. code-block:: bash
 
        $ git clone --depth=1 https://github.com/flwrlabs/flower.git \
-            && mv flower/examples/quickstart-pytorch . \
+            && mv flower/hub/apps/quickstart-pytorch . \
             && rm -rf flower && cd quickstart-pytorch
 
 2. Download the `compose.yml