FedModelKit 0.5.0__py3-none-any.whl

FedModelKit/templates/ds_template.ipynb

@@ -0,0 +1,332 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Data Scientist (DS)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Change `LOCAL_TEST` to True if you want to run the clients locally to test.   \n",
+    "With `LOCAL_TEST = False`, please have your syftbox client running. Installation instructions here https://www.syftbox.net/."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "LOCAL_TEST = True"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Some paths and constants "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "SYFTBOX_DATASET_NAME = \"pima-indians-diabetes-database\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Log into the data owners' datasites"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if LOCAL_TEST:\n",
+    "    from syft_rds.orchestra import setup_rds_server\n",
+    "\n",
+    "    print(\"Running locally!\")\n",
+    "\n",
+    "    DS = \"ds@openmined.org\"\n",
+    "    print(\"DS email: \", DS)\n",
+    "\n",
+    "    DO1 = \"do1@openmined.org\"\n",
+    "    DO2 = \"do2@openmined.org\"\n",
+    "\n",
+    "    ds_stack = setup_rds_server(email=DS, key=\"flwr\", root_dir=Path(\".\"))\n",
+    "    do_client_1 = ds_stack.init_session(host=DO1)\n",
+    "    do_client_2 = ds_stack.init_session(host=DO2)\n",
+    "else:\n",
+    "    import syft_rds as sy\n",
+    "    from syft_core import Client\n",
+    "\n",
+    "    DS = Client.load().email\n",
+    "    print(\"DS email: \", DS)\n",
+    "\n",
+    "    DO1 = \"flower-test-group-1@openmined.org\"\n",
+    "    DO2 = \"flower-test-group-2@openmined.org\"\n",
+    "\n",
+    "    do_client_1 = sy.init_session(host=DO1)\n",
+    "    print(\"Logged into: \", do_client_1.host)\n",
+    "\n",
+    "    do_client_2 = sy.init_session(host=DO2)\n",
+    "    print(\"Logged into: \", do_client_2.host)\n",
+    "\n",
+    "do_clients = [do_client_1, do_client_2]\n",
+    "do_emails = [DO1, DO2]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Explore the datasets"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SYFTBOX_DATASET_NAME"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mock_paths = []\n",
+    "for client in do_clients:\n",
+    "    dataset = client.dataset.get(name=SYFTBOX_DATASET_NAME)\n",
+    "    mock_paths.append(dataset.get_mock_path())\n",
+    "    print(f\"Client {client.host}'s dataset: \\n{dataset}\\n\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Bootstrapping and run `syft_flwr` simulation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SYFT_FLWR_PROJECT_PATH = Path(\"./fl-diabetes-prediction\")\n",
+    "assert SYFT_FLWR_PROJECT_PATH.exists()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import syft_flwr\n",
+    "\n",
+    "try:\n",
+    "    !rm -rf {SYFT_FLWR_PROJECT_PATH / \"main.py\"}\n",
+    "    syft_flwr.bootstrap(SYFT_FLWR_PROJECT_PATH, aggregator=DS, datasites=do_emails)\n",
+    "    print(\"Bootstrapped project successfully ✅\")\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run `flwr` and `syft_flwr` simulations (optional)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "RUN_SIMULATION = True"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if RUN_SIMULATION:\n",
+    "    !flwr run {SYFT_FLWR_PROJECT_PATH}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# clean up\n",
+    "!rm -rf {SYFT_FLWR_PROJECT_PATH / \"fl_diabetes_prediction\" / \"__pycache__\"}\n",
+    "!rm -rf weights/"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mock_paths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if RUN_SIMULATION:\n",
+    "    print(f\"running syft_flwr simulation with mock paths: {mock_paths}\")\n",
+    "    syft_flwr.run(SYFT_FLWR_PROJECT_PATH, mock_paths)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Submit jobs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"./images/dsSendsJobs.png\" width=\"80%\" alt=\"DS Submits Jobs\">"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# clean up before submitting jobs\n",
+    "!rm -rf {SYFT_FLWR_PROJECT_PATH / \"fl_diabetes_prediction\" / \"__pycache__\"}\n",
+    "!rm -rf {SYFT_FLWR_PROJECT_PATH / \"simulation_logs\"}\n",
+    "!rm -rf weights/"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for client in do_clients:\n",
+    "    print(f\"sending job to {client.host}\")\n",
+    "    job = client.jobs.submit(\n",
+    "        name=\"Syft Flower Experiment\",\n",
+    "        description=\"Syft Flower Federated Learning Experiment\",\n",
+    "        user_code_path=SYFT_FLWR_PROJECT_PATH,\n",
+    "        dataset_name=SYFTBOX_DATASET_NAME,\n",
+    "        tags=[\"federated learning\", \"fl\", \"syft_flwr\", \"flwr\"],\n",
+    "        entrypoint=\"main.py\",\n",
+    "    )\n",
+    "    print(job)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"./images/dsDoneSubmittingJobs.png\" width=\"40%\" alt=\"DS waits for jobs to be approved\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## DS starts the FL server code"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "if LOCAL_TEST:\n",
+    "    os.environ[\"SYFTBOX_CLIENT_CONFIG_PATH\"] = str(ds_stack.client.config_path)\n",
+    "\n",
+    "os.environ[\"LOGURU_LEVEL\"] = \"DEBUG\"\n",
+    "os.environ[\"SYFT_FLWR_MSG_TIMEOUT\"] = \"60\"\n",
+    "\n",
+    "!uv run {str(SYFT_FLWR_PROJECT_PATH / \"main.py\")} --active"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "By running the FL server code, the DS aggregates the models trained on DOs' private local data into an improved global model\n",
+    "\n",
+    "<img src=\"./images/dsAggregateModels.png\" width=\"30%\" alt=\"DS Aggregates Models\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## DS Observes the Results"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now the DS can monitor the aggregated models trained no DO's private datasets in the `weights` folder"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

