flwr 1.21.0__py3-none-any.whl → 1.23.0__py3-none-any.whl

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

@@ -0,0 +1,61 @@
+# =====================================================================
+# For a full TOML configuration guide, check the Flower docs:
+# https://flower.ai/docs/framework/how-to-configure-pyproject-toml.html
+# =====================================================================
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "$package_name"
+version = "1.0.0"
+description = ""
+license = "Apache-2.0"
+# Dependencies for your Flower App
+dependencies = [
+    "flwr[simulation]>=1.23.0",
+    "flwr-datasets>=0.5.0",
+    "xgboost>=2.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.flwr.app]
+publisher = "$username"
+
+[tool.flwr.app.components]
+serverapp = "$import_name.server_app:app"
+clientapp = "$import_name.client_app:app"
+
+# Custom config values accessible via `context.run_config`
+[tool.flwr.app.config]
+num-server-rounds = 3
+fraction-train = 0.1
+fraction-evaluate = 0.1
+local-epochs = 1
+
+# XGBoost parameters
+params.objective = "binary:logistic"
+params.eta = 0.1 # Learning rate
+params.max-depth = 8
+params.eval-metric = "auc"
+params.nthread = 16
+params.num-parallel-tree = 1
+params.subsample = 1
+params.tree-method = "hist"
+
+# Default federation to use when running the app
+[tool.flwr.federations]
+default = "local-simulation"
+
+# Local simulation federation with 10 virtual SuperNodes
+[tool.flwr.federations.local-simulation]
+options.num-supernodes = 10
+
+# Remote federation example for use with SuperLink
+[tool.flwr.federations.remote-federation]
+address = "<SUPERLINK-ADDRESS>:<PORT>"
+insecure = true  # Remove this line to enable TLS
+# root-certificates = "<PATH/TO/ca.crt>"  # For TLS setup

flwr/cli/pull.py

@@ -0,0 +1,100 @@
+# 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 `pull` 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.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
+from flwr.common.constant import FAB_CONFIG_FILE
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    PullArtifactsRequest,
+    PullArtifactsResponse,
+)
+from flwr.proto.control_pb2_grpc import ControlStub
+
+from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+
+
+def pull(  # pylint: disable=R0914
+    run_id: Annotated[
+        int,
+        typer.Option(
+            "--run-id",
+            help="Run ID to pull artifacts from.",
+        ),
+    ],
+    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."),
+    ] = None,
+    federation_config_overrides: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--federation-config",
+            help=FEDERATION_CONFIG_HELP_MESSAGE,
+        ),
+    ] = None,
+) -> None:
+    """Pull artifacts from a Flower run."""
+    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 = 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, "pull")
+    channel = None
+    try:
+
+        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():
+            res: PullArtifactsResponse = stub.PullArtifacts(
+                PullArtifactsRequest(run_id=run_id)
+            )
+
+        if not res.url:
+            typer.secho(
+                f"❌ A download URL for artifacts from run {run_id} couldn't be "
+                "obtained.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+
+        typer.secho(
+            f"✅ Artifacts for run {run_id} can be downloaded from: {res.url}",
+            fg=typer.colors.GREEN,
+        )
+    finally:
+        if channel:
+            channel.close()

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, Optional, 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,7 +39,7 @@ 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
@@ -45,7 +47,7 @@ from flwr.proto.control_pb2 import StartRunRequest  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
 
 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
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
 
@@ -148,14 +150,16 @@ def _run_with_control_api(
 ) -> None:
     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)
 
-        fab_bytes, fab_hash, config = build_fab(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)
+        fab = Fab(fab_hash, fab_bytes, {})
 
         # Construct a `ConfigRecord` out of a flattened `UserConfig`
         fed_config = flatten_dict(federation_config.get("options", {}))

flwr/cli/stop.py

@@ -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
@@ -89,7 +89,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
 

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",
+]

flwr/cli/supernode/ls.py

