flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.15.0.dev20250114__py3-none-any.whl

flwr/client/client.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower client (abstract base class)."""
 
+
 # Needed to `Client` class can return a type of `Client` (not needed in py3.11+)
 from __future__ import annotations
 
@@ -21,7 +22,6 @@ from abc import ABC
 
 from flwr.common import (
     Code,
-    Context,
     EvaluateIns,
     EvaluateRes,
     FitIns,
@@ -38,8 +38,6 @@ from flwr.common import (
 class Client(ABC):
     """Abstract base class for Flower clients."""
 
-    context: Context
-
     def get_properties(self, ins: GetPropertiesIns) -> GetPropertiesRes:
         """Return set of client's properties.
 
@@ -141,14 +139,6 @@ class Client(ABC):
             metrics={},
         )
 
-    def get_context(self) -> Context:
-        """Get the run context from this client."""
-        return self.context
-
-    def set_context(self, context: Context) -> None:
-        """Apply a run context to this client."""
-        self.context = context
-
     def to_client(self) -> Client:
         """Return client (itself)."""
         return self

flwr/client/client_app.py

@@ -1,4 +1,4 @@
-# Copyright 2023 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2024 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.
@@ -15,18 +15,71 @@
 """Flower ClientApp."""
 
 
-from typing import Callable, List, Optional
+import inspect
+from typing import Callable, Optional
 
+from flwr.client.client import Client
 from flwr.client.message_handler.message_handler import (
     handle_legacy_message_from_msgtype,
 )
 from flwr.client.mod.utils import make_ffn
-from flwr.client.typing import ClientFn, Mod
+from flwr.client.typing import ClientFnExt, Mod
 from flwr.common import Context, Message, MessageType
+from flwr.common.logger import warn_deprecated_feature, warn_preview_feature
 
 from .typing import ClientAppCallable
 
 
+def _alert_erroneous_client_fn() -> None:
+    raise ValueError(
+        "A `ClientApp` cannot make use of a `client_fn` that does "
+        "not have a signature in the form: `def client_fn(context: "
+        "Context)`. You can import the `Context` like this: "
+        "`from flwr.common import Context`"
+    )
+
+
+def _inspect_maybe_adapt_client_fn_signature(client_fn: ClientFnExt) -> ClientFnExt:
+    client_fn_args = inspect.signature(client_fn).parameters
+
+    if len(client_fn_args) != 1:
+        _alert_erroneous_client_fn()
+
+    first_arg = list(client_fn_args.keys())[0]
+    first_arg_type = client_fn_args[first_arg].annotation
+
+    if first_arg_type is str or first_arg == "cid":
+        # Warn previous signature for `client_fn` seems to be used
+        warn_deprecated_feature(
+            "`client_fn` now expects a signature `def client_fn(context: Context)`."
+            "The provided `client_fn` has signature: "
+            f"{dict(client_fn_args.items())}. You can import the `Context` like this:"
+            " `from flwr.common import Context`"
+        )
+
+        # Wrap depcreated client_fn inside a function with the expected signature
+        def adaptor_fn(
+            context: Context,
+        ) -> Client:  # pylint: disable=unused-argument
+            # if patition-id is defined, pass it. Else pass node_id that should
+            # always be defined during Context init.
+            cid = context.node_config.get("partition-id", context.node_id)
+            return client_fn(str(cid))  # type: ignore
+
+        return adaptor_fn
+
+    return client_fn
+
+
+class ClientAppException(Exception):
+    """Exception raised when an exception is raised while executing a ClientApp."""
+
+    def __init__(self, message: str):
+        ex_name = self.__class__.__name__
+        self.message = f"\nException {ex_name} occurred. Message: " + message
+        super().__init__(self.message)
+
+
 class ClientApp:
     """Flower ClientApp.
 
@@ -38,7 +91,7 @@ class ClientApp:
     >>> class FlowerClient(NumPyClient):
     >>>     # ...
     >>>
-    >>> def client_fn(cid):
+    >>> def client_fn(context: Context):
     >>>    return FlowerClient().to_client()
     >>>
     >>> app = ClientApp(client_fn)
@@ -55,15 +108,17 @@ class ClientApp:
 
     def __init__(
         self,
-        client_fn: Optional[ClientFn] = None,  # Only for backward compatibility
-        mods: Optional[List[Mod]] = None,
+        client_fn: Optional[ClientFnExt] = None,  # Only for backward compatibility
+        mods: Optional[list[Mod]] = None,
     ) -> None:
-        self._mods: List[Mod] = mods if mods is not None else []
+        self._mods: list[Mod] = mods if mods is not None else []
 
         # Create wrapper function for `handle`
         self._call: Optional[ClientAppCallable] = None
         if client_fn is not None:
 
+            client_fn = _inspect_maybe_adapt_client_fn_signature(client_fn)
+
             def ffn(
                 message: Message,
                 context: Context,
@@ -115,7 +170,7 @@ class ClientApp:
         >>> def train(message: Message, context: Context) -> Message:
         >>>    print("ClientApp training running")
         >>>    # Create and return an echo reply message
-        >>>    return message.create_reply(content=message.content(), ttl="")
+        >>>    return message.create_reply(content=message.content())
         """
 
         def train_decorator(train_fn: ClientAppCallable) -> ClientAppCallable:
@@ -123,6 +178,8 @@ class ClientApp:
             if self._call:
                 raise _registration_error(MessageType.TRAIN)
 
+            warn_preview_feature("ClientApp-register-train-function")
+
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
             self._train = make_ffn(train_fn, self._mods)
@@ -143,7 +200,7 @@ class ClientApp:
         >>> def evaluate(message: Message, context: Context) -> Message:
         >>>    print("ClientApp evaluation running")
         >>>    # Create and return an echo reply message
-        >>>    return message.create_reply(content=message.content(), ttl="")
+        >>>    return message.create_reply(content=message.content())
         """
 
         def evaluate_decorator(evaluate_fn: ClientAppCallable) -> ClientAppCallable:
@@ -151,6 +208,8 @@ class ClientApp:
             if self._call:
                 raise _registration_error(MessageType.EVALUATE)
 
+            warn_preview_feature("ClientApp-register-evaluate-function")
+
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
             self._evaluate = make_ffn(evaluate_fn, self._mods)
@@ -171,7 +230,7 @@ class ClientApp:
         >>> def query(message: Message, context: Context) -> Message:
         >>>    print("ClientApp query running")
         >>>    # Create and return an echo reply message
-        >>>    return message.create_reply(content=message.content(), ttl="")
+        >>>    return message.create_reply(content=message.content())
         """
 
         def query_decorator(query_fn: ClientAppCallable) -> ClientAppCallable:
@@ -179,6 +238,8 @@ class ClientApp:
             if self._call:
                 raise _registration_error(MessageType.QUERY)
 
+            warn_preview_feature("ClientApp-register-query-function")
+
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
             self._query = make_ffn(query_fn, self._mods)
@@ -202,10 +263,10 @@ def _registration_error(fn_name: str) -> ValueError:
         >>> class FlowerClient(NumPyClient):
         >>>     # ...
         >>>
-        >>> def client_fn(cid) -> Client:
+        >>> def client_fn(context: Context):
         >>>     return FlowerClient().to_client()
         >>>
-        >>> app = ClientApp()
+        >>> app = ClientApp(
         >>>     client_fn=client_fn,
         >>> )
 
@@ -218,7 +279,7 @@ def _registration_error(fn_name: str) -> ValueError:
         >>>    print("ClientApp {fn_name} running")
         >>>    # Create and return an echo reply message
         >>>    return message.create_reply(
-        >>>        content=message.content(), ttl=""
+        >>>        content=message.content()
         >>>    )
         """,
     )

flwr/client/clientapp/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2024 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 AppIO service."""
+
+
+from .app import flwr_clientapp as flwr_clientapp
+
+__all__ = [
+    "flwr_clientapp",
+]

flwr/client/clientapp/app.py