FedModelKit/templates/extern_pyproject_template.toml

@@ -0,0 +1,17 @@
+[project]
+name = "EXPERIMENT_NAME"
+version = "0.1.0"
+description = "Description of the experiment"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "flwr-datasets>=0.5.0",
+    "flwr[simulation]==1.17.0",
+    "imblearn>=0.0",
+    "jupyterlab>=4.4.4",
+    "loguru>=0.7.3",
+    "pandas>=2.3.0",
+    "scikit-learn==1.6.1",
+    "syft-flwr>=0.1.5",
+    "torch==2.7.0",
+]

FedModelKit/templates/main_template.py

@@ -0,0 +1,27 @@
+import os
+from pathlib import Path
+
+from syft_core import Client
+
+from syft_flwr.config import load_flwr_pyproject
+from syft_flwr.run import syftbox_run_flwr_client, syftbox_run_flwr_server
+
+DATA_DIR = os.getenv("DATA_DIR")
+OUTPUT_DIR = os.getenv("OUTPUT_DIR")
+
+
+flower_project_dir = Path(__file__).parent.absolute()
+client = Client.load()
+config = load_flwr_pyproject(flower_project_dir)
+
+is_client = client.email in config["tool"]["syft_flwr"]["datasites"]
+is_server = client.email in config["tool"]["syft_flwr"]["aggregator"]
+
+if is_client:
+    # run by each DO
+    syftbox_run_flwr_client(flower_project_dir)
+elif is_server:
+    # run by the DS
+    syftbox_run_flwr_server(flower_project_dir)
+else:
+    raise ValueError(f"{client.email} is not in config.datasites or config.aggregator")

FedModelKit/templates/pyproject_template.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "EXPERIMENT_NAME"
+version = "1.0.0"
+description = "Description of the experiment"
+license = "Apache-2.0"
+dependencies = [    
+    "flwr[simulation]==1.17.0",
+    "flwr-datasets>=0.5.0",
+    "torch==2.7.0",
+    "imblearn",
+    "pandas",
+    "scikit-learn==1.6.1",
+    "loguru",
+    "jupyter",
+    "syft_flwr==0.1.5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    ".",
+]
+
+[tool.flwr.app]
+publisher = "OpenMined"
+
+[tool.flwr.app.components]
+serverapp = "EXPERIMENT_NAME.server_app:app"
+clientapp = "EXPERIMENT_NAME.client_app:app"
+
+[tool.flwr.app.config]
+num-server-rounds = 3
+partition-id = 0
+num-partitions = 1
+
+[tool.flwr.federations]
+default = "local-simulation"
+
+[tool.flwr.federations.local-simulation.options]
+num-supernodes = 2
+
+[tool.syft_flwr]
+app_name = "ds@openmined.org_fl-diabetes-prediction_1751887833"
+datasites = [
+    "do1@openmined.org",
+    "do2@openmined.org",
+]
+aggregator = "ds@openmined.org"

FedModelKit/templates/readme_template.md

