flwr-nightly 1.21.0.dev20250826__py3-none-any.whl → 1.21.0.dev20250827__py3-none-any.whl

flwr/common/exit/exit_code.py

@@ -34,6 +34,9 @@ class ExitCode:
     SUPERLINK_LICENSE_URL_INVALID = 103
     SUPERLINK_INVALID_ARGS = 104
 
+    # ServerApp-specific exit codes (200-299)
+    SERVERAPP_STRATEGY_PRECONDITION_UNMET = 200
+
     # SuperNode-specific exit codes (300-399)
     SUPERNODE_REST_ADDRESS_INVALID = 300
     SUPERNODE_NODE_AUTH_KEYS_REQUIRED = 301
@@ -76,6 +79,16 @@ EXIT_CODE_HELP = {
         "Invalid arguments provided to SuperLink. Use `--help` check for the correct "
         "usage. Alternatively, check the documentation."
     ),
+    # ServerApp-specific exit codes (200-299)
+    ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET: (
+        "The strategy received replies that cannot be aggregated. Please ensure all "
+        "replies returned by ClientApps have one `ArrayRecord` (none when replies are "
+        "from a round of federated evaluation, i.e. when message type is "
+        "`MessageType.EVALUATE`) and one `MetricRecord`. The records in all replies "
+        "must use identical keys. In addition, if the strategy expects a key to "
+        "perform weighted average (e.g. in FedAvg) please ensure the returned "
+        "MetricRecord from ClientApps do include this key."
+    ),
     # SuperNode-specific exit codes (300-399)
     ExitCode.SUPERNODE_REST_ADDRESS_INVALID: (
         "When using the REST API, please provide `https://` or "

flwr/serverapp/__init__.py

@@ -13,3 +13,13 @@
 # limitations under the License.
 # ==============================================================================
 """Public Flower ServerApp APIs."""
+
+from .fedavg import FedAvg
+from .result import Result
+from .strategy import Strategy
+
+__all__ = [
+    "FedAvg",
+    "Result",
+    "Strategy",
+]

flwr/serverapp/fedavg.py

@@ -0,0 +1,292 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower message-based FedAvg strategy."""
+
+
+from collections.abc import Iterable
+from logging import INFO
+from typing import Callable, Optional
+
+from flwr.common import (
+    ArrayRecord,
+    ConfigRecord,
+    Message,
+    MessageType,
+    MetricRecord,
+    RecordDict,
+    log,
+)
+from flwr.server import Grid
+
+from .strategy import Strategy
+from .strategy_utils import (
+    aggregate_arrayrecords,
+    aggregate_metricrecords,
+    sample_nodes,
+    validate_message_reply_consistency,
+)
+
+
+# pylint: disable=too-many-instance-attributes
+class FedAvg(Strategy):
+    """Federated Averaging strategy.
+
+    Implementation based on https://arxiv.org/abs/1602.05629
+
+    Parameters
+    ----------
+    fraction_train : float (default: 1.0)
+        Fraction of nodes used during training. In case `min_train_nodes`
+        is larger than `fraction_train * total_connected_nodes`, `min_train_nodes`
+        will still be sampled.
+    fraction_evaluate : float (default: 1.0)
+        Fraction of nodes used during validation. In case `min_evaluate_nodes`
+        is larger than `fraction_evaluate * total_connected_nodes`,
+        `min_evaluate_nodes` will still be sampled.
+    min_train_nodes : int (default: 2)
+        Minimum number of nodes used during training.
+    min_evaluate_nodes : int (default: 2)
+        Minimum number of nodes used during validation.
+    min_available_nodes : int (default: 2)
+        Minimum number of total nodes in the system.
+    weighted_by_key : str (default: "num-examples")
+        The key within each MetricRecord whose value is used as the weight when
+        computing weighted averages for both ArrayRecords and MetricRecords.
+    arrayrecord_key : str (default: "arrays")
+        Key used to store the ArrayRecord when constructing Messages.
+    configrecord_key : str (default: "config")
+         Key used to store the ConfigRecord when constructing Messages.
+    train_metrics_aggr_fn : Optional[callable] (default: None)
+        Function with signature (list[RecordDict], str) -> MetricRecord,
+        used to aggregate MetricRecords from training round replies.
+        If `None`, defaults to `aggregate_metricrecords`, which performs a weighted
+        average using the provided weight factor key.
+    evaluate_metrics_aggr_fn : Optional[callable] (default: None)
+        Function with signature (list[RecordDict], str) -> MetricRecord,
+        used to aggregate MetricRecords from training round replies.
+        If `None`, defaults to `aggregate_metricrecords`, which performs a weighted
+        average using the provided weight factor key.
+    """
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        fraction_train: float = 1.0,
+        fraction_evaluate: float = 1.0,
+        min_train_nodes: int = 2,
+        min_evaluate_nodes: int = 2,
+        min_available_nodes: int = 2,
+        weighted_by_key: str = "num-examples",
+        arrayrecord_key: str = "arrays",
+        configrecord_key: str = "config",
+        train_metrics_aggr_fn: Optional[
+            Callable[[list[RecordDict], str], MetricRecord]
+        ] = None,
+        evaluate_metrics_aggr_fn: Optional[
+            Callable[[list[RecordDict], str], MetricRecord]
+        ] = None,
+    ) -> None:
+        self.fraction_train = fraction_train
+        self.fraction_evaluate = fraction_evaluate
+        self.min_train_nodes = min_train_nodes
+        self.min_evaluate_nodes = min_evaluate_nodes
+        self.min_available_nodes = min_available_nodes
+        self.weighted_by_key = weighted_by_key
+        self.arrayrecord_key = arrayrecord_key
+        self.configrecord_key = configrecord_key
+        self.train_metrics_aggr_fn = train_metrics_aggr_fn or aggregate_metricrecords
+        self.evaluate_metrics_aggr_fn = (
+            evaluate_metrics_aggr_fn or aggregate_metricrecords
+        )
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        log(INFO, "\t├──> Sampling:")
+        log(
+            INFO,
+            "\t│\t├──Fraction: train (%.2f) | evaluate ( %.2f)",
+            self.fraction_train,
+            self.fraction_evaluate,
+        )  # pylint: disable=line-too-long
+        log(
+            INFO,
+            "\t│\t├──Minimum nodes: train (%d) | evaluate (%d)",
+            self.min_train_nodes,
+            self.min_evaluate_nodes,
+        )  # pylint: disable=line-too-long
+        log(INFO, "\t│\t└──Minimum available nodes: %d", self.min_available_nodes)
+        log(INFO, "\t└──> Keys in records:")
+        log(INFO, "\t\t├── Weighted by: '%s'", self.weighted_by_key)
+        log(INFO, "\t\t├── ArrayRecord key: '%s'", self.arrayrecord_key)
+        log(INFO, "\t\t└── ConfigRecord key: '%s'", self.configrecord_key)
+
+    def _construct_messages(
+        self, record: RecordDict, node_ids: list[int], message_type: str
+    ) -> Iterable[Message]:
+        """Construct N Messages carrying the same RecordDict payload."""
+        messages = []
+        for node_id in node_ids:  # one message for each node
+            message = Message(
+                content=record,
+                message_type=message_type,
+                dst_node_id=node_id,
+            )
+            messages.append(message)
+        return messages
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated training."""
+        # Sample nodes
+        num_nodes = int(len(list(grid.get_node_ids())) * self.fraction_train)
+        sample_size = max(num_nodes, self.min_train_nodes)
+        node_ids, num_total = sample_nodes(grid, self.min_available_nodes, sample_size)
+        log(
+            INFO,
+            "configure_train: Sampled %s nodes (out of %s)",
+            len(node_ids),
+            len(num_total),
+        )
+        # Always inject current server round
+        config["server-round"] = server_round
+
+        # Construct messages
+        record = RecordDict(
+            {self.arrayrecord_key: arrays, self.configrecord_key: config}
+        )
+        return self._construct_messages(record, node_ids, MessageType.TRAIN)
+
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        if not replies:
+            return None, None
+
+        # Log if any Messages carried errors
+        # Filter messages that carry content
+        num_errors = 0
+        replies_with_content = []
+        for msg in replies:
+            if msg.has_error():
+                log(
+                    INFO,
+                    "Received error in reply from node %d: %s",
+                    msg.metadata.src_node_id,
+                    msg.error,
+                )
+                num_errors += 1
+            else:
+                replies_with_content.append(msg.content)
+
+        log(
+            INFO,
+            "aggregate_train: Received %s results and %s failures",
+            len(replies_with_content) - num_errors,
+            num_errors,
+        )
+
+        # Ensure expected ArrayRecords and MetricRecords are received
+        validate_message_reply_consistency(
+            replies=replies_with_content,
+            weighted_by_key=self.weighted_by_key,
+            check_arrayrecord=True,
+        )
+
+        # Aggregate ArrayRecords
+        arrays = aggregate_arrayrecords(
+            replies_with_content,
+            self.weighted_by_key,
+        )
+
+        # Aggregate MetricRecords
+        metrics = self.train_metrics_aggr_fn(
+            replies_with_content,
+            self.weighted_by_key,
+        )
+        return arrays, metrics
+
+    def configure_evaluate(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated evaluation."""
+        # Sample nodes
+        num_nodes = int(len(list(grid.get_node_ids())) * self.fraction_evaluate)
+        sample_size = max(num_nodes, self.min_evaluate_nodes)
+        node_ids, num_total = sample_nodes(grid, self.min_available_nodes, sample_size)
+        log(
+            INFO,
+            "configure_evaluate: Sampled %s nodes (out of %s)",
+            len(node_ids),
+            len(num_total),
+        )
+
+        # Always inject current server round
+        config["server-round"] = server_round
+
+        # Construct messages
+        record = RecordDict(
+            {self.arrayrecord_key: arrays, self.configrecord_key: config}
+        )
+        return self._construct_messages(record, node_ids, MessageType.EVALUATE)
+
+    def aggregate_evaluate(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> Optional[MetricRecord]:
+        """Aggregate MetricRecords in the received Messages."""
+        if not replies:
+            return None
+
+        # Log if any Messages carried errors
+        # Filter messages that carry content
+        num_errors = 0
+        replies_with_content = []
+        for msg in replies:
+            if msg.has_error():
+                log(
+                    INFO,
+                    "Received error in reply from node %d: %s",
+                    msg.metadata.src_node_id,
+                    msg.error,
+                )
+                num_errors += 1
+            else:
+                replies_with_content.append(msg.content)
+
+        log(
+            INFO,
+            "aggregate_evaluate: Received %s results and %s failures",
+            len(replies_with_content) - num_errors,
+            num_errors,
+        )
+
+        # Ensure expected ArrayRecords and MetricRecords are received
+        validate_message_reply_consistency(
+            replies=replies_with_content,
+            weighted_by_key=self.weighted_by_key,
+            check_arrayrecord=False,
+        )
+
+        # Aggregate MetricRecords
+        metrics = self.evaluate_metrics_aggr_fn(
+            replies_with_content,
+            self.weighted_by_key,
+        )
+        return metrics

flwr/serverapp/result.py

@@ -0,0 +1,30 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Strategy results."""
+
+
+from dataclasses import dataclass, field
+
+from flwr.common import ArrayRecord, MetricRecord
+
+
+@dataclass
+class Result:
+    """Data class carrying records generated during the execution of a strategy."""
+
+    arrays: ArrayRecord = field(default_factory=ArrayRecord)
+    train_metrics_clientapp: dict[int, MetricRecord] = field(default_factory=dict)
+    evaluate_metrics_clientapp: dict[int, MetricRecord] = field(default_factory=dict)
+    evaluate_metrics_serverapp: dict[int, MetricRecord] = field(default_factory=dict)

flwr/serverapp/strategy.py

@@ -0,0 +1,286 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower message-based strategy."""
+
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from logging import INFO
+from typing import Callable, Optional
+
+from flwr.common import ArrayRecord, ConfigRecord, Message, MetricRecord, log
+from flwr.common.exit import ExitCode, flwr_exit
+from flwr.server import Grid
+
+from .result import Result
+from .strategy_utils import InconsistentMessageReplies, log_strategy_start_info
+
+
+class Strategy(ABC):
+    """Abstract base class for server strategy implementations."""
+
+    @abstractmethod
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        arrays : ArrayRecord
+            Current global ArrayRecord (e.g. global model) to be sent to client
+            nodes for training.
+        config : ConfigRecord
+            Configuration to be sent to clients nodes for training.
+        grid : Grid
+            The Grid instance used for node sampling and communication.
+
+        Returns
+        -------
+        Iterable[Message]
+            An iterable of messages to be sent to selected client nodes for training.
+        """
+
+    @abstractmethod
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate training results from client nodes.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning, starting from 1.
+        replies : Iterable[Message]
+            Iterable of reply messages received from client nodes after training.
+            Each message contains ArrayRecords and MetricRecords that get aggregated.
+
+        Returns
+        -------
+        tuple[Optional[ArrayRecord], Optional[MetricRecord]]
+            A tuple containing:
+            - ArrayRecord: Aggregated ArrayRecord, or None if aggregation failed
+            - MetricRecord: Aggregated MetricRecord, or None if aggregation failed
+        """
+
+    @abstractmethod
+    def configure_evaluate(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of evaluation.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        arrays : ArrayRecord
+            Current global ArrayRecord (e.g. global model) to be sent to client
+            nodes for evaluation.
+        config : ConfigRecord
+            Configuration to be sent to clients nodes for evaluation.
+        grid : Grid
+            The Grid instance used for node sampling and communication.
+
+        Returns
+        -------
+        Iterable[Message]
+            An iterable of messages to be sent to selected client nodes for evaluation.
+        """
+
+    @abstractmethod
+    def aggregate_evaluate(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> Optional[MetricRecord]:
+        """Aggregate evaluation metrics from client nodes.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        replies : Iterable[Message]
+            Iterable of reply messages received from client nodes after evaluation.
+            MetricRecords in the messages are aggregated.
+
+        Returns
+        -------
+        Optional[MetricRecord]
+            Aggregated evaluation metrics from all participating clients,
+            or None if aggregation failed.
+        """
+
+    @abstractmethod
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+
+    # pylint: disable=too-many-arguments, too-many-positional-arguments, too-many-locals
+    def start(
+        self,
+        grid: Grid,
+        initial_arrays: ArrayRecord,
+        num_rounds: int = 3,
+        timeout: float = 3600,
+        train_config: Optional[ConfigRecord] = None,
+        evaluate_config: Optional[ConfigRecord] = None,
+        evaluate_fn: Optional[Callable[[int, ArrayRecord], MetricRecord]] = None,
+    ) -> Result:
+        """Execute the federated learning strategy.
+
+        Runs the complete federated learning workflow for the specified number of
+        rounds, including training, evaluation, and optional centralized evaluation.
+
+        Parameters
+        ----------
+        grid : Grid
+            The Grid instance used to send/receive Messages from nodes executing a
+            ClientApp.
+        initial_arrays : ArrayRecord
+            Initial model parameters (arrays) to be used for federated learning.
+        num_rounds : int (default: 3)
+            Number of federated learning rounds to execute.
+        timeout : float (default: 3600)
+            Timeout in seconds for waiting for node responses.
+        train_config : ConfigRecord, optional
+            Configuration to be sent to nodes during training rounds.
+            If unset, an empty ConfigRecord will be used.
+        evaluate_config : ConfigRecord, optional
+            Configuration to be sent to nodes during evaluation rounds.
+            If unset, an empty ConfigRecord will be used.
+        evaluate_fn : Callable[[int, ArrayRecord], MetricRecord], optional
+            Optional function for centralized evaluation of the global model. Takes
+            server round number and array record, returns a MetricRecord. If provided,
+            will be called before the first round and after each round. Defaults to
+            None.
+
+        Returns
+        -------
+        Results
+            Results containing final model arrays and also training metrics, evaluation
+            metrics and global evaluation metrics (if provided) from all rounds.
+        """
+        log(INFO, "Starting %s strategy:", self.__class__.__name__)
+        log_strategy_start_info(
+            num_rounds, initial_arrays, train_config, evaluate_config
+        )
+        self.summary()
+        log(INFO, "")
+
+        # Initialize if None
+        train_config = ConfigRecord() if train_config is None else train_config
+        evaluate_config = ConfigRecord() if evaluate_config is None else evaluate_config
+        result = Result()
+
+        t_start = time.time()
+        # Evaluate starting global parameters
+        if evaluate_fn:
+            res = evaluate_fn(0, initial_arrays)
+            log(INFO, "Initial global evaluation results: %s", res)
+            result.evaluate_metrics_serverapp[0] = res
+
+        arrays = initial_arrays
+
+        for current_round in range(1, num_rounds + 1):
+            log(INFO, "")
+            log(INFO, "[ROUND %s/%s]", current_round, num_rounds)
+
+            # -----------------------------------------------------------------
+            # --- TRAINING ----------------------------------------------------
+            # -----------------------------------------------------------------
+
+            # Call strategy to configure training round
+            # Send messages and wait for replies
+            train_replies = grid.send_and_receive(
+                messages=self.configure_train(
+                    current_round,
+                    arrays,
+                    train_config,
+                    grid,
+                ),
+                timeout=timeout,
+            )
+
+            # Aggregate train
+            try:
+                agg_arrays, agg_train_metrics = self.aggregate_train(
+                    current_round,
+                    train_replies,
+                )
+            except InconsistentMessageReplies as e:
+                flwr_exit(
+                    ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET, message=str(e)
+                )
+
+            # Log training metrics and append to history
+            if agg_arrays is not None:
+                result.arrays = agg_arrays
+                arrays = agg_arrays
+            if agg_train_metrics is not None:
+                log(INFO, "\t└──> Aggregated MetricRecord: %s", agg_train_metrics)
+                result.train_metrics_clientapp[current_round] = agg_train_metrics
+
+            # -----------------------------------------------------------------
+            # --- EVALUATION (LOCAL) ------------------------------------------
+            # -----------------------------------------------------------------
+
+            # Call strategy to configure evaluation round
+            # Send messages and wait for replies
+            evaluate_replies = grid.send_and_receive(
+                messages=self.configure_evaluate(
+                    current_round,
+                    arrays,
+                    evaluate_config,
+                    grid,
+                ),
+                timeout=timeout,
+            )
+
+            # Aggregate evaluate
+            try:
+                agg_evaluate_metrics = self.aggregate_evaluate(
+                    current_round,
+                    evaluate_replies,
+                )
+            except InconsistentMessageReplies as e:
+                flwr_exit(
+                    ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET, message=str(e)
+                )
+
+            # Log training metrics and append to history
+            if agg_evaluate_metrics is not None:
+                log(INFO, "\t└──> Aggregated MetricRecord: %s", agg_evaluate_metrics)
+                result.evaluate_metrics_clientapp[current_round] = agg_evaluate_metrics
+
+            # -----------------------------------------------------------------
+            # --- EVALUATION (GLOBAL) -----------------------------------------
+            # -----------------------------------------------------------------
+
+            # Centralized evaluation
+            if evaluate_fn:
+                log(INFO, "Global evaluation")
+                res = evaluate_fn(current_round, arrays)
+                log(INFO, "\t└──> MetricRecord: %s", res)
+                result.evaluate_metrics_serverapp[current_round] = res
+
+        log(INFO, "")
+        log(INFO, "Strategy execution finished in %.2fs", time.time() - t_start)
+        log(INFO, "")
+
+        return result

flwr/serverapp/strategy_utils.py

@@ -0,0 +1,256 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower message-based strategy utilities."""
+
+
+import random
+from collections import OrderedDict
+from logging import INFO
+from time import sleep
+from typing import Optional, cast
+
+from flwr.common import (
+    Array,
+    ArrayRecord,
+    ConfigRecord,
+    MetricRecord,
+    NDArray,
+    RecordDict,
+    log,
+)
+from flwr.server import Grid
+
+
+# Define a new exception
+class InconsistentMessageReplies(Exception):
+    """Exception triggered when replies are inconsistent and therefore aggregation must
+    be skipped."""
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+
+
+def config_to_str(config: ConfigRecord) -> str:
+    """Convert a ConfigRecord to a string representation masking bytes."""
+    content = ", ".join(
+        f"'{k}': {'<bytes>' if isinstance(v, bytes) else v}" for k, v in config.items()
+    )
+    return f"{{{content}}}"
+
+
+def log_strategy_start_info(
+    num_rounds: int,
+    arrays: ArrayRecord,
+    train_config: Optional[ConfigRecord],
+    evaluate_config: Optional[ConfigRecord],
+) -> None:
+    """Log information about the strategy start."""
+    log(INFO, "\t├── Number of rounds: %d", num_rounds)
+    log(
+        INFO,
+        "\t├── ArrayRecord (%.2f MB)",
+        sum(len(array.data) for array in arrays.values()) / (1024**2),
+    )
+    log(
+        INFO,
+        "\t├── ConfigRecord (train): %s",
+        config_to_str(train_config) if train_config else "(empty!)",
+    )
+    log(
+        INFO,
+        "\t├── ConfigRecord (evaluate): %s",
+        config_to_str(evaluate_config) if evaluate_config else "(empty!)",
+    )
+
+
+def aggregate_arrayrecords(
+    records: list[RecordDict], weighting_metric_name: str
+) -> ArrayRecord:
+    """Perform weighted aggregation all ArrayRecords using a specific key."""
+    # Retrieve weighting factor from MetricRecord
+    weights: list[float] = []
+    for record in records:
+        # Get the first (and only) MetricRecord in the record
+        metricrecord = next(iter(record.metric_records.values()))
+        # Because replies have been checked for consistency,
+        # we can safely cast the weighting factor to float
+        w = cast(float, metricrecord[weighting_metric_name])
+        weights.append(w)
+
+    # Average
+    total_weight = sum(weights)
+    weight_factors = [w / total_weight for w in weights]
+
+    # Perform weighted aggregation
+    aggregated_np_arrays: dict[str, NDArray] = {}
+
+    for record, weight in zip(records, weight_factors):
+        for record_item in record.array_records.values():
+            # aggregate in-place
+            for key, value in record_item.items():
+                if key not in aggregated_np_arrays:
+                    aggregated_np_arrays[key] = value.numpy() * weight
+                else:
+                    aggregated_np_arrays[key] += value.numpy() * weight
+
+    return ArrayRecord(
+        OrderedDict({k: Array(v) for k, v in aggregated_np_arrays.items()})
+    )
+
+
+def aggregate_metricrecords(
+    records: list[RecordDict], weighting_metric_name: str
+) -> MetricRecord:
+    """Perform weighted aggregation all MetricRecords using a specific key."""
+    # Retrieve weighting factor from MetricRecord
+    weights: list[float] = []
+    for record in records:
+        # Get the first (and only) MetricRecord in the record
+        metricrecord = next(iter(record.metric_records.values()))
+        # Because replies have been checked for consistency,
+        # we can safely cast the weighting factor to float
+        w = cast(float, metricrecord[weighting_metric_name])
+        weights.append(w)
+
+    # Average
+    total_weight = sum(weights)
+    weight_factors = [w / total_weight for w in weights]
+
+    aggregated_metrics = MetricRecord()
+    for record, weight in zip(records, weight_factors):
+        for record_item in record.metric_records.values():
+            # aggregate in-place
+            for key, value in record_item.items():
+                if key == weighting_metric_name:
+                    # We exclude the weighting key from the aggregated MetricRecord
+                    continue
+                if key not in aggregated_metrics:
+                    if isinstance(value, list):
+                        aggregated_metrics[key] = [v * weight for v in value]
+                    else:
+                        aggregated_metrics[key] = value * weight
+                else:
+                    if isinstance(value, list):
+                        current_list = cast(list[float], aggregated_metrics[key])
+                        aggregated_metrics[key] = [
+                            curr + val * weight
+                            for curr, val in zip(current_list, value)
+                        ]
+                    else:
+                        current_value = cast(float, aggregated_metrics[key])
+                        aggregated_metrics[key] = current_value + value * weight
+
+    return aggregated_metrics
+
+
+def sample_nodes(
+    grid: Grid, min_available_nodes: int, sample_size: int
+) -> tuple[list[int], list[int]]:
+    """Sample the specified number of nodes using the Grid.
+
+    Parameters
+    ----------
+    grid : Grid
+        The grid object.
+    min_available_nodes : int
+        The minimum number of available nodes to sample from.
+    sample_size : int
+        The number of nodes to sample.
+
+    Returns
+    -------
+    tuple[list[int], list[int]]
+        A tuple containing the sampled node IDs and the list
+        of all connected node IDs.
+    """
+    sampled_nodes = []
+
+    # Ensure min_available_nodes is at least as large as sample_size
+    min_available_nodes = max(min_available_nodes, sample_size)
+
+    # wait for min_available_nodes to be online
+    while len(all_nodes := list(grid.get_node_ids())) < min_available_nodes:
+        log(
+            INFO,
+            "Waiting for nodes to connect: %d connected (minimum required: %d).",
+            len(all_nodes),
+            min_available_nodes,
+        )
+        sleep(1)
+
+    # Sample nodes
+    sampled_nodes = random.sample(all_nodes, sample_size)
+
+    return sampled_nodes, all_nodes
+
+
+# pylint: disable=too-many-return-statements
+def validate_message_reply_consistency(
+    replies: list[RecordDict], weighted_by_key: str, check_arrayrecord: bool
+) -> None:
+    """Validate that replies contain exactly one ArrayRecord and one MetricRecord, and
+    that the MetricRecord includes a weight factor key.
+
+    These checks ensure that Message-based strategies behave consistently with
+    *Ins/*Res-based strategies.
+    """
+    # Checking for ArrayRecord consistency
+    if check_arrayrecord:
+        if any(len(msg.array_records) != 1 for msg in replies):
+            raise InconsistentMessageReplies(
+                reason="Expected exactly one ArrayRecord in replies. "
+                "Skipping aggregation."
+            )
+
+        # Ensure all key are present in all ArrayRecords
+        record_key = next(iter(replies[0].array_records.keys()))
+        all_keys = set(replies[0][record_key].keys())
+        if any(set(msg.get(record_key, {}).keys()) != all_keys for msg in replies[1:]):
+            raise InconsistentMessageReplies(
+                reason="All ArrayRecords must have the same keys for aggregation. "
+                "This condition wasn't met. Skipping aggregation."
+            )
+
+    # Checking for MetricRecord consistency
+    if any(len(msg.metric_records) != 1 for msg in replies):
+        raise InconsistentMessageReplies(
+            reason="Expected exactly one MetricRecord in replies, but found more. "
+            "Skipping aggregation."
+        )
+
+    # Ensure all key are present in all MetricRecords
+    record_key = next(iter(replies[0].metric_records.keys()))
+    all_keys = set(replies[0][record_key].keys())
+    if any(set(msg.get(record_key, {}).keys()) != all_keys for msg in replies[1:]):
+        raise InconsistentMessageReplies(
+            reason="All MetricRecords must have the same keys for aggregation. "
+            "This condition wasn't met. Skipping aggregation."
+        )
+
+    # Verify the weight factor key presence in all MetricRecords
+    if weighted_by_key not in all_keys:
+        raise InconsistentMessageReplies(
+            reason=f"Missing required key `{weighted_by_key}` in the MetricRecord of "
+            "reply messages. Cannot average ArrayRecords and MetricRecords. Skipping "
+            "aggregation."
+        )
+
+    # Check that it is not a list
+    if any(isinstance(msg[record_key][weighted_by_key], list) for msg in replies):
+        raise InconsistentMessageReplies(
+            reason=f"Key `{weighted_by_key}` in the MetricRecord of reply messages "
+            "must be a single value (int or float), but a list was found. Skipping "
+            "aggregation."
+        )

flwr/serverapp/strategy_utils_tests.py

@@ -0,0 +1,277 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Tests for message-based strategy utilities."""
+
+
+from collections import OrderedDict
+
+import numpy as np
+import pytest
+from parameterized import parameterized
+
+from flwr.common import Array, ArrayRecord, ConfigRecord, MetricRecord, RecordDict
+
+from .strategy_utils import (
+    InconsistentMessageReplies,
+    aggregate_arrayrecords,
+    aggregate_metricrecords,
+    config_to_str,
+    validate_message_reply_consistency,
+)
+
+
+def test_config_to_str() -> None:
+    """Test that items of types bytes are masked out."""
+    config = ConfigRecord({"a": 123, "b": [1, 2, 3], "c": b"bytes"})
+    expected_str = "{'a': 123, 'b': [1, 2, 3], 'c': <bytes>}"
+    assert config_to_str(config) == expected_str
+
+
+def test_arrayrecords_aggregation() -> None:
+    """Test aggregation of ArrayRecords."""
+    num_replies = 3
+    num_arrays = 4
+    weights = [0.25, 0.4, 0.35]
+    np_arrays = [
+        [np.random.randn(7, 3) for _ in range(num_arrays)] for _ in range(num_replies)
+    ]
+
+    avg_list = [
+        np.average([lst[i] for lst in np_arrays], axis=0, weights=weights)
+        for i in range(num_arrays)
+    ]
+
+    # Construct RecordDicts (mimicing replies)
+    records = [
+        RecordDict(
+            {
+                "arrays": ArrayRecord(np_arrays[i]),
+                "metrics": MetricRecord({"weight": weights[i]}),
+            }
+        )
+        for i in range(num_replies)
+    ]
+    # Execute aggregate
+    aggrd = aggregate_arrayrecords(records, weighting_metric_name="weight")
+
+    # Assert consistency
+    assert all(np.allclose(a, b) for a, b in zip(aggrd.to_numpy_ndarrays(), avg_list))
+    assert aggrd.object_id == ArrayRecord(avg_list).object_id
+
+
+def test_metricrecords_aggregation() -> None:
+    """Test aggregation of MetricRecords."""
+    num_replies = 3
+    weights = [0.25, 0.4, 0.35]
+    metric_records = [
+        MetricRecord({"a": 1, "b": 2.0, "c": np.random.randn(3).tolist()})
+        for _ in range(num_replies)
+    ]
+
+    # Compute expected aggregated MetricRecord.
+    # For ease, we convert everything into numpy arrays, then aggregate
+    as_np_entries = [
+        {
+            k: np.array(v) if isinstance(v, (int, float, list)) else v
+            for k, v in record.items()
+        }
+        for record in metric_records
+    ]
+    avg_list = [
+        np.average(
+            [list(entries.values())[i] for entries in as_np_entries],
+            axis=0,
+            weights=weights,
+        ).tolist()
+        for i in range(len(as_np_entries[0]))
+    ]
+    expected_record = MetricRecord(dict(zip(as_np_entries[0].keys(), avg_list)))
+    expected_record["a"] = float(expected_record["a"])  # type: ignore
+    expected_record["b"] = float(expected_record["b"])  # type: ignore
+
+    # Construct RecordDicts (mimicing replies)
+    # Inject weighting factor
+    records = [
+        RecordDict(
+            {
+                "metrics": MetricRecord(
+                    record.__dict__["_data"] | {"weight": weights[i]}
+                ),
+            }
+        )
+        for i, record in enumerate(metric_records)
+    ]
+
+    # Execute aggregate
+    aggrd = aggregate_metricrecords(records, weighting_metric_name="weight")
+    # Assert
+    assert expected_record.object_id == aggrd.object_id
+
+
+@parameterized.expand(  # type: ignore
+    [
+        (
+            True,
+            RecordDict(
+                {
+                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                    "metrics": MetricRecord({"weight": 0.123}),
+                }
+            ),
+        ),  # Compliant
+        (
+            False,
+            RecordDict(
+                {
+                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                    "metrics": MetricRecord({"weight": [0.123]}),
+                }
+            ),
+        ),  # Weighting key is not a scalar (BAD)
+        (
+            False,
+            RecordDict(
+                {
+                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                    "metrics": MetricRecord({"loss": 0.01}),
+                }
+            ),
+        ),  # No weighting key in MetricRecord (BAD)
+        (
+            False,
+            RecordDict({"global-model": ArrayRecord([np.random.randn(7, 3)])}),
+        ),  # No MetricsRecord (BAD)
+        (
+            False,
+            RecordDict(
+                {
+                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                    "another-model": ArrayRecord([np.random.randn(7, 3)]),
+                }
+            ),
+        ),  # Two ArrayRecords (BAD)
+        (
+            False,
+            RecordDict(
+                {
+                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                    "metrics": MetricRecord({"weight": 0.123}),
+                    "more-metrics": MetricRecord({"loss": 0.321}),
+                }
+            ),
+        ),  # Two MetricRecords (BAD)
+    ]
+)
+def test_consistency_of_replies_with_matching_keys(
+    is_valid: bool, recorddict: RecordDict
+) -> None:
+    """Test consistency in replies."""
+    # Create dummy records
+    records = [recorddict for _ in range(3)]
+
+    if not is_valid:
+        # Should raise InconsistentMessageReplies exception
+        with pytest.raises(InconsistentMessageReplies):
+            validate_message_reply_consistency(
+                records, weighted_by_key="weight", check_arrayrecord=True
+            )
+    else:
+        # Should not raise an exception
+        validate_message_reply_consistency(
+            records, weighted_by_key="weight", check_arrayrecord=True
+        )
+
+
+@parameterized.expand(  # type: ignore
+    [
+        (
+            [
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+                RecordDict(
+                    {
+                        "model": ArrayRecord([np.random.randn(7, 3)]),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+            ],
+        ),  # top-level keys don't match for ArrayRecords
+        (
+            [
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord(
+                            OrderedDict({"a": Array(np.random.randn(7, 3))})
+                        ),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord(
+                            OrderedDict({"b": Array(np.random.randn(7, 3))})
+                        ),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+            ],
+        ),  # top-level keys match for ArrayRecords but not those for Arrays
+        (
+            [
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                        "my-metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+            ],
+        ),  # top-level keys don't match for MetricRecords
+        (
+            [
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                        "metrics": MetricRecord({"weight": 0.123}),
+                    }
+                ),
+                RecordDict(
+                    {
+                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
+                        "my-metrics": MetricRecord({"my-weights": 0.123}),
+                    }
+                ),
+            ],
+        ),  # top-level keys match for MetricRecords but not inner ones
+    ]
+)
+def test_consistency_of_replies_with_different_keys(
+    list_records: list[RecordDict],
+) -> None:
+    """Test consistency in replies when records don't have matching keys."""
+    # All test cases expect InconsistentMessageReplies exception to be raised
+    with pytest.raises(InconsistentMessageReplies):
+        validate_message_reply_consistency(
+            list_records, weighted_by_key="weight", check_arrayrecord=True
+        )

{flwr_nightly-1.21.0.dev20250826.dist-info → flwr_nightly-1.21.0.dev20250827.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.21.0.dev20250826
+Version: 1.21.0.dev20250827
 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.21.0.dev20250826.dist-info → flwr_nightly-1.21.0.dev20250827.dist-info}/RECORD

@@ -118,7 +118,7 @@ flwr/common/event_log_plugin/__init__.py,sha256=ts3VAL3Fk6Grp1EK_1Qg_V-BfOof9F86
 flwr/common/event_log_plugin/event_log_plugin.py,sha256=4SkVa1Ic-sPlICJShBuggXmXDcQtWQ1KDby4kthFNF0,2064
 flwr/common/exit/__init__.py,sha256=-ZOJYLaNnR729a7VzZiFsLiqngzKQh3xc27svYStZ_Q,826
 flwr/common/exit/exit.py,sha256=dWZgznSZkg8Tr_Bh9jRHGUhlWk2228q5XFIK98Zr4Tc,3531
-flwr/common/exit/exit_code.py,sha256=oFsMThjzOipMZ842BxaQbnlPbK1Do8hjzd-DIdKs0ig,4151
+flwr/common/exit/exit_code.py,sha256=K0QSQg5elE3xl3OHBaMu1vClAXpyxqBEo6t_weFkh7I,4910
 flwr/common/exit_handlers.py,sha256=IaqJ60fXZuu7McaRYnoYKtlbH9t4Yl9goNExKqtmQbs,4304
 flwr/common/grpc.py,sha256=y70hUFvXkIf3l03xOhlb7qhS6W1UJZRSZqCdB0ir0v8,10381
 flwr/common/heartbeat.py,sha256=SyEpNDnmJ0lni0cWO67rcoJVKasCLmkNHm3dKLeNrLU,5749
@@ -320,7 +320,12 @@ flwr/server/workflow/default_workflows.py,sha256=RlD26dXbSksY-23f3ZspnN1YU1DOhDY
 flwr/server/workflow/secure_aggregation/__init__.py,sha256=vGkycLb65CxdaMkKsANxQE6AS4urfZKvwcS3r1Vln_c,880
 flwr/server/workflow/secure_aggregation/secagg_workflow.py,sha256=b_pKk7gmbahwyj0ftOOLXvu-AMtRHEc82N9PJTEO8dc,5839
 flwr/server/workflow/secure_aggregation/secaggplus_workflow.py,sha256=DkayCsnlAya6Y2PZsueLgoUCMRtV-GbnW08RfWx_SXM,29460
-flwr/serverapp/__init__.py,sha256=HPvC_ZvMS7GCM7ALVrG_Wwm4bSDr4DZETeC561v3T9w,719
+flwr/serverapp/__init__.py,sha256=SRPsqsa4pOfcF9J3_i1hb9KJi3z4KDTTCqCTwv7DcK0,864
+flwr/serverapp/fedavg.py,sha256=Z051Z3XBYmaMzIKRn5uSlqb9FrRTUAXxuoMurMZn3PE,10861
+flwr/serverapp/result.py,sha256=rw1ZoCGBosSVSNrTLLUFMxP1XzDwJWWsn1qdBR7JtlI,1229
+flwr/serverapp/strategy.py,sha256=1mxxtA5Pyg9lZ1d3g4OCL-m8YR_0E3HUGl8Gv5BGOXY,10982
+flwr/serverapp/strategy_utils.py,sha256=P2DO3pcrDTDYcrjkmYuL79Bbv2boj7T4bZ42EeRTyYk,9412
+flwr/serverapp/strategy_utils_tests.py,sha256=taG6HwApwutkjUuMY3R8Ib48Xepw6g5xl9HEB_-leoY,9232
 flwr/simulation/__init__.py,sha256=Gg6OsP1Z-ixc3-xxzvl7j7rz2Fijy9rzyEPpxgAQCeM,1556
 flwr/simulation/app.py,sha256=LbGLMvN9Ap119yBqsUcNNmVLRnCySnr4VechqcQ1hpA,10401
 flwr/simulation/legacy_app.py,sha256=nMISQqW0otJL1-2Kfd94O6BLlGS2IEmEPKTM2WGKrIs,15861
@@ -380,7 +385,7 @@ flwr/supernode/servicer/__init__.py,sha256=lucTzre5WPK7G1YLCfaqg3rbFWdNSb7ZTt-ca
 flwr/supernode/servicer/clientappio/__init__.py,sha256=7Oy62Y_oijqF7Dxi6tpcUQyOpLc_QpIRZ83NvwmB0Yg,813
 flwr/supernode/servicer/clientappio/clientappio_servicer.py,sha256=nIHRu38EWK-rpNOkcgBRAAKwYQQWFeCwu0lkO7OPZGQ,10239
 flwr/supernode/start_client_internal.py,sha256=ftS8GOyT9M1tOWpbobN_Xrz4xwPAPOvsTGiWSfzhheE,20269
-flwr_nightly-1.21.0.dev20250826.dist-info/METADATA,sha256=bsY60LCl-uEmARuZmk2J5LWeTLo0RNcxv-nL6JoRW04,15967
-flwr_nightly-1.21.0.dev20250826.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-flwr_nightly-1.21.0.dev20250826.dist-info/entry_points.txt,sha256=hxHD2ixb_vJFDOlZV-zB4Ao32_BQlL34ftsDh1GXv14,420
-flwr_nightly-1.21.0.dev20250826.dist-info/RECORD,,
+flwr_nightly-1.21.0.dev20250827.dist-info/METADATA,sha256=bBuFboanPjg8v12eYhwPbkoGwCxFJbwgOnTUsaZG2sU,15967
+flwr_nightly-1.21.0.dev20250827.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+flwr_nightly-1.21.0.dev20250827.dist-info/entry_points.txt,sha256=hxHD2ixb_vJFDOlZV-zB4Ao32_BQlL34ftsDh1GXv14,420
+flwr_nightly-1.21.0.dev20250827.dist-info/RECORD,,