flwr-nightly 1.19.0.dev20250511__tar.gz → 1.19.0.dev20250513__tar.gz

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.19.0.dev20250511
+Version: 1.19.0.dev20250513
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/constant.py

@@ -62,6 +62,7 @@ HEARTBEAT_BASE_MULTIPLIER = 0.8
 HEARTBEAT_RANDOM_RANGE = (-0.1, 0.1)
 HEARTBEAT_MAX_INTERVAL = 1e300
 HEARTBEAT_PATIENCE = 2
+RUN_FAILURE_DETAILS_NO_HEARTBEAT = "No heartbeat received from the run."
 
 # IDs
 RUN_ID_NUM_BYTES = 8

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/heartbeat.py

@@ -77,6 +77,11 @@ class HeartbeatSender:
         self._stop_event.set()
         self._thread.join()
 
+    @property
+    def is_running(self) -> bool:
+        """Return True if the heartbeat sender is running, False otherwise."""
+        return self._thread.is_alive() and not self._stop_event.is_set()
+
     def _run(self) -> None:
         """Periodically send heartbeats until stopped."""
         while not self._stop_event.is_set():

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/inflatable.py

@@ -15,6 +15,8 @@
 """InflatableObject base class."""
 
 
+from __future__ import annotations
+
 import hashlib
 from typing import TypeVar
 
@@ -31,7 +33,9 @@ class InflatableObject:
         raise NotImplementedError()
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> "InflatableObject":
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> InflatableObject:
         """Inflate the object from bytes.
 
         Parameters
@@ -39,6 +43,10 @@ class InflatableObject:
         object_content : bytes
             The deflated object content.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Dictionary of children InflatableObjects mapped to their object IDs. These
+            childrens enable the full inflation of the parent InflatableObject.
+
         Returns
         -------
         InflatableObject
@@ -51,6 +59,11 @@ class InflatableObject:
         """Get object_id."""
         return get_object_id(self.deflate())
 
+    @property
+    def children(self) -> dict[str, InflatableObject] | None:
+        """Get all child objects as a dictionary or None if there are no children."""
+        return None
+
 
 def get_object_id(object_content: bytes) -> str:
     """Return a SHA-256 hash of the (deflated) object content."""

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/record/array.py

@@ -265,7 +265,9 @@ class Array(InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> Array:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> Array:
         """Inflate an Array from bytes.
 
         Parameters
