flwr-nightly 1.8.0.dev20240303__py3-none-any.whl → 1.8.0.dev20240305__py3-none-any.whl

flwr/cli/new/new.py

@@ -28,6 +28,7 @@ from ..utils import prompt_options
 class MlFramework(str, Enum):
     """Available frameworks."""
 
+    NUMPY = "NumPy"
     PYTORCH = "PyTorch"
     TENSORFLOW = "TensorFlow"
 

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

@@ -0,0 +1,24 @@
+"""$project_name: A Flower / NumPy app."""
+
+import flwr as fl
+import numpy as np
+
+
+# Flower client, adapted from Pytorch quickstart example
+class FlowerClient(fl.client.NumPyClient):
+    def get_parameters(self, config):
+        return [np.ones((1, 1))]
+
+    def fit(self, parameters, config):
+        return ([np.ones((1, 1))], 1, {})
+
+    def evaluate(self, parameters, config):
+        return float(0.0), 1, {"accuracy": float(1.0)}
+
+
+def client_fn(cid: str):
+    return FlowerClient().to_client()
+
+
+# ClientApp for Flower-Next
+app = fl.client.ClientApp(client_fn=client_fn)

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

@@ -0,0 +1,12 @@
+"""$project_name: A Flower / NumPy app."""
+
+import flwr as fl
+
+# Configure the strategy
+strategy = fl.server.strategy.FedAvg()
+
+# Flower ServerApp
+app = fl.server.ServerApp(
+    config=fl.server.ServerConfig(num_rounds=1),
+    strategy=strategy,
+)

flwr/cli/new/templates/app/flower.toml.tpl

@@ -1,10 +1,10 @@
-[flower]
+[project]
 name = "$project_name"
 version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 authors = ["The Flower Authors <hello@flower.ai>"]
 
-[components]
+[flower.components]
 serverapp = "$project_name.server:app"
 clientapp = "$project_name.client:app"

flwr/cli/new/templates/app/requirements.numpy.txt.tpl

@@ -0,0 +1,2 @@
+flwr>=1.8, <2.0
+numpy >= 1.21.0

flwr/client/app.py

@@ -20,7 +20,9 @@ import sys
 import time
 from logging import DEBUG, INFO, WARN
 from pathlib import Path
-from typing import Callable, ContextManager, Optional, Tuple, Union
+from typing import Callable, ContextManager, Optional, Tuple, Type, Union
+
+from grpc import RpcError
 
 from flwr.client.client import Client
 from flwr.client.client_app import ClientApp
@@ -36,6 +38,7 @@ from flwr.common.constant import (
 )
 from flwr.common.exit_handlers import register_exit_handlers
 from flwr.common.logger import log, warn_deprecated_feature, warn_experimental_feature
+from flwr.common.retry_invoker import RetryInvoker, exponential
 
 from .client_app import load_client_app
 from .grpc_client.connection import grpc_connection
@@ -104,6 +107,8 @@ def run_client_app() -> None:
         transport="rest" if args.rest else "grpc-rere",
         root_certificates=root_certificates,
         insecure=args.insecure,
+        max_retries=args.max_retries,
+        max_wait_time=args.max_wait_time,
     )
     register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
 
@@ -141,6 +146,22 @@ def _parse_args_run_client_app() -> argparse.ArgumentParser:
         default="0.0.0.0:9092",
         help="Server address",
     )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=None,