@@ -0,0 +1,260 @@
+# 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 list` command."""
+
+
+import io
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Optional, cast
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+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 FAB_CONFIG_FILE, NOOP_FLWR_AID, CliOutputFormat
+from flwr.common.date import format_timedelta, isoformat8601_utc
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    ListNodesRequest,
+    ListNodesResponse,
+)
+from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.proto.node_pb2 import NodeInfo  # pylint: disable=E0611
+
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+
+_NodeListType = tuple[int, str, str, str, str, str, str, str]
+
+
+def ls(  # pylint: disable=R0914, R0913, R0917
+    ctx: typer.Context,
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """List SuperNodes in the federation."""
+    # Resolve command used (list or ls)
+    command_name = cast(str, ctx.command.name) if ctx.command else "ls"
+
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+    try:
+        if suppress_output:
+            redirect_output(captured_output)
+        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 = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config
+        )
+        exit_if_no_address(federation_config, f"supernode {command_name}")
+        channel = None
+        try:
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ControlStub(channel)
+            typer.echo("📄 Listing all nodes...")
+            formatted_nodes = _list_nodes(stub)
+            restore_output()
+            if output_format == CliOutputFormat.JSON:
+                Console().print_json(_to_json(formatted_nodes, verbose=verbose))
+            else:
+                Console().print(_to_table(formatted_nodes, verbose=verbose))
+
+        finally:
+            if channel:
+                channel.close()
+    except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
+        if suppress_output:
+            restore_output()
+            e_message = captured_output.getvalue()
+            print_json_error(e_message, err)
+        else:
+            typer.secho(
+                f"{err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()
+
+
+def _list_nodes(stub: ControlStub) -> list[_NodeListType]:
+    """List all nodes."""
+    with flwr_cli_grpc_exc_handler():
+        res: ListNodesResponse = stub.ListNodes(ListNodesRequest())
+
+    return _format_nodes(list(res.nodes_info), res.now)
+
+
+def _format_nodes(
+    nodes_info: list[NodeInfo], now_isoformat: str
+) -> list[_NodeListType]:
+    """Format node information for display."""
+
+    def _format_datetime(dt_str: Optional[str]) -> str:
+        dt = datetime.fromisoformat(dt_str) if dt_str else None
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    formatted_nodes: list[_NodeListType] = []
+    # Add rows
+    for node in sorted(
+        nodes_info, key=lambda x: datetime.fromisoformat(x.registered_at)
+    ):
+
+        # Calculate elapsed times
+        elapsed_time_activated = timedelta()
+        if node.last_activated_at:
+            end_time = datetime.fromisoformat(now_isoformat)
+            elapsed_time_activated = end_time - datetime.fromisoformat(
+                node.last_activated_at
+            )
+
+        formatted_nodes.append(
+            (
+                node.node_id,
+                node.owner_aid,
+                node.status,
+                _format_datetime(node.registered_at),
+                _format_datetime(node.last_activated_at),
+                _format_datetime(node.last_deactivated_at),
+                _format_datetime(node.unregistered_at),
+                format_timedelta(elapsed_time_activated),
+            )
+        )
+
+    return formatted_nodes
+
+
+def _to_table(nodes_info: list[_NodeListType], verbose: bool) -> Table:
+    """Format the provided node list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # Add columns
+    table.add_column(
+        Text("Node ID", justify="center"), style="bright_black", no_wrap=True
+    )
+    table.add_column(Text("Owner", justify="center"))
+    table.add_column(Text("Status", justify="center"))
+    table.add_column(Text("Elapsed", justify="center"))
+    table.add_column(Text("Status Changed @", justify="center"), style="bright_black")
+
+    for row in nodes_info:
+        (
+            node_id,
+            owner_aid,
+            status,
+            _,
+            last_activated_at,
+            last_deactivated_at,
+            unregistered_at,
+            elapse_activated,
+        ) = row
+
+        if status == "online":
+            status_style = "green"
+            time_at = last_activated_at
+        elif status == "offline":
+            status_style = "bright_yellow"
+            time_at = last_deactivated_at
+        elif status == "unregistered":
+            if not verbose:
+                continue
+            status_style = "red"
+            time_at = unregistered_at
+        elif status == "registered":
+            status_style = "blue"
+            time_at = "N/A"
+        else:
+            raise ValueError(f"Unexpected node status '{status}'")
+
+        formatted_row = (
+            f"[bold]{node_id}[/bold]",
+            f"{owner_aid}" if owner_aid != NOOP_FLWR_AID else f"[dim]{owner_aid}[/dim]",
+            f"[{status_style}]{status}",
+            f"[cyan]{elapse_activated}[/cyan]" if status == "online" else "",
+            time_at,
+        )
+        table.add_row(*formatted_row)
+
+    return table
+
+
+def _to_json(nodes_info: list[_NodeListType], verbose: bool) -> str:
+    """Format node list to a JSON formatted string."""
+    nodes_list = []
+    for row in nodes_info:
+        (
+            node_id,
+            owner_aid,
+            status,
+            created_at,
+            activated_at,
+            deactivated_at,
+            deleted_at,
+            elapse_activated,
+        ) = row
+
+        if status == "deleted" and not verbose:
+            continue
+
+        nodes_list.append(
+            {
+                "node-id": node_id,
+                "owner-aid": owner_aid,
+                "status": status,
+                "created-at": created_at,
+                "online-at": activated_at,
+                "online-elapsed": elapse_activated,
+                "offline-at": deactivated_at,
+                "deleted-at": deleted_at,
+            }
+        )
+
+    return json.dumps({"success": True, "nodes": nodes_list})