Rename third party and improve collaboration comments

app.py

@@ -24,7 +24,7 @@ from backend import (
     keygen_send,
     pre_process_encrypt_send_user,
     pre_process_encrypt_send_bank,
-    pre_process_encrypt_send_third_party,
+    pre_process_encrypt_send_cs_agency,
     run_fhe,
     get_output_and_decrypt,
     explain_encrypt_run_decrypt,
@@ -61,12 +61,14 @@ with demo:
         """
     )
 
-    gr.Markdown("# Client side")
+    gr.Markdown("# Client, Bank and Credit Scoring Agency setup")
 
     gr.Markdown("## Step 1: Generate the keys.")
     gr.Markdown(
         """
-        - The private key is used to encrypt and decrypt the data and shall never be shared.
+        - The private key is generated jointly by the entities that collaborate to compute the 
+            credit score. It is used to encrypt and decrypt the data and shall never be shared with 
+            any other party.
         - The evaluation key is a public key that the server needs to process encrypted data. It is
         therefore transmitted to the server for further processing as well.
         """
@@ -91,7 +93,7 @@ with demo:
         - a user's personal information in order to evaluate his/her credit card eligibility;
         - the user’s bank account history, which provides any type of information on the user's 
         banking information relevant to the decision (here, we consider duration of account);
-        - and third party information, which represents any other information (here, employment 
+        - and credit scoring agency information, which represents any other information (here, employment 
         history) that could provide additional insight relevant to the decision.
         """
     )
@@ -187,7 +189,7 @@ with demo:
 
     with gr.Row():
         with gr.Column(scale=2):
-            gr.Markdown("### Third party ")
+            gr.Markdown("### Credit Scoring Agency ")
             employed = gr.Radio(["Yes", "No"], label="Is the person employed ?", value="Yes")
             years_employed = gr.Dropdown(
                 choices=YEARS_EMPLOYED_BINS, 
@@ -197,9 +199,9 @@ with demo:
             )
 
         with gr.Column():
-            encrypt_button_third_party = gr.Button("Encrypt the inputs and send to server.")
+            encrypt_button_cs_agency = gr.Button("Encrypt the inputs and send to server.")
 
-            encrypted_input_third_party = gr.Textbox(
+            encrypted_input_cs_agency = gr.Textbox(
                 label="Encrypted input representation:", max_lines=2, interactive=False
             )
 
@@ -220,12 +222,12 @@ with demo:
         outputs=[encrypted_input_bank],
     )
 
-    # Button to pre-process, generate the key, encrypt and send the third party inputs from the 
+    # Button to pre-process, generate the key, encrypt and send the credit scoring agency inputs from the 
     # client side to the server    
