flip.flower.metrics

Flower metrics utilities — mirrors flip.nvflare.metrics for the Flower framework.

In Flower, clients return metrics in their reply Message via MetricRecord. The server-side strategy receives these in aggregate_train / aggregate_evaluate and should call handle_client_metrics to forward them to the Central Hub.

Only the fl-server should import from this module — it forwards to the Central Hub using credentials that must never reach the fl-client containers.

Usage (server-side, in a FedAvg strategy subclass):

from flip.flower.metrics import handle_client_metrics, handle_client_exception

def aggregate_train(self, server_round, replies):
for msg in replies:

handle_client_metrics(msg, server_round, self.model_id, self.flip) handle_client_exception(msg, self.model_id, self.flip)

return super().aggregate_train(server_round, replies)

Functions

handle_client_metrics() → None)

Forward per-client metrics from a Flower reply Message to the Central Hub.

handle_client_exception(, site_name)

Forward a crashed-client reply to the Central Hub and mark the run ERROR.

Module Contents

flip.flower.metrics.handle_client_metrics(msg: flwr.common.message.Message, server_round: int, model_id: str, flip: flip.FLIP = FLIP()) → None

Forward per-client metrics from a Flower reply Message to the Central Hub.

Extracts all numeric metrics from the client’s MetricRecord and sends each one to the Central Hub via flip.send_metrics. The metric label is converted to uppercase to match the FLIP convention (e.g. “train_loss” -> “TRAIN_LOSS”).

Metric keys following the “<label>[@<x_label>][.x_<V>]” pattern are split so each data point carries its own plot coordinate (a float x-value) and optional x-axis label, letting the Hub plot intra-round progress (e.g. “train_loss@epoch.x_5” -> label=”TRAIN_LOSS”, x_label=”epoch”, x_value=5.0). The FL global round is always recorded alongside as provenance and is the default plot coordinate for keys with no “.x_” suffix.

Only the fl-server should call this function — fl-clients must not hold the credentials needed to reach the Central Hub.

Parameters:

  • msg – A Flower reply Message from a client. Expected to contain a “metrics” MetricRecord and optionally a “config” ConfigRecord with a “site” key identifying the client.

  • server_round – The current server round number — recorded as every metric’s provenance global round, and the default plot coordinate for any metric that does not embed its own “.x_<V>” suffix.

  • model_id – The FLIP model ID. Validated by the underlying flip implementation when it reaches the Central Hub; the handler itself is tolerant so LOCAL_DEV runs with placeholder ids work.

  • flip – The FLIP instance used to reach the Central Hub.

flip.flower.metrics.handle_client_exception(msg: flwr.common.message.Message, model_id: str, flip: flip.FLIP = FLIP(), site_name: str | None = None) → None

Forward a crashed-client reply to the Central Hub and mark the run ERROR.

When a Flower client raises, the reply Message arrives with has_error() set. This helper both forwards the error string (so the Hub can display it alongside the model run) and transitions the run status to ERROR — without the latter, a crashed client would leave the Hub showing a still-running run indefinitely.

A crashed reply carries neither content nor a usable node id, so the caller may supply site_name (FlipFedAvg names the client by elimination). When the client cannot be identified the exception is reported model-level (client_name=None) rather than under a fabricated unknown_<node_id> name: hubs older than the round-telemetry release reject an unresolvable name outright (losing the traceback), and current hubs keep the row only as an “unattributed client” fallback — the fabricated name is noise either way.

Only the fl-server should call this function — fl-clients must not hold the credentials needed to reach the Central Hub.

Parameters:

  • msg – A Flower reply Message from a client.

  • model_id – The FLIP model ID. Validated by the underlying flip implementation when it reaches the Central Hub.

  • flip – The FLIP instance used to reach the Central Hub.

  • site_name – The client’s site, when the caller established it out-of-band.