flwr-nightly 1.21.0.dev20250902__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/exit_code.py

@@ -36,6 +36,7 @@ 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)
@@ -90,6 +91,7 @@ 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."

flwr/server/serverapp/app.py

@@ -37,7 +37,8 @@ from flwr.common.constant import (
     Status,
     SubStatus,
 )
-from flwr.common.exit import ExitCode, flwr_exit
+from flwr.common.exception import AppExitException
+from flwr.common.exit import ExitCode, add_exit_handler, flwr_exit
 from flwr.common.heartbeat import HeartbeatSender, get_grpc_app_heartbeat_fn
 from flwr.common.logger import (
     log,
@@ -133,12 +134,34 @@ def run_serverapp(  # pylint: disable=R0913, R0914, R0915, R0917, W0212
     # Resolve directory where FABs are installed
     flwr_dir_ = get_flwr_dir(flwr_dir)
     log_uploader = None
-    success = True
     hash_run_id = None
     run_status = None
     heartbeat_sender = None
     grid = None
     context = None
+    exit_code = ExitCode.SUCCESS
+
+    def on_exit() -> None:
+        # Stop heartbeat sender
+        if heartbeat_sender:
+            heartbeat_sender.stop()
+
+        # Stop log uploader for this run and upload final logs
+        if log_uploader:
+            stop_log_uploader(log_queue, log_uploader)
+
+        # Update run status
+        if run_status and grid:
+            run_status_proto = run_status_to_proto(run_status)
+            grid._stub.UpdateRunStatus(
+                UpdateRunStatusRequest(run_id=run.run_id, run_status=run_status_proto)
+            )
+
+        # Close the Grpc connection
+        if grid:
+            grid.close()
+
+    add_exit_handler(on_exit)
 
     try:
         # Initialize the GrpcGrid
@@ -229,43 +252,33 @@ def run_serverapp(  # pylint: disable=R0913, R0914, R0915, R0917, W0212
         _ = grid._stub.PushAppOutputs(out_req)
 
         run_status = RunStatus(Status.FINISHED, SubStatus.COMPLETED, "")
+
+    # Raised when the run is already stopped by the user
     except RunNotRunningException:
         log(INFO, "")
         log(INFO, "Run ID %s stopped.", run.run_id)
         log(INFO, "")
         run_status = None
-        success = False
+        # No need to update the exit code since this is expected behavior
 
     except Exception as ex:  # pylint: disable=broad-exception-caught
         exc_entity = "ServerApp"
         log(ERROR, "%s raised an exception", exc_entity, exc_info=ex)
         run_status = RunStatus(Status.FINISHED, SubStatus.FAILED, str(ex))
-        success = False
 
-    finally:
-        # Stop heartbeat sender
-        if heartbeat_sender:
-            heartbeat_sender.stop()
-
-        # Stop log uploader for this run and upload final logs
-        if log_uploader:
-            stop_log_uploader(log_queue, log_uploader)
-
-        # Update run status
-        if run_status and grid:
-            run_status_proto = run_status_to_proto(run_status)
-            grid._stub.UpdateRunStatus(
-                UpdateRunStatusRequest(run_id=run.run_id, run_status=run_status_proto)
-            )
-
-        # Close the Grpc connection
-        if grid:
-            grid.close()
-
-        event(
-            EventType.FLWR_SERVERAPP_RUN_LEAVE,
-            event_details={"run-id-hash": hash_run_id, "success": success},
-        )
+        # Set exit code
+        exit_code = ExitCode.SERVERAPP_EXCEPTION  # General exit code
+        if isinstance(ex, AppExitException):
+            exit_code = ex.exit_code
+
+    flwr_exit(
+        code=exit_code,
+        event_type=EventType.FLWR_SERVERAPP_RUN_LEAVE,
+        event_details={
+            "run-id-hash": hash_run_id,
+            "success": exit_code == ExitCode.SUCCESS,
+        },
+    )
 
 
 def _parse_args_run_flwr_serverapp() -> argparse.ArgumentParser: