chore: adding an example from our template with a NeuralNetClassifier.

README.md

@@ -1,3 +1,47 @@
 ---
 license: apache-2.0
 ---
+
+# Template for Concrete ML
+
+Concrete ML is Zama's open-source privacy-preserving ML package, based on fully homomorphic encryption (FHE). We refer the reader to fhe.org or Zama's websites for more information on FHE.
+
+This directory is used:
+- by ML practicioners, to create Concrete ML FHE-friendly models, and make them available to HF users
+- by companies, institutions or people to deploy those models over HF inference endpoints
+- by developers, to use these entry points to make applications on privacy-preserving ML
+
+## Creating models and making them available on HF
+
+This is quite easy. Fork this template (maybe use this experimental tool https://huggingface.co/spaces/huggingface-projects/repo_duplicator for that), and then:
+- install everything with: `pip install -r requirements.txt`
+- edit `creating_models.py`, and fill the part between "# BEGIN: insert your ML task here" and
+"# END: insert your ML task here"
+- run the python file: `python creating_models.py`
+
+At the end, if the script is successful, you'll have your compiled model ready in `compiled_model`. Now you can commit and push your repository (with in particular `compiled_model`, `handler.py`, `play_with_endpoint.py` and `requirements.txt`, but you can include the other files as well).
+
+We recommend you to tag your Concrete ML compiled repository with `Concrete ML FHE friendly` tag, such that people can find them easily.
+
+## Deploying a compiled model on HF inference endpoint
+
+If you find an `Concrete ML FHE friendly` repository that you would like to deploy, it is very easy.
+- click on 'Deploy' button in HF interface
+- chose "Inference endpoints"
+- chose the right model repository
+- (the rest of the options are classical to HF end points; we refer you to their documentation for more information)
+and then click on 'Create endpoint'
+
+And now, your model should be deployed, after few secunds of installation.
+
+## Using HF entry points on privacy-preserving models
+
+Now, this is the final step: using the entry point. You should:
+- if your inference endpoint is private, set an environment variable HF_TOKEN with your HF token
+- edit `play_with_endpoint.py`
+- replace `API_URL` by your entry point URL
+- replace the part between "# BEGIN: replace this part with your privacy-preserving application" and
+"# END: replace this part with your privacy-preserving application" with your application
+
+Finally, you'll be able to launch your application with `python play_with_endpoint.py`.
+

compiled_model/client.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52473c839cbf2951945693fb255e48214c888e8e6ef513c3a06ccf866bc66aa4
+size 3403

compiled_model/server.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:697fe8a7e1a6c5133dd29553c7f90457f4c2a388888051654e84d189d01fc9f4
+size 1781

compiled_model/versions.json

@@ -0,0 +1 @@
+{"concrete-python": "2.5.0rc1", "concrete-ml": "1.3.0", "python": "3.9.15"}

creating_models.py

@@ -0,0 +1,74 @@
+import shutil
+import sys
+from pathlib import Path
+
+from concrete.ml.deployment import FHEModelDev
+from concrete.ml.deployment import FHEModelClient
+
+
+def compile_and_make_it_deployable(model_dev, X_train):
+
+    path_to_model = Path("compiled_model")
+
+    # Compile into FHE
+    model_dev.compile(X_train)
+
+    # Saving the model
+    shutil.rmtree(path_to_model, ignore_errors=True)
+    fhemodel_dev = FHEModelDev(path_to_model, model_dev)
+    fhemodel_dev.save(via_mlir=True)
+
+    # To see the size of the key
+    fhemodel_client = FHEModelClient(path_to_model)
+
+    # Generate the keys
+    fhemodel_client.generate_private_and_evaluation_keys()
+    evaluation_keys = fhemodel_client.get_serialized_evaluation_keys()
+
+    print(f"Your keys will be {sys.getsizeof(evaluation_keys) / 1024 / 1024}-megabytes long")
+
+    # Check accuracy with p_error
+    y_pred_simulated = model_dev.predict(X_test, fhe="simulate")
+    simulated_accuracy = accuracy_score(Y_test, y_pred_simulated)
+
+    print(f"Concrete average precision score (simulate): {simulated_accuracy:0.2f}")
+
+
+# BEGIN: insert your ML task here
+# Typically
+from concrete.ml.sklearn import NeuralNetClassifier
+from sklearn.metrics import accuracy_score
+from sklearn.model_selection import train_test_split
+from sklearn.datasets import load_iris
+from torch import nn
+
+# Get iris data-set
+X, y = load_iris(return_X_y=True)
+
+# Split into train and test
+X_train, X_test, Y_train, Y_test = train_test_split(X, y, test_size=0.25, random_state=42)
+
+# Scikit-Learn and Concrete ML neural networks only handle float32 input values
+X_train, X_test = X_train.astype("float32"), X_test.astype("float32")
+
+params = {
+    "module__n_layers": 3,
+    "module__activation_function": nn.ReLU,
+    "max_epochs": 1000,
+    "verbose": 0,
+}
+
+model_dev = NeuralNetClassifier(**params)
+
+model_dev = model_dev.fit(X=X_train, y=Y_train)
+
+# Evaluate the Concrete ML model in the clear
+y_pred_simulated = model_dev.predict(X_test)
+
+simulated_accuracy = accuracy_score(Y_test, y_pred_simulated)
+print(f"The test accuracy of the trained Concrete ML simulated model is {simulated_accuracy:.2f}")
+
+# END: insert your ML task here
+
+compile_and_make_it_deployable(model_dev, X_train)
+print("Your model is ready to be deployable.")

handler.py

@@ -0,0 +1,71 @@
+from typing import Dict, List, Any
+import numpy as np
+from concrete.ml.deployment import FHEModelServer
+
+
+def from_json(python_object):
+    if "__class__" in python_object:
+        return bytes(python_object["__value__"])
+
+
+def to_json(python_object):
+    if isinstance(python_object, bytes):
+        return {"__class__": "bytes", "__value__": list(python_object)}
+    raise TypeError(repr(python_object) + " is not JSON serializable")
+
+
+class EndpointHandler:
+    def __init__(self, path=""):
+
+        # For server
+        self.fhemodel_server = FHEModelServer(path + "/compiled_model")
+
+        # Simulate a database of keys
+        self.key_database = {}
+
+    def __call__(self, data: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """
+         data args:
+              inputs (:obj: `str`)
+              date (:obj: `str`)
+        Return:
+              A :obj:`list` | `dict`: will be serialized and returned
+        """
+
+        # Get method
+        method = data.pop("method", data)
+
+        if method == "save_key":
+
+            # Get keys
+            evaluation_keys = from_json(data.pop("evaluation_keys", data))
+
+            uid = np.random.randint(2**32)
+
+            while uid in self.key_database.keys():
+                uid = np.random.randint(2**32)
+
+            self.key_database[uid] = evaluation_keys
+
+            return {"uid": uid}
+
+        elif method == "inference":
+
+            uid = data.pop("uid", data)
+
+            assert uid in self.key_database.keys(), f"{uid} not in DB, {self.key_database.keys()=}"
+
+            # Get inputs
+            encrypted_inputs = from_json(data.pop("encrypted_inputs", data))
+
+            # Find key in the database
+            evaluation_keys = self.key_database[uid]
+
+            # Run CML prediction
+            encrypted_prediction = self.fhemodel_server.run(encrypted_inputs, evaluation_keys)
+
+            return to_json(encrypted_prediction)
+
+        else:
+
+            return

play_with_endpoint.py

@@ -0,0 +1,115 @@
+import numpy as np
+import time
+import os, sys
+
+from pathlib import Path
+
+from concrete.ml.deployment import FHEModelClient
+
+import requests
+
+
+def to_json(python_object):
+    if isinstance(python_object, bytes):
+        return {"__class__": "bytes", "__value__": list(python_object)}
+    raise TypeError(repr(python_object) + " is not JSON serializable")
+
+
+def from_json(python_object):
+    if "__class__" in python_object:
+        return bytes(python_object["__value__"])
+
+
+# TODO: put the right link `API_URL` for your entryp point
+API_URL = "https://XXXXXXX.us-east-1.aws.endpoints.huggingface.cloud"
+headers = {
+    "Authorization": "Bearer " + os.environ.get("HF_TOKEN"),
+    "Content-Type": "application/json",
+}
+
+
+def query(payload):
+    response = requests.post(API_URL, headers=headers, json=payload)
+
+    if "error" in response:
+        assert False, f"Got an error: {response=}"
+
+    return response.json()
+
+
+path_to_model = Path("compiled_model")
+
+# BEGIN: replace this part with your privacy-preserving application
+from sklearn.datasets import make_classification
+from sklearn.model_selection import train_test_split
+
+x, y = make_classification(n_samples=1000, class_sep=2, n_features=30, random_state=42)
+_, X_test, _, Y_test = train_test_split(x, y, test_size=0.2, random_state=42)
+
+# Recover parameters for client side
+fhemodel_client = FHEModelClient(path_to_model)
+
+# Generate the keys
+fhemodel_client.generate_private_and_evaluation_keys()
+evaluation_keys = fhemodel_client.get_serialized_evaluation_keys()
+
+# Save the key in the database
+payload = {
+    "inputs": "fake",
+    "evaluation_keys": to_json(evaluation_keys),
+    "method": "save_key",
+}
+
+uid = query(payload)["uid"]
+print(f"Storing the key in the database under {uid=}")
+
+# Test the handler
+nb_good = 0
+nb_samples = len(X_test)
+verbose = True
+time_start = time.time()
+duration = 0
+is_first = True
+
+for i in range(nb_samples):
+
+    # Quantize the input and encrypt it
+    encrypted_inputs = fhemodel_client.quantize_encrypt_serialize([X_test[i]])
+
+    # Prepare the payload
+    payload = {
+        "inputs": "fake",
+        "encrypted_inputs": to_json(encrypted_inputs),
+        "method": "inference",
+        "uid": uid,
+    }
+
+    if is_first:
+        print(f"Size of the payload: {sys.getsizeof(payload) / 1024} kilobytes")
+        is_first = False
+
+    # Run the inference on HF servers
+    duration -= time.time()
+    duration_inference = -time.time()
+    encrypted_prediction = query(payload)
+    duration += time.time()
+    duration_inference += time.time()
+
+    encrypted_prediction = from_json(encrypted_prediction)
+
+    # Decrypt the result and dequantize
+    prediction_proba = fhemodel_client.deserialize_decrypt_dequantize(encrypted_prediction)[0]
+    prediction = np.argmax(prediction_proba)
+
+    if verbose:
+        print(
+            f"for {i}-th input, {prediction=} with expected {Y_test[i]} in {duration_inference:.3f} seconds"
+        )
+
+    # Measure accuracy
+    nb_good += Y_test[i] == prediction
+
+print(f"Accuracy on {nb_samples} samples is {nb_good * 1. / nb_samples}")
+print(f"Total time: {time.time() - time_start:.3f} seconds")
+print(f"Duration per inference: {duration / nb_samples:.3f} seconds")
+# END: replace this part with your privacy-preserving application

requirements.txt

@@ -0,0 +1 @@
+concrete-ml==1.3.0