flwr new @flwrlabs/fed-fin-fraud

Federated Financial Fraud Detection with PyTorch and Flower

This example demonstrates federated learning for financial fraud detection using Flower and PyTorch on a tabular transaction dataset.

It uses a federated version of the PaySim dataset (flwrlabs/fed-fraud-paysim-banks) and supports both:

• IID partitioning
• Natural partitioning by bank (BankID)

The project includes:

• A multi-layer perceptron (MLP) model with LayerNorm and dropout
• Feature preprocessing (normalization + feature engineering + one-hot encoding)
• Handling of class imbalance via weighted sampling and loss weighting
• Evaluation across multiple classification thresholds

Fetch the App

Install Flower:

pip install flwr

Fetch the app:

flwr new @flwrlabs/fed-fin-fraud

Then, install dependencies:

cd fed-fin-fraud && pip install -e .

Project structure:

fed-fin-fraud
├── fed_fraud
│   ├── __init__.py
│   ├── client_app.py   # Client-side training logic
│   ├── server_app.py   # Server-side orchestration and evaluation
│   └── task.py         # Model, preprocessing, training, evaluation
├── pyproject.toml      # Dependencies and configuration
└── README.md

Run the App

You can run this Flower App in both simulation and deployment mode.

Run with the Simulation Engine

In simulation mode:

• Dataset is automatically loaded from Hugging Face

• Training data is partitioned across clients:

  • iid → random split
  • natural → grouped by BankID

Run with default configuration:

flwr run .

Override configuration (example):

flwr run . --run-config "num-server-rounds=5 batch-size=512"

Key configuration options (from pyproject.toml):

• seed: base random seed for deterministic server and client execution (default: 42)
• num-server-rounds: number of FL rounds
• local-epochs: local training epochs
• batch-size: training batch size
• hidden-dim-1, hidden-dim-2: model size
• dropout: dropout rate
• use-class-weights: handle class imbalance
• partitioner: iid or natural
• learning-rate-max/min: cosine annealing schedule

For a reproducible run with a different seed:

PYTHONHASHSEED=2026 flwr run . --run-config "seed=2026"

The server uses the base seed, while each client round receives a stable seed derived from the base seed, client partition, and server round. Deterministic PyTorch kernels are required; the run fails instead of silently using a known nondeterministic kernel. Exact replay also requires the same data, participating clients, dependency versions, hardware, and runtime configuration.

The seed must be an integer between 0 and 4294967295. The run seed controls model initialization, training randomness, and client sampling. Dataset partitioning keeps its existing fixed seed so seed sweeps compare the same client data. Sampling and aggregation use sorted Flower node IDs, so exact replay requires the same node-ID-to-partition mapping and client availability. For local data, the client seed uses partition-id when provided, otherwise data-path; give clients distinct stable identities to obtain distinct streams. Set PYTHONHASHSEED before starting the ServerApp and ClientApp runtimes (including remote workers), since setting it in an already running interpreter has no effect on that interpreter's hash seed. Timing and memory metrics are not deterministic.

Model

The model is a fully connected neural network (MLP):

• Input: engineered tabular features

• Two hidden layers with:

  • LayerNorm (optional)
  • ReLU activation
  • Dropout

• Output: single logit for binary classification

Data Pipeline

Dataset:

• flwrlabs/fed-fraud-paysim-banks

Processing steps:

1. Standardization of numeric features

2. Feature engineering:

   • balance deltas
   • transaction inconsistencies

3. One-hot encoding of transaction type

4. Construction of final feature vector

Class imbalance handling:

• Weighted sampling (WeightedRandomSampler)
• Optional pos_weight in loss function

Supports:

• Simulation mode via FederatedDataset
• Deployment mode via load_from_disk

Training

Each client:

• Receives global model weights

• Trains locally using:

  • BCEWithLogitsLoss
  • Optional class weighting
  • Gradient clipping

• Uses cosine annealing learning rate schedule

Evaluation

Server-side evaluation:

• Uses centralized test split

• Computes metrics at multiple thresholds:

  • Accuracy
  • Precision
  • Recall
  • F1-score
  • PR-AUC (average precision)

Thresholds evaluated:

0.05, 0.1, 0.2, 0.5, 0.8, 0.9, 0.95, 0.99

Run with the Deployment Engine

To run in deployment mode, prepare local dataset partitions.

Step 1: Prepare data

Partition and store the dataset locally (e.g., using Flower Datasets or custom pipeline).

Step 2: Start SuperNodes

flower-supernode \
    --insecure \
    --superlink <SUPERLINK-FLEET-API> \
    --node-config="data-path=/path/to/local_partition"

Step 3: Run federation

flwr run . <SUPERLINK-CONNECTION> --stream

Benchmarking and System Metrics

This app writes a benchmark summary next to the standard Flower result pickle:

result_<run-name>_communication.json

The summary includes per-round and total communication volume:

• total_comm_bytes
• comm_bytes_total per training round

Enable system metric tracking with:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-system-metrics=true"

When enabled, the benchmark summary also includes:

• client_train_time_sec
• server_aggregation_time_sec
• round_wall_clock_sec
• client_peak_cpu_memory_mb
• client_peak_gpu_memory_mb

Server-side centralized evaluation can be disabled for benchmark-only runs:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-run-server-eval=false"

Dataset Fingerprint Verification

FedFinFraud supports a preflight dataset fingerprint check before training. Enable it with:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-verify-dataset=true"

The server asks each connected client for its partition metadata, then verifies:

• expected client count
• partition IDs
• dataset version
• number of examples
• dataset fingerprint

The verification result is written into result_<run-name>_communication.json under verification. If any partition does not match the benchmark manifest, the run fails before training.

Expected deployment fingerprints for flwrlabs/fed-fraud-paysim-banks with natural partitioning:

Client	Partition ID	Examples	Dataset fingerprint
0	0	1374326	c35c860d5f75655c0b53312ba8a5b555eeb97b20ac3610b8aabec724e69ef1f7
1	1	1202535	b3cc17127b78219d7a8d18c60bb88fc59f041012acef3ef5efa37a64ba42cd3f
2	2	1145272	d311265f241964508546973919ee804d1f19615d464cf5819f40e6a1daf06d06
3	3	1030745	3c22c4e9d5ffebed3076b86bbfa330f9425431237a4c74a8ce06511346c821bc
4	4	973480	cf41d0946d13478a69785086a252ac6a4d0e1a1ba77943eb587b77abdba647f9

Notes

• Designed for highly imbalanced fraud detection
• Uses PR-AUC as a key evaluation metric
• Supports both research (simulation) and real-world deployment
• Automatically uses GPU if available