README.md

---
title: BlossomTune Flower Superlink
emoji: 🌸
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: 5.44.1
app_file: blossomtune_gradio/__main__.py
pinned: false
hf_oauth: true
short_description: BlossomTune 🌸 Flower Superlink & Runner
---

# BlossomTune 🌸 Flower Superlink & Runner Orchestrator

Welcome to BlossomTune\! This application provides a comprehensive web-based orchestrator for managing federated learning (FL) experiments using Flower and Gradio.

It serves as a central control plane for administrators to manage the federation's infrastructure and for participants to securely join and receive their configurations.

## Project Overview

BlossomTune is designed to simplify the operational aspects of federated learning.

It provides a user-friendly interface that abstracts away the complexities of starting, monitoring, and managing the components of a Flower-based FL system.

The system manages a participant onboarding workflow, from initial request to admin approval, and provides the necessary connection details for approved participants to join the federated training process.

The project comes bundled with a sample federated learning application, `quickstart-huggingface`, which fine-tunes a `bert-tiny` model on the IMDB sentiment analysis dataset.

## Features

  * **Federated Learning Control**: Administrators can start and stop the core Flower `Superlink` and `Runner` processes directly from the UI.
  * **Participant Onboarding**: A dedicated tab allows new participants to request to join the federation by authenticating with their Hugging Face account and providing a contact email.
  * **Admin Panel**: A secure admin panel allows federation owners to review pending requests, approve or deny participants, and assign them to specific data partitions.
  * **Live Monitoring**: Provides a live, auto-scrolling log feed from the backend processes (`Superlink` and `Runner`) for real-time monitoring.
  * **Dynamic Configuration**: The system dynamically provides approved participants with the necessary connection details, their unique partition ID, and example commands to connect their client node.

## Setup and Installation

### Prerequisites

  * Python 3.11
  * Git

### Installation Steps

1.  **Clone the Repository**:

    ```bash
    git clone https://github.com/ethicalabs-ai/BlossomTune-Gradio.git
    cd BlossomTune-Flower-Superlink
    ```

2.  **Install Dependencies**:
    The project dependencies are defined in `pyproject.toml`. Install them using pip:

    ```bash
    pip install -e .
    ```

    This will install Gradio, Flower, Transformers, PyTorch, and other necessary packages.

3.  **(Optional) Setup Pre-commit Hooks**:
    This project uses `ruff` for code formatting and linting, managed via pre-commit hooks. To enable this, install pre-commit and set up the hooks:

    ```bash
    pip install pre-commit
    pre-commit install
    ```

## How to Run the Application

Launch the Gradio web interface by running:

```bash
python -m blossomtune_gradio
```

The application will be accessible via a local URL provided by Gradio.

## Generating Self-Signed Certificates for Local Development (Docker)

When running the application with `docker-compose`, the `superlink` service requires TLS certificates to enable secure connections.

For local development, you can generate a self-signed Certificate Authority (CA) and a `localhost` certificate using the provided script.

**Step 1: Run the Certificate Generator**

Execute the interactive TLS generation script located in the `blossomtune_gradio` directory:

```bash
python3 -m blossomtune_gradio.generate_tls
```

**Step 2: Choose the Development Option**

When prompted, select option **1** to generate a self-signed certificate for `localhost`.

```text
===== BlossomTune TLS Certificate Generator =====
Select an option:
  1. Generate a self-signed 'localhost' certificate (for Development)
  2. Generate a server certificate using the main CA (for Production)
  3. Exit
Enter your choice [1]: 1
```

The script will create a new directory named `certificates_localhost` containing the generated CA (`ca.crt`) and the server certificate files (`server.key`, `server.crt`, `server.pem`).

**Step 3: Copy Certificates to the Data Directory**

The `docker-compose.yml` file is configured to mount a local `./data/certs` directory into the `superlink` container. You must copy the essential certificate files into this location:

```bash
cp certificates_localhost/ca.crt ./data/certs/
cp certificates_localhost/server.key ./data/certs/
cp certificates_localhost/server.pem ./data/certs/
```

Once these files are in place, you can start the services using `docker compose up`.

The Superlink will automatically find and use these certificates to secure its connections.


## Usage Guide

### For Participants

1.  **Navigate to the "Join Federation" tab**.
2.  **Log in** using your Hugging Face account. On a Hugging Face Space, this is done via the login button.
3.  **Enter your contact email** and submit your request.
4.  You will receive an email with an **activation code**.
5.  Return to the "Join Federation" tab, enter the activation code, and submit it to activate your request.
6.  Once submitted and activated, your request will be **pending administrator review**. You can check your status on the same page.
7.  If **approved**, you will see the Superlink connection address and your assigned data partition ID, which you will use to configure your Flower client.

### For Administrators

1.  **Log in** with the Hugging Face account designated as the `SPACE_OWNER`. When running locally, admin controls are enabled by default.
2.  Navigate to the **"Admin Panel"** tab.
3.  **Start the Infrastructure**:
      * Click the "Start Superlink" button to launch the Flower Superlink process. Its status will change to "Running".
      * Select a "Runner App" (e.g., `flower_apps.quickstart_huggingface`), provide a "Run ID", and set the "Total Partitions".
      * Click "Start Federated Run" to launch the Flower Runner, which executes the federated learning strategy defined in the server app.
4.  **Manage Participant Requests**:
      * View pending requests in the "Pending Requests" table.
      * Click on a row to select a participant. Their ID will populate the management form, and a new partition ID will be suggested.
      * Click "Approve" or "Deny" to manage the request.

## Project Structure

The codebase is organized into two main packages: `blossomtune_gradio` (the web application) and `flower_apps` (the federated learning tasks).

```
└── BlossomTune-Gradio/
    ├── pyproject.toml              # Project metadata and dependencies for the orchestrator
    ├── .pre-commit-config.yaml     # Configuration for pre-commit hooks (ruff)
    ├── blossomtune_gradio/
    │   ├── __main__.py             # Makes the package runnable
    │   ├── config.py               # Application configuration from environment variables
    │   ├── database.py             # SQLite database initialization and schema
    │   ├── federation.py           # Logic for participant onboarding and management
    │   ├── gradio_app.py           # Defines the main Gradio UI layout and structure
    │   ├── processing.py           # Handles starting/stopping backend Flower processes
    │   └── ui/
    │       ├── auth.py             # Authentication logic (checks for space owner)
    │       ├── callbacks.py        # Callback functions for Gradio UI events
    │       └── components.py       # Reusable Gradio UI components
    └── flower_apps/
        └── quickstart_huggingface/
            ├── pyproject.toml      # Dependencies and config for this specific Flower app
            └── huggingface_example/
                ├── client_app.py   # Defines the Flower ClientApp
                ├── server_app.py   # Defines the Flower ServerApp
                └── task.py         # Defines the ML model, data loading, training, and evaluation
```