flip.schemas
============

.. py:module:: flip.schemas

.. autoapi-nested-parse::

   Request schemas for the payloads the flip package POSTs to the Central Hub.

   These mirror the Pydantic models the hub validates against (flip-api
   ``domain/schemas/private.py``). They are separate codebases, so the two
   definitions must be kept in sync — the snake_case field names below are the
   on-the-wire contract for the ``/model/{id}/metrics`` and ``/model/{id}/logs``
   internal endpoints.



Attributes
----------

.. autoapisummary::

   flip.schemas.DEFAULT_X_AXIS_LABEL


Classes
-------

.. autoapisummary::

   flip.schemas.FLLogEvent
   flip.schemas.TrainingMetrics
   flip.schemas.TrainingLog


Functions
---------

.. autoapisummary::

   flip.schemas.split_x_label


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

.. py:data:: DEFAULT_X_AXIS_LABEL
   :value: 'Global Rounds'


.. py:function:: split_x_label(key: str) -> tuple[str, str | None]

   Split a metric key of the form ``<label>[@<x_label>]`` into ``(label, x_label)``.

   The ``@<x_label>`` segment names the x-axis a metric is plotted against (FLIP#148); absent, the
   x_label is ``None`` and the hub defaults it to "Global Rounds". Shared by every path that encodes
   the x-label inside a metric name (Flower MetricRecord keys, NVFLARE Client-API SummaryWriter tags).

   :param key: The metric key, e.g. ``"train_loss@epoch"`` or ``"train_loss"``.
   :type key: str

   :returns: The bare label and the x-label (``None`` when the key has none).
   :rtype: tuple[str, str | None]


.. py:class:: FLLogEvent

   Bases: :py:obj:`enum.StrEnum`


   Typed FL progress events for ``POST /model/{id}/logs``.

   The FL layer reports **facts** (event type + structured details); display
   text is composed hub-side at serve time, so wording changes are a flip-api
   redeploy and never an FL-image rebuild. Mirrors flip-api's
   ``domain/schemas/types.py::FLLogEvent``.

   Rounds are 1-based on every event, on both backends (NVFLARE's internal
   ``_current_round`` is 0-based and must be normalised before sending).


   .. py:attribute:: ROUND_STARTED
      :value: 'ROUND_STARTED'



   .. py:attribute:: CLIENT_RESULT_RECEIVED
      :value: 'CLIENT_RESULT_RECEIVED'



   .. py:attribute:: ROUND_AGGREGATED
      :value: 'ROUND_AGGREGATED'



.. py:class:: TrainingMetrics

   Bases: :py:obj:`pydantic.BaseModel`


   A single training/evaluation metric value reported for one FL client.

   ``fl_client_name`` is the FL client's identity as the FL server sees it —
   the FL participant name for NVFLARE, the SUPERNODE_NAME for Flower. The hub resolves
   it to a trust before storing the metric.

   ``global_round`` is provenance — always the FL global round the metric was reported in, never
   overridden. The plot coordinate is the (``x_label``, ``x_value``) pair, defaulting to the global
   round on the "Global Rounds" axis — see FLIP#148.


   .. py:attribute:: fl_client_name
      :type:  str


   .. py:attribute:: global_round
      :type:  int


   .. py:attribute:: label
      :type:  str


   .. py:attribute:: result
      :type:  float


   .. py:attribute:: x_value
      :type:  float


   .. py:attribute:: x_label
      :type:  str


   .. py:method:: _default_x_value_to_global_round(data: Any) -> Any
      :classmethod:


      Backfill a missing/None ``x_value`` from ``global_round`` (back-compat with old senders).



.. py:class:: TrainingLog

   Bases: :py:obj:`pydantic.BaseModel`


   One row for ``POST /model/{id}/logs``: free text XOR a typed round event.

   Mirrors flip-api's ``domain/schemas/private.py::TrainingLog`` — keep in sync.
   Free-text rows (``log`` set) carry exception reports verbatim; typed event
   rows (``event_type`` set) carry round-progress facts. ``fl_client_name`` is
   ``None`` for hub-attributed rows (e.g. ``ROUND_STARTED`` from the fl-server's
   own control flow).


   .. py:attribute:: fl_client_name
      :type:  str | None
      :value: None



   .. py:attribute:: log
      :type:  str | None
      :value: None



   .. py:attribute:: event_type
      :type:  str | None


   .. py:attribute:: global_round
      :type:  int | None


   .. py:attribute:: details
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: success
      :type:  bool
      :value: True



   .. py:method:: _log_xor_event() -> TrainingLog


   .. py:method:: _bound_details() -> TrainingLog