flwr-nightly 1.14.0.dev20241204__py3-none-any.whl → 1.14.0.dev20241216__py3-none-any.whl

flwr/cli/app.py

@@ -14,15 +14,18 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
 import typer
 from typer.main import get_command
 
 from .build import build
 from .install import install
 from .log import log
+from .login import login
 from .ls import ls
 from .new import new
 from .run import run
+from .stop import stop
 
 app = typer.Typer(
     help=typer.style(
@@ -39,6 +42,8 @@ app.command()(build)
 app.command()(install)
 app.command()(log)
 app.command()(ls)
+app.command()(stop)
+app.command()(login)
 
 typer_click_object = get_command(app)
 

flwr/cli/build.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `build` command."""
 
+
 import hashlib
 import os
 import shutil

flwr/cli/cli_user_auth_interceptor.py

@@ -0,0 +1,86 @@
+# 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 run interceptor."""
+
+
+from typing import Any, Callable, Union
+
+import grpc
+
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    StartRunRequest,
+    StreamLogsRequest,
+)
+
+Request = Union[
+    StartRunRequest,
+    StreamLogsRequest,
+]
+
+
+class CliUserAuthInterceptor(
+    grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
+):
+    """CLI interceptor for user authentication."""
+
+    def __init__(self, auth_plugin: CliAuthPlugin):
+        self.auth_plugin = auth_plugin
+
+    def _authenticated_call(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Send and receive tokens via metadata."""
+        new_metadata = self.auth_plugin.write_tokens_to_metadata(
+            client_call_details.metadata or []
+        )
+
+        details = client_call_details._replace(metadata=new_metadata)
+
+        response = continuation(details, request)
+        if response.initial_metadata():
+            retrieved_metadata = dict(response.initial_metadata())
+            self.auth_plugin.store_tokens(retrieved_metadata)
+
+        return response
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-unary call for user authentication.
+
+        This method intercepts a unary-unary RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)
+
+    def intercept_unary_stream(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-stream call for user authentication.
+
+        This method intercepts a unary-stream RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)

flwr/cli/config_utils.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Utility to validate the `pyproject.toml` file."""
 
+
 import zipfile
 from io import BytesIO
 from pathlib import Path
@@ -230,10 +231,14 @@ def load_from_string(toml_content: str) -> Optional[dict[str, Any]]:
         return None
 
 
-def validate_project_config(
+def process_loaded_project_config(
     config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
 ) -> dict[str, Any]:
-    """Validate and return the Flower project configuration."""
+    """Process and return the loaded project configuration.
+
+    This function handles errors and warnings from the `load_and_validate` function,
+    exits on critical issues, and returns the validated configuration.
+    """
     if config is None:
         typer.secho(
             "Project configuration could not be loaded.\n"
@@ -324,3 +329,15 @@ def validate_certificate_in_federation_config(
             raise typer.Exit(code=1)
 
     return insecure, root_certificates_bytes
+
+
+def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
+    """Exit if the provided federation_config has no "address" key."""
+    if "address" not in federation_config:
+        typer.secho(
+            f"❌ `flwr {cmd}` currently works with a SuperLink. Ensure that the correct"
+            "SuperLink (Exec API) address is provided in `pyproject.toml`.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)

flwr/cli/example.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `example` command."""
 
+
 import json
 import os
 import subprocess

flwr/cli/install.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `install` command."""
 
+
 import hashlib
 import shutil
 import tempfile

flwr/cli/log.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `log` command."""
 
+
 import time
 from logging import DEBUG, ERROR, INFO
 from pathlib import Path
@@ -23,17 +24,18 @@ import grpc
 import typer
 
 from flwr.cli.config_utils import (
+    exit_if_no_address,
     load_and_validate,
-    validate_certificate_in_federation_config,
+    process_loaded_project_config,
     validate_federation_in_project_config,
-    validate_project_config,
 )
 from flwr.common.constant import CONN_RECONNECT_INTERVAL, CONN_REFRESH_PERIOD
-from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
 from flwr.common.logger import log as logger
 from flwr.proto.exec_pb2 import StreamLogsRequest  # pylint: disable=E0611
 from flwr.proto.exec_pb2_grpc import ExecStub
 
+from .utils import init_channel, try_obtain_cli_auth_plugin
+
 
 def start_stream(
     run_id: int, channel: grpc.Channel, refresh_period: int = CONN_REFRESH_PERIOD
@@ -126,11 +128,6 @@ def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
         logger(DEBUG, "Channel closed")
 
 
-def on_channel_state_change(channel_connectivity: str) -> None:
-    """Log channel connectivity."""
-    logger(DEBUG, channel_connectivity)
-
-
 def log(
     run_id: Annotated[
         int,
@@ -157,41 +154,24 @@ def log(
 
     pyproject_path = app / "pyproject.toml" if app else None
     config, errors, warnings = load_and_validate(path=pyproject_path)
-    config = validate_project_config(config, errors, warnings)
+    config = process_loaded_project_config(config, errors, warnings)
     federation, federation_config = validate_federation_in_project_config(
         federation, config
     )
+    exit_if_no_address(federation_config, "log")
 
-    if "address" not in federation_config:
-        typer.secho(
-            "❌ `flwr log` currently works with Exec API. Ensure that the correct"
-            "Exec API address is provided in the `pyproject.toml`.",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
-
-    _log_with_exec_api(app, federation_config, run_id, stream)
+    _log_with_exec_api(app, federation, federation_config, run_id, stream)
 
 
 def _log_with_exec_api(
     app: Path,
+    federation: str,
     federation_config: dict[str, Any],
     run_id: int,
     stream: bool,
 ) -> None:
-
-    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
-        app, federation_config
-    )
-    channel = create_channel(
-        server_address=federation_config["address"],
-        insecure=insecure,
-        root_certificates=root_certificates_bytes,
-        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
-        interceptors=None,
-    )
-    channel.subscribe(on_channel_state_change)
+    auth_plugin = try_obtain_cli_auth_plugin(app, federation)
+    channel = init_channel(app, federation_config, auth_plugin)
 
     if stream:
         start_stream(run_id, channel, CONN_REFRESH_PERIOD)

flwr/cli/login/__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 command line interface `login` command."""
+
+
+from .login import login as login
+
+__all__ = [
+    "login",
+]

flwr/cli/login/login.py

@@ -0,0 +1,81 @@
+# 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 command line interface `login` command."""
+
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from flwr.cli.config_utils import (
+    exit_if_no_address,
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import AUTH_TYPE
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    GetLoginDetailsRequest,
+    GetLoginDetailsResponse,
+)
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+from ..utils import init_channel, try_obtain_cli_auth_plugin
+
+
+def login(  # pylint: disable=R0914
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower App to run."),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation to login into."),
+    ] = None,
+) -> None:
+    """Login to Flower SuperLink."""
+    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+    pyproject_path = app / "pyproject.toml" if app else None
+    config, errors, warnings = load_and_validate(path=pyproject_path)
+
+    config = process_loaded_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
+    exit_if_no_address(federation_config, "login")
+    channel = init_channel(app, federation_config, None)
+    stub = ExecStub(channel)
+
+    login_request = GetLoginDetailsRequest()
+    login_response: GetLoginDetailsResponse = stub.GetLoginDetails(login_request)
+
+    # Get the auth plugin
+    auth_type = login_response.login_details.get(AUTH_TYPE)
+    auth_plugin = try_obtain_cli_auth_plugin(app, federation, auth_type)
+    if auth_plugin is None:
+        typer.secho(
+            f'❌ Authentication type "{auth_type}" not found',
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Login
+    auth_config = auth_plugin.login(dict(login_response.login_details), stub)
+
+    # Store the tokens
+    auth_plugin.store_tokens(auth_config)

flwr/cli/ls.py

@@ -18,27 +18,23 @@
 import io
 import json
 from datetime import datetime, timedelta
-from logging import DEBUG
 from pathlib import Path
-from typing import Annotated, Any, Optional, Union
+from typing import Annotated, Optional
 
-import grpc
 import typer
 from rich.console import Console
 from rich.table import Table
 from rich.text import Text
-from typer import Exit
 
 from flwr.cli.config_utils import (
+    exit_if_no_address,
     load_and_validate,
-    validate_certificate_in_federation_config,
+    process_loaded_project_config,
     validate_federation_in_project_config,
-    validate_project_config,
 )
 from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat, SubStatus
 from flwr.common.date import format_timedelta, isoformat8601_utc
-from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
-from flwr.common.logger import log, redirect_output, remove_emojis, restore_output
+from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import run_from_proto
 from flwr.common.typing import Run
 from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
@@ -47,6 +43,8 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.exec_pb2_grpc import ExecStub
 
+from .utils import init_channel, try_obtain_cli_auth_plugin
+
 _RunListType = tuple[int, str, str, str, str, str, str, str, str]
 
 
@@ -82,7 +80,20 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches
         ),
     ] = CliOutputFormat.DEFAULT,
 ) -> None:
-    """List runs."""
+    """List the details of one provided run ID or all runs in a Flower federation.
+
+    The following details are displayed:
+
+    - **Run ID:** Unique identifier for the run.
+    - **FAB:** Name of the FAB associated with the run (``{FAB_ID} (v{FAB_VERSION})``).
+    - **Status:** Current status of the run (pending, starting, running, finished).
+    - **Elapsed:** Time elapsed since the run started (``HH:MM:SS``).
+    - **Created At:** Timestamp when the run was created.
+    - **Running At:** Timestamp when the run started running.
+    - **Finished At:** Timestamp when the run finished.
+
+    All timestamps follow ISO 8601, UTC and are formatted as ``YYYY-MM-DD HH:MM:SSZ``.
+    """
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
     try:
@@ -94,27 +105,19 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches
 
         pyproject_path = app / FAB_CONFIG_FILE if app else None
         config, errors, warnings = load_and_validate(path=pyproject_path)
-        config = validate_project_config(config, errors, warnings)
+        config = process_loaded_project_config(config, errors, warnings)
         federation, federation_config = validate_federation_in_project_config(
             federation, config
         )
-
-        if "address" not in federation_config:
-            typer.secho(
-                "❌ `flwr ls` currently works with Exec API. Ensure that the correct"
-                "Exec API address is provided in the `pyproject.toml`.",
-                fg=typer.colors.RED,
-                bold=True,
-            )
-            raise typer.Exit(code=1)
+        exit_if_no_address(federation_config, "ls")
 
         try:
             if runs and run_id is not None:
                 raise ValueError(
                     "The options '--runs' and '--run-id' are mutually exclusive."
                 )
-
-            channel = _init_channel(app, federation_config)
+            auth_plugin = try_obtain_cli_auth_plugin(app, federation)
+            channel = init_channel(app, federation_config, auth_plugin)
             stub = ExecStub(channel)
 
             # Display information about a specific run ID
@@ -141,7 +144,7 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches
         if suppress_output:
             restore_output()
             e_message = captured_output.getvalue()
-            _print_json_error(e_message, err)
+            print_json_error(e_message, err)
         else:
             typer.secho(
                 f"{err}",
@@ -154,27 +157,6 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches
         captured_output.close()
 
 
-def on_channel_state_change(channel_connectivity: str) -> None:
-    """Log channel connectivity."""
-    log(DEBUG, channel_connectivity)
-
-
-def _init_channel(app: Path, federation_config: dict[str, Any]) -> grpc.Channel:
-    """Initialize gRPC channel to the Exec API."""
-    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
-        app, federation_config
-    )
-    channel = create_channel(
-        server_address=federation_config["address"],
-        insecure=insecure,
-        root_certificates=root_certificates_bytes,
-        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
-        interceptors=None,
-    )
-    channel.subscribe(on_channel_state_change)
-    return channel
-
-
 def _format_runs(run_dict: dict[int, Run], now_isoformat: str) -> list[_RunListType]:
     """Format runs to a list."""
 
@@ -340,15 +322,3 @@ def _display_one_run(
         Console().print_json(_to_json(formatted_runs))
     else:
         Console().print(_to_table(formatted_runs))
-
-
-def _print_json_error(msg: str, e: Union[Exit, Exception]) -> None:
-    """Print error message as JSON."""
-    Console().print_json(
-        json.dumps(
-            {
-                "success": False,
-                "error-message": remove_emojis(str(msg) + "\n" + str(e)),
-            }
-        )
-    )

flwr/cli/new/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `new` command."""
 
+
 from .new import new as new
 
 __all__ = [

flwr/cli/new/new.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `new` command."""
 
+
 import re
 from enum import Enum
 from pathlib import Path
@@ -81,7 +82,7 @@ def render_template(template: str, data: dict[str, str]) -> str:
 def create_file(file_path: Path, content: str) -> None:
     """Create file including all nessecary directories and write content into file."""
     file_path.parent.mkdir(exist_ok=True)
-    file_path.write_text(content)
+    file_path.write_text(content, encoding="utf-8")
 
 
 def render_and_create(file_path: Path, template: str, context: dict[str, str]) -> None:

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

@@ -12,10 +12,10 @@ dependencies = [
     "flwr-datasets>=0.3.0",
     "torch==2.3.1",
     "trl==0.8.1",
-    "bitsandbytes==0.43.0",
+    "bitsandbytes==0.45.0",
     "scipy==1.13.0",
     "peft==0.6.2",
-    "transformers==4.43.1",
+    "transformers==4.47.0",
     "sentencepiece==0.2.0",
     "omegaconf==2.3.0",
     "hf_transfer==0.1.8",

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

@@ -10,8 +10,7 @@ license = "Apache-2.0"
 dependencies = [
     "flwr[simulation]>=1.13.1",
     "flwr-datasets[vision]>=0.3.0",
-    "mlx==0.16.1",
-    "numpy==1.24.4",
+    "mlx==0.21.1",
 ]
 
 [tool.hatch.build.targets.wheel]

flwr/cli/run/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `run` command."""
 
+
 from .run import run as run
 
 __all__ = [