Add descriptions and fix comments

app.py

@@ -44,23 +44,43 @@ with demo:
         """
     )
 
-    gr.Markdown("## Client side")
+    gr.Markdown("# Client side")
 
-    gr.Markdown("### Step 1: Generate the keys. ")
+    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 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.
+        """
+    )
     keygen_button = gr.Button("Generate the keys and send evaluation key to the server.")
     evaluation_key = gr.Textbox(
         label="Evaluation key representation:", max_lines=2, interactive=False
     )
     client_id = gr.Textbox(label="", max_lines=2, interactive=False, visible=False)
     
-    gr.Markdown("### Step 2: Infos. ")
+    gr.Markdown("## Step 2: Fill in some information.")
+    gr.Markdown(
+        """
+        Select any information that corresponds to the profile you want to evaluate. Three
+        dissociated parties are represented :
+        - the user, which provides some personal information in order to evaluate its credit card 
+        eligibility 
+        - the user's bank, which provides any of the user's banking information relevant to the 
+        decision
+        - a third party, which represents any other party (here, the user's employer) that could 
+        provide any information relevant to the decision
+        """
+    )
+
     with gr.Row():
         with gr.Column():
             gr.Markdown("### User")
             gender = gr.Radio(["Female", "Male"], label="Gender", value="Female")
             bool_inputs = gr.CheckboxGroup(["Car", "Property", "Work phone", "Phone", "Email"], label="What do you own ?")
             num_children = gr.Slider(**CHILDREN_MIN_MAX, step=1, label="Number of children", info="How many children do you have ?")
-            household_size = gr.Slider(**FAMILY_MIN_MAX, step=1, label="Household size", info="How many members does your family have? ?")
+            household_size = gr.Slider(**FAMILY_MIN_MAX, step=1, label="Household size", info="How many members does your household have? ?")
             total_income = gr.Slider(**INCOME_MIN_MAX, label="Income", info="What's you total yearly income (in euros) ?")
             age = gr.Slider(**AGE_MIN_MAX, step=1, label="Age", info="How old are you ?")
             income_type = gr.Dropdown(choices=INCOME_TYPES, value=INCOME_TYPES[0], label="Income type", info="What is your main type of income ?")
@@ -79,7 +99,7 @@ with demo:
             years_salaried = gr.Slider(**SALARIED_MIN_MAX, step=1, label="Years of employment", info="How long have this person been salaried (in years) ?")
 
 
-    gr.Markdown("### Step 3: Encrypt  using FHE and send the inputs to the server.")
+    gr.Markdown("## Step 3: Encrypt the inputs using FHE and send them to the server.")
     with gr.Row():
         with gr.Column():
             gr.Markdown("### User")
@@ -107,40 +127,50 @@ with demo:
                 label="Encrypted input representation:", max_lines=2, interactive=False
             )
 
-    gr.Markdown("## Server side")
+    gr.Markdown("# Server side")
     gr.Markdown(
-        "The encrypted values are received by the server. The server can then compute the prediction "
-        "directly over them. Once the computation is finished, the server returns "
-        "the encrypted result to the client."
+        """
+        Once the server receives the encrypted inputs, it can compute the prediction without ever 
+        needing to decrypt any value.
+
+        This server employs an [XGBoost](https://github.com/dmlc/xgboost) classifier model that has 
+        been trained on [this credit card data-set](https://www.kaggle.com/datasets/rikdifos/credit-card-approval-prediction/data).
+        """
     )
 
-    gr.Markdown("### Step 4: Run FHE execution.")
+    gr.Markdown("## Step 4: Run FHE execution.")
     execute_fhe_button = gr.Button("Run FHE execution.")
     fhe_execution_time = gr.Textbox(
         label="Total FHE execution time (in seconds):", max_lines=1, interactive=False
     )
 
-    gr.Markdown("## Client side")  
+    gr.Markdown("# Client side")  
     gr.Markdown(
-        "The encrypted output is sent back to the client, who can finally decrypt it with the "
-        "private key."
+        """
+        Once the server completed the inference, the encrypted output is returned to the user.
+        """
     )
 
-    gr.Markdown("### Step 5: Receive the encrypted output from the server.")
+    gr.Markdown("## Step 5: Receive the encrypted output from the server.")
     gr.Markdown(
-        "The output displayed here is the encrypted result sent by the server, which has been "
-        "decrypted using a different private key. This is only used to visually represent an "
-        "encrypted output."
+        """
+        The value displayed below is a shortened byte representation of the actual encrypted output.
+        """
     )
-    get_output_button = gr.Button("Receive the encrypted output from the server.")
 
+    get_output_button = gr.Button("Receive the encrypted output from the server.")
     encrypted_output_representation = gr.Textbox(
         label="Encrypted output representation: ", max_lines=2, interactive=False
     )
 
-    gr.Markdown("### Step 6: Decrypt the output.")
-    decrypt_button = gr.Button("Decrypt the output")
+    gr.Markdown("## Step 6: Decrypt the output.")
+    gr.Markdown(
+        """
+        The user is able to decrypt the prediction using its private key.
+        """
+    )
 
+    decrypt_button = gr.Button("Decrypt the output")
     prediction_output = gr.Textbox(
         label="Prediction", max_lines=1, interactive=False
     )

development.py

@@ -30,8 +30,8 @@ print("Load and pre-process the data")
 # https://www.kaggle.com/code/samuelcortinhas/credit-cards-data-cleaning
 # A few additional pre-processing steps has bee applied to this data set as well : 
 # - "ID" column has been removed 
-# - "Total_income" values have been multiplied by 0.14 to make its median value match France's 
-#   annual salary one from 2023 (in euros) 
+# - "Total_income" values have been multiplied by 0.14 to make its median match France's annual
+#    salary one from 2023 (in euros) 
 data = pandas.read_csv(DATA_PATH, encoding="utf-8")
 
 # Define input and target data

utils/pre_processing.py

@@ -1,4 +1,11 @@
-"""Data pre-processing functions."""
+"""Data pre-processing functions.
+
+The pre-processing steps are heavily inspired by the following notebook :
+https://www.kaggle.com/code/rikdifos/credit-card-approval-prediction-using-ml
+
+Additional steps, mostly including renaming some values or features, were added for better user 
+experience.
+"""
 
 import numpy
 from sklearn.compose import ColumnTransformer