@@ -273,11 +275,18 @@ class Array(InflatableObject):
         object_content : bytes
             The deflated object content of the Array.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``Array`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         Array
             The inflated Array.
         """
+        if children is not None:
+            raise ValueError("`Array` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         proto_array = ArrayProto.FromString(obj_body)
         return cls(

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/record/arrayrecord.py

@@ -18,6 +18,7 @@
 from __future__ import annotations
 
 import gc
+import json
 import sys
 from collections import OrderedDict
 from logging import WARN
@@ -26,6 +27,7 @@ from typing import TYPE_CHECKING, Any, cast, overload
 import numpy as np
 
 from ..constant import GC_THRESHOLD
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
 from ..typing import NDArray
 from .array import Array
@@ -56,7 +58,7 @@ def _check_value(value: Array) -> None:
         )
 
 
-class ArrayRecord(TypedDict[str, Array]):
+class ArrayRecord(TypedDict[str, Array], InflatableObject):
     """Array record.
 
     A typed dictionary (``str`` to :class:`Array`) that can store named arrays,
@@ -365,6 +367,68 @@ class ArrayRecord(TypedDict[str, Array]):
 
         return num_bytes
 
+    @property
+    def children(self) -> dict[str, InflatableObject]:
+        """Return a dictionary of Arrays with their Object IDs as keys."""
+        return {arr.object_id: arr for arr in self.values()}
+
+    def deflate(self) -> bytes:
+        """Deflate the ArrayRecord."""
+        # array_name: array_object_id mapping
+        array_refs: dict[str, str] = {}
+
+        for array_name, array in self.items():
+            array_refs[array_name] = array.object_id
+
+        # Serialize references dict
+        object_body = json.dumps(array_refs).encode("utf-8")
+        return add_header_to_object_body(object_body=object_body, cls=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> ArrayRecord:
+        """Inflate an ArrayRecord from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the ArrayRecord.
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the ArrayRecord.
+
+        Returns
+        -------
+        ArrayRecord
+            The inflated ArrayRecord.
+        """
+        if children is None:
+            children = {}
+
+        # Inflate mapping of array_names (keys in the ArrayRecord) to Arrays' object IDs
+        obj_body = get_object_body(object_content, cls)
+        array_refs: dict[str, str] = json.loads(obj_body.decode(encoding="utf-8"))
+
+        unique_arrays = set(array_refs.values())
+        children_obj_ids = set(children.keys())
+        if unique_arrays != children_obj_ids:
+            raise ValueError(
+                "Unexpected set of `children`. "
+                f"Expected {unique_arrays} but got {children_obj_ids}."
+            )
+
+        # Ensure children are of type Array
+        if not all(isinstance(arr, Array) for arr in children.values()):
+            raise ValueError("`Children` are expected to be of type `Array`.")
+
+        # Instantiate new ArrayRecord
+        return ArrayRecord(
+            OrderedDict(
+                {name: children[object_id] for name, object_id in array_refs.items()}
+            )
+        )
+
 
 class ParametersRecord(ArrayRecord):
     """Deprecated class ``ParametersRecord``, use ``ArrayRecord`` instead.

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/record/configrecord.py

@@ -185,7 +185,9 @@ class ConfigRecord(TypedDict[str, ConfigRecordValues], InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> ConfigRecord:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> ConfigRecord:
         """Inflate a ConfigRecord from bytes.
 
         Parameters
@@ -193,11 +195,18 @@ class ConfigRecord(TypedDict[str, ConfigRecordValues], InflatableObject):
         object_content : bytes
             The deflated object content of the ConfigRecord.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``ConfigRecord`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         ConfigRecord
             The inflated ConfigRecord.
         """
+        if children is not None:
+            raise ValueError("`ConfigRecord` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         config_record_proto = ProtoConfigRecord.FromString(obj_body)
 

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/record/metricrecord.py

@@ -160,7 +160,9 @@ class MetricRecord(TypedDict[str, MetricRecordValues], InflatableObject):
         return add_header_to_object_body(object_body=obj_body, cls=self)
 
     @classmethod
-    def inflate(cls, object_content: bytes) -> MetricRecord:
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> MetricRecord:
         """Inflate a MetricRecord from bytes.
 
         Parameters
