flip

FLIP - Federated Learning and Interoperability Platform

This package provides the core functionality for federated learning in the FLIP platform.

Main exports:

  • FLIP: Factory function that returns the appropriate FLIP implementation based on job type

  • FLIPBase: Abstract base class for FLIP implementations

  • ResultsUploadError: Raised when uploading training results to S3 fails

Example usage:

from flip import FLIP

flip = FLIP()  # Uses default "standard" job type

df = flip.get_dataframe(project_id, query)

Submodules

Exceptions

ResultsUploadError

Raised when uploading federated training results to S3 fails.

Classes

FLIPBase

Abstract base class for FLIP functionality across all job types.

Functions

FLIP(→ flip.core.base.FLIPBase)

Factory function to create appropriate FLIP instance based on job type.

Package Contents

class flip.FLIPBase

Bases: abc.ABC

Abstract base class for FLIP functionality across all job types.

This class defines the interface that all FLIP implementations must follow. Concrete implementations handle the differences between development and production environments, as well as job-type-specific behavior.

_name = 'FLIPBase'
logger
abstractmethod get_dataframe(project_id: str, query: str) → pandas.DataFrame

Returns a dataframe for the project/query.

Parameters:

  • project_id (str) – The project identifier

  • query (str) – SQL query string

Returns:

Dataframe containing the query results

Return type:

pd.DataFrame

abstractmethod 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 data for the given accession number.

Parameters:

  • project_id (str) – The project identifier

  • accession_id (str) – The accession ID of the imaging study

  • resource_type (ResourceType | list[ResourceType]) – Type(s) of resources to download

Returns:

Path to the downloaded data

Return type:

Path

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

Adds specific image to XNAT for an accession ID.

Parameters:

  • project_id (str) – The project identifier

  • accession_id (str) – The accession ID

  • scan_id (str) – The scan ID

  • resource_id (str) – The resource type ID

  • files (list[str]) – List of file paths to upload

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

Updates training status in Central Hub.

Parameters:

  • model_id (str) – The model UUID

  • new_model_status (ModelStatus) – The new status to set

abstractmethod 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 client name sending the metric

  • model_id (str) – The model UUID

  • 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. Always the true round; it is NOT the plot coordinate (that’s x_value).

  • x_value (float | None) – The x-coordinate the metric is plotted at (e.g. an epoch counter). None plots it at global_round.

  • x_label (str | None) – Label naming the x-axis the metric is plotted against. None lets the hub default it to “Global Rounds”. A plot’s identity is (label, x_label) — see FLIP#148.

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

Sends a training-related exception to Central Hub.

Parameters:

  • formatted_exception (str) – The formatted exception message

  • client_name (str | None) – The client name that raised the exception; None when the client cannot be identified, so the hub records it model-level

  • model_id (str) – The model UUID

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

The event carries facts only — the hub composes the display text at serve time, so wording never lives in FL images. Best-effort like every hub call: a failed post is logged and never breaks training.

Parameters:

  • model_id (str) – The model UUID

  • event_type (FLLogEvent) – Which round event this is

  • global_round (int) – The 1-based federated round the event belongs to

  • client_name (str | None) – FL client identity for trust-attributed events (e.g. CLIENT_RESULT_RECEIVED); None for hub-attributed ones

  • details (dict[str, Any] | None) – Event-specific facts (total_rounds, size_bytes, returned/expected counts)

  • success (bool) – Whether the event marks a healthy step

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

Uploads results to S3 bucket.

Parameters:

  • results_folder (Path) – The folder containing results to upload

  • model_id (str) – The model UUID for which results are being uploaded

abstractmethod cleanup(path: pathlib.Path) → None

Cleans up local files.

Parameters:

path (Path) – The path to the file or directory to clean up

check_query(query: str) → None

Check whether the query is a string type.

Parameters:

query (str) – The query to validate

Raises:

TypeError – If query is not a string

check_project_id(project_id: str) → None

Checks whether the project id is a string type.

Parameters:

project_id (str) – The project ID to validate

Raises:

TypeError – If project_id is not a string

check_accession_id(accession_id: str) → None

Checks whether accession_id is a string type.

Parameters:

accession_id (str) – The accession ID to validate

Raises:

TypeError – If accession_id is not a string

check_resource_type(resource_type: flip.constants.flip_constants.ResourceType | list[flip.constants.flip_constants.ResourceType]) → list[flip.constants.flip_constants.ResourceType]

Check whether resource type is valid and returns them reformatted.

Parameters:

resource_type (ResourceType | list[ResourceType]) – Single ResourceType or list of ResourceTypes

Returns:

List of validated resource types

Return type:

list[ResourceType]

Raises:

TypeError – If resource_type is not valid

flip.FLIP(job_type: flip.constants.job_types.JobType | flip.constants.job_types.JobTypeStr = JobType.STANDARD, **kwargs) → flip.core.base.FLIPBase

Factory function to create appropriate FLIP instance based on job type.

This is the main entry point for users to create FLIP instances. The factory automatically selects the correct implementation based on:

  1. The job type (standard, evaluation, fed_opt, diffusion_model)

  2. The environment (LOCAL_DEV or production)

Parameters:

  • job_type – One of “standard”, “evaluation”, “fed_opt”, “diffusion_model” or a JobType enum value. Defaults to “standard”.

  • **kwargs – Additional arguments passed to the constructor

Returns:

Appropriate FLIP instance for the job type and environment

Return type:

FLIPBase

Examples

Create a standard FLIP instance:

flip = FLIP()
df = flip.get_dataframe(project_id, query)

Create an evaluation-specific FLIP instance:

flip = FLIP(job_type="evaluation")

Use the enum-based job type:

from flip.constants import JobType
flip = FLIP(job_type=JobType.DIFFUSION)
exception flip.ResultsUploadError

Bases: Exception

Raised when uploading federated training results to S3 fails.

Distinct from generic training failures so callers can report a model status of RESULTS_UPLOAD_FAILED (training succeeded, results upload did not) rather than a blanket ERROR.