@@ -0,0 +1,259 @@
+# Copyright 2024 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 ClientApp process."""
+
+
+import argparse
+import sys
+import time
+from logging import DEBUG, ERROR, INFO
+from typing import Optional
+
+import grpc
+
+from flwr.cli.install import install_from_fab
+from flwr.client.client_app import ClientApp, LoadClientAppError
+from flwr.common import Context, Message
+from flwr.common.args import add_args_flwr_app_common
+from flwr.common.config import get_flwr_dir
+from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCode
+from flwr.common.grpc import create_channel
+from flwr.common.logger import log
+from flwr.common.message import Error
+from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
+from flwr.common.serde import (
+    context_from_proto,
+    context_to_proto,
+    fab_from_proto,
+    message_from_proto,
+    message_to_proto,
+    run_from_proto,
+)
+from flwr.common.typing import Fab, Run
+
+# pylint: disable=E0611
+from flwr.proto.clientappio_pb2 import (
+    GetTokenRequest,
+    GetTokenResponse,
+    PullClientAppInputsRequest,
+    PullClientAppInputsResponse,
+    PushClientAppOutputsRequest,
+    PushClientAppOutputsResponse,
+)
+from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+
+from .utils import get_load_client_app_fn
+
+
+def flwr_clientapp() -> None:
+    """Run process-isolated Flower ClientApp."""
+    args = _parse_args_run_flwr_clientapp().parse_args()
+    if not args.insecure:
+        log(
+            ERROR,
+            "flwr-clientapp does not support TLS yet. "
+            "Please use the '--insecure' flag.",
+        )
+        sys.exit(1)
+
+    log(INFO, "Starting Flower ClientApp")
+    log(
+        DEBUG,
+        "Starting isolated `ClientApp` connected to SuperNode's ClientAppIo API at %s "
+        "with token %s",
+        args.clientappio_api_address,
+        args.token,
+    )
+    run_clientapp(
+        clientappio_api_address=args.clientappio_api_address,
+        run_once=(args.token is not None),
+        token=args.token,
+        flwr_dir=args.flwr_dir,
+        certificates=None,
+    )
+
+
+def on_channel_state_change(channel_connectivity: str) -> None:
+    """Log channel connectivity."""
+    log(DEBUG, channel_connectivity)
+
+
+def run_clientapp(  # pylint: disable=R0914
+    clientappio_api_address: str,
+    run_once: bool,
+    token: Optional[int] = None,
+    flwr_dir: Optional[str] = None,
+    certificates: Optional[bytes] = None,
+) -> None:
+    """Run Flower ClientApp process."""
+    channel = create_channel(
+        server_address=clientappio_api_address,
+        insecure=(certificates is None),
+        root_certificates=certificates,
+    )
+    channel.subscribe(on_channel_state_change)
+
+    # Resolve directory where FABs are installed
+    flwr_dir_ = get_flwr_dir(flwr_dir)
+    try:
+        stub = ClientAppIoStub(channel)
+        _wrap_stub(stub, _make_simple_grpc_retry_invoker())
+
+        while True:
+            # If token is not set, loop until token is received from SuperNode
+            while token is None:
+                token = get_token(stub)
+                time.sleep(1)
+
+            # Pull Message, Context, Run and (optional) FAB from SuperNode
+            message, context, run, fab = pull_message(stub=stub, token=token)
+
+            # Install FAB, if provided
+            if fab:
+                log(DEBUG, "Flower ClientApp starts FAB installation.")
+                install_from_fab(fab.content, flwr_dir=flwr_dir_, skip_prompt=True)
+
+            load_client_app_fn = get_load_client_app_fn(
+                default_app_ref="",
+                app_path=None,
+                multi_app=True,
+                flwr_dir=str(flwr_dir_),
+            )
+
+            try:
+                # Load ClientApp
+                client_app: ClientApp = load_client_app_fn(
+                    run.fab_id, run.fab_version, fab.hash_str if fab else ""
+                )
+
+                # Execute ClientApp
+                reply_message = client_app(message=message, context=context)
+
+            except Exception as ex:  # pylint: disable=broad-exception-caught
+                # Don't update/change NodeState
+
+                e_code = ErrorCode.CLIENT_APP_RAISED_EXCEPTION
+                # Ex fmt: "<class 'ZeroDivisionError'>:<'division by zero'>"
+                reason = str(type(ex)) + ":<'" + str(ex) + "'>"
+                exc_entity = "ClientApp"
+                if isinstance(ex, LoadClientAppError):
+                    reason = (
+                        "An exception was raised when attempting to load `ClientApp`"
+                    )
+                    e_code = ErrorCode.LOAD_CLIENT_APP_EXCEPTION
+
+                log(ERROR, "%s raised an exception", exc_entity, exc_info=ex)
+
+                # Create error message
+                reply_message = message.create_error_reply(
+                    error=Error(code=e_code, reason=reason)
+                )
+
+            # Push Message and Context to SuperNode
+            _ = push_message(
+                stub=stub, token=token, message=reply_message, context=context
+            )
+
+            # Reset token to `None` to prevent flwr-clientapp from trying to pull the
+            # same inputs again
+            token = None
+
+            # Stop the loop if `flwr-clientapp` is expected to process only a single
+            # message
+            if run_once:
+                break
+
+    except KeyboardInterrupt:
+        log(INFO, "Closing connection")
+    except grpc.RpcError as e:
+        log(ERROR, "GRPC error occurred: %s", str(e))
+    finally:
+        channel.close()
+
+
+def get_token(stub: grpc.Channel) -> Optional[int]:
+    """Get a token from SuperNode."""
+    log(DEBUG, "Flower ClientApp process requests token")
+    try:
+        res: GetTokenResponse = stub.GetToken(GetTokenRequest())
+        log(DEBUG, "[GetToken] Received token: %s", res.token)
+        return res.token
+    except grpc.RpcError as e:
+        if e.code() == grpc.StatusCode.FAILED_PRECONDITION:  # pylint: disable=no-member
+            log(DEBUG, "[GetToken] No token available yet")
+        else:
+            log(ERROR, "[GetToken] gRPC error occurred: %s", str(e))
+        return None
+
+
+def pull_message(
+    stub: grpc.Channel, token: int
+) -> tuple[Message, Context, Run, Optional[Fab]]:
+    """Pull message from SuperNode to ClientApp."""
+    log(INFO, "Pulling ClientAppInputs for token %s", token)
+    try:
+        res: PullClientAppInputsResponse = stub.PullClientAppInputs(
+            PullClientAppInputsRequest(token=token)
+        )
+        message = message_from_proto(res.message)
+        context = context_from_proto(res.context)
+        run = run_from_proto(res.run)
+        fab = fab_from_proto(res.fab) if res.fab else None
+        return message, context, run, fab
+    except grpc.RpcError as e:
+        log(ERROR, "[PullClientAppInputs] gRPC error occurred: %s", str(e))
+        raise e
+
+
+def push_message(
+    stub: grpc.Channel, token: int, message: Message, context: Context
+) -> PushClientAppOutputsResponse:
+    """Push message to SuperNode from ClientApp."""
+    log(INFO, "Pushing ClientAppOutputs for token %s", token)
+    proto_message = message_to_proto(message)
+    proto_context = context_to_proto(context)
+
+    try:
+        res: PushClientAppOutputsResponse = stub.PushClientAppOutputs(
+            PushClientAppOutputsRequest(
+                token=token, message=proto_message, context=proto_context
+            )
+        )
+        return res
+    except grpc.RpcError as e:
+        log(ERROR, "[PushClientAppOutputs] gRPC error occurred: %s", str(e))
+        raise e
+
+
+def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
+    """Parse flwr-clientapp command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Run a Flower ClientApp",
+    )
+    parser.add_argument(
+        "--clientappio-api-address",
+        default=CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS,
+        type=str,
+        help="Address of SuperNode's ClientAppIo API (IPv4, IPv6, or a domain name)."
+        f"By default, it is set to {CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS}.",
+    )
+    parser.add_argument(
+        "--token",
+        type=int,
+        required=False,
+        help="Unique token generated by SuperNode for each ClientApp execution",
+    )
+    add_args_flwr_app_common(parser=parser)
+    return parser