SwiftSyft

SwiftSyft makes it easy for you to train and inference PySyft models on iOS devices. This allows you to utilize training data located directly on the device itself, bypassing the need to send a user's data to a central server. This is known as federated learning.

⚙️ Training and inference of any PySyft model written in PyTorch or TensorFlow
👤 Allows all data to stay on the user's device
🔙 Support for delegation to background task scheduler
🔑 Support for JWT authentication to protect models from Sybil attacks
👍 Host of inbuilt best practices to prevent apps from over using device resources.
- 🔌 Charge detection to allow background training only when device is connected to charger
- 💤 Sleep and wake detection so that the app does not occupy resource when user starts using the device
- 💸 Wifi and metered network detection to ensure the model updates do not use all the available data quota
- 🔕 All of these smart defaults are easily are overridable
:mortarboard: Support for both reactive and callback patterns so you have your freedom of choice (_in progress)
🔒 Support for secure multi-party computation and secure aggregation protocols using peer-to-peer WebRTC connections (in progress).

There are a variety of additional privacy-preserving protections that may be applied, including differential privacy, muliti-party computation, and secure aggregation.

OpenMined set out to build the world's first open-source ecosystem for federated learning on web and mobile. SwiftSyft is a part of this ecosystem, responsible for bringing secure federated learning to iOS devices. You may also train models on Android devices using KotlinSyft or in web browsers using syft.js.

If you want to know how scalable federated systems are built, Towards Federated Learning at Scale is a fantastic introduction!

Installation

Cocoapods

Cocoapods is a dependency manager for Cocoa projects. Just add OpenMinedSwiftSyft to your Podfile like below:

pod 'OpenMinedSwiftSyft', ~> 0.1.3-beta1

Quick Start

As a developer, there are few steps to building your own secure federated learning system upon the OpenMined infrastructure:

🤖 Generate your secure ML model using PySyft. By design, PySyft is built upon PyTorch and TensorFlow so you don't need to learn a new ML framework. You will also need to write a training plan (training code the worker runs) and an averaging plan (code that PyGrid runs to average the model diff).
🌎 Host your model and plans on PyGrid which will deal with all the federated learning components of your pipeline. You will need to set up a PyGrid server somewhere, please see their installation instructions on how to do this.
🎉 Start training on the device!

📓 The entire workflow and process is described in greater detail in our project roadmap.

You can use SwiftSyft as a front-end or as a background service. The following is a quick start example usage:

// This is a demonstration of how to use SwiftSyft with PyGrid to train a plan on local data on an iOS device

// Authentication token
let authToken = /* Get auth token from somewhere (if auth is required): */

