flip.flower.metrics
===================

.. py:module:: flip.flower.metrics

.. autoapi-nested-parse::

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

.. autoapisummary::

   flip.flower.metrics.handle_client_metrics
   flip.flower.metrics.handle_client_exception


Module Contents
---------------

.. py:function:: 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").

   Per-epoch metric keys following the "<label>.round_<N>" pattern are split so
   each data point is recorded against its own round number, letting the Hub
   plot intra-round progress (e.g. "train_loss.round_5" -> label="TRAIN_LOSS",
   round=5).

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

   :param 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.
   :param server_round: The current server round number, used as the default
                        x-axis value for any metric that does not embed its own round.
   :param 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.
   :param flip: The FLIP instance used to reach the Central Hub.


.. py:function:: handle_client_exception(msg: flwr.common.message.Message, model_id: str, flip: flip.FLIP = FLIP()) -> 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.

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

   :param msg: A Flower reply Message from a client.
   :param model_id: The FLIP model ID. Validated by the underlying ``flip``
                    implementation when it reaches the Central Hub.
   :param flip: The FLIP instance used to reach the Central Hub.