flwr 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/new/templates/app/code/task.pytorch.py.tpl

@@ -84,6 +84,7 @@ def train(net, trainloader, epochs, lr, device):
 def test(net, testloader, device):
     """Validate the model on the test set."""
     net.to(device)
+    net.eval()
     criterion = torch.nn.CrossEntropyLoss()
     correct, loss = 0, 0.0
     with torch.no_grad():

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.8.0",
     "torchvision==0.23.0",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "torch==2.4.0",
     "trl==0.8.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "torch>=2.7.1",
     "transformers>=4.30.0,<5.0",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "jax==0.4.30",
     "jaxlib==0.4.30",
     "scikit-learn==1.6.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "mlx==0.29.0",
 ]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "numpy>=2.0.2",
 ]
 

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

@@ -14,10 +14,10 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
-    "torch==2.7.1",
-    "torchvision==0.22.1",
+    "torch>=2.7.1",
+    "torchvision>=0.22.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.7.1",
     "torchvision==0.22.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "scikit-learn>=1.6.1",
 ]

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

@@ -14,9 +14,9 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
-    "tensorflow>=2.11.1,<2.18.0",
+    "tensorflow>=2.18.0",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.22.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "xgboost>=2.0.0",
 ]

flwr/cli/pull.py

@@ -16,7 +16,7 @@
 
 
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 
@@ -34,7 +34,7 @@ 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, load_cli_auth_plugin
 
 
 def pull(  # pylint: disable=R0914
@@ -50,22 +50,26 @@ def pull(  # pylint: disable=R0914
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation."),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
         ),
     ] = None,
 ) -> None:
-    """Pull artifacts from a Flower run."""
+    """Pull artifacts from a Flower run.
+
+    Retrieve a download URL for artifacts generated during a completed Flower run. The
+    artifacts can then be downloaded from the provided URL.
+    """
     typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
     pyproject_path = app / FAB_CONFIG_FILE if app else None
