flip.core.standard

Standard FLIP Implementation.

This module contains the production and development implementations of FLIP for the standard, evaluation, and fed_opt job types.

Attributes

_HUB_POST_TIMEOUT_SECONDS

Classes

`FLIPStandardProd`	Production implementation of FLIP for standard job types.
`FLIPStandardDev`	Development implementation of FLIP for standard job types.

Functions

`_trust_internal_headers`(→ dict[str, str])	Return the auth header sent on every trust-internal call.
`_join_url`(→ str)	Join a base URL with a path, tolerating a trailing slash on the base.
`_hub_internal_headers`(→ dict[str, str])	Return the auth header sent on every hub-internal call.

Module Contents

flip.core.standard._HUB_POST_TIMEOUT_SECONDS: tuple[int, int] = (5, 30)

flip.core.standard._trust_internal_headers() → dict[str, str]

Return the auth header sent on every trust-internal call.

Used on outbound calls to imaging-api and data-access-api. The receiver (in the FLIP repo) compares the value with a constant-time compare against its own copy of the same per-trust key.

Returns:: Single-entry dict mapping the configured header name to the trust-internal service key.
Return type:: dict[str, str]

flip.core.standard._join_url(base: object, path: str) → str

Join a base URL with a path, tolerating a trailing slash on the base.

