Metadata-Version: 2.4
Name: roleml-ai
Version: 0.3.1
Summary: A role-oriented programming model for distributed ML
Project-URL: repository, https://github.com/mrtan-ys/RoleML
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: schema
Requires-Dist: fasteners>=0.19
Requires-Dist: PyYAML
Requires-Dist: typing_extensions>=4.4.0
Provides-Extra: http
Requires-Dist: flask; extra == "http"
Requires-Dist: werkzeug; extra == "http"
Requires-Dist: charset-normalizer>=3; extra == "http"
Requires-Dist: requests; extra == "http"
Provides-Extra: grpc
Requires-Dist: grpcio; extra == "grpc"
Requires-Dist: grpcio-tools; extra == "grpc"
Provides-Extra: containerization
Requires-Dist: psutil; extra == "containerization"
Requires-Dist: docker; extra == "containerization"
Requires-Dist: podman; extra == "containerization"
Requires-Dist: sqlalchemy; extra == "containerization"
Provides-Extra: profiling
Requires-Dist: viztracer; extra == "profiling"
Provides-Extra: starter
Requires-Dist: grpcio; extra == "starter"
Requires-Dist: grpcio-tools; extra == "starter"
Requires-Dist: viztracer; extra == "starter"
Dynamic: license-file

# RoleML

_A programming model for edge distributed ML_

![PyPI Version](https://img.shields.io/pypi/v/roleml-ai?labelColor=blue&color=tomato)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/roleml-ai?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=BRIGHTGREEN&left_text=downloads)](https://pepy.tech/projects/roleml-ai)
![GitHub License](https://img.shields.io/github/license/mrtan-ys/roleml?labelColor=blue&color=cyan)
![Last Commit](https://img.shields.io/github/last-commit/mrtan-ys/roleml/main?labelColor=blue&color=wheat)
![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmrtan-ys%2FRoleML%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&labelColor=blue&color=aliceblue)

---

Edge AI aims to enable distributed machine learning (DML) on edge resources to fulfill the need for data privacy and low latency. Meanwhile, the challenge of device heterogeneity and discrepancy in data distribution requires more sophisticated DML architectures that differ in topology and communication strategy. This calls for a _standardized and general programming interface and framework_ that provides support for easy development and testing of various DML architectures. Existing frameworks like FedML are designed for specific architectures (e.g. Federated Learning) and do not support users to customize new architectures on them.

RoleML is introduced as a novel, general-purpose **role-oriented programming model** for the development of DML architectures. RoleML breaks a DML architecture into a series of interactive components and represents them with a unified abstraction named _role_. Each role defines its behavior with three types of message _channels_, and uses _elements_ to specify the workloads in a modular manner and decouple them from the distributed training workflow. Powered by a runtime system, RoleML allows developers to flexibly and dynamically assign roles to different computation nodes, simplifying the implementation of complex architectures. We further provide an automatic role offloading mechanism based on containerization to enhance the reliability of DML applications.

## Installation

You can install RoleML via pip:

```shell
pip install roleml-ai[starter]
```

The `[starter]` extra is recommended for beginners. This will include dependencies for the gRPC communication backend, as well as a profiling tool `viztracer` for performance analysis.

Other extras available include:

* __grpc__: support for gRPC communication backend.
* __http__: support for HTTP communication backend.
* __profiling__: a profiling tool named `viztracer`, which is required to run the bundled profiling helper scripts.
* __containerization__: support for containerized mode powered by Docker (requires Python 3.11 or higher).

Alternatively, if you wish to customize the RoleML package, you can clone this repository and make an editable installation:

```shell
pip install -e path/to/roleml/source/directory[grpc]    # + dependencies for gRPC backend
```

> The list of available extras may change. Please check `pyproject.toml` for any latest update.

For a minimal installation (without communication backend dependencies):

```shell
# PyPI installation
pip install roleml-ai
# editable installation
pip install -e path/to/roleml/source/directory
```

### Other Dependencies

To run the examples in the `examples` directory, `PyTorch` is required. Please refer to its [official website]((https://pytorch.org/get-started/locally/)) for installation commands.

## Getting Started

* [Run a helloworld application](./docs/helloworld.ipynb) (requires Jupyter)
* [RoleML in 100 minutes](./docs/LEARN.ipynb) is a Jupyter notebook to help you learn RoleML while constructing a Federated Learning (FL) application.
* Also see the built-in examples in the `examples` directory. Besides FL, Gossip Learning (GL), E-Tree Learning (EL), and more are included.
* Detailed documents can be found in the `docs` directory.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## Cite This Project

A technical paper describing the system is published on the Middleware 2024 conference. If you find this repository useful, please cite the paper in your work:

__Yuesheng Tan, Lei Yang, Wenhao Li, and Yuda Wu. 2024. RoleML: a Role-Oriented Programming Model for Customizable Distributed Machine Learning on Edges. In Proceedings of the 25th International Middleware Conference (Middleware '24). Association for Computing Machinery, New York, NY, USA, 279–291. https://doi.org/10.1145/3652892.3700765__

```bibtex
@inproceedings {roleml,
  title = {RoleML: a Role-Oriented Programming Model for Customizable Distributed Machine Learning on Edges},
  author = {Tan, Yuesheng and Yang, Lei and Li, Wenhao and Wu, Yuda},
  year = {2024},
  isbn = {9798400706233},
  publisher = {Association for Computing Machinery},
  address = {New York, NY, USA},
  booktitle = {Proceedings of the 25th International Middleware Conference},
  pages = {279–291},
  series = {Middleware '24}
}
```
