flip.flower.strategy
====================

.. py:module:: flip.flower.strategy

.. autoapi-nested-parse::

   FLIP's Flower base strategy — FedAvg plus Central Hub telemetry.

   ``FlipFedAvg`` is the durable home for everything a FLIP Flower server app
   reports to the hub: the RUNNING status, per-client metric and
   exception forwarding (``flip.flower.metrics``), and the typed round events
   (``flip.flower.progress``). App templates subclass it and keep only their
   app-specific behaviour; the telemetry evolves here, in flip-utils, without
   touching uploaded apps.

   Round events attach to the phase the strategy actually runs: training rounds
   emit around configure_train/aggregate_train; an evaluation-only strategy
   (``fraction_train=0.0``) emits around the evaluate phase instead, so every job
   type yields a coherent round timeline without double-emission.

   Unlike the rest of ``flip.flower``, importing this module requires the ``flwr``
   package (present in the Flower fl-server images) — it subclasses the real
   ``FedAvg``. Keep logic in the helpers; this class is wiring.



Classes
-------

.. autoapisummary::

   flip.flower.strategy.FlipFedAvg


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

.. py:class:: FlipFedAvg(flip: flip.FLIP, model_id: str, *args, **kwargs)

   Bases: :py:obj:`flwr.serverapp.strategy.FedAvg`


   FedAvg with FLIP hub telemetry: status, metrics/exceptions, round events.

   :param flip: FLIP instance used by the fl-server to reach the Central Hub.
   :param model_id: FLIP model ID (UUID) for the current run.
   :param \*args: Passed through to ``FedAvg``.
   :param \*\*kwargs: Passed through to ``FedAvg``.


   .. py:attribute:: flip


   .. py:attribute:: model_id


   .. py:attribute:: num_rounds
      :type:  int | None
      :value: None



   .. py:attribute:: _telemetry


   .. py:method:: start(grid: flwr.serverapp.Grid, initial_arrays: flwr.app.ArrayRecord, num_rounds: int = 3, **kwargs)

      Capture the round total and mark the run as executing on the hub.



   .. py:method:: configure_train(server_round: int, arrays: flwr.app.ArrayRecord, config: flwr.common.ConfigRecord, grid: flwr.serverapp.Grid) -> collections.abc.Iterable[flwr.app.Message]

      Dispatch the round's train tasks, reporting the round start.



   .. py:method:: aggregate_train(server_round: int, replies: collections.abc.Iterable[flwr.app.Message]) -> flwr.app.ArrayRecord | None

      Forward per-client telemetry, aggregate, then report the round aggregated.



   .. py:method:: configure_evaluate(server_round: int, arrays: flwr.app.ArrayRecord, config: flwr.common.ConfigRecord, grid: flwr.serverapp.Grid) -> collections.abc.Iterable[flwr.app.Message]

      Dispatch the round's evaluate tasks; owns the round events when nothing trains.



   .. py:method:: aggregate_evaluate(server_round: int, replies: collections.abc.Iterable[flwr.app.Message]) -> flwr.app.MetricRecord | None

      Forward per-client telemetry, aggregate, and close evaluation-only rounds.