Metadata-Version: 2.4
Name: fluke-fl
Version: 0.8.1
Summary: Federated Learning Utility framework for Experimentation and research.
Author-email: Mirko Polato <mirko.polato@unito.it>
License-Expression: LGPL-2.1-or-later
Project-URL: Documentation, https://makgyver.github.io/fluke
Project-URL: Repository, https://github.com/makgyver/fluke
Project-URL: Issues, https://github.com/makgyver/fluke/issues
Keywords: federated learning,deep learning,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: torch
Requires-Dist: torchmetrics
Requires-Dist: torchvision
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: wandb
Requires-Dist: datasets
Requires-Dist: psutil
Requires-Dist: tensorboard
Requires-Dist: clearml
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: diskcache
Requires-Dist: opacus
Requires-Dist: cerberus
Requires-Dist: hydra-core
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: omegaconf
Requires-Dist: coverage
Requires-Dist: pytest
Dynamic: license-file

![Coveralls](https://img.shields.io/coverallsCoverage/github/makgyver/fluke?style=for-the-badge&logo=coveralls)
<a href="https://makgyver.github.io/fluke"><img src="https://img.shields.io/github/actions/workflow/status/makgyver/fluke/doc-publish.yml?style=for-the-badge&label=DOCUMENTATION"/></a>
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fluke-fl?style=for-the-badge&logo=python&logoColor=yellow)
![GitHub License](https://img.shields.io/github/license/makgyver/fluke?style=for-the-badge)
<!-- [![arXiv](https://img.shields.io/badge/arxiv-2412.15728-b31b1b.svg?style=for-the-badge&logo=arxiv&logoColor=red)](https://arxiv.org/abs/2412.15728) -->
[![FGCS](https://img.shields.io/badge/-Elsevier-FF6C00?style=for-the-badge&logo=elsevier&logoColor=white)](https://www.sciencedirect.com/science/article/pii/S0167739X25005357)
![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)

# **fluke**: **f**ederated **l**earning **u**tility framewor**k** for **e**xperimentation and research

``fluke`` is a Python package that provides a framework for federated learning research. It is designed to be modular and extensible, allowing researchers to easily implement and test new federated learning algorithms. ``fluke`` provides a set of pre-implemented state-of-the-art federated learning algorithms that can be used as a starting point for research or as a benchmark for comparison.

## Installation

### Pypi

``fluke`` is a Python package that can be installed via pip. To install it, you can run the following command:

```bash
pip install fluke-fl
```

### Clone the repository

You can also install ``fluke`` by cloning the repository and installing it in editable mode. This is useful if you want to contribute to the development of ``fluke`` or if you want to use the latest version of the code.

```bash
git clone https://github.com/makgyver/fluke.git
cd fluke
pip install -e .
```

> [!WARNING]
> Due to a recent repository tree refactoring, if you cloned the repository before June 2025, you need to reclone it to get the latest version of the code.

### 🐳 Docker

You can use this library directly inside a Docker container — no installation needed on your local machine.

```bash
docker build -t fluke_container .
```

Then, you can run an interactive session with

```bash
docker run --rm fluke_container fluke [ARGS]
```

where `ARGS` are the arguments you want to pass to the `fluke` command as described in the next section.

## Run a federated algorithm

To run an algorithm in ``fluke`` you need to create two configuration files:
- `EXP_CONFIG`: the experiment configuration file (independent from the algorithm);
- `ALG_CONFIG`: the algorithm configuration file;

Then, you can run the following command:

```bash
fluke federation EXP_CONFIG ALG_CONFIG
```

You can find some examples of these files in the [configs](https://github.com/makgyver/fluke/tree/main/configs) folder of the repository.

### Example
Let say you want to run the classic `FedAvg` algorithm on the `MNIST` dataset. Then, using the configuration files [exp.yaml](https://github.com/makgyver/fluke/blob/main/configs/exp.yaml) and [fedavg.yaml](https://github.com/makgyver/fluke/blob/main/configs/fedavg.yaml), you can run the following command:

```bash
fluke federation path_to_folder/exp.yaml path_to_folder/fedavg.yaml
```

where `path_to_folder` is the path to the folder containing the configuration files.


## Documentation

The documentation for ``fluke`` can be found [here](https://makgyver.github.io/fluke). It contains detailed information about the package, including how to install it, how to run an experiment, and how to implement new algorithms.

## Tutorials

Tutorials on how to use ``fluke`` can be found [here](https://makgyver.github.io/fluke/tutorials.html). In the following, you can find some quick tutorials to get started with ``fluke``:

- Getting started with `fluke` API [![Open in Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=flat-square&logo=google-colab&logoColor=yellow&labelColor=gray)
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_quick_api.ipynb)
- Run your algorithm in ``fluke`` [![Open in Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=flat-square&logo=google-colab&logoColor=yellow&labelColor=gray)
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_alg.ipynb)
- Use your own model with `fluke` [![Open in Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=flat-square&logo=google-colab&logoColor=yellow&labelColor=gray)
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_nn.ipynb)
- Add your dataset and use it with ``fluke`` [![Open in Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=flat-square&logo=google-colab&logoColor=yellow&labelColor=gray)
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_dataset.ipynb)
- Add your custom evaluation metric in ``fluke`` [![Open in Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=flat-square&logo=google-colab&logoColor=yellow&labelColor=gray)
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_eval.ipynb)

## Contributing

If you have suggestions for how ``fluke`` could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the [Contributing Guide](CONTRIBUTING.md).

## `fluke` @ ECML-PKDD 2024

`fluke` has been presented at the [ECML-PKDD 2024](https://ecmlpkdd2024.org/) conference in the [Workshop on Advancements in Federated Learning](https://wafl2024.di.unito.it). The slides of the presentation are available [here](slides/fluke_ecmlpkdd2024.pdf).

## `fluke` @ ECAI 2025
On 25th October, we will deliver a tutorial on `fluke` at the 28th European Conference on Artificial Intelligence (ECAI). [Here](https://sites.google.com/view/fluketutorialecai25/home) the website of the tutorial. 

## Citing `fluke`
``fluke`` is a research tool, and we kindly ask you to cite it in your research papers if you use it. You can use the following BibTeX entry:

```bibtex
@article{fluke2025fgcs,
	title = {Fluke: Federated learning utility framework for experimentation and research},
	journal = {Future Generation Computer Systems},
	volume = {177},
	pages = {108241},
	year = {2026},
	issn = {0167-739X},
	doi = {https://doi.org/10.1016/j.future.2025.108241},
	url = {https://www.sciencedirect.com/science/article/pii/S0167739X25005357},
	author = {Mirko Polato}
}
```

## Authors and main contributors

- [**Mirko Polato**](https://makgyver.github.io) - *Idealization*, *Design*, *Development*, *Testing*, *Tutorial*, and *Documentation*
- [**Roberto Esposito**](https://github.com/boborbt) - *Testing*
- [**Samuele Fonio**](https://github.com/samuelefonio) - *Testing*, *Tutorial*
- [**Edoardo Oglietti**](https://github.com/00-uno-00) - *Testing*
