flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.11.0.dev20240813__py3-none-any.whl

flwr/cli/new/new.py

@@ -14,23 +14,43 @@
 # ==============================================================================
 """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
 
 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"
+
+
+class LlmChallengeName(str, Enum):
+    """Available LLM challenges."""
+
+    GENERALNLP = "GeneralNLP"
+    FINANCE = "Finance"
+    MEDICAL = "Medical"
+    CODE = "Code"
 
 
 class TemplateNotFound(Exception):
@@ -39,10 +59,10 @@ 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:
@@ -53,47 +73,69 @@ 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)
 
 
-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)
+        framework_str_upper = str(framework.value)
     else:
         framework_value = prompt_options(
             "Please select ML framework by typing in the number",
@@ -104,50 +146,139 @@ def new(
             for name, value in vars(MlFramework).items()
             if value == framework_value
         ]
-        framework_str = selected_value[0]
+        framework_str_upper = selected_value[0]
 
-    framework_str = framework_str.lower()
+    framework_str = framework_str_upper.lower()
 
-    # Set project directory path
-    cwd = os.getcwd()
-    pnl = project_name.lower()
-    project_dir = os.path.join(cwd, pnl)
+    llm_challenge_str = None
+    if framework_str == "flowertune":
+        llm_challenge_value = prompt_options(
+            "Please select LLM challenge by typing in the number",
+            sorted([challenge.value for challenge in LlmChallengeName]),
+        )
+        selected_value = [
+            name
+            for name, value in vars(LlmChallengeName).items()
+            if value == llm_challenge_value
+        ]
+        llm_challenge_str = selected_value[0]
+        llm_challenge_str = llm_challenge_str.lower()
 
-    # 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_upper,
+        "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"}
+    # List of files to render
+    if llm_challenge_str:
+        files = {
+            ".gitignore": {"template": "app/.gitignore.tpl"},
+            "pyproject.toml": {"template": f"app/pyproject.{framework_str}.toml.tpl"},
+            "README.md": {"template": f"app/README.{framework_str}.md.tpl"},
+            f"{import_name}/__init__.py": {"template": "app/code/__init__.py.tpl"},
+            f"{import_name}/server.py": {
+                "template": "app/code/flwr_tune/server.py.tpl"
+            },
+            f"{import_name}/client.py": {
+                "template": "app/code/flwr_tune/client.py.tpl"
+            },
+            f"{import_name}/app.py": {"template": "app/code/flwr_tune/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}/conf/config.yaml": {
+                "template": "app/code/flwr_tune/config.yaml.tpl"
+            },
+            f"{import_name}/conf/static_config.yaml": {
+                "template": "app/code/flwr_tune/static_config.yaml.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.{framework_str}.toml.tpl"},
+            f"{import_name}/__init__.py": {"template": "app/code/__init__.py.tpl"},
+            f"{import_name}/server_app.py": {
+                "template": f"app/code/server.{framework_str}.py.tpl"
+            },
+            f"{import_name}/client_app.py": {
+                "template": f"app/code/client.{framework_str}.py.tpl"
+            },
+        }
+
+        # Depending on the framework, generate task.py file
+        frameworks_with_tasks = [
+            MlFramework.PYTORCH.value.lower(),
+            MlFramework.JAX.value.lower(),
+            MlFramework.HUGGINGFACE.value.lower(),
+            MlFramework.MLX.value.lower(),
+            MlFramework.TENSORFLOW.value.lower(),
+        ]
+        if framework_str in frameworks_with_tasks:
+            files[f"{import_name}/task.py"] = {
+                "template": f"app/code/task.{framework_str}.py.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",
+            "🎊 Flower App creation successful.\n\n"
+            "Use the following command to run your Flower App:\n",
             fg=typer.colors.GREEN,
             bold=True,
         )
     )
+
+    _add = "	huggingface-cli login\n" if framework_str == "flowertune" else ""
     print(
         typer.style(
-            f"	cd {project_name}\n" + "	pip install -e .\n	flwr run\n",
+            f"	cd {package_name}\n" + "	pip install -e .\n" + _add + "	flwr run\n",
             fg=typer.colors.BRIGHT_CYAN,
             bold=True,
         )

flwr/cli/new/templates/app/.gitignore.tpl

@@ -0,0 +1,160 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

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

@@ -0,0 +1,56 @@
+# FlowerTune LLM on $challenge_name Dataset
+
+This directory conducts federated instruction tuning with a pretrained [Mistral-7B](https://huggingface.co/mistralai/Mistral-7B-v0.3) model on a [$challenge_name dataset](https://huggingface.co/datasets/$dataset_name).
+We use [Flower Datasets](https://flower.dev/docs/datasets/) to download, partition and preprocess the dataset.
+Flower's Simulation Engine is used to simulate the LLM fine-tuning process in federated way,
+which allows users to perform the training on a single GPU.
+
+
+## Methodology
+
+This baseline performs federated LLM fine-tuning with [LoRA](https://arxiv.org/pdf/2106.09685) using the [🤗PEFT](https://huggingface.co/docs/peft/en/index) library.
+The clients' models are aggregated with FedAvg strategy.
+This provides a baseline performance for the leaderboard of $challenge_name challenge.
+
+
+## Environments setup
+
+Project dependencies are defined in `pyproject.toml`. Install them in an activated Python environment with:
+
+```shell
+pip install -e .
+```
+
+## Experimental setup
+
+The dataset is partitioned into $num_clients shards with IID fashion serving as clients.
+We randomly sample $fraction_fit clients to be available for each round,
+and the federated fine-tuning lasts for `200` rounds.
+All settings are defined in `$project_name/conf/static_config.yaml`, which is not allowed to be modified for fair competition if you plan to participated in the [LLM leaderboard](https://flower.ai/benchmarks/llm-leaderboard).
+
+
+## Running the challenge
+
+First make sure that you have got the access to [Mistral-7B](https://huggingface.co/mistralai/Mistral-7B-v0.3) model with your Hugging-Face account. You can request access directly from the Hugging-Face website.
+Then, follow the instruction [here](https://huggingface.co/docs/huggingface_hub/en/quick-start#login-command) to log in your account. Note you only need to complete this stage once in your development machine:
+
+```bash
+huggingface-cli login
+```
+
+Run the challenge with default config values.
+The configs are in `$project_name/conf/config.yaml` and `$project_name/conf/static_config.yaml`, and are loaded automatically.
+
+```bash
+flwr run
+```
+
+## VRAM consumption
+
+We use Mistral-7B model with 4-bit quantization as default. The estimated VRAM consumption per client for each challenge is shown below:
+
+| Challenges | GeneralNLP |   Finance  |   Medical  |    Code    |
+| :--------: | :--------: | :--------: | :--------: | :--------: |
+|    VRAM    | ~25.50 GB  | ~17.30 GB  | ~22.80 GB  | ~17.40 GB  |
+
+You can adjust the CPU/GPU resources you assign to each of the clients based on your device, which is specified with `flower.engine.simulation` in `pyproject.toml`.

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

@@ -1,13 +1,9 @@
-# $project_name
+# $project_name: A Flower / $framework_str app
 
 ## Install dependencies
 
 ```bash
-# Using pip
 pip install .
-
-# Or using Poetry
-poetry install
 ```
 
 ## Run (Simulation Engine)

flwr/cli/new/templates/app/code/__init__.py.tpl

@@ -1 +1 @@
-"""$project_name."""
+"""$project_name: A Flower / $framework_str app."""

flwr/cli/new/templates/app/code/client.huggingface.py.tpl

@@ -0,0 +1,65 @@
+"""$project_name: A Flower / $framework_str app."""
+
+from flwr.client import ClientApp, NumPyClient
+from flwr.common import Context
+from transformers import AutoModelForSequenceClassification
+
+from $import_name.task import (
+    get_weights,
+    load_data,
+    set_weights,
+    train,
+    test,
+    CHECKPOINT,
+    DEVICE,
+)
+
+
+# Flower client
+class FlowerClient(NumPyClient):
+    def __init__(self, net, trainloader, testloader, local_epochs):
+        self.net = net
+        self.trainloader = trainloader
+        self.testloader = testloader
+        self.local_epochs = local_epochs
+
+    def get_parameters(self, config):
+        return get_weights(self.net)
+
+    def set_parameters(self, parameters):
+        set_weights(self.net, parameters)
+
+    def fit(self, parameters, config):
+        self.set_parameters(parameters)
+        train(
+            self.net,
+            self.trainloader,
+            epochs=self.local_epochs,
+        )
+        return self.get_parameters(config={}), len(self.trainloader), {}
+
+    def evaluate(self, parameters, config):
+        self.set_parameters(parameters)
+        loss, accuracy = test(self.net, self.testloader)
+        return float(loss), len(self.testloader), {"accuracy": accuracy}
+
+
+def client_fn(context: Context):
+    # Load model and data
+    net = AutoModelForSequenceClassification.from_pretrained(
+        CHECKPOINT, num_labels=2
+    ).to(DEVICE)
+
+    partition_id = context.node_config["partition-id"]
+    num_partitions = context.node_config["num-partitions"]
+    trainloader, valloader = load_data(partition_id, num_partitions)
+    local_epochs = context.run_config["local-epochs"]
+
+    # Return Client instance
+    return FlowerClient(net, trainloader, valloader, local_epochs).to_client()
+
+
+# Flower ClientApp
+app = ClientApp(
+    client_fn,
+)

flwr/cli/new/templates/app/code/client.jax.py.tpl

@@ -0,0 +1,56 @@
+"""$project_name: A Flower / $framework_str app."""
+
+import jax
+from flwr.client import NumPyClient, ClientApp
+from flwr.common import Context
+
+from $import_name.task import (
+    evaluation,
+    get_params,
+    load_data,
+    load_model,
+    loss_fn,
+    set_params,
+    train,
+)
+
+
+# Define Flower Client and client_fn
+class FlowerClient(NumPyClient):
+    def __init__(self):
+        self.train_x, self.train_y, self.test_x, self.test_y = load_data()
+        self.grad_fn = jax.grad(loss_fn)
+        model_shape = self.train_x.shape[1:]
+
+        self.params = load_model(model_shape)
+
+    def get_parameters(self, config):
+        return get_params(self.params)
+
+    def set_parameters(self, parameters):
+        set_params(self.params, parameters)
+
+    def fit(self, parameters, config):
+        self.set_parameters(parameters)
+        self.params, loss, num_examples = train(
+            self.params, self.grad_fn, self.train_x, self.train_y
+        )
+        parameters = self.get_parameters(config={})
+        return parameters, num_examples, {"loss": float(loss)}
+
+    def evaluate(self, parameters, config):
+        self.set_parameters(parameters)
+        loss, num_examples = evaluation(
+            self.params, self.grad_fn, self.test_x, self.test_y
+        )
+        return float(loss), num_examples, {"loss": float(loss)}
+
+def client_fn(context: Context):
+    # Return Client instance
+    return FlowerClient().to_client()
+
+
+# Flower ClientApp
+app = ClientApp(
+    client_fn,
+)