flwr-nightly 1.22.0.dev20250917__py3-none-any.whl → 1.22.0.dev20250919__py3-none-any.whl

flwr/cli/new/new.py

@@ -41,6 +41,7 @@ class MlFramework(str, Enum):
     JAX = "JAX"
     MLX = "MLX"
     NUMPY = "NumPy"
+    XGBOOST = "XGBoost"
     FLOWERTUNE = "FlowerTune"
     BASELINE = "Flower Baseline"
     PYTORCH_LEGACY_API = "PyTorch (Legacy API, deprecated)"
@@ -247,6 +248,7 @@ def new(
             MlFramework.TENSORFLOW.value,
             MlFramework.SKLEARN.value,
             MlFramework.NUMPY.value,
+            MlFramework.XGBOOST.value,
             "pytorch_legacy_api",
         ]
         if framework_str in frameworks_with_tasks:

flwr/cli/new/templates/app/code/client.xgboost.py.tpl

@@ -0,0 +1,110 @@
+"""$project_name: A Flower / $framework_str app."""
+
+import warnings
+
+import numpy as np
+import xgboost as xgb
+from flwr.app import ArrayRecord, Context, Message, MetricRecord, RecordDict
+from flwr.clientapp import ClientApp
+from flwr.common.config import unflatten_dict
+
+from $import_name.task import load_data, replace_keys
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+# Flower ClientApp
+app = ClientApp()
+
+
+def _local_boost(bst_input, num_local_round, train_dmatrix):
+    # Update trees based on local training data.
+    for i in range(num_local_round):
+        bst_input.update(train_dmatrix, bst_input.num_boosted_rounds())
+
+    # Bagging: extract the last N=num_local_round trees for sever aggregation
+    bst = bst_input[
+        bst_input.num_boosted_rounds()
+        - num_local_round : bst_input.num_boosted_rounds()
+    ]
+    return bst
+
+
+@app.train()
+def train(msg: Message, context: Context) -> Message:
+    # Load model and data
+    partition_id = context.node_config["partition-id"]
+    num_partitions = context.node_config["num-partitions"]
+    train_dmatrix, _, num_train, _ = load_data(partition_id, num_partitions)
+
+    # Read from run config
+    num_local_round = context.run_config["local-epochs"]
+    # Flatted config dict and replace "-" with "_"
+    cfg = replace_keys(unflatten_dict(context.run_config))
+    params = cfg["params"]
+
+    global_round = msg.content["config"]["server-round"]
+    if global_round == 1:
+        # First round local training
+        bst = xgb.train(
+            params,
+            train_dmatrix,
+            num_boost_round=num_local_round,
+        )
+    else:
+        bst = xgb.Booster(params=params)
+        global_model = bytearray(msg.content["arrays"]["0"].numpy().tobytes())
+
+        # Load global model into booster
+        bst.load_model(global_model)
+
+        # Local training
+        bst = _local_boost(bst, num_local_round, train_dmatrix)
+
+    # Save model
+    local_model = bst.save_raw("json")
+    model_np = np.frombuffer(local_model, dtype=np.uint8)
+
+    # Construct reply message
+    # Note: we store the model as the first item in a list into ArrayRecord,
+    # which can be accessed using index ["0"].
+    model_record = ArrayRecord([model_np])
+    metrics = {
+        "num-examples": num_train,
+    }
+    metric_record = MetricRecord(metrics)
+    content = RecordDict({"arrays": model_record, "metrics": metric_record})
+    return Message(content=content, reply_to=msg)
+
+
+@app.evaluate()
+def evaluate(msg: Message, context: Context) -> Message:
+    # Load model and data
+    partition_id = context.node_config["partition-id"]
+    num_partitions = context.node_config["num-partitions"]
+    _, valid_dmatrix, _, num_val = load_data(partition_id, num_partitions)
+
+    # Load config
+    cfg = replace_keys(unflatten_dict(context.run_config))
+    params = cfg["params"]
+
+    # Load global model
+    bst = xgb.Booster(params=params)
+    global_model = bytearray(msg.content["arrays"]["0"].numpy().tobytes())
+    bst.load_model(global_model)
+
+    # Run evaluation
+    eval_results = bst.eval_set(
+        evals=[(valid_dmatrix, "valid")],
+        iteration=bst.num_boosted_rounds() - 1,
+    )
+    auc = float(eval_results.split("\t")[1].split(":")[1])
+
+    # Construct and return reply Message
+    metrics = {
+        "auc": auc,
+        "num-examples": num_val,
+    }
+    metric_record = MetricRecord(metrics)
+    content = RecordDict({"metrics": metric_record})
+    return Message(content=content, reply_to=msg)

flwr/cli/new/templates/app/code/server.xgboost.py.tpl

@@ -0,0 +1,56 @@
+"""$project_name: A Flower / $framework_str app."""
+
+import numpy as np
+import xgboost as xgb
+from flwr.app import ArrayRecord, Context
+from flwr.common.config import unflatten_dict
+from flwr.serverapp import Grid, ServerApp
+from flwr.serverapp.strategy import FedXgbBagging
+
+from $import_name.task import replace_keys
+
+# Create ServerApp
+app = ServerApp()
+
+
+@app.main()
+def main(grid: Grid, context: Context) -> None:
+    # Read run config
+    num_rounds = context.run_config["num-server-rounds"]
+    fraction_train = context.run_config["fraction-train"]
+    fraction_evaluate = context.run_config["fraction-evaluate"]
+    # Flatted config dict and replace "-" with "_"
+    cfg = replace_keys(unflatten_dict(context.run_config))
+    params = cfg["params"]
+
+    # Init global model
+    # Init with an empty object; the XGBooster will be created
+    # and trained on the client side.
+    global_model = b""
+    # Note: we store the model as the first item in a list into ArrayRecord,
+    # which can be accessed using index ["0"].
+    arrays = ArrayRecord([np.frombuffer(global_model, dtype=np.uint8)])
+
+    # Initialize FedXgbBagging strategy
+    strategy = FedXgbBagging(
+        fraction_train=fraction_train,
+        fraction_evaluate=fraction_evaluate,
+    )
+
+    # Start strategy, run FedXgbBagging for `num_rounds`
+    result = strategy.start(
+        grid=grid,
+        initial_arrays=arrays,
+        num_rounds=num_rounds,
+    )
+
+    # Save final model to disk
+    bst = xgb.Booster(params=params)
+    global_model = bytearray(result.arrays["0"].numpy().tobytes())
+
+    # Load global model into booster
+    bst.load_model(global_model)
+
+    # Save model
+    print("\nSaving final model to disk...")
+    bst.save_model("final_model.json")

flwr/cli/new/templates/app/code/task.xgboost.py.tpl

@@ -0,0 +1,67 @@
+"""$project_name: A Flower / $framework_str app."""
+
+import xgboost as xgb
+from flwr_datasets import FederatedDataset
+from flwr_datasets.partitioner import IidPartitioner
+
+
+def train_test_split(partition, test_fraction, seed):
+    """Split the data into train and validation set given split rate."""
+    train_test = partition.train_test_split(test_size=test_fraction, seed=seed)
+    partition_train = train_test["train"]
+    partition_test = train_test["test"]
+
+    num_train = len(partition_train)
+    num_test = len(partition_test)
+
+    return partition_train, partition_test, num_train, num_test
+
+
+def transform_dataset_to_dmatrix(data):
+    """Transform dataset to DMatrix format for xgboost."""
+    x = data["inputs"]
+    y = data["label"]
+    new_data = xgb.DMatrix(x, label=y)
+    return new_data
+
+
+fds = None  # Cache FederatedDataset
+
+
+def load_data(partition_id, num_clients):
+    """Load partition HIGGS data."""
+    # Only initialize `FederatedDataset` once
+    global fds
+    if fds is None:
+        partitioner = IidPartitioner(num_partitions=num_clients)
+        fds = FederatedDataset(
+            dataset="jxie/higgs",
+            partitioners={"train": partitioner},
+        )
+
+    # Load the partition for this `partition_id`
+    partition = fds.load_partition(partition_id, split="train")
+    partition.set_format("numpy")
+
+    # Train/test splitting
+    train_data, valid_data, num_train, num_val = train_test_split(
+        partition, test_fraction=0.2, seed=42
+    )
+
+    # Reformat data to DMatrix for xgboost
+    train_dmatrix = transform_dataset_to_dmatrix(train_data)
+    valid_dmatrix = transform_dataset_to_dmatrix(valid_data)
+
+    return train_dmatrix, valid_dmatrix, num_train, num_val
+
+
+def replace_keys(input_dict, match="-", target="_"):
+    """Recursively replace match string with target string in dictionary keys."""
+    new_dict = {}
+    for key, value in input_dict.items():
+        new_key = key.replace(match, target)
+        if isinstance(value, dict):
+            new_dict[new_key] = replace_keys(value, match, target)
+        else:
+            new_dict[new_key] = value
+    return new_dict