@@ -168,11 +170,18 @@ class MetricRecord(TypedDict[str, MetricRecordValues], InflatableObject):
         object_content : bytes
             The deflated object content of the MetricRecord.
 
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``MetricRecord`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
         Returns
         -------
         MetricRecord
             The inflated MetricRecord.
         """
+        if children is not None:
+            raise ValueError("`MetricRecord` objects do not have children.")
+
         obj_body = get_object_body(object_content, cls)
         metric_record_proto = ProtoMetricRecord.FromString(obj_body)
 

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/common/record/recorddict.py

@@ -17,10 +17,12 @@
 
 from __future__ import annotations
 
+import json
 from logging import WARN
 from textwrap import indent
 from typing import TypeVar, Union, cast
 
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
 from .arrayrecord import ArrayRecord
 from .configrecord import ConfigRecord
@@ -97,7 +99,7 @@ class _SyncedDict(TypedDict[str, T]):
             )
 
 
-class RecordDict(TypedDict[str, RecordType]):
+class RecordDict(TypedDict[str, RecordType], InflatableObject):
     """RecordDict stores groups of arrays, metrics and configs.
 
     A :class:`RecordDict` is the unified mechanism by which arrays,
@@ -286,6 +288,72 @@ class RecordDict(TypedDict[str, RecordType]):
             )
         return self.config_records
 
+    @property
+    def children(self) -> dict[str, InflatableObject]:
+        """Return a dictionary of records with their Object IDs as keys."""
+        return {record.object_id: record for record in self.values()}
+
+    def deflate(self) -> bytes:
+        """Deflate the RecordDict."""
+        # record_name: record_object_id mapping
+        record_refs: dict[str, str] = {}
+
+        for record_name, record in self.items():
+            record_refs[record_name] = record.object_id
+
+        # Serialize references dict
+        object_body = json.dumps(record_refs).encode("utf-8")
+        return add_header_to_object_body(object_body=object_body, cls=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> RecordDict:
+        """Inflate an RecordDict from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the RecordDict.
+        children : Optional[dict[str, InflatableObject]]  (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the RecordDict. Default is None.
+
+        Returns
+        -------
+        RecordDict
+            The inflated RecordDict.
+        """
+        if children is None:
+            children = {}
+
+        # Inflate mapping of record_names (keys in the RecordDict) to Record' object IDs
+        obj_body = get_object_body(object_content, cls)
+        record_refs: dict[str, str] = json.loads(obj_body.decode(encoding="utf-8"))
+
+        unique_records = set(record_refs.values())
+        children_obj_ids = set(children.keys())
+        if unique_records != children_obj_ids:
+            raise ValueError(
+                "Unexpected set of `children`. "
+                f"Expected {unique_records} but got {children_obj_ids}."
+            )
+
+        # Ensure children are one of the *Record objects exepecte in a RecordDict
+        if not all(
+            isinstance(ch, (ArrayRecord, ConfigRecord, MetricRecord))
+            for ch in children.values()
+        ):
+            raise ValueError(
+                "`Children` are expected to be of type `ArrayRecord`, "
+                "`ConfigRecord` or `MetricRecord`."
+            )
+
+        # Instantiate new RecordDict
+        return RecordDict(
+            {name: children[object_id] for name, object_id in record_refs.items()}  # type: ignore
+        )
+
 
 class RecordSet(RecordDict):
     """Deprecated class ``RecordSet``, use ``RecordDict`` instead.

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/server/superlink/linkstate/in_memory_linkstate.py

@@ -25,12 +25,15 @@ from uuid import UUID, uuid4
 
 from flwr.common import Context, Message, log, now
 from flwr.common.constant import (
+    HEARTBEAT_MAX_INTERVAL,
     HEARTBEAT_PATIENCE,
     MESSAGE_TTL_TOLERANCE,
     NODE_ID_NUM_BYTES,
+    RUN_FAILURE_DETAILS_NO_HEARTBEAT,
     RUN_ID_NUM_BYTES,
     SUPERLINK_NODE_ID,
     Status,
+    SubStatus,
 )
 from flwr.common.record import ConfigRecord
 from flwr.common.typing import Run, RunStatus, UserConfig
@@ -52,8 +55,11 @@ class RunRecord:  # pylint: disable=R0902
     """The record of a specific run, including its status and timestamps."""
 
     run: Run
+    active_until: float = 0.0
+    heartbeat_interval: float = 0.0
     logs: list[tuple[float, str]] = field(default_factory=list)
     log_lock: threading.Lock = field(default_factory=threading.Lock)
+    lock: threading.RLock = field(default_factory=threading.RLock)
 
 
 class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
@@ -461,8 +467,29 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
         with self.lock:
             return set(self.run_ids.keys())
 
+    def _check_and_tag_inactive_run(self, run_ids: set[int]) -> None:
+        """Check if any runs are no longer active.
+
+        Marks runs with status 'starting' or 'running' as failed
+        if they have not sent a heartbeat before `active_until`.
+        """
+        current = now()
+        for record in [self.run_ids[run_id] for run_id in run_ids]:
+            with record.lock:
+                if record.run.status.status in (Status.STARTING, Status.RUNNING):
+                    if record.active_until < current.timestamp():
+                        record.run.status = RunStatus(
+                            status=Status.FINISHED,
+                            sub_status=SubStatus.FAILED,
+                            details=RUN_FAILURE_DETAILS_NO_HEARTBEAT,
+                        )
+                        record.run.finished_at = now().isoformat()
+
     def get_run(self, run_id: int) -> Optional[Run]:
         """Retrieve information about the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         with self.lock:
             if run_id not in self.run_ids:
                 log(ERROR, "`run_id` is invalid")
@@ -471,6 +498,9 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
 
     def get_run_status(self, run_ids: set[int]) -> dict[int, RunStatus]:
         """Retrieve the statuses for the specified runs."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids=run_ids)
+
         with self.lock:
             return {
                 run_id: self.run_ids[run_id].run.status
@@ -480,12 +510,16 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
 
     def update_run_status(self, run_id: int, new_status: RunStatus) -> bool:
         """Update the status of the run with the specified `run_id`."""
+        # Check if runs are still active
+        self._check_and_tag_inactive_run(run_ids={run_id})
+
         with self.lock:
             # Check if the run_id exists
             if run_id not in self.run_ids:
                 log(ERROR, "`run_id` is invalid")
                 return False
 
+        with self.run_ids[run_id].lock:
             # Check if the status transition is valid
             current_status = self.run_ids[run_id].run.status
             if not is_valid_transition(current_status, new_status):
@@ -507,14 +541,23 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
                 )
                 return False
 
-            # Update the status
+            # Initialize heartbeat_interval and active_until
+            # when switching to starting or running
+            current = now()
             run_record = self.run_ids[run_id]
+            if new_status.status in (Status.STARTING, Status.RUNNING):
+                run_record.heartbeat_interval = HEARTBEAT_MAX_INTERVAL
+                run_record.active_until = (
+                    current.timestamp() + run_record.heartbeat_interval
+                )
+
+            # Update the run status
             if new_status.status == Status.STARTING:
-                run_record.run.starting_at = now().isoformat()
+                run_record.run.starting_at = current.isoformat()
             elif new_status.status == Status.RUNNING:
-                run_record.run.running_at = now().isoformat()
+                run_record.run.running_at = current.isoformat()
             elif new_status.status == Status.FINISHED:
-                run_record.run.finished_at = now().isoformat()
+                run_record.run.finished_at = current.isoformat()
             run_record.run.status = new_status
             return True
 
@@ -558,6 +601,43 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
                 return True
         return False
 
+    def acknowledge_app_heartbeat(self, run_id: int, heartbeat_interval: float) -> bool:
+        """Acknowledge a heartbeat received from a ServerApp for a given run.
+
+        A run with status `"running"` is considered alive as long as it sends heartbeats
+        within the tolerated interval: HEARTBEAT_PATIENCE × heartbeat_interval.
+        HEARTBEAT_PATIENCE = N allows for N-1 missed heartbeat before the run is
+        marked as `"completed:failed"`.
+        """
+        with self.lock:
+            # Search for the run
+            record = self.run_ids.get(run_id)
+
+            # Check if the run_id exists
+            if record is None:
+                log(ERROR, "`run_id` is invalid")
+                return False
+
+        with record.lock:
+            # Check if runs are still active
+            self._check_and_tag_inactive_run(run_ids={run_id})
+
+            # Check if the run is of status "running"/"starting"
+            current_status = record.run.status
+            if current_status.status not in (Status.RUNNING, Status.STARTING):
+                log(
+                    ERROR,
+                    'Cannot acknowledge heartbeat for run with status "%s"',
+                    current_status.status,
+                )
+                return False
+
+            # Update the `active_until` and `heartbeat_interval` for the given run
+            current = now().timestamp()
+            record.active_until = current + HEARTBEAT_PATIENCE * heartbeat_interval
+            record.heartbeat_interval = heartbeat_interval
+            return True
+
     def get_serverapp_context(self, run_id: int) -> Optional[Context]:
         """Get the context for the specified `run_id`."""
         return self.contexts.get(run_id)

{flwr_nightly-1.19.0.dev20250511 → flwr_nightly-1.19.0.dev20250513}/py/flwr/server/superlink/linkstate/linkstate.py

@@ -292,6 +292,29 @@ class LinkState(abc.ABC):  # pylint: disable=R0904
             True if the heartbeat is successfully acknowledged; otherwise, False.
         """
 
+    @abc.abstractmethod
+    def acknowledge_app_heartbeat(self, run_id: int, heartbeat_interval: float) -> bool:
+        """Acknowledge a heartbeat received from a ServerApp for a given run.
+
+        A run with status `"running"` is considered alive as long as it sends heartbeats
+        within the tolerated interval: HEARTBEAT_PATIENCE × heartbeat_interval.
+        HEARTBEAT_PATIENCE = N allows for N-1 missed heartbeat before the run is
+        marked as `"completed:failed"`.
+
+        Parameters
+        ----------
+        run_id : int
+            The `run_id` from which the heartbeat was received.
+        heartbeat_interval : float
+            The interval (in seconds) from the current timestamp within which the next
+            heartbeat from the ServerApp for this run must be received.
+
+        Returns
+        -------
+        is_acknowledged : bool
+            True if the heartbeat is successfully acknowledged; otherwise, False.
+        """
+
     @abc.abstractmethod
     def get_serverapp_context(self, run_id: int) -> Optional[Context]:
         """Get the context for the specified `run_id`.