flwr-nightly 1.23.0.dev20250930__py3-none-any.whl → 1.26.0.dev20260121__py3-none-any.whl

flwr/cli/run/run.py

@@ -15,53 +15,57 @@
 """Flower command line interface `run` command."""
 
 
+import hashlib
 import io
 import json
 import subprocess
 from pathlib import Path
-from typing import Annotated, Any, Optional
+from typing import Annotated, Any, cast
 
 import typer
 from rich.console import Console
 
-from flwr.cli.build import build_fab, get_fab_filename
-from flwr.cli.config_utils import (
-    load_and_validate,
-    process_loaded_project_config,
-    validate_federation_in_project_config,
-)
+from flwr.cli.build import build_fab_from_disk, get_fab_filename
+from flwr.cli.config_migration import migrate, warn_if_federation_config_overrides
+from flwr.cli.config_utils import load as load_toml
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE, RUN_CONFIG_HELP_MESSAGE
+from flwr.cli.flower_config import (
+    _serialize_simulation_options,
+    read_superlink_connection,
+)
+from flwr.cli.typing import SuperLinkConnection, SuperLinkSimulationOptions
 from flwr.common.config import (
-    flatten_dict,
     get_metadata_from_config,
     parse_config_args,
     user_config_to_configrecord,
 )
-from flwr.common.constant import CliOutputFormat
+from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat
 from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import config_record_to_proto, fab_to_proto, user_config_to_proto
 from flwr.common.typing import Fab
 from flwr.proto.control_pb2 import StartRunRequest  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.supercore.constant import NOOP_FEDERATION
+from flwr.supercore.utils import parse_app_spec
 
 from ..log import start_stream
