FedBloom User Guide

Installation

Windows Installer (recommended)

Run from Source (developers)

# Clone the repository
git clone https://github.com/ziaurrehman-bit/FedBloom
cd FedBloom/files/fedbloom-stage-D/fedkit

# Install in editable mode
pip install -e .

# Launch
fedkit

First Launch

When FedBloom opens you will see the Welcome Screen. This is the starting point for every session.

Server vs Client

Every federated learning session has two types of participants:

Creating Experiments

Experiments are the core unit of work in FedBloom. Each experiment defines a complete FL training job.

Create a new experiment

Configuration reference

Datasets

Built-in datasets

FedBloom ships with several standard datasets for experimentation:

Custom CSV datasets

You can upload any CSV file as a dataset. FedBloom handles all preprocessing automatically:

• Last column is treated as the label / target
• Numeric columns are z-score normalised
• String/categorical columns are one-hot encoded
• Data is split 80/20 into train and test sets
• Rows are distributed across clients using the selected Partitioner

Models

FedBloom ships 30 federated-learning-ready models across five families. Every model already knows which aggregation strategy it needs — when you pick a model in the New Experiment wizard, the Aggregation strategy dropdown auto-switches to the right one. You normally never have to think about this — it's covered here so you understand why the dropdown changed.

Neural networks (general purpose)

Trained with gradient descent. Aggregated with FedAvg by default (FedAdam / FedYogi / FedMedian also work — see Aggregation Strategies).

Image classification (pretrained, TorchVision)

Industry-standard architectures with optional ImageNet-pretrained weights, fine-tuned federatedly. All use FedAvg.

Tabular deep learning

Tree-based & boosting models specialised aggregation

These don't have gradients — a decision tree is a sequence of yes/no splits, not a tensor of weights. Averaging two trees' numbers together produces nonsense, so FedBloom uses three purpose-built aggregation strategies instead of FedAvg for these models: FedForest, FedBoost, and FedBayes. Each is explained with a worked example in How Tree Models Aggregate below.

Linear & probabilistic models

Also sklearn-based (no gradients shared with Flower), but unlike trees their parameters are simple vectors that can be meaningfully averaged or combined exactly.

Aggregation Strategies

The aggregation strategy controls how the server combines what each client sends back into one improved global model. FedBloom's New Experiment wizard exposes 9 strategies — 4 work on any gradient-based model, 4 are auto-selected for sklearn/tree models (see How Tree Models Aggregate), and one handles non-IID clients.

How Tree Models Aggregate

Neural networks are made of numbers (weights) that live in a shared vector space — averaging two networks' weights gives you something meaningful in between. Trees, forests, and boosters aren't like that: a tree is a nested sequence of "if feature X < 5, go left" rules. Averaging two trees' split thresholds produces a tree that doesn't represent either client's logic. FedBloom solves this with three different strategies depending on what the model actually is.

FedForest — tree union (Decision Tree, Random Forest, Extra Trees)

Used for models that are themselves just "a bunch of trees that vote."

To predict a label, every tree in the pool votes for a class and the majority wins — exactly like a single Random Forest, just grown collaboratively across clients who never shared raw data.

FedBoost — best-client selection (XGBoost, HistGB, AdaBoost, LightGBM, CatBoost)

Boosting models build trees sequentially — each new tree corrects the previous tree's mistakes — so unlike a forest, you can't just throw all clients' trees into one pool; the sequence matters.

FedBayes — exact statistics fusion (Naive Bayes)

Naive Bayes is the one model in FedBloom with mathematically exact federated aggregation — zero accuracy loss compared to training on everyone's data pooled together.

# Parallel-variance formula FedBloom's server runs:
sigma2_global = sum(n_i * (sigma2_i + (mu_i - mu_global)**2)) / N_total

FedLinear — coefficient averaging (Ridge, Elastic Net, LinearSVC)

Linear models do have weights that live in a shared vector space (a coefficient per feature, plus an intercept), so — unlike trees — straightforward weighted averaging works well here, similar in spirit to FedAvg but operating on sklearn's coef_/intercept_ arrays instead of PyTorch tensors.

Partitioners

Partitioners control how data is distributed across clients — crucial for realistic experiments.

Running & Monitoring

Starting a run

Select an experiment from the list and click ▶ Start. FedBloom will:

1. Initialise the FL server and virtual clients (simulation) or wait for real clients (deployment)
2. Begin round 1 — each client trains locally and sends updates
3. Aggregate updates and broadcast the new global model
4. Repeat for all configured rounds

Live metrics dashboard

While training runs, the Charts tab shows live plots:

• Global accuracy — model accuracy on the global test set per round
• Global loss — training loss curve
• Precision / Recall / F1 — per-class metrics bar chart
• ROC curve — with AUC score
• Computation cost — seconds per round
• Communication cost — MB exchanged per round
• CPU / GPU utilisation — live resource usage
• Memory utilisation — RAM and GPU memory

