flwr-nightly 1.22.0.dev20250916__py3-none-any.whl → 1.22.0.dev20250918__py3-none-any.whl

flwr/proto/control_pb2_grpc.py

@@ -44,6 +44,11 @@ class ControlStub(object):
                 request_serializer=flwr_dot_proto_dot_control__pb2.GetAuthTokensRequest.SerializeToString,
                 response_deserializer=flwr_dot_proto_dot_control__pb2.GetAuthTokensResponse.FromString,
                 )
+        self.PullArtifacts = channel.unary_unary(
+                '/flwr.proto.Control/PullArtifacts',
+                request_serializer=flwr_dot_proto_dot_control__pb2.PullArtifactsRequest.SerializeToString,
+                response_deserializer=flwr_dot_proto_dot_control__pb2.PullArtifactsResponse.FromString,
+                )
 
 
 class ControlServicer(object):
@@ -91,6 +96,13 @@ class ControlServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def PullArtifacts(self, request, context):
+        """Pull artifacts generated during a run (flwr pull)
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_ControlServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -124,6 +136,11 @@ def add_ControlServicer_to_server(servicer, server):
                     request_deserializer=flwr_dot_proto_dot_control__pb2.GetAuthTokensRequest.FromString,
                     response_serializer=flwr_dot_proto_dot_control__pb2.GetAuthTokensResponse.SerializeToString,
             ),
+            'PullArtifacts': grpc.unary_unary_rpc_method_handler(
+                    servicer.PullArtifacts,
+                    request_deserializer=flwr_dot_proto_dot_control__pb2.PullArtifactsRequest.FromString,
+                    response_serializer=flwr_dot_proto_dot_control__pb2.PullArtifactsResponse.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'flwr.proto.Control', rpc_method_handlers)
@@ -235,3 +252,20 @@ class Control(object):
             flwr_dot_proto_dot_control__pb2.GetAuthTokensResponse.FromString,
             options, channel_credentials,
             insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def PullArtifacts(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/flwr.proto.Control/PullArtifacts',
+            flwr_dot_proto_dot_control__pb2.PullArtifactsRequest.SerializeToString,
+            flwr_dot_proto_dot_control__pb2.PullArtifactsResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

flwr/proto/control_pb2_grpc.pyi

@@ -39,6 +39,11 @@ class ControlStub:
         flwr.proto.control_pb2.GetAuthTokensResponse]
     """Get auth tokens upon request"""
 
+    PullArtifacts: grpc.UnaryUnaryMultiCallable[
+        flwr.proto.control_pb2.PullArtifactsRequest,
+        flwr.proto.control_pb2.PullArtifactsResponse]
+    """Pull artifacts generated during a run (flwr pull)"""
+
 
 class ControlServicer(metaclass=abc.ABCMeta):
     @abc.abstractmethod
@@ -89,5 +94,13 @@ class ControlServicer(metaclass=abc.ABCMeta):
         """Get auth tokens upon request"""
         pass
 
+    @abc.abstractmethod
+    def PullArtifacts(self,
+        request: flwr.proto.control_pb2.PullArtifactsRequest,
+        context: grpc.ServicerContext,
+    ) -> flwr.proto.control_pb2.PullArtifactsResponse:
+        """Pull artifacts generated during a run (flwr pull)"""
+        pass
+
 
 def add_ControlServicer_to_server(servicer: ControlServicer, server: grpc.Server) -> None: ...

flwr/server/app.py

@@ -71,6 +71,7 @@ from flwr.server.fleet_event_log_interceptor import FleetEventLogInterceptor
 from flwr.supercore.ffs import FfsFactory
 from flwr.supercore.grpc_health import add_args_health, run_health_server_grpc_no_tls
 from flwr.supercore.object_store import ObjectStoreFactory
+from flwr.superlink.artifact_provider import ArtifactProvider
 from flwr.superlink.servicer.control import run_control_api_grpc
 
 from .superlink.fleet.grpc_adapter.grpc_adapter_servicer import GrpcAdapterServicer
@@ -91,6 +92,7 @@ try:
         get_control_auth_plugins,
         get_control_authz_plugins,
         get_control_event_log_writer_plugins,
+        get_ee_artifact_provider,
         get_fleet_event_log_writer_plugins,
     )
 except ImportError:
@@ -113,6 +115,10 @@ except ImportError:
             "No event log writer plugins are currently supported."
         )
 
+    def get_ee_artifact_provider(config_path: str) -> ArtifactProvider:
+        """Return the EE artifact provider."""
+        raise NotImplementedError("No artifact provider is currently supported.")
+
     def get_fleet_event_log_writer_plugins() -> dict[str, type[EventLogWriterPlugin]]:
         """Return all Fleet API event log writer plugins."""
         raise NotImplementedError(
@@ -199,6 +205,12 @@ def run_superlink() -> None:
         if args.enable_event_log:
             event_log_plugin = _try_obtain_control_event_log_writer_plugin()
 
+    # Load artifact provider if the args.artifact_provider_config is provided
+    artifact_provider = None
+    if cfg_path := getattr(args, "artifact_provider_config", None):
+        log(WARN, "The `--artifact-provider-config` flag is highly experimental.")
+        artifact_provider = get_ee_artifact_provider(cfg_path)
+
     # Initialize StateFactory
     state_factory = LinkStateFactory(args.database)
 
@@ -220,6 +232,7 @@ def run_superlink() -> None:
         auth_plugin=auth_plugin,
         authz_plugin=authz_plugin,
         event_log_plugin=event_log_plugin,
+        artifact_provider=artifact_provider,
     )
     grpc_servers = [control_server]
     bckg_threads: list[threading.Thread] = []

flwr/serverapp/strategy/__init__.py

@@ -24,8 +24,10 @@ from .fedadam import FedAdam
 from .fedavg import FedAvg
 from .fedavgm import FedAvgM
 from .fedmedian import FedMedian
+from .fedprox import FedProx
 from .fedtrimmedavg import FedTrimmedAvg
 from .fedxgb_bagging import FedXgbBagging
+from .fedxgb_cyclic import FedXgbCyclic
 from .fedyogi import FedYogi
 from .result import Result
 from .strategy import Strategy
@@ -38,8 +40,10 @@ __all__ = [
     "FedAvg",
     "FedAvgM",
     "FedMedian",
+    "FedProx",
     "FedTrimmedAvg",
     "FedXgbBagging",
+    "FedXgbCyclic",
     "FedYogi",
     "Result",
     "Strategy",

flwr/serverapp/strategy/fedprox.py

@@ -0,0 +1,174 @@
+# 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.
+# ==============================================================================
+"""Federated Optimization (FedProx) [Li et al., 2018] strategy.
+
+Paper: arxiv.org/abs/1812.06127
+"""
+
+
+from collections.abc import Iterable
+from logging import INFO, WARN
+from typing import Callable, Optional
+
+from flwr.common import (
+    ArrayRecord,
+    ConfigRecord,
+    Message,
+    MetricRecord,
+    RecordDict,
+    log,
+)
+from flwr.server import Grid
+
+from .fedavg import FedAvg
+
+
+class FedProx(FedAvg):
+    r"""Federated Optimization strategy.
+
+    Implementation based on https://arxiv.org/abs/1812.06127
+
+    FedProx extends FedAvg by introducing a proximal term into the client-side
+    optimization objective. The strategy itself behaves identically to FedAvg
+    on the server side, but each client **MUST** add a proximal regularization
+    term to its local loss function during training:
+
+    .. math::
+        \frac{\mu}{2} || w - w^t ||^2
+
+    Where $w^t$ denotes the global parameters and $w$ denotes the local weights
+    being optimized.
+
+    This strategy sends the proximal term inside the ``ConfigRecord`` as part of the
+    ``configure_train`` method under key ``"proximal-mu"``. The client can then use this
+    value to add the proximal term to the loss function.
+
+    In PyTorch, for example, the loss would go from:
+
+    .. code:: python
+        loss = criterion(net(inputs), labels)
+
+    To:
+
+    .. code:: python
+        # Get proximal term weight from message
+        mu = msg.content["config"]["proximal-mu"]
+
+        # Compute proximal term
+        proximal_term = 0.0
+        for local_weights, global_weights in zip(net.parameters(), global_params):
+            proximal_term += (local_weights - global_weights).norm(2)
+
+        # Update loss
+        loss = criterion(net(inputs), labels) + (mu / 2) * proximal_term
+
+    With ``global_params`` being a copy of the model parameters, created **after**
+    applying the received global weights but **before** local training begins.
+
+    .. code:: python
+        global_params = copy.deepcopy(net).parameters()
+
+    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.
+    proximal_mu : float (default: 0.0)
+        The weight of the proximal term used in the optimization. 0.0 makes
+        this strategy equivalent to FedAvg, and the higher the coefficient, the more
+        regularization will be used (that is, the client parameters will need to be
+        closer to the server parameters during training).
+    """
+
+    def __init__(  # pylint: disable=R0913, R0917
+        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,
+        proximal_mu: float = 0.0,
+    ) -> None:
+        super().__init__(
+            fraction_train=fraction_train,
+            fraction_evaluate=fraction_evaluate,
+            min_train_nodes=min_train_nodes,
+            min_evaluate_nodes=min_evaluate_nodes,
+            min_available_nodes=min_available_nodes,
+            weighted_by_key=weighted_by_key,
+            arrayrecord_key=arrayrecord_key,
+            configrecord_key=configrecord_key,
+            train_metrics_aggr_fn=train_metrics_aggr_fn,
+            evaluate_metrics_aggr_fn=evaluate_metrics_aggr_fn,
+        )
+        self.proximal_mu = proximal_mu
+
+        if self.proximal_mu == 0.0:
+            log(
+                WARN,
+                "FedProx initialized with `proximal_mu=0.0`. "
+                "This makes the strategy equivalent to FedAvg.",
+            )
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        log(INFO, "\t├──> FedProx settings:")
+        log(INFO, "\t|\t└── Proximal mu: %s", self.proximal_mu)
+        super().summary()
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated training."""
+        # Inject proximal term weight into config
+        config["proximal-mu"] = self.proximal_mu
+        return super().configure_train(server_round, arrays, config, grid)