@@ -0,0 +1,48 @@
+# Diabetes Prediction with `syft_flwr`
+
+## Introduction
+
+In this tutorial, we'll walk through a practical federated learning implementation for diabetes prediction using [syft_flwr](https://github.com/OpenMined/syft-flwr) — a framework that combines the flexibility of [Flower](https://github.com/adap/flower/) (a popular federated learning framework) with the privacy-preserving networking capabilities of [syftbox](https://www.syftbox.net/).
+
+![overview](./images/overview.png)
+
+Dataset: https://www.kaggle.com/datasets/uciml/pima-indians-diabetes-database/
+
+## Set up
+
+### Setup python virtual environment
+Assume that you have python and the [uv](https://docs.astral.sh/uv/) package manager installed. Now let's create a virtual python environment with all dependencies installed:
+```bash
+uv sync
+```
+
+### Install and run `syftbox` client
+Make sure you have syftbox client running in a terminal:
+1. Install `syftbox`: `curl -fsSL https://syftbox.net/install.sh | sh`
+2. Follow the instructions to start your `syftbox` client
+
+When you have `syftbox` installed and run in the background, you can proceeed and run the notebooks with the installed Python environment in your favorite IDE.
+
+### Local Setup
+At the start of the notebooks, you can set the flag `LOCAL_TEST` to `True` if you want to run all the clients (2 data owners and 1 data scientist) locally to test the whole workflow, where all clients' local datasites will be saved locally under the `flwr` folder. For this, you need to follow the running the notebooks `do1.ipynb`, `do2.ipynb`, then `ds.ipynb` in order.
+
+If running locally, you don't need your `syftbox client` running.
+
+
+### Distributed setup
+Set `LOCAL_TEST` to `False` and make sure you have your `syftbox` client running if you want to run the clients over the `syftbox` network.
+
+1. For the data scientist's workflow (prepare code, observe mock datasets on the data owner's datasites, submit jobs), please look into the `ds.ipynb` notebook. Following this notebook will help you submit jobs to two datasites named `flower-test-group-1@openmined.org` and `flower-test-group-2@openmined.org` that host 2 partitions of the `pima-indians-diabetes-database`, and they will approve your job automatically.
+
+Optionally, you can look at the `local_training.ipynb` to see the DS's process of processing data and training the neural network locally.
+
+2. For the data owner's workflow (uploading dataset, monitor and approve jobs), please take a look at `do.ipynb` notebook. Following this notebook, you will learn how to upload your partition of the `pima-indians-diabetes-database` so others can submit jobs to you.
+
+## References
+- https://syftbox.net
+- https://www.kaggle.com/datasets/uciml/pima-indians-diabetes-database/
+- https://github.com/OpenMined/syftbox
+- https://github.com/OpenMined/syft-flwr
+- https://github.com/adap/flower/
+- https://github.com/OpenMined/rds
+- https://github.com/elarsiad/diabetes-prediction-keras

FedModelKit/templates/server_app_template.py