-    config, errors, warnings = load_and_validate(path=pyproject_path)
+    config, errors, warnings = load_and_validate(pyproject_path, check_module=False)
     config = process_loaded_project_config(config, errors, warnings)
     federation, federation_config = validate_federation_in_project_config(
         federation, config, federation_config_overrides
@@ -74,7 +78,7 @@ def pull(  # pylint: disable=R0914
     channel = None
     try:
 
-        auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+        auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
         channel = init_channel(app, federation_config, auth_plugin)
         stub = ControlStub(channel)
         with flwr_cli_grpc_exc_handler():
@@ -88,6 +92,7 @@ def pull(  # pylint: disable=R0914
                 "obtained.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 

flwr/cli/run/run.py

@@ -15,16 +15,18 @@
 """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.build import build_fab_from_disk, get_fab_filename
+from flwr.cli.config_utils import load as load_toml
 from flwr.cli.config_utils import (
     load_and_validate,
     process_loaded_project_config,
@@ -37,31 +39,37 @@ from flwr.common.config import (
     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 ..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,
+    load_cli_auth_plugin,
+    parse_app_spec,
+)
 
 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],
+        str | None,
         typer.Argument(help="Name of the federation to run the app on."),
     ] = None,
     run_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--run-config",
             "-c",
@@ -69,7 +77,7 @@ def run(
         ),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -98,11 +106,25 @@ def run(
     try:
         if suppress_output:
             redirect_output(captured_output)
+
+        # Determine if app is remote
+        app_spec = None
+        if (app_str := str(app)).startswith("@"):
+            # Validate app version and ID format
+            _ = parse_app_spec(app_str)
+            app_spec = app_str
+        is_remote_app = app_spec is not None
+
         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)
+        # Disable the validation for remote apps
+        pyproject_path = app / "pyproject.toml" if not is_remote_app else None
+        # `./pyproject.toml` will be loaded when `pyproject_path` is None
+        config, errors, warnings = load_and_validate(
+            pyproject_path, check_module=not is_remote_app
+        )
         config = process_loaded_project_config(config, errors, warnings)
+
         federation, federation_config = validate_federation_in_project_config(
             federation, config, federation_config_overrides
         )
@@ -115,6 +137,7 @@ def run(
                 run_config_overrides,
                 stream,
                 output_format,
+                app_spec,
             )
         else:
             _run_without_control_api(
@@ -130,6 +153,7 @@ def run(
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -142,20 +166,32 @@ def _run_with_control_api(
     app: Path,
     federation: str,
     federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
+    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)
+        auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
         channel = init_channel(app, federation_config, auth_plugin)
         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)
+        real_federation: str = federation_config.get("federation", NOOP_FEDERATION)
 
         # Construct a `ConfigRecord` out of a flattened `UserConfig`
         fed_config = flatten_dict(federation_config.get("options", {}))
@@ -164,7 +200,9 @@ def _run_with_control_api(
         req = StartRunRequest(
             fab=fab_to_proto(fab),
             override_config=user_config_to_proto(parse_config_args(config_overrides)),
+            federation=real_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 +212,35 @@ 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)
+            if is_remote_app:
+                typer.secho(
+                    "❌ Failed to start run. Please check that the provided "
+                    "app identifier (@account_name/app_name) is correct.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+            else:
+                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": 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,14 +250,14 @@ def _run_with_control_api(
 
 
 def _run_without_control_api(
-    app: Optional[Path],
+    app: Path | None,
     federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
+    config_overrides: list[str] | None,
     federation: str,
 ) -> None:
     try:
         num_supernodes = federation_config["options"]["num-supernodes"]
-        verbose: Optional[bool] = federation_config["options"].get("verbose")
+        verbose: bool | None = federation_config["options"].get("verbose")
         backend_cfg = federation_config["options"].get("backend", {})
     except KeyError as err:
         typer.secho(
@@ -218,6 +268,7 @@ def _run_without_control_api(
             "options.num-supernodes = 10\n",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1) from err
 

flwr/cli/run_utils.py

@@ -0,0 +1,130 @@
+# 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.date import format_timedelta, isoformat8601_utc
+from flwr.common.typing import Run
+
+
+@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 : str
+        The formatted elapsed time.
+    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.
+    """
+
+    run_id: int
+    federation: str
+    fab_id: str
+    fab_version: str
+    fab_hash: str
+    status_text: str
+    elapsed: str
+    pending_at: str
+    starting_at: str
+    running_at: str
+    finished_at: str
+
+
+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=format_timedelta(elapsed_time),
+            pending_at=_format_datetime(pending_at),
+            starting_at=_format_datetime(starting_at),
+            running_at=_format_datetime(running_at),
+            finished_at=_format_datetime(finished_at),
+        )
+        run_list.append(row)
+    return run_list

flwr/cli/stop.py

@@ -18,7 +18,7 @@
 import io
 import json
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 from rich.console import Console
@@ -38,7 +38,7 @@ 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, load_cli_auth_plugin
 
 
 def stop(  # pylint: disable=R0914
@@ -51,11 +51,11 @@ def stop(  # pylint: disable=R0914
         typer.Argument(help="Path of the Flower project"),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation"),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -70,7 +70,11 @@ 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:
@@ -81,7 +85,7 @@ def stop(  # pylint: disable=R0914
         typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
         pyproject_path = app / FAB_CONFIG_FILE if app else None
-        config, errors, warnings = load_and_validate(path=pyproject_path)
+        config, errors, warnings = load_and_validate(pyproject_path, check_module=False)
         config = process_loaded_project_config(config, errors, warnings)
         federation, federation_config = validate_federation_in_project_config(
             federation, config, federation_config_overrides
@@ -89,7 +93,7 @@ def stop(  # pylint: disable=R0914
         exit_if_no_address(federation_config, "stop")
         channel = None
         try:
-            auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
             channel = init_channel(app, federation_config, auth_plugin)
             stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
 
@@ -101,6 +105,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 +121,7 @@ def stop(  # pylint: disable=R0914
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -124,7 +130,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:
@@ -139,4 +155,6 @@ def _stop_run(stub: ControlStub, run_id: int, output_format: str) -> None:
             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
+        )