flwr/serverapp/strategy/fedxgb_cyclic.py

@@ -0,0 +1,220 @@
+# 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 FedXgbCyclic strategy."""
+
+
+from collections.abc import Iterable
+from logging import INFO
+from typing import Callable, Optional, cast
+
+from flwr.common import (
+    ArrayRecord,
+    ConfigRecord,
+    Message,
+    MessageType,
+    MetricRecord,
+    RecordDict,
+    log,
+)
+from flwr.server import Grid
+
+from .fedavg import FedAvg
+from .strategy_utils import sample_nodes
+
+
+# pylint: disable=line-too-long
+class FedXgbCyclic(FedAvg):
+    """Configurable FedXgbCyclic strategy implementation.
+
+    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_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_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:
+        super().__init__(
+            fraction_train=fraction_train,
+            fraction_evaluate=fraction_evaluate,
+            min_train_nodes=2,
+            min_evaluate_nodes=2,
+            min_available_nodes=min_available_nodes,
+            weighted_by_key=weighted_by_key,
+            arrayrecord_key=arrayrecord_key,
+            configrecord_key=configrecord_key,
+            train_metrics_aggr_fn=train_metrics_aggr_fn,
+            evaluate_metrics_aggr_fn=evaluate_metrics_aggr_fn,
+        )
+
+        self.registered_nodes: dict[int, int] = {}
+
+        if fraction_train not in (0.0, 1.0):
+            raise ValueError(
+                "fraction_train can only be set to 1.0 or 0.0 for FedXgbCyclic."
+            )
+        if fraction_evaluate not in (0.0, 1.0):
+            raise ValueError(
+                "fraction_evaluate can only be set to 1.0 or 0.0 for FedXgbCyclic."
+            )
+
+    def _reorder_nodes(self, node_ids: list[int]) -> list[int]:
+        """Re-order node ids based on registered nodes.
+
+        Each node ID is assigned a persistent index in `self.registered_nodes`
+        the first time it appears. The input list is then reordered according
+        to these stored indices, and the result is compacted into ascending
+        order (1..N) for the current call.
+        """
+        # Assign new indices to unknown nodes
+        next_index = max(self.registered_nodes.values(), default=0) + 1
+        for nid in node_ids:
+            if nid not in self.registered_nodes:
+                self.registered_nodes[nid] = next_index
+                next_index += 1
+
+        # Sort node_ids by their stored indices
+        sorted_by_index = sorted(node_ids, key=lambda x: self.registered_nodes[x])
+
+        # Compact re-map of indices just for this output list
+        unique_indices = sorted(self.registered_nodes[nid] for nid in sorted_by_index)
+        remap = {old: new for new, old in enumerate(unique_indices, start=1)}
+
+        # Build the result list ordered by compact indices
+        result_list = [
+            nid
+            for _, nid in sorted(
+                (remap[self.registered_nodes[nid]], nid) for nid in sorted_by_index
+            )
+        ]
+        return result_list
+
+    def _make_sampling(
+        self, grid: Grid, server_round: int, configure_type: str
+    ) -> list[int]:
+        """Sample nodes using the Grid."""
+        # 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, _ = sample_nodes(grid, self.min_available_nodes, sample_size)
+
+        # Re-order node_ids
+        node_ids = self._reorder_nodes(node_ids)
+
+        # Sample the clients sequentially given server_round
+        sampled_idx = (server_round - 1) % len(node_ids)
+        sampled_node_id = [node_ids[sampled_idx]]
+
+        log(
+            INFO,
+            f"{configure_type}: Sampled %s nodes (out of %s)",
+            len(sampled_node_id),
+            len(node_ids),
+        )
+        return sampled_node_id
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated training."""
+        # Sample one node
+        sampled_node_id = self._make_sampling(grid, server_round, "configure_train")
+
+        # 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, sampled_node_id, 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."""
+        valid_replies, _ = self._check_and_log_replies(replies, is_train=True)
+
+        arrays, metrics = None, None
+        if valid_replies:
+            reply_contents = [msg.content for msg in valid_replies]
+            array_record_key = next(iter(reply_contents[0].array_records.keys()))
+
+            # Fetch the client model from current round as global model
+            arrays = cast(ArrayRecord, reply_contents[0][array_record_key])
+
+            # Aggregate MetricRecords
+            metrics = self.train_metrics_aggr_fn(
+                reply_contents,
+                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 one node
+        sampled_node_id = self._make_sampling(grid, server_round, "configure_evaluate")
+
+        # 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, sampled_node_id, MessageType.EVALUATE)

flwr/simulation/app.py

@@ -245,7 +245,7 @@ def run_simulation_process(  # pylint: disable=R0913, R0914, R0915, R0917, W0212
             run=run,
             enable_tf_gpu_growth=enable_tf_gpu_growth,
             verbose_logging=verbose,
-            server_app_run_config=fused_config,
+            server_app_context=context,
             is_app=True,
             exit_event=EventType.FLWR_SIMULATION_RUN_LEAVE,
         )