melody

melody is a command-line wrapper around the Flower federated learning framework. It enforces provenance capture via flwrCrate, versions your app code in a git repository on every run, and provides built-in access to SACRO-ML privacy attack assessment.

---

Requirements

• Python 3.8 or later
• Git available on your PATH
• A Flower app already set up with flwrCrate integrated (see Flower app requirements below)

---

Installation

pip install melody-wrapper

This also installs flwr and sacroml as dependencies.

---

Quick start

1. Create a config file

Create melody.toml in the directory where you will run melody:

[git]
# Path to an existing git repository where your app code will be versioned.
# Must already be initialised with `git init`.
directory = "/path/to/your/snapshot/repo"

[sacroml]
# Paths used by `melody attack`. Can be overridden on the command line.
target_dir    = "./sacroml_target"
attack_config = "./attack.yaml"

2. Run your Flower app

melody run myapp/

melody will check that your app uses FLCrateTracker, copy the app code into your snapshot repo, commit it, then hand off to flwr run.

3. Assess your model

melody gen-target   # one-time setup: describe your model and data
melody gen-attack   # one-time setup: choose which attacks to run
melody attack       # run SACRO-ML privacy attacks

---

Configuration

melody reads a TOML config file. It is located in one of two ways:

1. Explicit flag — pass --config (or -c) before the subcommand:

   melody --config /path/to/melody.toml run myapp/

2. Auto-discovery — if no flag is given, melody looks for melody.toml in the current directory.

If no config file is found, melody still works but features that require config values (git snapshotting, default attack paths) will error unless you supply the required values as command-line arguments.

Full config reference

[git]
# Absolute or relative path to a git repository.
# `melody run` copies your app here and commits it before each run.
directory = "/path/to/snapshot/repo"

[sacroml]
# Default target directory for `melody attack` (contains target.yaml + model).
target_dir = "./sacroml_target"
# Default attack config file for `melody attack`.
attack_config = "./attack.yaml"

---

Commands

melody run [APP] [SUPERLINK] [OPTIONS]

Runs a Flower app. Before starting, melody:

1. Checks that the app uses FLCrateTracker — the run is blocked if it does not (see Flower app requirements).
2. Copies the app directory into your configured git snapshot repository and creates a commit if anything has changed.
3. Calls flwr run with your original arguments unchanged.

APP defaults to . (current directory) if omitted. All flwr run flags are supported and passed through as-is.

melody run                            # run app in current directory
melody run myapp/                     # run app in myapp/
melody run myapp/ -c run-config.toml  # pass a run config to flwr

---

melody attack [TARGET_DIR] [ATTACK_CONFIG] [OPTIONS]

Runs SACRO-ML privacy attacks against a trained model.

TARGET_DIR is the directory containing a target.yaml file and the serialised model (generated by melody gen-target). ATTACK_CONFIG is the YAML file specifying which attacks to run (generated by melody gen-attack).

Both arguments are optional if the corresponding values are set in melody.toml:

melody attack                             # use sacroml.target_dir and sacroml.attack_config from config
melody attack ./my_target ./my_attack.yaml  # override both on the command line

---

melody gen-target

Launches an interactive wizard (provided by SACRO-ML) that asks for your model file path, training and test data, and feature metadata. It writes a target.yaml file and serialises your model ready for attack.

Run this once after your first successful melody run.

melody gen-target

---

melody gen-attack

Launches an interactive wizard (provided by SACRO-ML) that lets you choose which privacy attacks to run and configure their parameters. It writes an attack.yaml file.

melody gen-attack

---

All other commands

Any subcommand not listed above is forwarded directly to flwr. For example:

melody new          # same as: flwr new
melody log          # same as: flwr log
melody --help       # same as: flwr --help

---

Flower app requirements

All apps run via melody run must use flwrCrate to capture provenance. melody will refuse to run an app that does not.

How to integrate flwrCrate

1. Add it to your app's dependencies:

pip install flwrcrate

2. Wrap your strategy in server_app.py:

from flwrcrate import FLCrateTracker

strategy = FLCrateTracker(context, your_strategy, output_dir="/path/to/output", ...)

See the flwrCrate README for the full list of FLCrateTracker arguments and the complete integration pattern.

---

Typical workflow

# 1. Initialise a snapshot repository (one-time setup)
git init /path/to/snapshot/repo

# 2. Create your melody.toml
cat > melody.toml << 'EOF'
[git]
directory = "/path/to/snapshot/repo"

[sacroml]
target_dir    = "./sacroml_target"
attack_config = "./attack.yaml"
EOF

# 3. Run your federated learning job
melody run myapp/
#  → flwrCrate check passes
#  → app code committed to snapshot repo
#  → flwr run executes

# 4. Set up SACRO-ML (one-time, after first successful run)
melody gen-target   # point at the model flwrCrate produced
melody gen-attack   # choose your attacks

# 5. Run privacy attacks
melody attack
#  → produces a report and vulnerability matrix in your output directory

---

Troubleshooting

melody: this app does not use FLCrateTracker

Your server_app.py (or another .py file in the app) must import and use FLCrateTracker from flwrcrate. See Flower app requirements.

melody: git.directory '...' not found

The path set in [git] directory does not exist. Create it and initialise it as a git repository:

git init /path/to/snapshot/repo

melody: config file not found: ...

The path passed to --config does not exist. Check the path or create an melody.toml in the current directory.

melody attack: target directory required

Either pass TARGET_DIR as an argument or set sacroml.target_dir in melody.toml. Run melody gen-target first if you have not set up the target yet.