flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.15.0.dev20250114__py3-none-any.whl

flwr/cli/ls.py

@@ -0,0 +1,327 @@
+# 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."""
+
+
+import io
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Optional
+
+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, CliOutputFormat, SubStatus
+from flwr.common.date import format_timedelta, isoformat8601_utc
+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
+    ListRunsRequest,
+    ListRunsResponse,
+)
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+from .utils import init_channel, try_obtain_cli_auth_plugin, unauthenticated_exc_handler
+
+_RunListType = tuple[int, str, str, str, str, str, str, str, str]
+
+
+def ls(  # pylint: disable=too-many-locals, too-many-branches
+    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,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+) -> None:
+    """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:
+        if suppress_output:
+            redirect_output(captured_output)
+        # 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 = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config
+        )
+        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."
+                )
+            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
+            if run_id is not None:
+                typer.echo(f"🔍 Displaying information for run ID {run_id}...")
+                restore_output()
+                _display_one_run(stub, run_id, output_format)
+            # By default, list all runs
+            else:
+                typer.echo("📄 Listing all runs...")
+                restore_output()
+                _list_runs(stub, output_format)
+
+        except ValueError as err:
+            if suppress_output:
+                redirect_output(captured_output)
+            typer.secho(
+                f"❌ {err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1) from err
+        finally:
+            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 _format_runs(run_dict: dict[int, Run], now_isoformat: str) -> list[_RunListType]:
+    """Format runs to a list."""
+
+    def _format_datetime(dt: Optional[datetime]) -> str:
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    run_list: list[_RunListType] = []
+
+    # 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}"
+
+        # 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
+
+        run_list.append(
+            (
+                run.run_id,
+                run.fab_id,
+                run.fab_version,
+                run.fab_hash,
+                status_text,
+                format_timedelta(elapsed_time),
+                _format_datetime(pending_at),
+                _format_datetime(running_at),
+                _format_datetime(finished_at),
+            )
+        )
+    return run_list
+
+
+def _to_table(run_list: list[_RunListType]) -> Table:
+    """Format the provided run list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # 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")
+
+    for row in run_list:
+        (
+            run_id,
+            fab_id,
+            fab_version,
+            _,
+            status_text,
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
+        ) = row
+        # Style the status based on its value
+        sub_status = status_text.rsplit(":", maxsplit=1)[-1]
+        if sub_status == SubStatus.COMPLETED:
+            status_style = "green"
+        elif sub_status == SubStatus.FAILED:
+            status_style = "red"
+        else:
+            status_style = "yellow"
+
+        formatted_row = (
+            f"[bold]{run_id}[/bold]",
+            f"{fab_id} (v{fab_version})",
+            f"[{status_style}]{status_text}[/{status_style}]",
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
+        )
+        table.add_row(*formatted_row)
+
+    return table
+
+
+def _to_json(run_list: list[_RunListType]) -> str:
+    """Format run status list to a JSON formatted string."""
+    runs_list = []
+    for row in run_list:
+        (
+            run_id,
+            fab_id,
+            fab_version,
+            fab_hash,
+            status_text,
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
+        ) = row
+        runs_list.append(
+            {
+                "run-id": run_id,
+                "fab-id": fab_id,
+                "fab-name": fab_id.split("/")[-1],
+                "fab-version": fab_version,
+                "fab-hash": fab_hash[:8],
+                "status": status_text,
+                "elapsed": elapsed,
+                "created-at": created_at,
+                "running-at": running_at,
+                "finished-at": finished_at,
+            }
+        )
+
+    return json.dumps({"success": True, "runs": runs_list})
+
+
+def _list_runs(
+    stub: ExecStub,
+    output_format: str = CliOutputFormat.DEFAULT,
+) -> None:
+    """List all runs."""
+    with unauthenticated_exc_handler():
+        res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
+    run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
+
+    formatted_runs = _format_runs(run_dict, res.now)
+    if output_format == CliOutputFormat.JSON:
+        Console().print_json(_to_json(formatted_runs))
+    else:
+        Console().print(_to_table(formatted_runs))
+
+
+def _display_one_run(
+    stub: ExecStub,
+    run_id: int,
+    output_format: str = CliOutputFormat.DEFAULT,
+) -> None:
+    """Display information about a specific run."""
+    with unauthenticated_exc_handler():
+        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()}
+
+    formatted_runs = _format_runs(run_dict, res.now)
+    if output_format == CliOutputFormat.JSON:
+        Console().print_json(_to_json(formatted_runs))
+    else:
+        Console().print(_to_table(formatted_runs))

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,23 +14,44 @@
 # ==============================================================================
 """Flower command line interface `new` command."""
 