Pydantic v2 serializes a host-only HttpUrl with a trailing slash (e.g. http://data-access-api:8000/), so naive f-string concatenation with /cohort/dataframe yields a double slash (//cohort/dataframe) that Starlette does not route — producing a spurious 404 Not Found. Normalising the base before joining keeps every trust-internal and hub-internal call working regardless of whether the configured URL carries a trailing slash. See FLIP#652.

Parameters:

base – The base URL (str or pydantic HttpUrl).
path – The path to append (a leading slash is optional).

Returns:

<base-without-trailing-slash>/<path-without-leading-slash>.

Return type:

str

flip.core.standard._hub_internal_headers() → dict[str, str]

Return the auth header sent on every hub-internal call.

Used by fl-server on the Central Hub for outbound calls to flip-api (update_status, send_metrics, send_handled_exception). The receiver (flip-api) compares the value with a constant-time compare against its own copy. Distinct boundary from the trust-internal key — a leak in one trust never affects this hub-side path and vice versa.

Returns:: Single-entry dict mapping the configured header name to the hub internal-service key.
Return type:: dict[str, str]

class flip.core.standard.FLIPStandardProd

Bases: flip.core.base.FLIPBase

Production implementation of FLIP for standard job types.

Method usage by FL role:

Server-only (fl-server on Central Hub → calls flip-api):

update_status() — update model training status
send_metrics() — forward per-client training/evaluation metrics
send_handled_exception() — forward client exception logs
upload_results_to_s3() — upload trained model to S3

Client-only (fl-client on trust side → calls local trust APIs):

get_dataframe() — fetch cohort data from data-access-api
get_images() — download images from imaging-api
download_data_from_s3() — download federated data from S3

_name = 'FLIPStandardProd'

logger

get_dataframe(project_id: str, query: str) → pandas.DataFrame

Retrieves the dataframe from the trust OMOP using the SQL query. Calls the FLIP data-access-api.

Parameters:

project_id (str) – Project identifier
query (str) – SQL query

Returns:

Dataframe containing the resulting accession ids and additional data.

Return type:

pd.DataFrame

get_by_accession_number(project_id: str, accession_id: str, resource_type: flip.constants.flip_constants.ResourceType | list[flip.constants.flip_constants.ResourceType] = ResourceType.NIFTI) → pathlib.Path

Calls the imaging-service to return a filepath that contains images downloaded from XNAT based on the accession number.

Parameters:

project_id (str) – The ID of the project.
accession_id (str) – The accession ID of the imaging study.
resource_type (ResourceType | list[ResourceType]) – The type of resource to download. Defaults to
ResourceType.NIFTI.

Returns:

Path to the downloaded data for that accession_id.

Return type:

Path

add_resource(project_id: str, accession_id: str, scan_id: str, resource_id: str, files: list[str]) → None

Calls the imaging-service to upload image(s) to XNAT based on the accession number, scan ID, and resource ID.

Parameters:

project_id (str) – Unique project identifier
accession_id (str) – Accession ID to upload the resource to
scan_id (str) – ID of the scan to upload
resource_id (str) – Type of resource that is being uploaded (e.g. NIFTI)
files (list[str]) – List of files to upload

update_status(model_id: str, new_model_status: flip.constants.flip_constants.ModelStatus) → None

Updates the model status on the Central Hub.

Parameters:

model_id (str) – Unique model identifier.
new_model_status (ModelStatus) – New model status value.

send_metrics(client_name: str, model_id: str, label: str, value: float, global_round: int, x_value: float | None = None, x_label: str | None = None) → None

Sends a metric value to the Central Hub.

Parameters:

client_name (str) – The name of the client.
model_id (str) – The ID of the model.
label (str) – The label of the metric.
value (float) – The value of the metric.
global_round (int) – Provenance — the FL global round the metric is reported in (never the plot coordinate).
x_value (float | None) – The x-coordinate the metric is plotted at; None plots it at global_round (the schema backfills it).
x_label (str | None) – Label naming the x-axis; falls back to “Global Rounds” when not given.

send_handled_exception(formatted_exception: str, client_name: str | None, model_id: str) → None

Sends a handled exception to the Central Hub.

Parameters:

formatted_exception (str) – The formatted exception message.
client_name (str | None) – The name of the client that raised the exception. None when the client cannot be identified (e.g. a Flower reply that crashed before its first healthy response), in which case the hub records the exception model-level rather than rejecting it.
model_id (str) – The ID of the model associated with the exception.

send_event(model_id: str, event_type: flip.schemas.FLLogEvent, global_round: int, client_name: str | None = None, details: dict[str, Any] | None = None, success: bool = True) → None

Sends a typed round-progress event to the Central Hub.

Facts only — the hub composes display text at serve time. Best-effort: a failed post and a payload that fails validation are logged and never break training. Only an invalid model_id raises — a deliberate precondition, matching send_handled_exception.

Parameters:

model_id (str) – The ID of the model the event belongs to.
event_type (FLLogEvent) – Which round event this is.
global_round (int) – The 1-based federated round.
client_name (str | None) – FL client identity for trust-attributed events; None for hub-attributed ones.
details (dict[str, Any] | None) – Event-specific facts.
success (bool) – Whether the event marks a healthy step.

upload_results_to_s3(results_folder: pathlib.Path, model_id: str) → None

Uploads results to S3 bucket in standard mode.

Parameters:

results_folder (Path) – The folder containing results to upload
model_id (str) – The model UUID for which results are being uploaded

cleanup(path: pathlib.Path) → None: Cleans up local files by deleting the specified path.

class flip.core.standard.FLIPStandardDev

Bases: flip.core.base.FLIPBase

Development implementation of FLIP for standard job types.

_name = 'FLIPStandardDev'

logger

get_dataframe(project_id: str, query: str) → pandas.DataFrame

Retrieves the dataframe from the specified CSV path.

Parameters:

project_id (str) – Project identifier (validated but not used in dev)
query (str) – SQL query (validated but not used in dev)

Returns:

Dataframe from the DEV_DATAFRAME CSV file.

Return type:

pd.DataFrame

get_by_accession_number(project_id: str, accession_id: str, resource_type: flip.constants.flip_constants.ResourceType | list[flip.constants.flip_constants.ResourceType] = ResourceType.NIFTI) → pathlib.Path

Returns the path to the image directory for a specific accession ID.

Parameters:

project_id (str) – Project identifier
accession_id (str) – Accession ID to retrieve
resource_type (ResourceType | list[ResourceType]) – Type of imaging resource (not used in dev)

Returns:

Path to the accession_id folder within the images folder.

Return type:

Path

add_resource(project_id: str, accession_id: str, scan_id: str, resource_id: str, files: list[str]) → None: Log only in dev mode - no actual upload.

update_status(model_id: str, new_model_status: flip.constants.flip_constants.ModelStatus) → None: Log only in dev mode - no actual status update.

send_metrics(client_name: str, model_id: str, label: str, value: float, global_round: int, x_value: float | None = None, x_label: str | None = None) → None: Log only in dev mode - no actual metrics sending.

send_handled_exception(formatted_exception: str, client_name: str | None, model_id: str) → None: Log only in dev mode - no actual exception sending.

send_event(model_id: str, event_type: flip.schemas.FLLogEvent, global_round: int, client_name: str | None = None, details: dict[str, Any] | None = None, success: bool = True) → None: Log only in dev mode - no actual event sending.

upload_results_to_s3(results_folder: pathlib.Path, model_id: str) → None: Log only in dev mode - no actual upload.

cleanup(path: pathlib.Path) → None: Log only in dev mode - no actual deletion of any files.