flip.schemas

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

DEFAULT_X_AXIS_LABEL

Classes

`FLLogEvent`	Typed FL progress events for `POST /model/{id}/logs`.
`TrainingMetrics`	A single training/evaluation metric value reported for one FL client.
`TrainingLog`	One row for `POST /model/{id}/logs`: free text XOR a typed round event.

Functions

split_x_label(→ tuple[str, str | None])

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

Module Contents

flip.schemas.DEFAULT_X_AXIS_LABEL = 'Global Rounds'

flip.schemas.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).

Parameters:: key (str) – The metric key, e.g. "train_loss@epoch" or "train_loss".
Returns:: The bare label and the x-label (None when the key has none).
Return type:: tuple[str, str | None]

class flip.schemas.FLLogEvent

Bases: 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).

ROUND_STARTED = 'ROUND_STARTED'

CLIENT_RESULT_RECEIVED = 'CLIENT_RESULT_RECEIVED'

ROUND_AGGREGATED = 'ROUND_AGGREGATED'

class flip.schemas.TrainingMetrics

Bases: 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.

fl_client_name: str

global_round: int

label: str

result: float

x_value: float

x_label: str

classmethod _default_x_value_to_global_round(data: Any) → Any: Backfill a missing/None x_value from global_round (back-compat with old senders).

class flip.schemas.TrainingLog

Bases: 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).

fl_client_name: str | None = None

log: str | None = None

event_type: str | None

global_round: int | None

details: dict[str, Any] | None = None

success: bool = True

_log_xor_event() → TrainingLog

_bound_details() → TrainingLog