-import os
+
+import re
 from enum import Enum
+from pathlib import Path
 from string import Template
-from typing import Dict, Optional
+from typing import Annotated, Optional
 
 import typer
-from typing_extensions import Annotated
 
-from ..utils import prompt_options, prompt_text
+from ..utils import (
+    is_valid_project_name,
+    prompt_options,
+    prompt_text,
+    sanitize_project_name,
+)
 
 
 class MlFramework(str, Enum):
     """Available frameworks."""
 
-    NUMPY = "NumPy"
     PYTORCH = "PyTorch"
     TENSORFLOW = "TensorFlow"
+    SKLEARN = "sklearn"
+    HUGGINGFACE = "HuggingFace"
+    JAX = "JAX"
+    MLX = "MLX"
+    NUMPY = "NumPy"
+    FLOWERTUNE = "FlowerTune"
+    BASELINE = "Flower Baseline"
+
+
+class LlmChallengeName(str, Enum):
+    """Available LLM challenges."""
+
+    GENERALNLP = "GeneralNLP"
+    FINANCE = "Finance"
+    MEDICAL = "Medical"
+    CODE = "Code"
 
 
 class TemplateNotFound(Exception):
@@ -39,116 +60,239 @@ class TemplateNotFound(Exception):
 
 def load_template(name: str) -> str:
     """Load template from template directory and return as text."""
-    tpl_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "templates"))
-    tpl_file_path = os.path.join(tpl_dir, name)
+    tpl_dir = (Path(__file__).parent / "templates").absolute()
+    tpl_file_path = tpl_dir / name
 
-    if not os.path.isfile(tpl_file_path):
+    if not tpl_file_path.is_file():
         raise TemplateNotFound(f"Template '{name}' not found")
 
     with open(tpl_file_path, encoding="utf-8") as tpl_file:
         return tpl_file.read()
 
 
-def render_template(template: str, data: Dict[str, str]) -> str:
+def render_template(template: str, data: dict[str, str]) -> str:
     """Render template."""
     tpl_file = load_template(template)
     tpl = Template(tpl_file)
-    result = tpl.substitute(data)
-    return result
+    if ".gitignore" not in template:
+        return tpl.substitute(data)
+    return tpl.template
 
 
-def create_file(file_path: str, content: str) -> None:
+def create_file(file_path: Path, content: str) -> None:
     """Create file including all nessecary directories and write content into file."""
-    os.makedirs(os.path.dirname(file_path), exist_ok=True)
-    with open(file_path, "w", encoding="utf-8") as f:
-        f.write(content)
+    file_path.parent.mkdir(exist_ok=True)
+    file_path.write_text(content, encoding="utf-8")
 
 
-def render_and_create(file_path: str, template: str, context: Dict[str, str]) -> None:
+def render_and_create(file_path: Path, template: str, context: dict[str, str]) -> None:
     """Render template and write to file."""
     content = render_template(template, context)
     create_file(file_path, content)
 
 