Topology view

The Topology tab shows a visual graph of connected clients with their training status:

• Blue — idle / waiting
• Orange — training locally
• Green — completed, update sent
• Red — error

Results & Artefacts

Results tab

After training, the Results tab shows a table with per-client and global metrics for every round. You can export this as a CSV file.

Artefacts tab

The Artefacts tab lists all saved model files and metadata:

• training_metadata.json — full experiment configuration
• metrics_all_rounds.csv — all metrics for all rounds
• round_XXX_global_model.pkl — saved global model per round

Click Download Bundle to export all artefacts as a ZIP.

Settings

Open Settings from the sidebar to control appearance, simulation behaviour, email, and licensing. The most important option to understand is the simulation backend toggle, explained below.

Simulation backend — "Use Ray multi-process backend"

When you run a simulation experiment, FedBloom has two ways to run the virtual clients on your machine. This checkbox in Settings → Simulation switches between them.

Which should you choose?

Windows — why to keep it OFF

If you enable the Ray backend on Windows, you may experience one or more of the following:

• Training freezes or crashes — Windows launches new processes differently from Linux/macOS. Each Ray worker process must fully reload all libraries from scratch, which can fail or get stuck, especially when PyTorch is involved.
• Windows Defender / Firewall prompts — Ray runs a small internal server on your machine to coordinate its worker processes. Windows often flags this and prompts you to allow the connection, which interrupts the training session.
• Zombie processes after stopping a run — If you stop a training run mid-way, Ray worker processes can get stuck in the background. You may need to open Task Manager to close them manually.
• No speed benefit — Even when it works, the overhead of launching and coordinating separate processes on Windows usually cancels out any parallelism benefit for typical experiment sizes.

Does "OFF" mean slower training?

Not meaningfully for typical use. Running clients sequentially means your machine still uses all its CPU/GPU capacity — it's just doing one virtual client at a time rather than several simultaneously. For experiments with 2–50 clients and 5–30 rounds, the difference in total wall-clock time is rarely noticeable. The sequential mode is what FedBloom was built and tested on for Windows.

Local Network Deployment

When all participants are on the same WiFi or LAN:

Tailscale VPN (cross-network)

For participants on different networks (e.g., different hospitals, home offices):

1. Install Tailscale on every machine.
2. All machines join the same Tailscale network (or a shared Tailnet).
3. Use the machine's Tailscale IP (e.g., 100.x.x.x) as the server address.
4. No port forwarding or firewall rules needed — Tailscale handles NAT traversal.

Public IP + Port Forwarding

If Tailscale is not an option:

1. Find your server's public IP (search "what is my IP" in a browser).
2. In your router, create a port forward rule: external port → server machine's local IP, port 8080.
3. Ensure your OS firewall allows inbound connections on port 8080.
4. Clients connect using your public IP and the forwarded port.

Hyperparameter Optimisation (HPO) Pro

HPO automatically searches for the best training configuration. Navigate to HPO in the sidebar:

1. Select the experiment to optimise.
2. Choose the metric to maximise (accuracy, F1) or minimise (loss).
3. Define search ranges for learning rate, batch size, local epochs.
4. Set the number of trials and click Run HPO.
5. Results show the best configuration — apply it to your experiment with one click.

Privacy & Security Pro

Differential Privacy (DP-SGD)

Enable DP in the experiment configuration to add mathematically guaranteed privacy noise to client updates. This prevents the server from reconstructing raw training data from model weights.

• Noise multiplier — higher = more privacy, lower accuracy
• Max grad norm — clips gradients before adding noise

Robustness against bad clients

FedBloom has two aggregation strategies for this (see Aggregation Strategies):

• FedMedian — element-wise median of client updates instead of the mean. Cheap, always-on protection: a misbehaving client's update gets outvoted rather than blended in.
• Krum — scores every client by distance to its nearest neighbours and keeps only the most consistent client(s), discarding anything that looks like an outlier entirely. Stronger guarantee, more compute (needs at least 3 participating clients).

AI Assistant Advanced

The AI Assistant (powered by a local Ollama LLM) helps you interpret experiment results, suggest configurations, and explain model behaviour.

Setup

1. Install Ollama from ollama.com.
2. Pull a model: ollama pull llama3
3. In FedBloom Settings, set the Ollama base URL (default: http://localhost:11434) and model name.

Open the Assistant section in the sidebar to start a conversation about your experiments.

Plans & Licensing

Activate your plan in the Subscription & Account section by signing in with Google (auto-applies your plan) or by entering the license key received after purchase.

Use Case: Healthcare

Use Case: Finance & Banking

Use Case: Genomics

Use Case: Insurance

Use Case: Academic Research