+        help="The maximum number of times the client will try to connect to the"
+        "server before giving up in case of a connection error. By default,"
+        "it is set to None, meaning there is no limit to the number of tries.",
+    )
+    parser.add_argument(
+        "--max-wait-time",
+        type=float,
+        default=None,
+        help="The maximum duration before the client stops trying to"
+        "connect to the server in case of connection error. By default, it"
+        "is set to None, meaning there is no limit to the total time.",
+    )
     parser.add_argument(
         "--dir",
         default="",
@@ -180,6 +201,8 @@ def start_client(
     root_certificates: Optional[Union[bytes, str]] = None,
     insecure: Optional[bool] = None,
     transport: Optional[str] = None,
+    max_retries: Optional[int] = None,
+    max_wait_time: Optional[float] = None,
 ) -> None:
     """Start a Flower client node which connects to a Flower server.
 
@@ -213,6 +236,14 @@ def start_client(
         - 'grpc-bidi': gRPC, bidirectional streaming
         - 'grpc-rere': gRPC, request-response (experimental)
         - 'rest': HTTP (experimental)
+    max_retries: Optional[int] (default: None)
+        The maximum number of times the client will try to connect to the
+        server before giving up in case of a connection error. If set to None,
+        there is no limit to the number of tries.
+    max_wait_time: Optional[float] (default: None)
+        The maximum duration before the client stops trying to
+        connect to the server in case of connection error.
+        If set to None, there is no limit to the total time.
 
     Examples
     --------
@@ -254,6 +285,8 @@ def start_client(
         root_certificates=root_certificates,
         insecure=insecure,
         transport=transport,
+        max_retries=max_retries,
+        max_wait_time=max_wait_time,
     )
     event(EventType.START_CLIENT_LEAVE)
 
@@ -272,6 +305,8 @@ def _start_client_internal(
     root_certificates: Optional[Union[bytes, str]] = None,
     insecure: Optional[bool] = None,
     transport: Optional[str] = None,
+    max_retries: Optional[int] = None,
+    max_wait_time: Optional[float] = None,
 ) -> None:
     """Start a Flower client node which connects to a Flower server.
 
@@ -299,7 +334,7 @@ def _start_client_internal(
         The PEM-encoded root certificates as a byte string or a path string.
         If provided, a secure connection using the certificates will be
         established to an SSL-enabled Flower server.
-    insecure : bool (default: True)
+    insecure : Optional[bool] (default: None)
         Starts an insecure gRPC connection when True. Enables HTTPS connection
         when False, using system certificates if `root_certificates` is None.
     transport : Optional[str] (default: None)
@@ -307,6 +342,14 @@ def _start_client_internal(
         - 'grpc-bidi': gRPC, bidirectional streaming
         - 'grpc-rere': gRPC, request-response (experimental)
         - 'rest': HTTP (experimental)
+    max_retries: Optional[int] (default: None)
+        The maximum number of times the client will try to connect to the
+        server before giving up in case of a connection error. If set to None,
+        there is no limit to the number of tries.
+    max_wait_time: Optional[float] (default: None)
+        The maximum duration before the client stops trying to
+        connect to the server in case of connection error.
+        If set to None, there is no limit to the total time.
     """
     if insecure is None:
         insecure = root_certificates is None
@@ -338,7 +381,45 @@ def _start_client_internal(
     # Both `client` and `client_fn` must not be used directly
 
     # Initialize connection context manager
-    connection, address = _init_connection(transport, server_address)
+    connection, address, connection_error_type = _init_connection(
+        transport, server_address
+    )
+
+    retry_invoker = RetryInvoker(
+        wait_factory=exponential,
+        recoverable_exceptions=connection_error_type,
+        max_tries=max_retries,
+        max_time=max_wait_time,
+        on_giveup=lambda retry_state: (
+            log(
+                WARN,
+                "Giving up reconnection after %.2f seconds and %s tries.",
+                retry_state.elapsed_time,
+                retry_state.tries,
+            )
+            if retry_state.tries > 1
+            else None
+        ),
+        on_success=lambda retry_state: (
+            log(
+                INFO,
+                "Connection successful after %.2f seconds and %s tries.",
+                retry_state.elapsed_time,
+                retry_state.tries,
+            )
+            if retry_state.tries > 1
+            else None
+        ),
+        on_backoff=lambda retry_state: (
+            log(WARN, "Connection attempt failed, retrying...")
+            if retry_state.tries == 1
+            else log(
+                DEBUG,
+                "Connection attempt failed, retrying in %.2f seconds",
+                retry_state.actual_wait,
+            )
+        ),
+    )
 
     node_state = NodeState()
 
@@ -347,6 +428,7 @@ def _start_client_internal(
         with connection(
             address,
             insecure,
+            retry_invoker,
             grpc_max_message_length,
             root_certificates,
         ) as conn:
@@ -509,7 +591,7 @@ def start_numpy_client(
 
 def _init_connection(transport: Optional[str], server_address: str) -> Tuple[
     Callable[
-        [str, bool, int, Union[bytes, str, None]],
+        [str, bool, RetryInvoker, int, Union[bytes, str, None]],
         ContextManager[
             Tuple[
                 Callable[[], Optional[Message]],
@@ -520,6 +602,7 @@ def _init_connection(transport: Optional[str], server_address: str) -> Tuple[
         ],
     ],
     str,
+    Type[Exception],
 ]:
     # Parse IP address
     parsed_address = parse_address(server_address)
@@ -535,6 +618,8 @@ def _init_connection(transport: Optional[str], server_address: str) -> Tuple[
     # Use either gRPC bidirectional streaming or REST request/response
     if transport == TRANSPORT_TYPE_REST:
         try:
+            from requests.exceptions import ConnectionError as RequestsConnectionError
+
             from .rest_client.connection import http_request_response
         except ModuleNotFoundError:
             sys.exit(MISSING_EXTRA_REST)
@@ -543,14 +628,14 @@ def _init_connection(transport: Optional[str], server_address: str) -> Tuple[
                 "When using the REST API, please provide `https://` or "
                 "`http://` before the server address (e.g. `http://127.0.0.1:8080`)"
             )
-        connection = http_request_response
+        connection, error_type = http_request_response, RequestsConnectionError
     elif transport == TRANSPORT_TYPE_GRPC_RERE:
-        connection = grpc_request_response
+        connection, error_type = grpc_request_response, RpcError
     elif transport == TRANSPORT_TYPE_GRPC_BIDI:
-        connection = grpc_connection
+        connection, error_type = grpc_connection, RpcError
     else:
         raise ValueError(
             f"Unknown transport type: {transport} (possible: {TRANSPORT_TYPES})"
         )
 
-    return connection, address
+    return connection, address, error_type

flwr/client/grpc_client/connection.py

@@ -39,6 +39,7 @@ from flwr.common.constant import (
 )
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
+from flwr.common.retry_invoker import RetryInvoker
 from flwr.proto.transport_pb2 import (  # pylint: disable=E0611
     ClientMessage,
     Reason,
@@ -62,6 +63,7 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 def grpc_connection(  # pylint: disable=R0915
     server_address: str,
     insecure: bool,
+    retry_invoker: RetryInvoker,  # pylint: disable=unused-argument
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
     root_certificates: Optional[Union[bytes, str]] = None,
 ) -> Iterator[
@@ -80,6 +82,11 @@ def grpc_connection(  # pylint: disable=R0915
         The IPv4 or IPv6 address of the server. If the Flower server runs on the same
         machine on port 8080, then `server_address` would be `"0.0.0.0:8080"` or
         `"[::]:8080"`.
+    insecure : bool
+        Starts an insecure gRPC connection when True. Enables HTTPS connection
+        when False, using system certificates if `root_certificates` is None.
+    retry_invoker: RetryInvoker
+        Unused argument present for compatibilty.
     max_message_length : int
         The maximum length of gRPC messages that can be exchanged with the Flower
         server. The default should be sufficient for most models. Users who train

flwr/client/grpc_rere_client/connection.py

@@ -27,6 +27,7 @@ from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log, warn_experimental_feature
 from flwr.common.message import Message, Metadata
+from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.serde import message_from_taskins, message_to_taskres
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     CreateNodeRequest,
@@ -51,6 +52,7 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 def grpc_request_response(
     server_address: str,
     insecure: bool,
+    retry_invoker: RetryInvoker,
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,  # pylint: disable=W0613
     root_certificates: Optional[Union[bytes, str]] = None,
 ) -> Iterator[
@@ -72,6 +74,13 @@ def grpc_request_response(
         The IPv6 address of the server with `http://` or `https://`.
         If the Flower server runs on the same machine
         on port 8080, then `server_address` would be `"http://[::]:8080"`.
+    insecure : bool
+        Starts an insecure gRPC connection when True. Enables HTTPS connection
+        when False, using system certificates if `root_certificates` is None.
+    retry_invoker: RetryInvoker
+        `RetryInvoker` object that will try to reconnect the client to the server
+        after gRPC errors. If None, the client will only try to
+        reconnect once after a failure.
     max_message_length : int
         Ignored, only present to preserve API-compatibility.
     root_certificates : Optional[Union[bytes, str]] (default: None)
@@ -113,7 +122,8 @@ def grpc_request_response(
     def create_node() -> None:
         """Set create_node."""
         create_node_request = CreateNodeRequest()
-        create_node_response = stub.CreateNode(
+        create_node_response = retry_invoker.invoke(
+            stub.CreateNode,
             request=create_node_request,
         )
         node_store[KEY_NODE] = create_node_response.node
@@ -127,7 +137,7 @@ def grpc_request_response(
         node: Node = cast(Node, node_store[KEY_NODE])
 
         delete_node_request = DeleteNodeRequest(node=node)
-        stub.DeleteNode(request=delete_node_request)
+        retry_invoker.invoke(stub.DeleteNode, request=delete_node_request)
 
         del node_store[KEY_NODE]
 
@@ -141,7 +151,7 @@ def grpc_request_response(
 
         # Request instructions (task) from server
         request = PullTaskInsRequest(node=node)
-        response = stub.PullTaskIns(request=request)
+        response = retry_invoker.invoke(stub.PullTaskIns, request=request)
 
         # Get the current TaskIns
         task_ins: Optional[TaskIns] = get_task_ins(response)
@@ -185,7 +195,7 @@ def grpc_request_response(
 
         # Serialize ProtoBuf to bytes
         request = PushTaskResRequest(task_res_list=[task_res])
-        _ = stub.PushTaskRes(request)
+        _ = retry_invoker.invoke(stub.PushTaskRes, request)
 
         state[KEY_METADATA] = None
 

flwr/client/rest_client/connection.py

@@ -27,6 +27,7 @@ from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import MISSING_EXTRA_REST
 from flwr.common.logger import log
 from flwr.common.message import Message, Metadata
+from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.serde import message_from_taskins, message_to_taskres
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     CreateNodeRequest,
@@ -61,6 +62,7 @@ PATH_PUSH_TASK_RES: str = "api/v0/fleet/push-task-res"
 def http_request_response(
     server_address: str,
     insecure: bool,  # pylint: disable=unused-argument
+    retry_invoker: RetryInvoker,
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,  # pylint: disable=W0613
     root_certificates: Optional[
         Union[bytes, str]
@@ -84,6 +86,12 @@ def http_request_response(
         The IPv6 address of the server with `http://` or `https://`.
         If the Flower server runs on the same machine
         on port 8080, then `server_address` would be `"http://[::]:8080"`.
+    insecure : bool
+        Unused argument present for compatibilty.
+    retry_invoker: RetryInvoker
+        `RetryInvoker` object that will try to reconnect the client to the server
+        after REST connection errors. If None, the client will only try to
+        reconnect once after a failure.
     max_message_length : int
         Ignored, only present to preserve API-compatibility.
     root_certificates : Optional[Union[bytes, str]] (default: None)
@@ -134,7 +142,8 @@ def http_request_response(
         create_node_req_proto = CreateNodeRequest()
         create_node_req_bytes: bytes = create_node_req_proto.SerializeToString()
 
-        res = requests.post(
+        res = retry_invoker.invoke(
+            requests.post,
             url=f"{base_url}/{PATH_CREATE_NODE}",
             headers={
                 "Accept": "application/protobuf",
@@ -177,7 +186,8 @@ def http_request_response(
         node: Node = cast(Node, node_store[KEY_NODE])
         delete_node_req_proto = DeleteNodeRequest(node=node)
         delete_node_req_req_bytes: bytes = delete_node_req_proto.SerializeToString()
-        res = requests.post(
+        res = retry_invoker.invoke(
+            requests.post,
             url=f"{base_url}/{PATH_DELETE_NODE}",
             headers={
                 "Accept": "application/protobuf",
@@ -218,7 +228,8 @@ def http_request_response(
         pull_task_ins_req_bytes: bytes = pull_task_ins_req_proto.SerializeToString()
 
         # Request instructions (task) from server
-        res = requests.post(
+        res = retry_invoker.invoke(
+            requests.post,
             url=f"{base_url}/{PATH_PULL_TASK_INS}",
             headers={
                 "Accept": "application/protobuf",
@@ -298,7 +309,8 @@ def http_request_response(
         )
 
         # Send ClientMessage to server
-        res = requests.post(
+        res = retry_invoker.invoke(
+            requests.post,
             url=f"{base_url}/{PATH_PUSH_TASK_RES}",
             headers={
                 "Accept": "application/protobuf",

flwr/common/__init__.py

@@ -15,11 +15,13 @@
 """Common components shared between server and client."""
 
 
+from .constant import MessageType as MessageType
 from .context import Context as Context
 from .date import now as now
 from .grpc import GRPC_MAX_MESSAGE_LENGTH
 from .logger import configure as configure
 from .logger import log as log
+from .message import Error as Error
 from .message import Message as Message
 from .message import Metadata as Metadata
 from .parameter import bytes_to_ndarray as bytes_to_ndarray
@@ -74,6 +76,7 @@ __all__ = [
     "EventType",
     "FitIns",
     "FitRes",
+    "Error",
     "GetParametersIns",
     "GetParametersRes",
     "GetPropertiesIns",
@@ -81,6 +84,7 @@ __all__ = [
     "GRPC_MAX_MESSAGE_LENGTH",
     "log",
     "Message",
+    "MessageType",
     "Metadata",
     "Metrics",
     "MetricsAggregationFn",

flwr/common/constant.py

@@ -42,6 +42,17 @@ MESSAGE_TYPE_FIT = "fit"
 MESSAGE_TYPE_EVALUATE = "evaluate"
 
 
+class MessageType:
+    """Message type."""
+
+    TRAIN = "train"
+    EVALUATE = "evaluate"
+
+    def __new__(cls) -> MessageType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
 class SType:
     """Serialisation type."""
 

flwr/server/app.py

@@ -362,10 +362,10 @@ def run_superlink() -> None:
         f_stop = asyncio.Event()  # Does nothing
         _run_fleet_api_vce(
             num_supernodes=args.num_supernodes,
-            client_app_module_name=args.client_app,
+            client_app_attr=args.client_app,
             backend_name=args.backend,
             backend_config_json_stream=args.backend_config,
-            working_dir=args.dir,
+            app_dir=args.app_dir,
             state_factory=state_factory,
             f_stop=f_stop,
         )
@@ -438,10 +438,10 @@ def _run_fleet_api_grpc_rere(
 # pylint: disable=too-many-arguments
 def _run_fleet_api_vce(
     num_supernodes: int,
-    client_app_module_name: str,
+    client_app_attr: str,
     backend_name: str,
     backend_config_json_stream: str,
-    working_dir: str,
+    app_dir: str,
     state_factory: StateFactory,
     f_stop: asyncio.Event,
 ) -> None:
@@ -449,11 +449,11 @@ def _run_fleet_api_vce(
 
     start_vce(
         num_supernodes=num_supernodes,
-        client_app_module_name=client_app_module_name,
+        client_app_attr=client_app_attr,
         backend_name=backend_name,
         backend_config_json_stream=backend_config_json_stream,
         state_factory=state_factory,
-        working_dir=working_dir,
+        app_dir=app_dir,
         f_stop=f_stop,
     )
 
@@ -705,7 +705,7 @@ def _add_args_fleet_api(parser: argparse.ArgumentParser) -> None:
         "`flwr.common.typing.ConfigsRecordValues`. ",
     )
     parser.add_argument(
-        "--dir",
+        "--app-dir",
         default="",
         help="Add specified directory to the PYTHONPATH and load"
         "ClientApp from there."

flwr/server/run_serverapp.py

@@ -16,7 +16,6 @@
 
 
 import argparse
-import asyncio
 import sys
 from logging import DEBUG, WARN
 from pathlib import Path
@@ -30,17 +29,27 @@ from .server_app import ServerApp, load_server_app
 
 
 def run(
-    server_app_attr: str,
     driver: Driver,
     server_app_dir: str,
-    stop_event: Optional[asyncio.Event] = None,
+    server_app_attr: Optional[str] = None,
+    loaded_server_app: Optional[ServerApp] = None,
 ) -> None:
     """Run ServerApp with a given Driver."""
+    if not (server_app_attr is None) ^ (loaded_server_app is None):
+        raise ValueError(
+            "Either `server_app_attr` or `loaded_server_app` should be set "
+            "but not both. "
+        )
+
     if server_app_dir is not None:
         sys.path.insert(0, server_app_dir)
 
+    # Load ServerApp if needed
     def _load() -> ServerApp:
-        server_app: ServerApp = load_server_app(server_app_attr)
+        if server_app_attr:
+            server_app: ServerApp = load_server_app(server_app_attr)
+        if loaded_server_app:
+            server_app = loaded_server_app
         return server_app
 
     server_app = _load()
@@ -52,10 +61,6 @@ def run(
     server_app(driver=driver, context=context)
 
     log(DEBUG, "ServerApp finished running.")
-    # Upon completion, trigger stop event if one was passed
-    if stop_event is not None:
-        log(DEBUG, "Triggering stop event.")
-        stop_event.set()
 
 
 def run_server_app() -> None:
@@ -117,7 +122,7 @@ def run_server_app() -> None:
     )
 
     # Run the Server App with the Driver
-    run(server_app_attr, driver, server_app_dir)
+    run(driver=driver, server_app_dir=server_app_dir, server_app_attr=server_app_attr)
 
     # Clean up
     driver.__del__()  # pylint: disable=unnecessary-dunder-call

flwr/server/server.py

@@ -17,7 +17,7 @@
 
 import concurrent.futures
 import timeit
-from logging import DEBUG, INFO, WARN
+from logging import INFO, WARN
 from typing import Dict, List, Optional, Tuple, Union
 
 from flwr.common import (
@@ -173,7 +173,7 @@ class Server:
             log(INFO, "evaluate_round %s: no clients selected, cancel", server_round)
             return None
         log(
-            DEBUG,
+            INFO,
             "evaluate_round %s: strategy sampled %s clients (out of %s)",
             server_round,
             len(client_instructions),
@@ -188,7 +188,7 @@ class Server:
             group_id=server_round,
         )
         log(
-            DEBUG,
+            INFO,
             "evaluate_round %s received %s results and %s failures",
             server_round,
             len(results),
@@ -223,7 +223,7 @@ class Server:
             log(INFO, "fit_round %s: no clients selected, cancel", server_round)
             return None
         log(
-            DEBUG,
+            INFO,
             "fit_round %s: strategy sampled %s clients (out of %s)",
             server_round,
             len(client_instructions),
@@ -238,7 +238,7 @@ class Server:
             group_id=server_round,
         )
         log(
-            DEBUG,
+            INFO,
             "fit_round %s received %s results and %s failures",
             server_round,
             len(results),

flwr/server/superlink/driver/driver_servicer.py

@@ -49,7 +49,7 @@ class DriverServicer(driver_pb2_grpc.DriverServicer):
         self, request: GetNodesRequest, context: grpc.ServicerContext
     ) -> GetNodesResponse:
         """Get available nodes."""
-        log(INFO, "DriverServicer.GetNodes")
+        log(DEBUG, "DriverServicer.GetNodes")
         state: State = self.state_factory.state()
         all_ids: Set[int] = state.get_nodes(request.run_id)
         nodes: List[Node] = [