+# pylint: disable=too-many-locals,too-many-branches,too-many-statements
 def new(
-    project_name: Annotated[
+    app_name: Annotated[
         Optional[str],
-        typer.Argument(metavar="project_name", help="The name of the project"),
+        typer.Argument(help="The name of the Flower App"),
     ] = None,
     framework: Annotated[
         Optional[MlFramework],
         typer.Option(case_sensitive=False, help="The ML framework to use"),
     ] = None,
+    username: Annotated[
+        Optional[str],
+        typer.Option(case_sensitive=False, help="The Flower username of the author"),
+    ] = None,
 ) -> None:
-    """Create new Flower project."""
-    print(
-        typer.style(
-            f"🔨 Creating Flower project {project_name}...",
-            fg=typer.colors.GREEN,
-            bold=True,
+    """Create new Flower App."""
+    if app_name is None:
+        app_name = prompt_text("Please provide the app name")
+    if not is_valid_project_name(app_name):
+        app_name = prompt_text(
+            "Please provide a name that only contains "
+            "characters in {'-', a-zA-Z', '0-9'}",
+            predicate=is_valid_project_name,
+            default=sanitize_project_name(app_name),
         )
-    )
 
-    if project_name is None:
-        project_name = prompt_text("Please provide project name")
+    # Set project directory path
+    package_name = re.sub(r"[-_.]+", "-", app_name).lower()
+    import_name = package_name.replace("-", "_")
+    project_dir = Path.cwd() / package_name
+
+    if project_dir.exists():
+        if not typer.confirm(
+            typer.style(
+                f"\n💬 {app_name} already exists, do you want to override it?",
+                fg=typer.colors.MAGENTA,
+                bold=True,
+            )
+        ):
+            return
+
+    if username is None:
+        username = prompt_text("Please provide your Flower username")
 
     if framework is not None:
         framework_str = str(framework.value)
     else:
-        framework_value = prompt_options(
+        framework_str = prompt_options(
             "Please select ML framework by typing in the number",
             [mlf.value for mlf in MlFramework],
         )
-        selected_value = [
-            name
-            for name, value in vars(MlFramework).items()
-            if value == framework_value
-        ]
-        framework_str = selected_value[0]
 
-    framework_str = framework_str.lower()
+    llm_challenge_str = None
+    if framework_str == MlFramework.FLOWERTUNE:
+        llm_challenge_value = prompt_options(
+            "Please select LLM challenge by typing in the number",
+            sorted([challenge.value for challenge in LlmChallengeName]),
+        )
+        llm_challenge_str = llm_challenge_value.lower()
 
-    # Set project directory path
-    cwd = os.getcwd()
-    pnl = project_name.lower()
-    project_dir = os.path.join(cwd, pnl)
+    if framework_str == MlFramework.BASELINE:
+        framework_str = "baseline"
 
-    # List of files to render
-    files = {
-        "README.md": {"template": "app/README.md.tpl"},
-        "requirements.txt": {"template": f"app/requirements.{framework_str}.txt.tpl"},
-        "flower.toml": {"template": "app/flower.toml.tpl"},
-        "pyproject.toml": {"template": f"app/pyproject.{framework_str}.toml.tpl"},
-        f"{pnl}/__init__.py": {"template": "app/code/__init__.py.tpl"},
-        f"{pnl}/server.py": {"template": f"app/code/server.{framework_str}.py.tpl"},
-        f"{pnl}/client.py": {"template": f"app/code/client.{framework_str}.py.tpl"},
+    print(
+        typer.style(
+            f"\n🔨 Creating Flower App {app_name}...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+
+    context = {
+        "framework_str": framework_str,
+        "import_name": import_name.replace("-", "_"),
+        "package_name": package_name,
+        "project_name": app_name,
+        "username": username,
     }
 
-    # In case framework is MlFramework.PYTORCH generate additionally the task.py file
-    if framework_str == MlFramework.PYTORCH.value.lower():
-        files[f"{pnl}/task.py"] = {"template": f"app/code/task.{framework_str}.py.tpl"}
+    template_name = framework_str.lower()
+
+    # List of files to render
+    if llm_challenge_str:
+        files = {
+            ".gitignore": {"template": "app/.gitignore.tpl"},
+            "pyproject.toml": {"template": f"app/pyproject.{template_name}.toml.tpl"},
+            "README.md": {"template": f"app/README.{template_name}.md.tpl"},
+            f"{import_name}/__init__.py": {"template": "app/code/__init__.py.tpl"},
+            f"{import_name}/server_app.py": {
+                "template": "app/code/flwr_tune/server_app.py.tpl"
+            },
+            f"{import_name}/client_app.py": {
+                "template": "app/code/flwr_tune/client_app.py.tpl"
+            },
+            f"{import_name}/models.py": {
+                "template": "app/code/flwr_tune/models.py.tpl"
+            },
+            f"{import_name}/dataset.py": {
+                "template": "app/code/flwr_tune/dataset.py.tpl"
+            },
+            f"{import_name}/strategy.py": {
+                "template": "app/code/flwr_tune/strategy.py.tpl"
+            },
+        }
+
+        # Challenge specific context
+        fraction_fit = "0.2" if llm_challenge_str == "code" else "0.1"
+        if llm_challenge_str == "generalnlp":
+            challenge_name = "General NLP"
+            num_clients = "20"
+            dataset_name = "vicgalle/alpaca-gpt4"
+        elif llm_challenge_str == "finance":
+            challenge_name = "Finance"
+            num_clients = "50"
+            dataset_name = "FinGPT/fingpt-sentiment-train"
+        elif llm_challenge_str == "medical":
+            challenge_name = "Medical"
+            num_clients = "20"
+            dataset_name = "medalpaca/medical_meadow_medical_flashcards"
+        else:
+            challenge_name = "Code"
+            num_clients = "10"
+            dataset_name = "lucasmccabe-lmi/CodeAlpaca-20k"
 
-    context = {"project_name": project_name}
+        context["llm_challenge_str"] = llm_challenge_str
+        context["fraction_fit"] = fraction_fit
+        context["challenge_name"] = challenge_name
+        context["num_clients"] = num_clients
+        context["dataset_name"] = dataset_name
+    else:
+        files = {
+            ".gitignore": {"template": "app/.gitignore.tpl"},
+            "README.md": {"template": "app/README.md.tpl"},
+            "pyproject.toml": {"template": f"app/pyproject.{template_name}.toml.tpl"},
+            f"{import_name}/__init__.py": {"template": "app/code/__init__.py.tpl"},
+            f"{import_name}/server_app.py": {
+                "template": f"app/code/server.{template_name}.py.tpl"
+            },
+            f"{import_name}/client_app.py": {
+                "template": f"app/code/client.{template_name}.py.tpl"
+            },
+        }
+
+        # Depending on the framework, generate task.py file
+        frameworks_with_tasks = [
+            MlFramework.PYTORCH.value,
+            MlFramework.JAX.value,
+            MlFramework.HUGGINGFACE.value,
+            MlFramework.MLX.value,
+            MlFramework.TENSORFLOW.value,
+            MlFramework.SKLEARN.value,
+            MlFramework.NUMPY.value,
+        ]
+        if framework_str in frameworks_with_tasks:
+            files[f"{import_name}/task.py"] = {
+                "template": f"app/code/task.{template_name}.py.tpl"
+            }
+
+        if framework_str == "baseline":
+            # Include additional files for baseline template
+            for file_name in ["model", "dataset", "strategy", "utils", "__init__"]:
+                files[f"{import_name}/{file_name}.py"] = {
+                    "template": f"app/code/{file_name}.{template_name}.py.tpl"
+                }
+
+            # Replace README.md
+            files["README.md"]["template"] = f"app/README.{template_name}.md.tpl"
+
+            # Add LICENSE
+            files["LICENSE"] = {"template": "app/LICENSE.tpl"}
 
     for file_path, value in files.items():
         render_and_create(
-            file_path=os.path.join(project_dir, file_path),
+            file_path=project_dir / file_path,
             template=value["template"],
             context=context,
         )
 
-    print(
-        typer.style(
-            "🎊 Project creation successful.\n\n"
-            "Use the following command to run your project:\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,
     )
-    print(
-        typer.style(
-            f"	cd {project_name}\n" + "	pip install -e .\n	flwr run\n",
-            fg=typer.colors.BRIGHT_CYAN,
-            bold=True,
-        )
+
+    _add = "	huggingface-cli login\n" if llm_challenge_str else ""
+    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)