flwr/cli/new/templates/app/pyproject.xgboost.toml.tpl

@@ -0,0 +1,61 @@
+# =====================================================================
+# For a full TOML configuration guide, check the Flower docs:
+# https://flower.ai/docs/framework/how-to-configure-pyproject-toml.html
+# =====================================================================
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "$package_name"
+version = "1.0.0"
+description = ""
+license = "Apache-2.0"
+# Dependencies for your Flower App
+dependencies = [
+    "flwr[simulation]>=1.22.0",
+    "flwr-datasets>=0.5.0",
+    "xgboost>=2.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.flwr.app]
+publisher = "$username"
+
+[tool.flwr.app.components]
+serverapp = "$import_name.server_app:app"
+clientapp = "$import_name.client_app:app"
+
+# Custom config values accessible via `context.run_config`
+[tool.flwr.app.config]
+num-server-rounds = 3
+fraction-train = 0.1
+fraction-evaluate = 0.1
+local-epochs = 1
+
+# XGBoost parameters
+params.objective = "binary:logistic"
+params.eta = 0.1 # Learning rate
+params.max-depth = 8
+params.eval-metric = "auc"
+params.nthread = 16
+params.num-parallel-tree = 1
+params.subsample = 1
+params.tree-method = "hist"
+
+# Default federation to use when running the app
+[tool.flwr.federations]
+default = "local-simulation"
+
+# Local simulation federation with 10 virtual SuperNodes
+[tool.flwr.federations.local-simulation]
+options.num-supernodes = 10
+
+# Remote federation example for use with SuperLink
+[tool.flwr.federations.remote-federation]
+address = "<SUPERLINK-ADDRESS>:<PORT>"
+insecure = true  # Remove this line to enable TLS
+# root-certificates = "<PATH/TO/ca.crt>"  # For TLS setup

flwr/clientapp/mod/__init__.py

@@ -17,9 +17,10 @@
 
 from flwr.client.mod.comms_mods import arrays_size_mod, message_size_mod
 
-from .centraldp_mods import fixedclipping_mod
+from .centraldp_mods import adaptiveclipping_mod, fixedclipping_mod
 
 __all__ = [
+    "adaptiveclipping_mod",
     "arrays_size_mod",
     "fixedclipping_mod",
     "message_size_mod",

flwr/clientapp/mod/centraldp_mods.py

@@ -16,13 +16,26 @@
 
 
 from collections import OrderedDict
-from logging import INFO, WARN
+from logging import ERROR, INFO
 from typing import cast
 
-from flwr.client.typing import ClientAppCallable
-from flwr.common import Array, ArrayRecord, Context, Message, MessageType, log
-from flwr.common.differential_privacy import compute_clip_model_update
-from flwr.common.differential_privacy_constants import KEY_CLIPPING_NORM
+from flwr.app import Error
+from flwr.clientapp.typing import ClientAppCallable
+from flwr.common import (
+    Array,
+    ArrayRecord,
+    ConfigRecord,
+    Context,
+    Message,
+    MetricRecord,
+    log,
+)
+from flwr.common.constant import ErrorCode
+from flwr.common.differential_privacy import (
+    compute_adaptive_clip_model_update,
+    compute_clip_model_update,
+)
+from flwr.common.differential_privacy_constants import KEY_CLIPPING_NORM, KEY_NORM_BIT
 
 
 # pylint: disable=too-many-return-statements
@@ -46,33 +59,15 @@ def fixedclipping_mod(
 
     Typically, fixedclipping_mod should be the last to operate on params.
     """
-    if msg.metadata.message_type != MessageType.TRAIN:
-        return call_next(msg, ctxt)
-
     if len(msg.content.array_records) != 1:
-        log(
-            WARN,
-            "fixedclipping_mod is designed to work with a single ArrayRecord. "
-            "Skipping.",
-        )
-        return call_next(msg, ctxt)
-
+        return _handle_multi_record_err("fixedclipping_mod", msg, ArrayRecord)
     if len(msg.content.config_records) != 1:
-        log(
-            WARN,
-            "fixedclipping_mod is designed to work with a single ConfigRecord. "
-            "Skipping.",
-        )
-        return call_next(msg, ctxt)
+        return _handle_multi_record_err("fixedclipping_mod", msg, ConfigRecord)
 
     # Get keys in the single ConfigRecord
     keys_in_config = set(next(iter(msg.content.config_records.values())).keys())
     if KEY_CLIPPING_NORM not in keys_in_config:
-        raise KeyError(
-            f"The {KEY_CLIPPING_NORM} value is not supplied by the "
-            f"`DifferentialPrivacyClientSideFixedClipping` wrapper at"
-            f" the server side."
-        )
+        return _handle_no_key_err("fixedclipping_mod", msg)
     # Record array record communicated to client and clipping norm
     original_array_record = next(iter(msg.content.array_records.values()))
     clipping_norm = cast(
@@ -86,26 +81,16 @@ def fixedclipping_mod(
     if out_msg.has_error():
         return out_msg
 
-    # Ensure there is a single ArrayRecord
+    # Ensure reply has a single ArrayRecord
     if len(out_msg.content.array_records) != 1:
-        log(
-            WARN,
-            "fixedclipping_mod is designed to work with a single ArrayRecord. "
-            "Skipping.",
-        )
-        return out_msg
+        return _handle_multi_record_err("fixedclipping_mod", out_msg, ArrayRecord)
 
     new_array_record_key, client_to_server_arrecord = next(
         iter(out_msg.content.array_records.items())
     )
     # Ensure keys in returned ArrayRecord match those in the one sent from server
     if set(original_array_record.keys()) != set(client_to_server_arrecord.keys()):
-        log(
-            WARN,
-            "fixedclipping_mod: Keys in ArrayRecord must match those from the model "
-            "that the ClientApp received. Skipping.",
-        )
-        return out_msg
+        return _handle_array_key_mismatch_err("fixedclipping_mod", out_msg)
 
     client_to_server_ndarrays = client_to_server_arrecord.to_numpy_ndarrays()
     # Clip the client update
@@ -130,3 +115,134 @@ def fixedclipping_mod(
         )
     )
     return out_msg
+
+
+def adaptiveclipping_mod(
+    msg: Message, ctxt: Context, call_next: ClientAppCallable
+) -> Message:
+    """Client-side adaptive clipping modifier.
+
+    This mod needs to be used with the DifferentialPrivacyClientSideAdaptiveClipping
+    server-side strategy wrapper.
+
+    The wrapper sends the clipping_norm value to the client.
+
+    This mod clips the client model updates before sending them to the server.
+
+    It also sends KEY_NORM_BIT to the server for computing the new clipping value.
+
+    It operates on messages of type `MessageType.TRAIN`.
+
+    Notes
+    -----
+    Consider the order of mods when using multiple.
+
+    Typically, adaptiveclipping_mod should be the last to operate on params.
+    """
+    if len(msg.content.array_records) != 1:
+        return _handle_multi_record_err("adaptiveclipping_mod", msg, ArrayRecord)
+    if len(msg.content.config_records) != 1:
+        return _handle_multi_record_err("adaptiveclipping_mod", msg, ConfigRecord)
+
+    # Get keys in the single ConfigRecord
+    keys_in_config = set(next(iter(msg.content.config_records.values())).keys())
+    if KEY_CLIPPING_NORM not in keys_in_config:
+        return _handle_no_key_err("adaptiveclipping_mod", msg)
+
+    # Record array record communicated to client and clipping norm
+    original_array_record = next(iter(msg.content.array_records.values()))
+    clipping_norm = cast(
+        float, next(iter(msg.content.config_records.values()))[KEY_CLIPPING_NORM]
+    )
+
+    # Call inner app
+    out_msg = call_next(msg, ctxt)
+
+    # Ensure reply has a single ArrayRecord
+    if len(out_msg.content.array_records) != 1:
+        return _handle_multi_record_err("adaptiveclipping_mod", out_msg, ArrayRecord)
+
+    # Ensure reply has a single MetricRecord
+    if len(out_msg.content.metric_records) != 1:
+        return _handle_multi_record_err("adaptiveclipping_mod", out_msg, MetricRecord)
+
+    # Check if the msg has error
+    if out_msg.has_error():
+        return out_msg
+
+    new_array_record_key, client_to_server_arrecord = next(
+        iter(out_msg.content.array_records.items())
+    )
+
+    # Ensure keys in returned ArrayRecord match those in the one sent from server
+    if set(original_array_record.keys()) != set(client_to_server_arrecord.keys()):
+        return _handle_array_key_mismatch_err("adaptiveclipping_mod", out_msg)
+
+    client_to_server_ndarrays = client_to_server_arrecord.to_numpy_ndarrays()
+    # Clip the client update
+    norm_bit = compute_adaptive_clip_model_update(
+        client_to_server_ndarrays,
+        original_array_record.to_numpy_ndarrays(),
+        clipping_norm,
+    )
+    log(
+        INFO,
+        "adaptiveclipping_mod: ndarrays are clipped by value: %.4f.",
+        clipping_norm,
+    )
+    # Replace outgoing ArrayRecord's Array while preserving their keys
+    out_msg.content.array_records[new_array_record_key] = ArrayRecord(
+        OrderedDict(
+            {
+                k: Array(v)
+                for k, v in zip(
+                    client_to_server_arrecord.keys(), client_to_server_ndarrays
+                )
+            }
+        )
+    )
+    # Add to the MetricRecords the norm bit (recall reply messages only contain
+    # one MetricRecord)
+    metric_record_key = list(out_msg.content.metric_records.keys())[0]
+    # We cast it to `int` because MetricRecord does not support `bool` values
+    out_msg.content.metric_records[metric_record_key][KEY_NORM_BIT] = int(norm_bit)
+    return out_msg
+
+
+def _handle_err(msg: Message, reason: str) -> Message:
+    """Log and return error message."""
+    log(ERROR, reason)
+    return Message(
+        Error(code=ErrorCode.MOD_FAILED_PRECONDITION, reason=reason),
+        reply_to=msg,
+    )
+
+
+def _handle_multi_record_err(mod_name: str, msg: Message, record_type: type) -> Message:
+    """Log and return multi-record error."""
+    cnt = sum(isinstance(_, record_type) for _ in msg.content.values())
+    return _handle_err(
+        msg,
+        f"{mod_name} expects exactly one {record_type.__name__}, "
+        f"but found {cnt} {record_type.__name__}(s).",
+    )
+
+
+def _handle_no_key_err(mod_name: str, msg: Message) -> Message:
+    """Log and return no-key error."""
+    return _handle_err(
+        msg,
+        f"{mod_name} requires the key '{KEY_CLIPPING_NORM}' to be present in the "
+        "ConfigRecord, but it was not found. "
+        "Please ensure the `DifferentialPrivacyClientSideFixedClipping` wrapper "
+        "is used in the ServerApp.",
+    )
+
+
+def _handle_array_key_mismatch_err(mod_name: str, msg: Message) -> Message:
+    """Create array-key-mismatch error reasons."""
+    return _handle_err(
+        msg,
+        f"{mod_name} expects the keys in the ArrayRecord of the reply message to match "
+        "those from the ArrayRecord that the ClientApp received, but they do not.",
+    )

flwr/clientapp/typing.py

@@ -0,0 +1,22 @@
+# 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.
+# ==============================================================================
+"""Custom types for Flower clients."""
+
+
+from typing import Callable
+
+from flwr.common import Context, Message
+
+ClientAppCallable = Callable[[Message, Context], Message]

flwr/common/constant.py

@@ -202,6 +202,7 @@ class ErrorCode:
     MESSAGE_UNAVAILABLE = 3
     REPLY_MESSAGE_UNAVAILABLE = 4
     NODE_UNAVAILABLE = 5
+    MOD_FAILED_PRECONDITION = 6
 
     def __new__(cls) -> ErrorCode:
         """Prevent instantiation."""

flwr/common/exit/exit_code.py

@@ -45,6 +45,7 @@ class ExitCode:
     SUPERNODE_NODE_AUTH_KEYS_INVALID = 302
 
     # SuperExec-specific exit codes (400-499)
+    SUPEREXEC_INVALID_PLUGIN_CONFIG = 400
 
     # Common exit codes (600-699)
     COMMON_ADDRESS_INVALID = 600
@@ -112,6 +113,9 @@ EXIT_CODE_HELP = {
         "file and try again."
     ),
     # SuperExec-specific exit codes (400-499)
+    ExitCode.SUPEREXEC_INVALID_PLUGIN_CONFIG: (
+        "The YAML configuration for the SuperExec plugin is invalid."
+    ),
     # Common exit codes (600-699)
     ExitCode.COMMON_ADDRESS_INVALID: (
         "Please provide a valid URL, IPv4 or IPv6 address."

flwr/common/record/typeddict.py

@@ -18,6 +18,8 @@
 from collections.abc import ItemsView, Iterator, KeysView, MutableMapping, ValuesView
 from typing import Callable, Generic, TypeVar, cast
 
+from typing_extensions import Self
+
 K = TypeVar("K")  # Key type
 V = TypeVar("V")  # Value type
 
@@ -86,3 +88,13 @@ class TypedDict(MutableMapping[K, V], Generic[K, V]):
     def items(self) -> ItemsView[K, V]:
         """D.items() -> a set-like object providing a view on D's items."""
         return cast(dict[K, V], self.__dict__["_data"]).items()
+
+    def copy(self) -> Self:
+        """Return a shallow copy of the dictionary."""
+        # Allocate instance without going through __init__
+        new = self.__class__.__new__(type(self))
+        # Copy internal state
+        new.__dict__["_check_key_fn"] = self.__dict__["_check_key_fn"]
+        new.__dict__["_check_value_fn"] = self.__dict__["_check_value_fn"]
+        new.__dict__["_data"] = cast(dict[K, V], self.__dict__["_data"]).copy()
+        return new

flwr/serverapp/strategy/__init__.py

@@ -15,6 +15,10 @@
 """ServerApp strategies."""
 
 
+from .dp_adaptive_clipping import (
+    DifferentialPrivacyClientSideAdaptiveClipping,
+    DifferentialPrivacyServerSideAdaptiveClipping,
+)
 from .dp_fixed_clipping import (
     DifferentialPrivacyClientSideFixedClipping,
     DifferentialPrivacyServerSideFixedClipping,
@@ -27,12 +31,17 @@ 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 .krum import Krum
+from .qfedavg import QFedAvg
 from .result import Result
 from .strategy import Strategy
 
 __all__ = [
+    "DifferentialPrivacyClientSideAdaptiveClipping",
     "DifferentialPrivacyClientSideFixedClipping",
+    "DifferentialPrivacyServerSideAdaptiveClipping",
     "DifferentialPrivacyServerSideFixedClipping",
     "FedAdagrad",
     "FedAdam",
@@ -42,7 +51,10 @@ __all__ = [
     "FedProx",
     "FedTrimmedAvg",
     "FedXgbBagging",
+    "FedXgbCyclic",
     "FedYogi",
+    "Krum",
+    "QFedAvg",
     "Result",
     "Strategy",
 ]