flwr 1.12.0__py3-none-any.whl → 1.13.1__py3-none-any.whl

flwr/cli/app.py

@@ -20,6 +20,7 @@ from typer.main import get_command
 from .build import build
 from .install import install
 from .log import log
+from .ls import ls
 from .new import new
 from .run import run
 
@@ -37,6 +38,7 @@ app.command()(run)
 app.command()(build)
 app.command()(install)
 app.command()(log)
+app.command()(ls)
 
 typer_click_object = get_command(app)
 

flwr/cli/build.py

@@ -81,8 +81,8 @@ def build(
     if not is_valid_project_name(app.name):
         typer.secho(
             f"❌ The project name {app.name} is invalid, "
-            "a valid project name must start with a letter or an underscore, "
-            "and can only contain letters, digits, and underscores.",
+            "a valid project name must start with a letter, "
+            "and can only contain letters, digits, and hyphens.",
             fg=typer.colors.RED,
             bold=True,
         )

flwr/cli/config_utils.py

@@ -20,6 +20,7 @@ from pathlib import Path
 from typing import IO, Any, Optional, Union, get_args
 
 import tomli
+import typer
 
 from flwr.common import object_ref
 from flwr.common.typing import UserConfigValue
@@ -227,3 +228,99 @@ def load_from_string(toml_content: str) -> Optional[dict[str, Any]]:
         return data
     except tomli.TOMLDecodeError:
         return None
+
+
+def validate_project_config(
+    config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
+) -> dict[str, Any]:
+    """Validate and return the Flower project configuration."""
+    if config is None:
+        typer.secho(
+            "Project configuration could not be loaded.\n"
+            "pyproject.toml is invalid:\n"
+            + "\n".join([f"- {line}" for line in errors]),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    if warnings:
+        typer.secho(
+            "Project configuration is missing the following "
+            "recommended properties:\n" + "\n".join([f"- {line}" for line in warnings]),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+
+    typer.secho("Success", fg=typer.colors.GREEN)
+
+    return config
+
+
+def validate_federation_in_project_config(
+    federation: Optional[str], config: dict[str, Any]
+) -> tuple[str, dict[str, Any]]:
+    """Validate the federation name in the Flower project configuration."""
+    federation = federation or config["tool"]["flwr"]["federations"].get("default")
+
+    if federation is None:
+        typer.secho(
+            "❌ No federation name was provided and the project's `pyproject.toml` "
+            "doesn't declare a default federation (with an Exec API address or an "
+            "`options.num-supernodes` value).",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Validate the federation exists in the configuration
+    federation_config = config["tool"]["flwr"]["federations"].get(federation)
+    if federation_config is None:
+        available_feds = {
+            fed for fed in config["tool"]["flwr"]["federations"] if fed != "default"
+        }
+        typer.secho(
+            f"❌ There is no `{federation}` federation declared in the "
+            "`pyproject.toml`.\n The following federations were found:\n\n"
+            + "\n".join(available_feds),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    return federation, federation_config
+
+
+def validate_certificate_in_federation_config(
+    app: Path, federation_config: dict[str, Any]
+) -> tuple[bool, Optional[bytes]]:
+    """Validate the certificates in the Flower project configuration."""
+    insecure_str = federation_config.get("insecure")
+    if root_certificates := federation_config.get("root-certificates"):
+        root_certificates_bytes = (app / root_certificates).read_bytes()
+        if insecure := bool(insecure_str):
+            typer.secho(
+                "❌ `root_certificates` were provided but the `insecure` parameter "
+                "is set to `True`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+    else:
+        root_certificates_bytes = None
+        if insecure_str is None:
+            typer.secho(
+                "❌ To disable TLS, set `insecure = true` in `pyproject.toml`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+        if not (insecure := bool(insecure_str)):
+            typer.secho(
+                "❌ No certificate were given yet `insecure` is set to `False`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+
+    return insecure, root_certificates_bytes

flwr/cli/install.py

@@ -16,7 +16,6 @@
 
 import hashlib
 import shutil
-import subprocess
 import tempfile
 import zipfile
 from io import BytesIO
@@ -188,21 +187,6 @@ def validate_and_install(
         else:
             shutil.copy2(item, install_dir / item.name)
 
-    try:
-        subprocess.run(
-            ["pip", "install", "-e", install_dir, "--no-deps"],
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-    except subprocess.CalledProcessError as e:
-        typer.secho(
-            f"❌ Failed to `pip install` package(s) from {install_dir}:\n{e.stderr}",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1) from e
-
     typer.secho(
         f"🎊 Successfully installed {project_name} to {install_dir}.",
         fg=typer.colors.GREEN,

flwr/cli/log.py

@@ -14,33 +14,38 @@
 # ==============================================================================
 """Flower command line interface `log` command."""
 
-import sys
 import time
 from logging import DEBUG, ERROR, INFO
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated, Any, Optional, cast
 
 import grpc
 import typer
 
-from flwr.cli.config_utils import load_and_validate
+from flwr.cli.config_utils import (
+    load_and_validate,
+    validate_certificate_in_federation_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
 
-CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
-
 
 def start_stream(
     run_id: int, channel: grpc.Channel, refresh_period: int = CONN_REFRESH_PERIOD
 ) -> None:
     """Start log streaming for a given run ID."""
+    stub = ExecStub(channel)
+    after_timestamp = 0.0
     try:
+        logger(INFO, "Starting logstream for run_id `%s`", run_id)
         while True:
-            logger(INFO, "Starting logstream for run_id `%s`", run_id)
-            stream_logs(run_id, channel, refresh_period)
-            time.sleep(2)
+            after_timestamp = stream_logs(run_id, stub, refresh_period, after_timestamp)
+            time.sleep(CONN_RECONNECT_INTERVAL)
             logger(DEBUG, "Reconnecting to logstream")
     except KeyboardInterrupt:
         logger(INFO, "Exiting logstream")
@@ -54,16 +59,44 @@ def start_stream(
         channel.close()
 
 
-def stream_logs(run_id: int, channel: grpc.Channel, duration: int) -> None:
-    """Stream logs from the beginning of a run with connection refresh."""
-    start_time = time.time()
-    stub = ExecStub(channel)
-    req = StreamLogsRequest(run_id=run_id)
+def stream_logs(
+    run_id: int, stub: ExecStub, duration: int, after_timestamp: float
+) -> float:
+    """Stream logs from the beginning of a run with connection refresh.
+
+    Parameters
+    ----------
+    run_id : int
+        The identifier of the run.
+    stub : ExecStub
+        The gRPC stub to interact with the Exec service.
+    duration : int
+        The timeout duration for each stream connection in seconds.
+    after_timestamp : float
+        The timestamp to start streaming logs from.
+
+    Returns
+    -------
+    float
+        The latest timestamp from the streamed logs or the provided `after_timestamp`
+        if no logs are returned.
+    """
+    req = StreamLogsRequest(run_id=run_id, after_timestamp=after_timestamp)
+
+    latest_timestamp = 0.0
+    res = None
+    try:
+        for res in stub.StreamLogs(req, timeout=duration):
+            print(res.log_output, end="")
+    except grpc.RpcError as e:
+        # pylint: disable=E1101
+        if e.code() != grpc.StatusCode.DEADLINE_EXCEEDED:
+            raise e
+    finally:
+        if res is not None:
+            latest_timestamp = cast(float, res.latest_timestamp)
 
-    for res in stub.StreamLogs(req):
-        print(res.log_output)
-        if time.time() - start_time > duration:
-            break
+    return max(latest_timestamp, after_timestamp)
 
 
 def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
@@ -124,100 +157,33 @@ def log(
 
     pyproject_path = app / "pyproject.toml" if app else None
     config, errors, warnings = load_and_validate(path=pyproject_path)
-
-    if config is None:
-        typer.secho(
-            "Project configuration could not be loaded.\n"
-            "pyproject.toml is invalid:\n"
-            + "\n".join([f"- {line}" for line in errors]),
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        sys.exit()
-
-    if warnings:
-        typer.secho(
-            "Project configuration is missing the following "
-            "recommended properties:\n" + "\n".join([f"- {line}" for line in warnings]),
-            fg=typer.colors.RED,
-            bold=True,
-        )
-
-    typer.secho("Success", fg=typer.colors.GREEN)
-
-    federation = federation or config["tool"]["flwr"]["federations"].get("default")
-
-    if federation is None:
-        typer.secho(
-            "❌ No federation name was provided and the project's `pyproject.toml` "
-            "doesn't declare a default federation (with a SuperExec address or an "
-            "`options.num-supernodes` value).",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
-
-    # Validate the federation exists in the configuration
-    federation_config = config["tool"]["flwr"]["federations"].get(federation)
-    if federation_config is None:
-        available_feds = {
-            fed for fed in config["tool"]["flwr"]["federations"] if fed != "default"
-        }
-        typer.secho(
-            f"❌ There is no `{federation}` federation declared in the "
-            "`pyproject.toml`.\n The following federations were found:\n\n"
-            + "\n".join(available_feds),
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
+    config = validate_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
 
     if "address" not in federation_config:
         typer.secho(
-            "❌ `flwr log` currently works with `SuperExec`. Ensure that the correct"
-            "`SuperExec` address is provided in the `pyproject.toml`.",
+            "❌ `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_superexec(federation_config, run_id, stream)
+    _log_with_exec_api(app, federation_config, run_id, stream)
 
 
-# pylint: disable-next=too-many-branches
-def _log_with_superexec(
-    federation_config: dict[str, str],
+def _log_with_exec_api(
+    app: Path,
+    federation_config: dict[str, Any],
     run_id: int,
     stream: bool,
 ) -> None:
-    insecure_str = federation_config.get("insecure")
-    if root_certificates := federation_config.get("root-certificates"):
-        root_certificates_bytes = Path(root_certificates).read_bytes()
-        if insecure := bool(insecure_str):
-            typer.secho(
-                "❌ `root_certificates` were provided but the `insecure` parameter"
-                "is set to `True`.",
-                fg=typer.colors.RED,
-                bold=True,
-            )
-            raise typer.Exit(code=1)
-    else:
-        root_certificates_bytes = None
-        if insecure_str is None:
-            typer.secho(
-                "❌ To disable TLS, set `insecure = true` in `pyproject.toml`.",
-                fg=typer.colors.RED,
-                bold=True,
-            )
-            raise typer.Exit(code=1)
-        if not (insecure := bool(insecure_str)):
-            typer.secho(
-                "❌ No certificate were given yet `insecure` is set to `False`.",
-                fg=typer.colors.RED,
-                bold=True,
-            )
-            raise typer.Exit(code=1)
 
+    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
+        app, federation_config
+    )
     channel = create_channel(
         server_address=federation_config["address"],
         insecure=insecure,

flwr/cli/ls.py

@@ -0,0 +1,228 @@
+# 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 `ls` command."""
+
+
+from datetime import datetime, timedelta
+from logging import DEBUG
+from pathlib import Path
+from typing import Annotated, Any, Optional
+
+import grpc
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from flwr.cli.config_utils import (
+    load_and_validate,
+    validate_certificate_in_federation_config,
+    validate_federation_in_project_config,
+    validate_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE, 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
+from flwr.common.serde import run_from_proto
+from flwr.common.typing import Run
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    ListRunsRequest,
+    ListRunsResponse,
+)
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+
+def ls(
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+    runs: Annotated[
+        bool,
+        typer.Option(
+            "--runs",
+            help="List all runs",
+        ),
+    ] = False,
+    run_id: Annotated[
+        Optional[int],
+        typer.Option(
+            "--run-id",
+            help="Specific run ID to display",
+        ),
+    ] = None,
+) -> None:
+    """List runs."""
+    # Load and validate federation config
+    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 = validate_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)
+
+    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)
+        stub = ExecStub(channel)
+
+        # Display information about a specific run ID
+        if run_id is not None:
+            typer.echo(f"🔍 Displaying information for run ID {run_id}...")
+            _display_one_run(stub, run_id)
+        # By default, list all runs
+        else:
+            typer.echo("📄 Listing all runs...")
+            _list_runs(stub)
+
+    except ValueError as err:
+        typer.secho(
+            f"❌ {err}",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from err
+    finally:
+        channel.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_run_table(run_dict: dict[int, Run], now_isoformat: str) -> Table:
+    """Format run status as a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    def _format_datetime(dt: Optional[datetime]) -> str:
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    # Add columns
+    table.add_column(
+        Text("Run ID", justify="center"), style="bright_white", overflow="fold"
+    )
+    table.add_column(Text("FAB", justify="center"), style="dim white")
+    table.add_column(Text("Status", justify="center"))
+    table.add_column(Text("Elapsed", justify="center"), style="blue")
+    table.add_column(Text("Created At", justify="center"), style="dim white")
+    table.add_column(Text("Running At", justify="center"), style="dim white")
+    table.add_column(Text("Finished At", justify="center"), style="dim white")
+
+    # Add rows
+    for run in sorted(
+        run_dict.values(), 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}"
+
+        # Style the status based on its value
+        sub_status = run.status.sub_status
+        if sub_status == SubStatus.COMPLETED:
+            status_style = "green"
+        elif sub_status == SubStatus.FAILED:
+            status_style = "red"
+        else:
+            status_style = "yellow"
+
+        # Convert isoformat to datetime
+        pending_at = datetime.fromisoformat(run.pending_at) if run.pending_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
+
+        table.add_row(
+            f"[bold]{run.run_id}[/bold]",
+            f"{run.fab_id} (v{run.fab_version})",
+            f"[{status_style}]{status_text}[/{status_style}]",
+            format_timedelta(elapsed_time),
+            _format_datetime(pending_at),
+            _format_datetime(running_at),
+            _format_datetime(finished_at),
+        )
+    return table
+
+
+def _list_runs(
+    stub: ExecStub,
+) -> None:
+    """List all runs."""
+    res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
+    run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
+
+    Console().print(_format_run_table(run_dict, res.now))
+
+
+def _display_one_run(
+    stub: ExecStub,
+    run_id: int,
+) -> None:
+    """Display information about a specific run."""
+    res: ListRunsResponse = stub.ListRuns(ListRunsRequest(run_id=run_id))
+    if not res.run_dict:
+        raise ValueError(f"Run ID {run_id} not found")
+
+    run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
+
+    Console().print(_format_run_table(run_dict, res.now))

flwr/cli/new/new.py

@@ -268,20 +268,30 @@ def new(
             context=context,
         )
 
-    print(
-        typer.style(
-            "🎊 Flower App creation successful.\n\n"
-            "Use the following command to run your Flower App:\n",
-            fg=typer.colors.GREEN,
-            bold=True,
-        )
+    prompt = typer.style(
+        "🎊 Flower App creation successful.\n\n"
+        "To run your Flower App, use the following command:\n\n",
+        fg=typer.colors.GREEN,
+        bold=True,
     )
 
     _add = "	huggingface-cli login\n" if llm_challenge_str else ""
-    print(
-        typer.style(
-            f"	cd {package_name}\n" + "	pip install -e .\n" + _add + "	flwr run\n",
-            fg=typer.colors.BRIGHT_CYAN,
-            bold=True,
-        )
+    prompt += typer.style(
+        _add + f"	flwr run {package_name}\n\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "If you haven't installed all dependencies yet, follow these steps:\n\n",
+        fg=typer.colors.GREEN,
+        bold=True,
     )
+
+    prompt += typer.style(
+        f"	cd {package_name}\n" + "	pip install -e .\n" + _add + "	flwr run .\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    print(prompt)

flwr/cli/new/templates/app/README.md.tpl

@@ -14,7 +14,18 @@ In the `$project_name` directory, use `flwr run` to run a local simulation:
 flwr run .
 ```
 
+Refer to the [How to Run Simulations](https://flower.ai/docs/framework/how-to-run-simulations.html) guide in the documentation for advice on how to optimize your simulations.
+
 ## Run with the Deployment Engine
 
 > \[!NOTE\]
 > An update to this example will show how to run this Flower application with the Deployment Engine and TLS certificates, or with Docker.
+
+## Resources
+
+- Flower website: [flower.ai](https://flower.ai/)
+- Check the documentation: [flower.ai/docs](https://flower.ai/docs/)
+- Give Flower a ⭐️ on GitHub: [GitHub](https://github.com/adap/flower)
+- Join the Flower community!
+  - [Flower Slack](https://flower.ai/join-slack/)
+  - [Flower Discuss](https://discuss.flower.ai/)

flwr/cli/new/templates/app/code/flwr_tune/dataset.py.tpl

@@ -71,7 +71,7 @@ def load_data(partition_id: int, num_partitions: int, dataset_name: str):
             partitioners={"train": partitioner},
         )
     client_trainset = FDS.load_partition(partition_id, "train")
-    client_trainset = reformat(client_trainset, llm_task="generalnlp")
+    client_trainset = reformat(client_trainset, llm_task="$llm_challenge_str")
     return client_trainset