-    encrypt_button_third_party.click(
-        pre_process_encrypt_send_third_party,
+    encrypt_button_cs_agency.click(
+        pre_process_encrypt_send_cs_agency,
         inputs=[client_id, years_employed, employed],
-        outputs=[encrypted_input_third_party],
+        outputs=[encrypted_input_cs_agency],
     )
 
     gr.Markdown("# Server side")
@@ -248,10 +250,14 @@ with demo:
     # Button to send the encodings to the server using post method
     execute_fhe_button.click(run_fhe, inputs=[client_id], outputs=[fhe_execution_time])
 
-    gr.Markdown("# Client side")  
+    gr.Markdown("# Client, Bank and Credit Scoring Agency setup")  
     gr.Markdown(
         """
         Once the server completed the inference, the encrypted output is returned to the user.
+
+        The three entities that provide the information to compute the credit score are the only 
+        ones that can decrypt the result. They take part in a decryption protocol that allows to 
+        only decrypt the full result when all three parties decrypt their share of the result.
         """
     )
 

backend.py

@@ -20,11 +20,11 @@ from settings import (
     INPUT_SLICES,
     PRE_PROCESSOR_USER_PATH, 
     PRE_PROCESSOR_BANK_PATH,
-    PRE_PROCESSOR_THIRD_PARTY_PATH,
+    PRE_PROCESSOR_CS_AGENCY_PATH,
     CLIENT_TYPES,
     USER_COLUMNS,
     BANK_COLUMNS,
-    THIRD_PARTY_COLUMNS,
+    CS_AGENCY_COLUMNS,
     YEARS_EMPLOYED_BINS,
     YEARS_EMPLOYED_BIN_NAME_TO_INDEX,
 )
@@ -35,11 +35,11 @@ from utils.client_server_interface import MultiInputsFHEModelClient
 with (
     PRE_PROCESSOR_USER_PATH.open('rb') as file_user, 
     PRE_PROCESSOR_BANK_PATH.open('rb') as file_bank,
-    PRE_PROCESSOR_THIRD_PARTY_PATH.open('rb') as file_third_party,
+    PRE_PROCESSOR_CS_AGENCY_PATH.open('rb') as file_cs_agency,
 ):
     PRE_PROCESSOR_USER = pickle.load(file_user)
     PRE_PROCESSOR_BANK = pickle.load(file_bank)
-    PRE_PROCESSOR_THIRD_PARTY = pickle.load(file_third_party)
+    PRE_PROCESSOR_CS_AGENCY = pickle.load(file_cs_agency)
 
 
 def shorten_bytes_object(bytes_object, limit=500):
@@ -111,7 +111,7 @@ def _get_client_file_path(name, client_id, client_type=None):
             'encrypted_outputs').
         client_id (int): The client ID to consider.
         client_type (Optional[str]): The type of user to consider (either 'user', 'bank', 
-            'third_party' or None). Default to None, which is used for evaluation key and output.
+            'cs_agency' or None). Default to None, which is used for evaluation key and output.
 
     Returns:
         pathlib.Path: The file path.