-from ..utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
+from ..utils import flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
 
 
-# pylint: disable-next=too-many-locals, R0913, R0917
+# pylint: disable-next=too-many-locals, too-many-branches, R0913, R0917
 def run(
     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 run the app on."),
+    superlink: Annotated[
+        str | None,
+        typer.Argument(help="Name of the SuperLink connection."),
     ] = None,
     run_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--run-config",
             "-c",
@@ -69,10 +73,11 @@ def run(
         ),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
+            hidden=True,
         ),
     ] = None,
     stream: Annotated[
@@ -95,30 +100,49 @@ def run(
     """Run Flower App."""
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
+
+    if suppress_output:
+        redirect_output(captured_output)
+
+    # Warn `--federation-config` is ignored
+    warn_if_federation_config_overrides(federation_config_overrides)
+
+    # Migrate legacy usage if any
+    migrate(str(app), [], ignore_legacy_usage=True)
+
+    # Read superlink connection configuration
+    superlink_connection = read_superlink_connection(superlink)
+
     try:
-        if suppress_output:
-            redirect_output(captured_output)
-        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, federation_config_overrides
-        )
 
-        if "address" in federation_config:
+        # Determine if app is remote
+        app_spec = None
+        if (app_str := str(app)).startswith("@"):
+            # Validate app version and ID format
+            try:
+                _ = parse_app_spec(app_str)
+            except ValueError as e:
+                typer.secho(f"❌ {e}", fg=typer.colors.RED, err=True)
+                raise typer.Exit(code=1) from e
+
+            app_spec = app_str
+            # Set `app` to current directory for credential storage
+            app = Path(".")
+
+        if superlink_connection.address:
             _run_with_control_api(
                 app,
-                federation,
-                federation_config,
+                superlink_connection,
                 run_config_overrides,
                 stream,
                 output_format,
+                app_spec,
             )
         else:
             _run_without_control_api(
-                app, federation_config, run_config_overrides, federation
+                app=app,
+                simulation_options=superlink_connection.options,  # type: ignore
+                config_overrides=run_config_overrides,
             )
     except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
         if suppress_output:
@@ -130,6 +154,7 @@ def run(
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -140,31 +165,46 @@ def run(
 # pylint: disable-next=R0913, R0914, R0917
 def _run_with_control_api(
     app: Path,
-    federation: str,
-    federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
+    superlink_connection: SuperLinkConnection,
+    config_overrides: list[str] | None,
     stream: bool,
     output_format: str,
+    app_spec: str | None,
 ) -> None:
     channel = None
+    is_remote_app = app_spec is not None
     try:
-        auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
-        channel = init_channel(app, federation_config, auth_plugin)
+        channel = init_channel_from_connection(superlink_connection)
         stub = ControlStub(channel)
 
-        fab_bytes, fab_hash, config = build_fab(app)
-        fab_id, fab_version = get_metadata_from_config(config)
+        # Build FAB if local app
+        if not is_remote_app:
+            fab_bytes = build_fab_from_disk(app)
+            fab_hash = hashlib.sha256(fab_bytes).hexdigest()
+            config = cast(dict[str, Any], load_toml(app / FAB_CONFIG_FILE))
+            fab_id, fab_version = get_metadata_from_config(config)
+            fab = Fab(fab_hash, fab_bytes, {})
+        # Skip FAB build if remote app
+        else:
+            # Use empty values for FAB
+            fab_id = fab_version = fab_hash = ""
+            fab = Fab(fab_hash, b"", {})
 
-        fab = Fab(fab_hash, fab_bytes)
+        federation: str = superlink_connection.federation or NOOP_FEDERATION
 
         # Construct a `ConfigRecord` out of a flattened `UserConfig`
-        fed_config = flatten_dict(federation_config.get("options", {}))
-        c_record = user_config_to_configrecord(fed_config)
+        options = {}
+        if superlink_connection.options:
+            options = _serialize_simulation_options(superlink_connection.options)
+
+        c_record = user_config_to_configrecord(options)
 
         req = StartRunRequest(
             fab=fab_to_proto(fab),
             override_config=user_config_to_proto(parse_config_args(config_overrides)),
+            federation=federation,
             federation_options=config_record_to_proto(c_record),
+            app_spec=app_spec or "",
         )
         with flwr_cli_grpc_exc_handler():
             res = stub.StartRun(req)
@@ -174,23 +214,27 @@ def _run_with_control_api(
                 f"🎊 Successfully started run {res.run_id}", fg=typer.colors.GREEN
             )
         else:
-            typer.secho("❌ Failed to start run", fg=typer.colors.RED)
+            typer.secho("❌ Failed to start run", fg=typer.colors.RED, err=True)
             raise typer.Exit(code=1)
 
         if output_format == CliOutputFormat.JSON:
-            run_output = json.dumps(
-                {
-                    "success": res.HasField("run_id"),
-                    "run-id": res.run_id if res.HasField("run_id") else None,
-                    "fab-id": fab_id,
-                    "fab-name": fab_id.rsplit("/", maxsplit=1)[-1],
-                    "fab-version": fab_version,
-                    "fab-hash": fab_hash[:8],
-                    "fab-filename": get_fab_filename(config, fab_hash),
-                }
-            )
+            # Only include FAB metadata if we actually built a local FAB
+            payload: dict[str, Any] = {
+                "success": res.HasField("run_id"),
+                "run-id": f"{res.run_id}" if res.HasField("run_id") else None,
+            }
+            if not is_remote_app:
+                payload.update(
+                    {
+                        "fab-id": fab_id,
+                        "fab-name": fab_id.rsplit("/", maxsplit=1)[-1],
+                        "fab-version": fab_version,
+                        "fab-hash": fab_hash[:8],
+                        "fab-filename": get_fab_filename(config, fab_hash),
+                    }
+                )
             restore_output()
-            Console().print_json(run_output)
+            Console().print_json(json.dumps(payload))
 
         if stream:
             start_stream(res.run_id, channel, CONN_REFRESH_PERIOD)
@@ -200,26 +244,13 @@ def _run_with_control_api(
 
 
 def _run_without_control_api(
-    app: Optional[Path],
-    federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
-    federation: str,
+    app: Path | None,
+    simulation_options: SuperLinkSimulationOptions,
+    config_overrides: list[str] | None,
 ) -> None:
-    try:
-        num_supernodes = federation_config["options"]["num-supernodes"]
-        verbose: Optional[bool] = federation_config["options"].get("verbose")
-        backend_cfg = federation_config["options"].get("backend", {})
-    except KeyError as err:
-        typer.secho(
-            "❌ The project's `pyproject.toml` needs to declare the number of"
-            " SuperNodes in the simulation. To simulate 10 SuperNodes,"
-            " use the following notation:\n\n"
-            f"[tool.flwr.federations.{federation}]\n"
-            "options.num-supernodes = 10\n",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1) from err
+
+    num_supernodes = simulation_options.num_supernodes
+    verbose = False  # bool | None = superlink_connection.options.verbose
 
     command = [
         "flower-simulation",
@@ -229,9 +260,10 @@ def _run_without_control_api(
         f"{num_supernodes}",
     ]
 
-    if backend_cfg:
+    if simulation_options.backend:
         # Stringify as JSON
-        command.extend(["--backend-config", json.dumps(backend_cfg)])
+        backend_serial = _serialize_simulation_options(simulation_options)
+        command.extend(["--backend-config", json.dumps(backend_serial)])
 
     if verbose:
         command.extend(["--verbose"])

flwr/cli/run_utils.py

@@ -0,0 +1,148 @@
+# 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 command line interface utils."""
+
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from flwr.common.typing import Run
+from flwr.supercore.date import isoformat8601_utc
+
+
+@dataclass
+class RunRow:  # pylint: disable=too-many-instance-attributes
+    """Represents a single run's data for display.
+
+    Attributes
+    ----------
+    run_id : int
+        The unique identifier for the run.
+    federation : str
+        The federation name.
+    fab_id : str
+        The Flower App Bundle identifier.
+    fab_version : str
+        The FAB version string.
+    fab_hash : str
+        The SHA-256 hash of the FAB.
+    status_text : str
+        The formatted status text.
+    elapsed : float
+        The elapsed time in seconds.
+    pending_at : str
+        Timestamp when run entered pending state.
+    starting_at : str
+        Timestamp when run entered starting state.
+    running_at : str
+        Timestamp when run entered running state.
+    finished_at : str
+        Timestamp when run finished.
+    network_traffic_inbound : int
+        The total inbound network traffic (in bytes) used during the run.
+        It includes the traffic from SuperNodes to SuperLink.
+    network_traffic_outbound : int
+        The total outbound network traffic (in bytes) used during the run.
+        It includes the traffic from SuperLink to SuperNodes.
+    compute_time_serverapp : float
+        The total compute time (in seconds) of the ServerApp during the run.
+    compute_time_clientapp : float
+        The total compute time (in seconds) of all ClientApps during the run.
+    """
+
+    run_id: int
+    federation: str
+    fab_id: str
+    fab_version: str
+    fab_hash: str
+    status_text: str
+    elapsed: float
+    pending_at: str
+    starting_at: str
+    running_at: str
+    finished_at: str
+    network_traffic_inbound: int
+    network_traffic_outbound: int
+    compute_time_serverapp: float
+    compute_time_clientapp: float
+
+
+def format_runs(runs: list[Run], now_isoformat: str) -> list[RunRow]:
+    """Format runs to a list of RunRow objects.
+
+    Parameters
+    ----------
+    runs : list[Run]
+        List of Run objects to format.
+    now_isoformat : str
+        Current timestamp in ISO format for calculating elapsed time.
+
+    Returns
+    -------
+    list[RunRow]
+        List of formatted RunRow objects sorted by pending_at timestamp.
+    """
+
+    def _format_datetime(dt: datetime | None) -> str:
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    run_list: list[RunRow] = []
+
+    # Add rows
+    for run in sorted(runs, key=lambda x: datetime.fromisoformat(x.pending_at)):
+        # Combine status and sub-status into a single string
+        if run.status.sub_status == "":
+            status_text = run.status.status
+        else:
+            status_text = f"{run.status.status}:{run.status.sub_status}"
+
+        # Convert isoformat to datetime
+        pending_at = datetime.fromisoformat(run.pending_at) if run.pending_at else None
+        starting_at = (
+            datetime.fromisoformat(run.starting_at) if run.starting_at else None
+        )
+        running_at = datetime.fromisoformat(run.running_at) if run.running_at else None
+        finished_at = (
+            datetime.fromisoformat(run.finished_at) if run.finished_at else None
+        )
+
+        # Calculate elapsed time
+        elapsed_time = timedelta()
+        if running_at:
+            if finished_at:
+                end_time = finished_at
+            else:
+                end_time = datetime.fromisoformat(now_isoformat)
+            elapsed_time = end_time - running_at
+
+        row = RunRow(
+            run_id=run.run_id,
+            federation=run.federation,
+            fab_id=run.fab_id,
+            fab_version=run.fab_version,
+            fab_hash=run.fab_hash,
+            status_text=status_text,
+            elapsed=elapsed_time.total_seconds(),
+            pending_at=_format_datetime(pending_at),
+            starting_at=_format_datetime(starting_at),
+            running_at=_format_datetime(running_at),
+            finished_at=_format_datetime(finished_at),
+            network_traffic_inbound=run.bytes_recv,
+            network_traffic_outbound=run.bytes_sent,
+            compute_time_serverapp=elapsed_time.total_seconds(),
+            compute_time_clientapp=run.clientapp_runtime,
+        )
+        run_list.append(row)
+    return run_list

flwr/cli/stop.py

@@ -17,20 +17,15 @@
 
 import io
 import json
-from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 from rich.console import Console
 
-from flwr.cli.config_utils import (
-    exit_if_no_address,
-    load_and_validate,
-    process_loaded_project_config,
-    validate_federation_in_project_config,
-)
+from flwr.cli.config_migration import migrate, warn_if_federation_config_overrides
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
-from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat
+from flwr.cli.flower_config import read_superlink_connection
+from flwr.common.constant import CliOutputFormat
 from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StopRunRequest,
@@ -38,27 +33,25 @@ from flwr.proto.control_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
-from .utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
+from .utils import flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 
 def stop(  # pylint: disable=R0914
+    ctx: typer.Context,
     run_id: Annotated[  # pylint: disable=unused-argument
         int,
         typer.Argument(help="The Flower run ID to stop"),
     ],
-    app: Annotated[
-        Path,
-        typer.Argument(help="Path of the Flower project"),
-    ] = Path("."),
-    federation: Annotated[
-        Optional[str],
-        typer.Argument(help="Name of the federation"),
+    superlink: Annotated[
+        str | None,
+        typer.Argument(help="Name of the SuperLink connection."),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
+            hidden=True,
         ),
     ] = None,
     output_format: Annotated[
@@ -70,27 +63,29 @@ def stop(  # pylint: disable=R0914
         ),
     ] = CliOutputFormat.DEFAULT,
 ) -> None:
-    """Stop a run."""
+    """Stop a Flower run.
+
+    This command stops a running Flower App execution by sending a stop request to the
+    SuperLink via the Control API.
+    """
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
-    try:
-        if suppress_output:
-            redirect_output(captured_output)
 
-        # Load and validate federation config
-        typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+    if suppress_output:
+        redirect_output(captured_output)
 
-        pyproject_path = app / FAB_CONFIG_FILE 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, federation_config_overrides
-        )
-        exit_if_no_address(federation_config, "stop")
-        channel = None
+    # Warn `--federation-config` is ignored
+    warn_if_federation_config_overrides(federation_config_overrides)
+
+    migrate(superlink, args=ctx.args)
+
+    # Read superlink connection configuration
+    superlink_connection = read_superlink_connection(superlink)
+    channel = None
+
+    try:
         try:
-            auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
-            channel = init_channel(app, federation_config, auth_plugin)
+            channel = init_channel_from_connection(superlink_connection)
             stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
 
             typer.secho(f"✋ Stopping run ID {run_id}...", fg=typer.colors.GREEN)
@@ -101,6 +96,7 @@ def stop(  # pylint: disable=R0914
                 f"❌ {err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1) from err
         finally:
@@ -116,6 +112,7 @@ def stop(  # pylint: disable=R0914
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -124,7 +121,17 @@ def stop(  # pylint: disable=R0914
 
 
 def _stop_run(stub: ControlStub, run_id: int, output_format: str) -> None:
-    """Stop a run."""
+    """Stop a run and display the result.
+
+    Parameters
+    ----------
+    stub : ControlStub
+        The gRPC stub for Control API communication.
+    run_id : int
+        The unique identifier of the run to stop.
+    output_format : str
+        Output format ('default' or 'json').
+    """
     with flwr_cli_grpc_exc_handler():
         response: StopRunResponse = stub.StopRun(request=StopRunRequest(run_id=run_id))
     if response.success:
@@ -133,10 +140,12 @@ def _stop_run(stub: ControlStub, run_id: int, output_format: str) -> None:
             run_output = json.dumps(
                 {
                     "success": True,
-                    "run-id": run_id,
+                    "run-id": f"{run_id}",
                 }
             )
             restore_output()
             Console().print_json(run_output)
     else:
-        typer.secho(f"❌ Run {run_id} couldn't be stopped.", fg=typer.colors.RED)
+        typer.secho(
+            f"❌ Run {run_id} couldn't be stopped.", fg=typer.colors.RED, err=True
+        )

flwr/cli/supernode/__init__.py

@@ -0,0 +1,25 @@
+# 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 command line interface `supernode` command."""
+
+from .ls import ls as ls
+from .register import register as register
+from .unregister import unregister as unregister
+
+__all__ = [
+    "ls",
+    "register",
+    "unregister",
+]