@@ -0,0 +1,204 @@
+
+from typing import List
+import time
+
+import flwr as fl
+from flwr.common import (
+    Context,
+    NDArrays,
+    Message,
+    MessageType,
+    Metrics,
+    RecordSet,
+    ConfigsRecord,
+    DEFAULT_TTL,
+)
+from flwr.server import Driver
+
+import FedModelKit as msi
+
+from model_example import create_local_learner #type: ignore[import]
+
+
+# Run via `flower-server-app server:app`
+app = fl.server.ServerApp()
+
+
+
+
+@app.main()
+def main(driver: Driver, context: Context) -> None:
+    """
+    Main function to run the federated learning server.
+
+    Structure:
+    - Send a query message to clients for creating the local learner and loading the data
+    - Start global epochs loop for training and evaluation
+        - Send training messages to clients
+        - Aggregate parameters received from clients
+        - Send evaluation messages to clients
+        - Aggregate evaluation metrics
+    """
+    print("Starting test run")
+
+    # Get node IDs of connected clients
+    node_ids = driver.get_node_ids()
+
+    # Initialize the federated model
+    federated_model = msi.FederatedModel(create_local_learner=create_local_learner,
+                                        model_name='simple_lr')
+    global_model = federated_model.create_local_learner()
+    aggregation_strategy = federated_model.create_aggregator()
+
+    # Send a query message to clients for creating the local learner and loading the data
+    messages = []
+    for idx, node_id in enumerate(node_ids):
+        # Create messages to send to clients
+        recordset = RecordSet()
+
+        # Add a config with information to send the client for the query
+        recordset.configs_records["fancy_config"] = ConfigsRecord({"num_clients": len(node_ids), "client_id": idx})
+
+        # Create a query message for each client
+        message = driver.create_message(
+            content=recordset,
+            message_type=MessageType.QUERY,
+            dst_node_id=node_id,
+            group_id=str(1),
+            ttl=DEFAULT_TTL,
+        )
+        messages.append(message)
+
+    # Send training messages to clients
+    message_ids = driver.push_messages(messages)
+    print(f"Pushed {len(list(message_ids))} messages: {message_ids}")
+
+    # Wait for results from clients
+    message_ids = [message_id for message_id in message_ids if message_id != ""]
+    all_replies: List[Message] = []
+    while True:
+        replies = driver.pull_messages(message_ids=message_ids)
+        print(f"Got {len(list(replies))} results")
+        all_replies += replies
+        if len(all_replies) == len(message_ids):
+            break
+        time.sleep(12)
+
+    # Filter out messages with errors
+    all_replies = [
+        msg
+        for msg in all_replies
+        if msg.has_content()
+    ]
+    print(f"Received {len(all_replies)} answers")
+    
+
+    # Run federated training and evaluation for a fixed number of rounds
+    for server_round in range(3):
+        print(f"Commencing server train and evaluation round {server_round + 1}")
+
+        messages = []
+        for idx, node_id in enumerate(node_ids):
+            # Create messages to send to clients
+            recordset = RecordSet()
+
+            # Add model parameters to record
+            recordset.parameters_records["fancy_model"] = global_model.get_parameters()
+            # Add a config with information to send the client for training
+            recordset.configs_records["fancy_config"] = ConfigsRecord({"local_epochs": 3})
+
+            # Create a training message for each client
+            message = driver.create_message(
+                content=recordset,
+                message_type=MessageType.TRAIN,
+                dst_node_id=node_id,
+                group_id=str(server_round),
+                ttl=DEFAULT_TTL,
+            )
+            messages.append(message)
+
+        # Send training messages to clients
+        message_ids = driver.push_messages(messages)
+        print(f"Pushed {len(list(message_ids))} messages: {message_ids}")
+
+        # Wait for results from clients
+        message_ids = [message_id for message_id in message_ids if message_id != ""]
+        all_replies: List[Message] = []
+        while True:
+            replies = driver.pull_messages(message_ids=message_ids)
+            print(f"Got {len(list(replies))} results")
+            all_replies += replies
+            if len(all_replies) == len(message_ids):
+                break
+            time.sleep(12)
+
+        # Filter out messages with errors
+        all_replies = [
+            msg
+            for msg in all_replies
+            if msg.has_content()
+        ]
+        print(f"Received {len(all_replies)} results")
+
+        # Print metrics received from clients
+        for reply in all_replies:
+            print(reply.content.metrics_records)
+
+        # Aggregate parameters received from clients
+        parameter_records_list = [reply.content.parameters_records["fancy_model_returned"] for reply in all_replies]
+        new_parameter_record = aggregation_strategy.aggregate_parameters(parameter_records_list)
+        global_model.set_parameters(new_parameter_record)
+
+        # Evaluate the updated global model
+        messages = []
+        for idx, node_id in enumerate(node_ids):
+            # Create evaluation messages for clients
+            recordset = RecordSet()
+
+            # Add updated model parameters to record
+            recordset.parameters_records["fancy_model"] = new_parameter_record
+            # Add a config with information to send the client for evaluation
+            recordset.configs_records["fancy_config"] = ConfigsRecord({"local_epochs": 3})
+
+            # Create an evaluation message for each client
+            message = driver.create_message(
+                content=recordset,
+                message_type=MessageType.EVALUATE,
+                dst_node_id=node_id,
+                group_id=str(server_round),
+                ttl=DEFAULT_TTL,
+            )
+            messages.append(message)
+
+        # Send evaluation messages to clients
+        message_ids = driver.push_messages(messages)
+        print(f"Pushed {len(list(message_ids))} messages: {message_ids}")
+
+        # Wait for evaluation results from clients
+        message_ids = [message_id for message_id in message_ids if message_id != ""]
+        all_replies: List[Message] = []
+        while True:
+            replies = driver.pull_messages(message_ids=message_ids)
+            print(f"Got {len(list(replies))} results")
+            all_replies += replies
+            if len(all_replies) == len(message_ids):
+                break
+            time.sleep(3)
+
+        # Filter out messages with errors
+        all_replies = [
+            msg
+            for msg in all_replies
+            if msg.has_content()
+        ]
+        print(f"Received {len(all_replies)} results")
+
+        # Print evaluation metrics received from clients
+        metrics_records_list = [reply.content.metrics_records['eval_metrics'] for reply in all_replies]
+        for i, reply in enumerate(all_replies):
+            print(f"Client {i+1} metrics:   ", reply.content.metrics_records['eval_metrics'])
+
+        # Aggregate evaluation metrics
+        print("Aggregated metrics result:   ", aggregation_strategy.aggregate_metrics(metrics_records_list))
+    
+    print("🎉🎉🎉 Successfully completed federated learning run! 🎉🎉🎉")