flwr-nightly 1.21.0.dev20250901__py3-none-any.whl → 1.21.0.dev20250903__py3-none-any.whl

flwr/cli/constant.py

@@ -15,13 +15,30 @@
 """Constants for CLI commands."""
 
 
+# General help message for config overrides
+CONFIG_HELP_MESSAGE = (
+    "Override {0} values using one of the following formats:\n\n"
+    "--{1} '<k1>=<v1> <k2>=<v2>' | --{1} '<k1>=<v1>' --{1} '<k2>=<v2>'{2}\n\n"
+    "When providing key-value pairs, values can be of any type supported by TOML "
+    "(e.g., bool, int, float, string). The specified keys (<k1> and <k2> in the "
+    "example) must exist in the {0} under the `{3}` section of `pyproject.toml` to be "
+    "overridden.{4}"
+)
+
+# The help message for `--run-config` option
+RUN_CONFIG_HELP_MESSAGE = CONFIG_HELP_MESSAGE.format(
+    "run configuration",
+    "run-config",
+    " | --run-config <path/to/your/toml>",
+    "[tool.flwr.app.config]",
+    " Alternatively, provide a TOML file containing overrides.",
+)
+
 # The help message for `--federation-config` option
-FEDERATION_CONFIG_HELP_MESSAGE = (
-    "Override federation configuration values in the format:\n\n"
-    "`--federation-config 'key1=value1 key2=value2' --federation-config "
-    "'key3=value3'`\n\nValues can be of any type supported in TOML, such as "
-    "bool, int, float, or string. Ensure that the keys (`key1`, `key2`, `key3` "
-    "in this example) exist in the federation configuration under the "
-    "`[tool.flwr.federations.<YOUR_FEDERATION>]` table of the `pyproject.toml` "
-    "for proper overriding."
+FEDERATION_CONFIG_HELP_MESSAGE = CONFIG_HELP_MESSAGE.format(
+    "federation configuration",
+    "federation-config",
+    "",
+    "[tool.flwr.federations.<YOUR-FEDERATION>]",
+    "",
 )

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

@@ -1,7 +1,5 @@
 """$project_name: A Flower / $framework_str app."""
 
-from pprint import pprint
-
 import torch
 from flwr.common import ArrayRecord, ConfigRecord, Context
 from flwr.server import Grid, ServerApp
@@ -37,12 +35,6 @@ def main(grid: Grid, context: Context) -> None:
         num_rounds=num_rounds,
     )
 
-    # Log resulting metrics
-    print("\nDistributed train metrics:")
-    pprint(result.train_metrics_clientapp)
-    print("\nDistributed evaluate metrics:")
-    pprint(result.evaluate_metrics_clientapp)
-
     # Save final model to disk
     print("\nSaving final model to disk...")
     state_dict = result.arrays.to_torch_state_dict()

flwr/cli/run/run.py

@@ -30,7 +30,7 @@ from flwr.cli.config_utils import (
     process_loaded_project_config,
     validate_federation_in_project_config,
 )
