Metadata-Version: 2.4
Name: melody-flwr
Version: 0.0.1
Summary: A CLI wrapper for the Flower (flwr) framework
Author-email: James Friel <jfriel001@dundee.ac.uk>
Project-URL: Homepage, https://github.com/HicResearch/MELODY
Project-URL: Issues, https://github.com/HicResearch/MELODY/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flwr
Requires-Dist: sacroml
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Dynamic: license-file

# melody

`melody` is a command-line wrapper around the [Flower](https://flower.ai) federated
learning framework. It enforces provenance capture via
[flwrCrate](https://github.com/eScienceLab/flwrCrate), versions your app code in
a git repository on every run, and provides built-in access to
[SACRO-ML](https://github.com/AI-SDC/SACRO-ML) privacy attack assessment.

---

## Requirements

- Python 3.8 or later
- [Git](https://git-scm.com) available on your `PATH`
- A Flower app already set up with `flwrCrate` integrated (see
  [Flower app requirements](#flower-app-requirements) below)

---

## Installation

```bash
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`:

```toml
[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

```bash
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

```bash
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:
   ```bash
   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

```toml
[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](#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.

```bash
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`:

```bash
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`.

```bash
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.

```bash
melody gen-attack
```

---

### All other commands

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

```bash
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](https://github.com/eScienceLab/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:**

```bash
pip install flwrcrate
```

**2. Wrap your strategy in `server_app.py`:**

```python
from flwrcrate import FLCrateTracker

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

See the [flwrCrate README](https://github.com/eScienceLab/flwrCrate) for the
full list of `FLCrateTracker` arguments and the complete integration pattern.

---

## Typical workflow

```bash
# 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](#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:

```bash
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.