// Create a client with a PyGrid server URL
if let syftClient = SyftClient(url: URL(string: "ws://127.0.0.1:5000")!, authToken: authToken) {

  // Store the client as a property so it doesn't get deallocated during training.
  self.syftClient = syftClient

  // Create a new federated learning job with the model name and version
  self.syftJob = syftClient.newJob(modelName: "mnist", version: "1.0.0")

  // This function is called when SwiftSyft has downloaded the plans and model parameters from PyGrid
  // You are ready to train your model on your data
  // plan - Use this to generate diffs using our training data
  // clientConfig - contains the configuration for the training cycle (batchSize, learning rate) and
  // metadata for the model (name, version)
  // modelReport - Used as a completion block and reports the diffs to PyGrid.
  self.syftJob?.onReady(execute: { plan, clientConfig, modelReport in

    do {

        // This returns a lazily evaluated sequence for each MNIST image and the corresponding label
        // It divides the training data and the label by batches
        let (mnistData, labels) = try MNISTLoader.load(setType: .train, batchSize: clientConfig.batchSize)

        // Iterate through each batch of MNIST data and label
        for case let (batchData, labels) in zip(mnistData, labels) {

            // We need to create an autorelease pool to release the training data from memory after each loop
            try autoreleasepool {

                // Preprocess MNIST data by flattening all of the MNIST batch data as a single array
                let flattenedBatch = MNISTLoader.flattenMNISTData(batchData)
                // Preprocess the label ( 0 to 9 ) by creating one-hot features and then flattening the entire thing
                let oneHotLabels = MNISTLoader.oneHotMNISTLabels(labels: labels).compactMap { Float($0)}

                // Since we don't have native tensor wrappers in Swift yet, we use
                // `TrainingData` and `ValidationData` classes to store the data and shape.
                let trainingData = try TrainingData(data: flattenedBatch, shape: [clientConfig.batchSize, 784])
                let validationData = try ValidationData(data: oneHotLabels, shape: [clientConfig.batchSize, 10])

                // Execute the plan with the training data and validation data. `plan.execute()`
                // returns the loss and you can use it if you want to (plan.execute()
                // has the @discardableResult attribute)
                let loss = plan.execute(trainingData: trainingData,
                                      validationData: validationData,
                                        clientConfig: clientConfig)

            }

        }

        // Generate diff data and report the final diffs as
        let diffStateData = try plan.generateDiffData()
        modelReport(diffStateData)

    } catch let error {
        // Handle any error from the training cycle
        debugPrint(error.localizedDescription)
    }

  })

  // This is the error handler for any job exeuction errors like connecting to PyGrid
  self.syftJob?.onError(execute: { error in
    print(error)
  })

  // This is the error handler for being rejected in a cycle. You can retry again
  // after the suggested timeout.
  self.syftJob?.onRejected(execute: { timeout in
      if let timeout = timeout {
          // Retry again after timeout
          print(timeout)
      }
  })

  // Start the job. You can set that the job should only execute if the device is being charge and there is
  // a WiFi connection. These options are on by default if you don't specify them.
  self.syftJob?.start(chargeDetection: true, wifiDetection: true)
}

API Documenation

See API Documenation for complete reference.

Running in the background

A mini tutorial on how to run SwiftSyft on iOS using the background task scheduler can be found here

Running the Demo App

The demo app fetches the plans, protocols and model weights from PyGrid server hosted locally. The plans are then deserialized and executed using libtorch.

Follow these steps to setup an environment to run the demo app:

Clone the repo PyGrid and change directory to it

git clone https://github.com/OpenMined/PyGrid
cd PyGrid

Install docker
Install docker-compose.
Execute docker-compose in the command line to start pygrid server.

docker-compose up

Install PySyft from source in the virtual environment.

virtualenv -p python3 venv
source venv/bin/activate
python setup.py install

Make virtual environment available for Jupyter Notebook

python -m ipykernel install --user --name=venv

Host Jupyter Notebook

jupyter notebook

Open a browser and navigate to localhost:8888. You should be able to see the PySyft notebook console.
In the Jupyter Notebook, navigate to examples/model-centric
Run the notebook 01-Create-plan with the venv kernel. Now PyGrid is setup and the model is hosted over it.

syft.base_url="<IP_address_from_step_16>:5000"

Set-up demo project using Cocoapods
Install Cocoapods

gem install cocoapods

Install the dependencies of the project.

pod install # On the root directory of this project

Open the file SwiftSyft.xcworkspace in Xcode.
Run the SwiftSyft project. It automatically uses 127.0.0.1:5000 as the PyGrid URL.

Contributing

Set-up

You can work on the project by running pod install in the root directory. Then open the file SwiftSyft.xcworkspace in Xcode. When the project is open on Xcode, you can work on the SwiftSyft pod itself in Pods/Development Pods/SwiftSyft/Classes/*

Workflow

Star, for and clone the repo
Open the project in Xcode
Check out current issues and Github. For newcomers, check out issues labeled Good first issue
Do your work
Push your fork
Submit a PR to OpenMined/SwiftSyft

Read the contribution guide as a good starting place.

Support

For support in using this library, please join the #lib_swift_syft Slack channel. If you'd like to follow along with any code changes to the library, please join #code_swiftsyft Slack channel. Click here to join our Slack Community!