@@ -132,7 +132,7 @@ def _send_to_server(client_id, client_type, file_name):
     Args:
         client_id (int): The client ID to consider.
         client_type (Optional[str]): The type of client to consider (either 'user', 'bank', 
-            'third_party' or None).
+            'cs_agency' or None).
         file_name (str): File name to send (either 'evaluation_key' or 'encrypted_inputs').
     """
     # Get the paths to the encrypted inputs
@@ -204,7 +204,7 @@ def _encrypt_send(client_id, inputs, client_type):
     Args:
         client_id (str): The current client ID to consider.
         inputs (numpy.ndarray): The inputs to encrypt.
-        client_type (str): The type of client to consider (either 'user', 'bank' or 'third_party').
+        client_type (str): The type of client to consider (either 'user', 'bank' or 'cs_agency').
     
     Returns:
         encrypted_inputs_short (str): A short representation of the encrypted input to send in hex. 
@@ -303,8 +303,8 @@ def pre_process_encrypt_send_bank(client_id, *inputs):
     return _encrypt_send(client_id, preprocessed_bank_inputs, "bank")
 
 
-def pre_process_encrypt_send_third_party(client_id, *inputs):
-    """Pre-process, encrypt and send the third party inputs for a specific client to the server.
+def pre_process_encrypt_send_cs_agency(client_id, *inputs):
+    """Pre-process, encrypt and send the credit scoring agency inputs for a specific client to the server.
 
     Args:
         client_id (str): The current client ID to consider.
@@ -318,15 +318,15 @@ def pre_process_encrypt_send_third_party(client_id, *inputs):
     years_employed = YEARS_EMPLOYED_BIN_NAME_TO_INDEX[years_employed_bin]
     is_employed = employed == "Yes"
 
-    third_party_inputs = pandas.DataFrame({
+    cs_agency_inputs = pandas.DataFrame({
         "Years_employed": [years_employed],
         "Employed": [is_employed],
     })
 
-    third_party_inputs = third_party_inputs.reindex(THIRD_PARTY_COLUMNS, axis=1)
-    preprocessed_third_party_inputs = PRE_PROCESSOR_THIRD_PARTY.transform(third_party_inputs)
+    cs_agency_inputs = cs_agency_inputs.reindex(CS_AGENCY_COLUMNS, axis=1)
+    preprocessed_cs_agency_inputs = PRE_PROCESSOR_CS_AGENCY.transform(cs_agency_inputs)
 
-    return _encrypt_send(client_id, preprocessed_third_party_inputs, "third_party")
+    return _encrypt_send(client_id, preprocessed_cs_agency_inputs, "cs_agency")
 
 
 def run_fhe(client_id):
@@ -423,7 +423,7 @@ def explain_encrypt_run_decrypt(client_id, prediction_output, *inputs):
             "Explaining the prediction can only be done if the credit card is likely to be denied."
         )
 
-    # Retrieve the third party inputs
+    # Retrieve the credit scoring agency inputs
     years_employed, employed = inputs
 
     # Years_employed is divided into several ordered bins. Here, we retrieve the index representing 
@@ -441,7 +441,7 @@ def explain_encrypt_run_decrypt(client_id, prediction_output, *inputs):
         for years_employed_bin in YEARS_EMPLOYED_BINS[bin_index+1:]:
             
             # Send the new encrypted input
-            pre_process_encrypt_send_third_party(client_id, years_employed_bin, employed)
+            pre_process_encrypt_send_cs_agency(client_id, years_employed_bin, employed)
 
             # Run the model in FHE
             run_fhe(client_id)
@@ -452,9 +452,9 @@ def explain_encrypt_run_decrypt(client_id, prediction_output, *inputs):
             is_approved = "approved" in output_prediction[0]
             output_predictions.append(is_approved)
         
-        # Re-send the initial third party inputs in order to avoid unwanted conflict (as sending
+        # Re-send the initial credit scoring agency inputs in order to avoid unwanted conflict (as sending
         # some inputs basically re-writes the associated file on the server side)
-        pre_process_encrypt_send_third_party(client_id, years_employed, employed)
+        pre_process_encrypt_send_cs_agency(client_id, years_employed, employed)
         
         # In case the model predicted at least one approval
         if any(output_predictions):

development.py

@@ -11,10 +11,10 @@ from settings import (
     INPUT_SLICES, 
     PRE_PROCESSOR_USER_PATH, 
     PRE_PROCESSOR_BANK_PATH,
-    PRE_PROCESSOR_THIRD_PARTY_PATH,
+    PRE_PROCESSOR_CS_AGENCY_PATH,
     USER_COLUMNS,
     BANK_COLUMNS,
-    THIRD_PARTY_COLUMNS,
+    CS_AGENCY_COLUMNS,
 )
 from utils.client_server_interface import MultiInputsFHEModelDev
 from utils.model import MultiInputDecisionTreeClassifier, MultiInputDecisionTreeRegressor
@@ -33,7 +33,7 @@ def get_multi_inputs(data):
     return (
         data[:, INPUT_SLICES["user"]], 
         data[:, INPUT_SLICES["bank"]], 
-        data[:, INPUT_SLICES["third_party"]]
+        data[:, INPUT_SLICES["cs_agency"]]
     )
 
 
@@ -49,16 +49,16 @@ data_y = data_x.pop("Target").copy().to_frame()
 # Get data from all parties
 data_user = data_x[USER_COLUMNS].copy()
 data_bank = data_x[BANK_COLUMNS].copy()
-data_third_party = data_x[THIRD_PARTY_COLUMNS].copy()
+data_cs_agency = data_x[CS_AGENCY_COLUMNS].copy()
 
 # Feature engineer the data
-pre_processor_user, pre_processor_bank, pre_processor_third_party = get_pre_processors()
+pre_processor_user, pre_processor_bank, pre_processor_cs_agency = get_pre_processors()
 
 preprocessed_data_user = pre_processor_user.fit_transform(data_user)
 preprocessed_data_bank = pre_processor_bank.fit_transform(data_bank)
-preprocessed_data_third_party = pre_processor_third_party.fit_transform(data_third_party)
+preprocessed_data_cs_agency = pre_processor_cs_agency.fit_transform(data_cs_agency)
 
-preprocessed_data_x = numpy.concatenate((preprocessed_data_user, preprocessed_data_bank, preprocessed_data_third_party), axis=1)
+preprocessed_data_x = numpy.concatenate((preprocessed_data_user, preprocessed_data_bank, preprocessed_data_cs_agency), axis=1)
 
 
 print("\nTrain and compile the model")
@@ -85,10 +85,10 @@ fhe_model_dev.save(via_mlir=True)
 with (
     PRE_PROCESSOR_USER_PATH.open('wb') as file_user, 
     PRE_PROCESSOR_BANK_PATH.open('wb') as file_bank,
-    PRE_PROCESSOR_THIRD_PARTY_PATH.open('wb') as file_third_party,
+    PRE_PROCESSOR_CS_AGENCY_PATH.open('wb') as file_cs_agency,
 ):
     pickle.dump(pre_processor_user, file_user)
     pickle.dump(pre_processor_bank, file_bank)
-    pickle.dump(pre_processor_third_party, file_third_party)
+    pickle.dump(pre_processor_cs_agency, file_cs_agency)
 
 print("\nDone !")

server.py

@@ -20,7 +20,7 @@ def _get_server_file_path(name, client_id, client_type=None):
             'encrypted_outputs').
         client_id (int): The client ID to consider.
         client_type (Optional[str]): The type of user to consider (either 'user', 'bank', 
-            'third_party' or None). Default to None, which is used for evaluation key and output.
+            'cs_agency' or None). Default to None, which is used for evaluation key and output.
 
     Returns:
         pathlib.Path: The file path.

settings.py

@@ -18,7 +18,7 @@ DEPLOYMENT_PATH = DEPLOYMENT_PATH / "model"
 # Path targeting pre-processor saved files
 PRE_PROCESSOR_USER_PATH = DEPLOYMENT_PATH / 'pre_processor_user.pkl'
 PRE_PROCESSOR_BANK_PATH = DEPLOYMENT_PATH / 'pre_processor_bank.pkl'
-PRE_PROCESSOR_THIRD_PARTY_PATH = DEPLOYMENT_PATH / 'pre_processor_third_party.pkl'
+PRE_PROCESSOR_CS_AGENCY_PATH = DEPLOYMENT_PATH / 'pre_processor_cs_agency.pkl'
 
 # Create the necessary directories
 FHE_KEYS.mkdir(exist_ok=True)
@@ -34,16 +34,16 @@ DATA_PATH = "data/data.csv"
 # Development settings
 PROCESSED_INPUT_SHAPE = (1, 39)
 
-CLIENT_TYPES = ["user", "bank", "third_party"]
+CLIENT_TYPES = ["user", "bank", "cs_agency"]
 INPUT_INDEXES = {
     "user": 0,
     "bank": 1,
-    "third_party": 2,
+    "cs_agency": 2,
 }
 INPUT_SLICES = {
     "user": slice(0, 36),  # First position: start from 0
     "bank": slice(36, 37),  # Second position: start from n_feature_user
-    "third_party": slice(37, 39),  # Third position: start from n_feature_user + n_feature_bank
+    "cs_agency": slice(37, 39),  # Third position: start from n_feature_user + n_feature_bank
 }
 
 # Fix column order for pre-processing steps
@@ -53,7 +53,7 @@ USER_COLUMNS = [
     'Occupation_type',
 ]
 BANK_COLUMNS = ["Account_age"]
-THIRD_PARTY_COLUMNS = ["Years_employed", "Employed"]
+CS_AGENCY_COLUMNS = ["Years_employed", "Employed"]
 
 _data = pandas.read_csv(DATA_PATH, encoding="utf-8")
 

utils/client_server_interface.py

@@ -47,7 +47,7 @@ class MultiInputsFHEModelClient(FHEModelClient):
             x (numpy.ndarray): The input to consider. Here, the input should only represent a
                 single party.
             input_index (int): The index representing the type of model (0: "user", 1: "bank", 
-                2: "third_party")
+                2: "cs_agency")
             processed_input_shape (Tuple[int]): The total input shape (all parties combined) after
                 pre-processing.
             input_slice (slice): The slices to consider for the given party.

utils/pre_processing.py

@@ -55,10 +55,10 @@ def get_pre_processors():
         verbose_feature_names_out=False,
     )
 
-    pre_processor_third_party = ColumnTransformer(
+    pre_processor_cs_agency = ColumnTransformer(
         transformers=[],
         remainder='passthrough',
         verbose_feature_names_out=False,
     )
 
-    return pre_processor_user, pre_processor_bank, pre_processor_third_party
+    return pre_processor_user, pre_processor_bank, pre_processor_cs_agency