-from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
+from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE, RUN_CONFIG_HELP_MESSAGE
 from flwr.common.config import (
     flatten_dict,
     get_metadata_from_config,
@@ -65,11 +65,7 @@ def run(
         typer.Option(
             "--run-config",
             "-c",
-            help="Override run configuration values in the format:\n\n"
-            "`--run-config 'key1=value1 key2=value2' --run-config 'key3=value3'`\n\n"
-            "Values can be of any type supported in TOML, such as bool, int, "
-            "float, or string. Ensure that the keys (`key1`, `key2`, `key3` "
-            "in this example) exist in `pyproject.toml` for proper overriding.",
+            help=RUN_CONFIG_HELP_MESSAGE,
         ),
     ] = None,
     federation_config_overrides: Annotated[

flwr/clientapp/__init__.py

@@ -13,3 +13,7 @@
 # limitations under the License.
 # ==============================================================================
 """Public Flower ClientApp APIs."""
+
+from .centraldp_mods import fixedclipping_mod
+
+__all__ = ["fixedclipping_mod"]

flwr/clientapp/centraldp_mods.py

@@ -0,0 +1,132 @@
+# 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.
+# ==============================================================================
+"""Clipping modifiers for central DP with client-side clipping."""
+
+
+from collections import OrderedDict
+from logging import INFO, WARN
+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
+
+
+# pylint: disable=too-many-return-statements
+def fixedclipping_mod(
+    msg: Message, ctxt: Context, call_next: ClientAppCallable
+) -> Message:
+    """Client-side fixed clipping modifier.
+
+    This mod needs to be used with the `DifferentialPrivacyClientSideFixedClipping`
+    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 operates on messages of type `MessageType.TRAIN`.
+
+    Notes
+    -----
+    Consider the order of mods when using multiple.
+
+    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)
+
+    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)
+
+    # 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."
+        )
+    # 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)
+
+    # Check if the msg has error
+    if out_msg.has_error():
+        return out_msg
+
+    # Ensure there is 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
+
+    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
+
+    client_to_server_ndarrays = client_to_server_arrecord.to_numpy_ndarrays()
+    # Clip the client update
+    compute_clip_model_update(
+        param1=client_to_server_ndarrays,
+        param2=original_array_record.to_numpy_ndarrays(),
+        clipping_norm=clipping_norm,
+    )
+
+    log(
+        INFO, "fixedclipping_mod: parameters 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
+                )
+            }
+        )
+    )
+    return out_msg

flwr/common/exception.py

@@ -0,0 +1,31 @@
+# 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 application exceptions."""
+
+
+class AppExitException(Exception):
+    """Base exception for all application-level errors in ServerApp and ClientApp.
+
+    When raised, the process will exit and report a telemetry event with the associated
+    exit code.
+    """
+
+    # Default exit code — subclasses must override
+    exit_code = -1
+
+    def __init_subclass__(cls) -> None:
+        """Ensure subclasses override the exit_code attribute."""
+        if cls.exit_code == -1:
+            raise ValueError("Subclasses must override the exit_code attribute.")

flwr/common/exit/__init__.py

@@ -17,8 +17,12 @@
 
 from .exit import flwr_exit
 from .exit_code import ExitCode
+from .exit_handler import add_exit_handler
+from .signal_handler import register_signal_handlers
 
 __all__ = [
     "ExitCode",
+    "add_exit_handler",
     "flwr_exit",
+    "register_signal_handlers",
 ]

flwr/common/exit/exit.py

@@ -26,6 +26,7 @@ from flwr.common.version import package_version
 
 from ..logger import log
 from .exit_code import EXIT_CODE_HELP
+from .exit_handler import trigger_exit_handlers
 
 HELP_PAGE_URL = (
     f"https://flower.ai/docs/framework/v{package_version}/en/ref-exit-codes/"
@@ -80,6 +81,9 @@ def flwr_exit(
     # Log the exit message
     log(log_level, exit_message)
 
+    # Trigger exit handlers
+    trigger_exit_handlers()
+
     # Exit
     sys.exit(sys_exit_code)
 

flwr/common/exit/exit_code.py

@@ -36,6 +36,8 @@ class ExitCode:
 
     # ServerApp-specific exit codes (200-299)
     SERVERAPP_STRATEGY_PRECONDITION_UNMET = 200
+    SERVERAPP_EXCEPTION = 201
+    SERVERAPP_STRATEGY_AGGREGATION_ERROR = 202
 
     # SuperNode-specific exit codes (300-399)
     SUPERNODE_REST_ADDRESS_INVALID = 300
@@ -89,6 +91,11 @@ EXIT_CODE_HELP = {
         "perform weighted average (e.g. in FedAvg) please ensure the returned "
         "MetricRecord from ClientApps do include this key."
     ),
+    ExitCode.SERVERAPP_EXCEPTION: "An unhandled exception occurred in the ServerApp.",
+    ExitCode.SERVERAPP_STRATEGY_AGGREGATION_ERROR: (
+        "The strategy encountered an error during aggregation. Please check the logs "
+        "for more details."
+    ),
     # SuperNode-specific exit codes (300-399)
     ExitCode.SUPERNODE_REST_ADDRESS_INVALID: (
         "When using the REST API, please provide `https://` or "

flwr/common/exit/exit_handler.py

@@ -0,0 +1,62 @@
+# 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.
+# ==============================================================================
+"""Common function to register exit handlers."""
+
+
+import signal
+import threading
+from typing import Callable
+
+from .exit_code import ExitCode
+
+SIGNAL_TO_EXIT_CODE: dict[int, int] = {
+    signal.SIGINT: ExitCode.GRACEFUL_EXIT_SIGINT,
+    signal.SIGTERM: ExitCode.GRACEFUL_EXIT_SIGTERM,
+}
+registered_exit_handlers: list[Callable[[], None]] = []
+_lock_handlers = threading.Lock()
+
+# SIGQUIT is not available on Windows
+if hasattr(signal, "SIGQUIT"):
+    SIGNAL_TO_EXIT_CODE[signal.SIGQUIT] = ExitCode.GRACEFUL_EXIT_SIGQUIT
+
+
+def add_exit_handler(exit_handler: Callable[[], None]) -> None:
+    """Add an exit handler to be called on graceful exit.
+
+    This function allows you to register additional exit handlers
+    that will be executed when `flwr_exit` is called.
+
+    Parameters
+    ----------
+    exit_handler : Callable[[], None]
+        A callable that takes no arguments and performs cleanup or
+        other actions before the application exits.
+
+    Notes
+    -----
+    The registered exit handlers will be called in LIFO order, i.e.,
+    the last registered handler will be the first to be called.
+    """
+    with _lock_handlers:
+        registered_exit_handlers.append(exit_handler)
+
+
+def trigger_exit_handlers() -> None:
+    """Trigger all registered exit handlers in LIFO order."""
+    with _lock_handlers:
+        for handler in reversed(registered_exit_handlers):
+            handler()
+        registered_exit_handlers.clear()

flwr/common/{exit_handlers.py → exit/signal_handler.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Common function to register exit handlers for server and client."""
+"""Common function to register signal handlers."""
 
 
 import signal
@@ -24,20 +24,21 @@ from grpc import Server
 
 from flwr.common.telemetry import EventType
 
-from .exit import ExitCode, flwr_exit
+from .exit import flwr_exit
+from .exit_code import ExitCode
+from .exit_handler import add_exit_handler
 
 SIGNAL_TO_EXIT_CODE: dict[int, int] = {
     signal.SIGINT: ExitCode.GRACEFUL_EXIT_SIGINT,
     signal.SIGTERM: ExitCode.GRACEFUL_EXIT_SIGTERM,
 }
-registered_exit_handlers: list[Callable[[], None]] = []
 
 # SIGQUIT is not available on Windows
 if hasattr(signal, "SIGQUIT"):
     SIGNAL_TO_EXIT_CODE[signal.SIGQUIT] = ExitCode.GRACEFUL_EXIT_SIGQUIT
 
 
-def register_exit_handlers(
+def register_signal_handlers(
     event_type: EventType,
     exit_message: Optional[str] = None,
     grpc_servers: Optional[list[Server]] = None,
@@ -63,7 +64,21 @@ def register_exit_handlers(
         Additional exit handlers can be added using `add_exit_handler`.
     """
     default_handlers: dict[int, Callable[[int, FrameType], None]] = {}
-    registered_exit_handlers.extend(exit_handlers or [])
+
+    def _wait_to_stop() -> None:
+        if grpc_servers is not None:
+            for grpc_server in grpc_servers:
+                grpc_server.stop(grace=1)
+
+        if bckg_threads is not None:
+            for bckg_thread in bckg_threads:
+                bckg_thread.join()
+
+    # Ensure that `_wait_to_stop` is the last handler called on exit
+    add_exit_handler(_wait_to_stop)
+
+    for handler in exit_handlers or []:
+        add_exit_handler(handler)
 
     def graceful_exit_handler(signalnum: int, _frame: FrameType) -> None:
         """Exit handler to be registered with `signal.signal`.
@@ -74,17 +89,6 @@ def register_exit_handlers(
         # Reset to default handler
         signal.signal(signalnum, default_handlers[signalnum])  # type: ignore
 
-        for handler in registered_exit_handlers:
-            handler()
-
-        if grpc_servers is not None:
-            for grpc_server in grpc_servers:
-                grpc_server.stop(grace=1)
-
-        if bckg_threads is not None:
-            for bckg_thread in bckg_threads:
-                bckg_thread.join()
-
         # Setup things for graceful exit
         flwr_exit(
             code=SIGNAL_TO_EXIT_CODE[signalnum],
@@ -96,24 +100,3 @@ def register_exit_handlers(
     for sig in SIGNAL_TO_EXIT_CODE:
         default_handler = signal.signal(sig, graceful_exit_handler)  # type: ignore
         default_handlers[sig] = default_handler  # type: ignore
-
-
-def add_exit_handler(exit_handler: Callable[[], None]) -> None:
-    """Add an exit handler to be called on graceful exit.
-
-    This function allows you to register additional exit handlers
-    that will be executed when the application exits gracefully,
-    if `register_exit_handlers` was called.
-
-    Parameters
-    ----------
-    exit_handler : Callable[[], None]
-        A callable that takes no arguments and performs cleanup or
-        other actions before the application exits.
-
-    Notes
-    -----
-    This method is not thread-safe, and it allows you to add the
-    same exit handler multiple times.
-    """
-    registered_exit_handlers.append(exit_handler)

flwr/common/grpc.py

@@ -23,9 +23,6 @@ from logging import DEBUG, ERROR
 from typing import Any, Callable, Optional
 
 import grpc
-from grpc_health.v1.health_pb2_grpc import add_HealthServicer_to_server
-
-from flwr.supercore.grpc_health import SimpleHealthServicer
 
 from .address import is_port_in_use
 from .logger import log
@@ -109,7 +106,6 @@ def generic_create_grpc_server(  # pylint: disable=too-many-arguments, R0914, R0
     keepalive_time_ms: int = 210000,
     certificates: Optional[tuple[bytes, bytes, bytes]] = None,
     interceptors: Optional[Sequence[grpc.ServerInterceptor]] = None,
-    health_servicer: Optional[Any] = None,
 ) -> grpc.Server:
     """Create a gRPC server with a single servicer.
 
@@ -157,10 +153,6 @@ def generic_create_grpc_server(  # pylint: disable=too-many-arguments, R0914, R0
             * server private key.
     interceptors : Optional[Sequence[grpc.ServerInterceptor]] (default: None)
         A list of gRPC interceptors.
-    health_servicer : Optional[Any] (default: None)
-        An optional health servicer to add to the server. If provided, it should be an
-        instance of a class that inherits the `HealthServicer` class.
-        If None is provided, `SimpleHealthServicer` will be used by default.
 
     Returns
     -------
@@ -211,9 +203,6 @@ def generic_create_grpc_server(  # pylint: disable=too-many-arguments, R0914, R0
     )
     add_servicer_to_server_fn(servicer, server)
 
-    # Enable health service
-    add_HealthServicer_to_server(health_servicer or SimpleHealthServicer(), server)
-
     if certificates is not None:
         if not valid_certificates(certificates):
             sys.exit(1)

flwr/common/inflatable_utils.py

@@ -34,7 +34,7 @@ from .constant import (
     PULL_MAX_TIME,
     PULL_MAX_TRIES_PER_OBJECT,
 )
-from .exit_handlers import add_exit_handler
+from .exit import add_exit_handler
 from .inflatable import (
     InflatableObject,
     UnexpectedObjectContentError,

flwr/compat/server/app.py

@@ -22,7 +22,7 @@ from typing import Optional
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH, EventType, event
 from flwr.common.address import parse_address
 from flwr.common.constant import FLEET_API_GRPC_BIDI_DEFAULT_ADDRESS
-from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common.exit import register_signal_handlers
 from flwr.common.logger import log, warn_deprecated_feature
 from flwr.server.client_manager import ClientManager
 from flwr.server.history import History
@@ -154,7 +154,7 @@ def start_server(  # pylint: disable=too-many-arguments,too-many-locals
     )
 
     # Graceful shutdown
-    register_exit_handlers(
+    register_signal_handlers(
         event_type=EventType.START_SERVER_LEAVE,
         exit_message="Flower server terminated gracefully.",
         grpc_servers=[grpc_server],

flwr/server/app.py

@@ -57,8 +57,7 @@ from flwr.common.constant import (
     ExecPluginType,
 )
 from flwr.common.event_log_plugin import EventLogWriterPlugin
-from flwr.common.exit import ExitCode, flwr_exit
-from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common.exit import ExitCode, flwr_exit, register_signal_handlers
 from flwr.common.grpc import generic_create_grpc_server
 from flwr.common.logger import log
 from flwr.common.secure_aggregation.crypto.symmetric_encryption import (
@@ -70,6 +69,7 @@ from flwr.proto.fleet_pb2_grpc import (  # pylint: disable=E0611
 from flwr.proto.grpcadapter_pb2_grpc import add_GrpcAdapterServicer_to_server
 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.servicer.control import run_control_api_grpc
 
@@ -176,6 +176,9 @@ def run_superlink() -> None:
     serverappio_address, _, _ = _format_address(args.serverappio_api_address)
     control_address, _, _ = _format_address(args.control_api_address)
     simulationio_address, _, _ = _format_address(args.simulationio_api_address)
+    health_server_address = None
+    if args.health_server_address is not None:
+        health_server_address, _, _ = _format_address(args.health_server_address)
 
     # Obtain certificates
     certificates = try_obtain_server_certificates(args)
@@ -352,8 +355,13 @@ def run_superlink() -> None:
         # pylint: disable-next=consider-using-with
         subprocess.Popen(command)
 
+    # Launch gRPC health server
+    if health_server_address is not None:
+        health_server = run_health_server_grpc_no_tls(health_server_address)
+        grpc_servers.append(health_server)
+
     # Graceful shutdown
-    register_exit_handlers(
+    register_signal_handlers(
         event_type=EventType.RUN_SUPERLINK_LEAVE,
         exit_message="SuperLink terminated gracefully.",
         grpc_servers=grpc_servers,
@@ -610,6 +618,7 @@ def _parse_args_run_superlink() -> argparse.ArgumentParser:
     _add_args_fleet_api(parser=parser)
     _add_args_control_api(parser=parser)
     _add_args_simulationio_api(parser=parser)
+    add_args_health(parser=parser)
 
     return parser