chore: updating documentation

.gitignore

@@ -2,4 +2,3 @@
 __pycache__/
 /start-venv.sh
 /components/iframe/dist/
-/components/

README.md

@@ -80,6 +80,7 @@ This project is licensed under the MIT License, see [LICENSE](LICENSE.md) for mo
 - University: HTW Berlin
 
 See code for in detailed credits, work is strongly based on:
+
 #### GODEL
 - [HGF Model Page](https://huggingface.co/microsoft/GODEL-v1_1-large-seq2seq?text=Hey+my+name+is+Mariama%21+How+are+you%3F)
 - [Paper on HGF](https://huggingface.co/papers/2206.11309)
@@ -88,3 +89,7 @@ See code for in detailed credits, work is strongly based on:
 #### SHAP
 - [Github](https://github.com/shap/shap)
 - [Inital Paper](https://arxiv.org/abs/1705.07874)
+
+#### Custom Component (/components/iframe/)
+
+Is based on Gradio component, see indivdual README for full changelog.

__init__.py

@@ -1,2 +1 @@
-# empty init file for the package
-# for fastapi to recognize the module
+# empty init file for the module

backend/__init__.py

@@ -1,2 +1 @@
-# empty init file for the package
-# for fastapi to recognize the module
+# empty init file for the modules

backend/controller.py

@@ -1,15 +1,16 @@
 # controller for the application that calls the model and explanation functions
-# and returns the updated conversation history
+# returns the updated conversation history and extra elements
 
 # external imports
 import gradio as gr
 
 # internal imports
 from model import godel
-from explanation import interpret_shap as sint, visualize as viz
+from explanation import interpret_shap as shap_int, visualize as viz
 
 
 # main interference function that that calls chat functions depending on selections
+# is getting called on every chat submit
 def interference(
     prompt: str,
     history: list,
@@ -17,18 +18,19 @@ def interference(
     system_prompt: str,
     xai_selection: str,
 ):
-    # if no system prompt is given, use a default one
-    if system_prompt == "":
+    # if no proper system prompt is given, use a default one
+    if system_prompt in ('', ' '):
         system_prompt = """
             You are a helpful, respectful and honest assistant.
             Always answer as helpfully as possible, while being safe.
         """
 
-    # if a XAI approach is selected, grab the XAI instance
+    # if a XAI approach is selected, grab the XAI module instance
     if xai_selection in ("SHAP", "Attention"):
+        # matching selection
         match xai_selection.lower():
             case "shap":
-                xai = sint
+                xai = shap_int
             case "attention":
                 xai = viz
             case _:
@@ -37,9 +39,10 @@ def interference(
                     There was an error in the selected XAI Approach.
                     It is "{xai_selection}"
                     """)
+                # raise runtime exception
                 raise RuntimeError("There was an error in the selected XAI approach.")
 
-        # call the explained chat function
+        # call the explained chat function with the model instance
         prompt_output, history_output, xai_graphic, xai_markup = explained_chat(
             model=godel,
             xai=xai,
@@ -48,7 +51,7 @@ def interference(
             system_prompt=system_prompt,
             knowledge=knowledge,
         )
-    # if no (or invalid) XAI approach is selected call the vanilla chat function
+    # if no XAI approach is selected call the vanilla chat function
     else:
         # call the vanilla chat function
         prompt_output, history_output = vanilla_chat(
@@ -78,12 +81,12 @@ def vanilla_chat(
 ):
     # formatting the prompt using the model's format_prompt function
     prompt = model.format_prompt(message, history, system_prompt, knowledge)
+
     # generating an answer using the model's respond function
     answer = model.respond(prompt)
 
     # updating the chat history with the new answer
     history.append((message, answer))
-
     # returning the updated history
     return "", history
 
@@ -94,7 +97,7 @@ def explained_chat(
     # formatting the prompt using the model's format_prompt function
     prompt = model.format_prompt(message, history, system_prompt, knowledge)
 
-    # generating an answer using the xai methods explain and respond function
+    # generating an answer using the methods chat function
     answer, xai_graphic, xai_markup = xai.chat_explained(model, prompt)
 
     # updating the chat history with the new answer

components/iframe/README.md

@@ -1,51 +1,17 @@
-# gradio_iframe
-A custom gradio component to embed an iframe in a gradio interface. This component is based on the [HTML]() component.
-It's currently still a work in progress.
+# gradio iFrame
 
-## Usage
+This is a custom gradio component used to display the shap package text plot. Which is interactive HTML and needs a custom wrapper.
+See custom component examples at offical [docu](https://www.gradio.app/guides/custom-components-in-five-minutes)
 
-The usage is similar to the HTML component. You can pass valid html and it will be rendered in the interface as an iframe, meaning you can embed any website or webapp that supports iframes.
-Also, JavaScript should run normal. You can even pass an iframe inside an iframe (see below!), i.e. a youtube or spotify embed.
+# Credit
+CREDIT: based mostly of Gradio template component, HTML
+see: https://www.gradio.app/docs/html
 
-The size will adjust to the size of the iframe (onload), **this is gonna be a bit delayed**. The width is default at 100%.
-You can also set the height and width manually.
+## Changes
+**Addition/changes are marked. Everything else can be considered the work of other (the Gradio Team)**
 
-### Example
-
-```python
-import gradio as gr
-from gradio_iframe import iFrame
-
-gr.Interface(
-    iFrame(
-        label="iFrame Example",
-        value=("""
-        <iframe width="560"
-            height="315"
-            src="https://www.youtube.com/embed/dQw4w9WgXcQ?si=QfHLpHZsI98oZT1G"
-            title="YouTube video player"
-            frameborder="0"
-            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-            allowfullscreen>
-        </iframe>"""),
-        show_label=True)
-)
-```
-
-## Roadmap
-
-- [ ] Add manual hand over of other iFrame options.
-- [ ] Explore switch between src and srcdoc through variable.
-
-## Known Issues
-
-**There are many reason why it's not a good idea to embed websites in an iframe.**
-See [this](https://blog.bitsrc.io/4-security-concerns-with-iframes-every-web-developer-should-know-24c73e6a33e4), or just google "iframe security concerns" for more information. Also, iFrames will use additional computing power and memory, which can slow down the interface.
-
-Also, this component is still a work in progress and not fully tested. Use at your own risk.
-
-### Other Issues
-
-- Height sometimes does not grow according to the inner component.
-- The component is not completely responsive yet and struggles with variable heigth.
-- ...
+#### Changes Files/Contributions
+- backend/iframe.py - updating component to accept custom height/width and added new example
+- demo/app.py - slightly changed demo file for better dev experience
+- frontend/index.svelte - slightly changed to accept custom height/width
+- frontend/HTML.svelte - updated to use iFrame and added custom function to programmtically set heigth values

components/iframe/backend/gradio_iframe/iframe.py

@@ -62,10 +62,12 @@ class iFrame(Component):
             value=value,
         )
 
+        # updating component to take custom height and width values
         self.height = height
         self.width = width
 
     def example_inputs(self) -> Any:
+        # setting a custom example
         return """<iframe width="560" height="315" src="https://www.youtube.com/embed/dQw4w9WgXcQ?si=QfHLpHZsI98oZT1G" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>"""
 
     def preprocess(self, payload: str | None) -> str | None:

components/iframe/frontend/Index.svelte

@@ -1,3 +1,5 @@
+# index component that wraps the custom iFrame ("HTML")
+
 <script lang="ts">
 	import type { Gradio } from "@gradio/utils";
 	import HTML from "./shared/HTML.svelte";
@@ -10,6 +12,7 @@
 	export let elem_classes: string[] = [];
 	export let visible = true;
 	export let value = "";
+	# updated to take custom heigth
 	export let height: string;
 	export let width: string = "100%";
 	export let loading_status: LoadingStatus;

components/iframe/frontend/shared/HTML.svelte

@@ -1,3 +1,5 @@
+# HTML component that implements custom iFrame
+
 <script lang="ts">
 	import { createEventDispatcher } from "svelte";
 	export let elem_classes: string[] = [];
@@ -5,6 +7,7 @@
 	export let visible = true;
 	export let min_height = false;
 
+	# default setting height and width
 	export let height = "100%";
 	export let width = "100%";
 
@@ -12,10 +15,14 @@
 
 	let iframeElement;
 
+	# custom function to update iFrame height on load of HTML
     const onLoad = () => {
 		try {
+			# calling iFrame document
 			const iframeDocument = iframeElement.contentDocument || iframeElement.contentWindow.document;
+			# if heigth not custom, setting height individually
 			if (height === "100%") {
+				# grabbing height from iFrame document
 				const height = iframeDocument.documentElement.scrollHeight;
 				iframeElement.style.height = `${height}px`;
 			}
@@ -33,6 +40,7 @@
 	class:hide={!visible}
 	class:height={height}
 >
+	# updated to use Iframe instead of HTML, using string values with srcdoc
     <iframe
         bind:this={iframeElement}
         title="iframe component"

explanation/__init__.py

@@ -1,2 +1 @@
-# empty init file for the package
-# for fastapi to recognize the module
+# empty init file for the modules

explanation/interpret_shap.py

@@ -1,4 +1,5 @@
 # interpret module that implements the interpretability method
+
 # external imports
 from shap import models, maskers, plots, PartitionExplainer
 import torch
@@ -14,14 +15,15 @@ TEXT_MASKER = None
 
 # main explain function that returns a chat with explanations
 def chat_explained(model, prompt):
-    model.set_config()
+    model.set_config({})
 
     # create the shap explainer
     shap_explainer = PartitionExplainer(model.MODEL, model.TOKENIZER)
+
     # get the shap values for the prompt
     shap_values = shap_explainer([prompt])
 
-    # create the explanation graphic and plot
+    # create the explanation graphic and marked text array
     graphic = create_graphic(shap_values)
     marked_text = markup_text(
         shap_values.data[0], shap_values.values[0], variant="shap"
@@ -29,20 +31,26 @@ def chat_explained(model, prompt):
 
     # create the response text
     response_text = fmt.format_output_text(shap_values.output_names)
+
+    # return response, graphic and marked_text array
     return response_text, graphic, marked_text
 
 
+# function used to wrap the model with a shap model
 def wrap_shap(model):
+    # calling global variants
     global TEXT_MASKER, TEACHER_FORCING
 
     # set the device to cuda if gpu is available
     device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 
-    # updating the model settings again
+    # updating the model settings
     model.set_config()
 
     # (re)initialize the shap models and masker
+    # creating a shap text_generation model
     text_generation = models.TextGeneration(model.MODEL, model.TOKENIZER)
+    # wrapping the text generation model in a teacher forcing model
     TEACHER_FORCING = models.TeacherForcing(
         text_generation,
         model.TOKENIZER,
@@ -50,13 +58,15 @@ def wrap_shap(model):
         similarity_model=model.MODEL,
         similarity_tokenizer=model.TOKENIZER,
     )
+    # setting the text masker as an empty string
     TEXT_MASKER = maskers.Text(model.TOKENIZER, " ", collapse_mask_token=True)
 
 
 # graphic plotting function that creates a html graphic (as string) for the explanation
 def create_graphic(shap_values):
+
     # create the html graphic using shap text plot function
     graphic_html = plots.text(shap_values, display=False)
 
-    # return the html graphic as string
+    # return the html graphic as string to display in iFrame
     return str(graphic_html)

explanation/markup.py

@@ -1,4 +1,4 @@
-# markup module that provides marked up text and a plot for the explanations
+# markup module that provides marked up text as an array
 
 # external imports
 import numpy as np
@@ -8,10 +8,12 @@ from numpy import ndarray
 from utils import formatting as fmt
 
 
+# main function that assigns each text snipped a marked bucket
 def markup_text(input_text: list, text_values: ndarray, variant: str):
+    # naming of the 11 buckets
     bucket_tags = ["-5", "-4", "-3", "-2", "-1", "0", "+1", "+2", "+3", "+4", "+5"]
 
-    # Flatten the values depending on the source
+    # flatten the values depending on the source
     # attention is averaged, SHAP summed up
     if variant == "shap":
         text_values = np.transpose(text_values)
@@ -22,34 +24,49 @@ def markup_text(input_text: list, text_values: ndarray, variant: str):
     # Determine the minimum and maximum values
     min_val, max_val = np.min(text_values), np.max(text_values)
 
-    # Separate the threshold calculation for negative and positive values
+    # separate the threshold calculation for negative and positive values
+    # visualization negative thresholds are all 0 since attetion always positive
     if variant == "visualizer":
         neg_thresholds = np.linspace(
             0, 0, num=(len(bucket_tags) - 1) // 2 + 1, endpoint=False
         )[1:]
+    # standart config for 5 negative buckets
     else:
         neg_thresholds = np.linspace(
             min_val, 0, num=(len(bucket_tags) - 1) // 2 + 1, endpoint=False
         )[1:]
+    # creating positive thresholds between 0 and max values
     pos_thresholds = np.linspace(0, max_val, num=(len(bucket_tags) - 1) // 2 + 1)[1:]
+    # combining thresholds
     thresholds = np.concatenate([neg_thresholds, [0], pos_thresholds])
 
+    # init empty marked text list
     marked_text = []
 
-    # Function to determine the bucket for a given value
+    # looping over each text snippet and attribution value
     for text, value in zip(input_text, text_values):
+        # setting inital bucket at lowest
         bucket = "-5"
+
+        # looping over all bucket and their threshold
         for i, threshold in zip(bucket_tags, thresholds):
+            # updating assigned bucket if value is above threshold
             if value >= threshold:
                 bucket = i
+        # finally adding text and bucket assignment to list of tuples
         marked_text.append((text, str(bucket)))
 
+    # returning list of marked text snippets as list of tuples
     return marked_text
 
 
+# function that defines color codes
+# coloring along SHAP style coloring for consistency
 def color_codes():
     return {
-        # 1-5: Strong Light Sky Blue to Lighter Sky Blue
+        # -5 to -1: Strong Light Sky Blue to Lighter Sky Blue
+        # 0: white (assuming default light mode)
+        # +1 to +5 light pink to string magenta
         "-5": "#3251a8",  # Strong Light Sky Blue
         "-4": "#5A7FB2",  # Slightly Lighter Sky Blue
         "-3": "#8198BC",  # Intermediate Sky Blue

explanation/visualize.py

@@ -1,21 +1,26 @@
-# visualization module that creates an attention visualization using BERTViz
+# visualization module that creates an attention visualization
 
 
 # internal imports
 from utils import formatting as fmt
+from model.godel import CONFIG
 from .markup import markup_text
 
 
-# plotting function that plots the attention values in a heatmap
+# chat function that returns an answer
+# and marked text based on attention
 def chat_explained(model, prompt):
 
-    model.set_config()
-
-    # get encoded input and output vectors
+    # get encoded input
     encoder_input_ids = model.TOKENIZER(
         prompt, return_tensors="pt", add_special_tokens=True
     ).input_ids
-    decoder_input_ids = model.MODEL.generate(encoder_input_ids, output_attentions=True)
+    # generate output together with attentions of the model
+    decoder_input_ids = model.MODEL.generate(
+        encoder_input_ids, output_attentions=True, **CONFIG
+    )
+
+    # get input and output text as list of strings
     encoder_text = fmt.format_tokens(
         model.TOKENIZER.convert_ids_to_tokens(encoder_input_ids[0])
     )
@@ -24,20 +29,25 @@ def chat_explained(model, prompt):
     )
 
     # get attention values for the input and output vectors
+    # using already generated input and output
     attention_output = model.MODEL(
         input_ids=encoder_input_ids,
         decoder_input_ids=decoder_input_ids,
         output_attentions=True,
     )
 
+    # averaging attention across layers
     averaged_attention = fmt.avg_attention(attention_output)
 
-    # create the response text and marked text for ui
+    # format response text for clean output
     response_text = fmt.format_output_text(decoder_text)
+    # setting placeholder for iFrame graphic
     graphic = (
         "<div style='text-align: center; font-family:arial;'><h4>Attention"
         " Visualization doesn't support an interactive graphic.</h4></div>"
     )
+    # creating marked text using markup_text function and attention
     marked_text = markup_text(encoder_text, averaged_attention, variant="visualizer")
 
+    # returning response, graphic and marked text array
     return response_text, graphic, marked_text

main.py

@@ -14,13 +14,21 @@ from gradio_iframe import iFrame
 from backend.controller import interference
 from explanation.markup import color_codes
 
-# Global Variables and css
+
+# global Variables and js/css
+# creating FastAPI app and getting color codes
 app = FastAPI()
+coloring = color_codes()
+
+
+# defining custom css and js for certain environments
 css = """
     .examples {text-align: start;}
     .seperatedRow {border-top: 1rem solid;}",
     """
-js = """
+# custom js to force lightmode in custom environments
+if os.environ["HOSTING"].lower() != "spaces":
+    js = """
     function () {
         gradioURL = window.location.href
         if (!gradioURL.endsWith('?__theme=light')) {
@@ -28,7 +36,8 @@ js = """
         }
     }
     """
-coloring = color_codes()
+else:
+    js = ""
 
 
 # different functions to provide frontend abilities
@@ -56,8 +65,8 @@ def xai_info(xai_radio):
         gr.Info("No XAI method was selected.")
 
 
-# ui interface based on Gradio Blocks (see documentation:
-# https://www.gradio.app/docs/interface)
+# ui interface based on Gradio Blocks
+# see https://www.gradio.app/docs/interface)
 with gr.Blocks(
     css=css,
     js=js,
@@ -88,6 +97,7 @@ with gr.Blocks(
                 """)
         # row with columns for the different settings
         with gr.Row(equal_height=True):
+            # accordion that extends if clicked
             with gr.Accordion(label="Application Settings", open=False):
                 # column that takes up 3/4 of the row
                 with gr.Column(scale=3):
@@ -95,6 +105,7 @@ with gr.Blocks(
                     system_prompt = gr.Textbox(
                         label="System Prompt",
                         info="Set the models system prompt, dictating how it answers.",
+                        # default system prompt is set to this in the backend
                         placeholder=(
                             "You are a helpful, respectful and honest assistant. Always"
                             " answer as helpfully as possible, while being safe."
@@ -105,26 +116,29 @@ with gr.Blocks(
                     # checkbox group to select the xai method
                     xai_selection = gr.Radio(
                         ["None", "SHAP", "Attention"],
-                        label="XAI Settings",
-                        info="Select a XAI Implementation to use.",
+                        label="Interpretability Settings",
+                        info="Select a Interpretability Implementation to use.",
                         value="None",
                         interactive=True,
                         show_label=True,
                     )
 
-            # calling info functions on inputs for different settings
+            # calling info functions on inputs/submits for different settings
             system_prompt.submit(system_prompt_info, [system_prompt])
             xai_selection.input(xai_info, [xai_selection])
 
         # row with chatbot ui displaying "conversation" with the model
         with gr.Row(equal_height=True):
+            # group to display components closely together
             with gr.Group(elem_classes="border: 1px solid black;"):
                 # accordion to display the normalized input explanation
                 with gr.Accordion(label="Input Explanation", open=False):
                     gr.Markdown("""
                     The explanations are based on 10 buckets that range between the
                     lowest negative value (1 to 5) and the highest positive attribution value (6 to 10).
-                    **The legend show the color for each bucket.**
+                    **The legend shows the color for each bucket.**
+                                
+                    *HINT*: This works best in light mode.
                     """)
                     xai_text = gr.HighlightedText(
                         color_map=coloring,
@@ -132,15 +146,19 @@ with gr.Blocks(
                         show_legend=True,
                         show_label=False,
                     )
-                # out of the  box chatbot component
+                # out of the  box chatbot component with avatar images
                 # see documentation: https://www.gradio.app/docs/chatbot
                 chatbot = gr.Chatbot(
                     layout="panel",
                     show_copy_button=True,
                     avatar_images=("./public/human.jpg", "./public/bot.jpg"),
                 )
-                # textbox to enter the knowledge
+                # extenable components for extra knowledge
                 with gr.Accordion(label="Additional Knowledge", open=False):
+                    gr.Markdown(
+                        "*Hint:* Add extra knowledge to see GODEL work the best."
+                    )
+                    # textbox to enter the knowledge
                     knowledge_input = gr.Textbox(
                         value="",
                         label="Knowledge",
@@ -149,24 +167,31 @@ with gr.Blocks(
                         show_label=True,
                     )
                 # textbox to enter the user prompt
+                gr.Markdown(
+                    "*Hint:* More complicated question give better explanation"
+                    " insights!"
+                )
                 user_prompt = gr.Textbox(
                     label="Input Message",
                     max_lines=5,
                     info="""
                     Ask the ChatBot a question.
-                    Hint: More complicated question give better explanation insights!
                     """,
                     show_label=True,
                 )
         # row with columns for buttons to submit and clear content
         with gr.Row(elem_classes=""):
-            with gr.Column(scale=1):
+            with gr.Column():
                 # out of the box clear button which clearn the given components (see
-                # documentation: https://www.gradio.app/docs/clearbutton)
+                # see: https://www.gradio.app/docs/clearbutton)
                 clear_btn = gr.ClearButton([user_prompt, chatbot])
-            with gr.Column(scale=1):
+            with gr.Column():
+                # submit button that calls the backend functions on click
                 submit_btn = gr.Button("Submit", variant="primary")
+        # row with content examples that get autofilled on click
         with gr.Row(elem_classes="examples"):
+            # examples util component
+            # see: https://www.gradio.app/docs/examples
             gr.Examples(
                 label="Example Questions",
                 examples=[
@@ -235,18 +260,21 @@ with gr.Blocks(
     # final row to show legal information
     ## - credits, data protection and link to the License
     with gr.Tab(label="About"):
+        # load about.md markdown
         gr.Markdown(value=load_md("public/about.md"))
         with gr.Accordion(label="Credits, Data Protection, License"):
+            # load credits and dataprotection markdown
             gr.Markdown(value=load_md("public/credits_dataprotection_license.md"))
 
 # mount function for fastAPI Application
 app = gr.mount_gradio_app(app, ui, path="/")
 
-# launch function using uvicorn to launch the fastAPI application
+# launch function to launch the application
 if __name__ == "__main__":
 
     # use standard gradio launch option for hgf spaces
     if os.environ["HOSTING"].lower() == "spaces":
+        # set password to deny public access
         ui.launch(auth=("htw", "berlin@123"))
 
     # otherwise run the application on port 8080 in reload mode

model/__init__.py

@@ -1,2 +1 @@
-# empty init file for the package
-# for fastapi to recognize the module
+# empty init file for the module

model/godel.py

@@ -6,21 +6,28 @@ from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
 # internal imports
 from utils import modelling as mdl
 
-# model and tokenizer instance
+# global model and tokenizer instance (created on inital build)
 TOKENIZER = AutoTokenizer.from_pretrained("microsoft/GODEL-v1_1-large-seq2seq")
 MODEL = AutoModelForSeq2SeqLM.from_pretrained("microsoft/GODEL-v1_1-large-seq2seq")
+
+# default model config
 CONFIG = {"max_new_tokens": 50, "min_length": 8, "top_p": 0.9, "do_sample": True}
 
 
-# TODO: Make config variable
-def set_config(config: dict = None):
-    if config is None:
-        config = {}
+# function to (re) set config
+def set_config(config: dict):
+    global CONFIG
 
-    MODEL.config.max_new_tokens = 50
-    MODEL.config.min_length = 8
-    MODEL.config.top_p = 0.9
-    MODEL.config.do_sample = True
+    # if config dict is given, update it
+    if config != {}:
+        CONFIG = config
+    else:
+        # hard setting model config to default
+        # needed for shap
+        MODEL.config.max_new_tokens = 50
+        MODEL.config.min_length = 8
+        MODEL.config.top_p = 0.9
+        MODEL.config.do_sample = True
 
 
 # formatting class to formatting input for the model
@@ -56,8 +63,12 @@ def format_prompt(message: str, history: list, system_prompt: str, knowledge: st
 # CREDIT: Copied from official interference example on Huggingface
 ## see https://huggingface.co/microsoft/GODEL-v1_1-large-seq2seq
 def respond(prompt):
+    # tokenizing input string
     input_ids = TOKENIZER(f"{prompt}", return_tensors="pt").input_ids
+
+    # generating using config and decoding output
     outputs = MODEL.generate(input_ids, **CONFIG)
     output = TOKENIZER.decode(outputs[0], skip_special_tokens=True)
 
+    # returns the model output string
     return output

utils/__init__.py

@@ -0,0 +1 @@
+# empty init file for the module

utils/formatting.py

@@ -7,8 +7,10 @@ from numpy import ndarray
 
 
 # function to format the model reponse nicely
+# takes a list of strings and returnings a combined string
 def format_output_text(output: list):
-    # remove special tokens from list
+
+    # remove special tokens from list using other function
     formatted_output = format_tokens(output)
 
     # start string with first list item if it is not empty
@@ -34,8 +36,10 @@ def format_output_text(output: list):
 
 # format the tokens by removing special tokens and special characters
 def format_tokens(tokens: list):
-    # define special tokens to remove and initialize empty list
+    # define special tokens to remove
     special_tokens = ["[CLS]", "[SEP]", "[PAD]", "[UNK]", "[MASK]", "▁", "Ġ", "</w>"]
+
+    # initialize empty list
     updated_tokens = []
 
     # loop through tokens
@@ -44,7 +48,7 @@ def format_tokens(tokens: list):
         if t.startswith("▁"):
             t = t.lstrip("▁")
 
-        # loop through special tokens and remove them if found
+        # loop through special tokens list and remove from current token if matched
         for s in special_tokens:
             t = t.replace(s, "")
 
@@ -55,15 +59,17 @@ def format_tokens(tokens: list):
     return updated_tokens
 
 
-# function to flatten values into a 2d list by averaging the explanation values
+# function to flatten shap values into a 2d list by summing them up
 def flatten_attribution(values: ndarray, axis: int = 0):
     return np.sum(values, axis=axis)
 
 
+# function to flatten values into a 2d list by averaging the attention values
 def flatten_attention(values: ndarray, axis: int = 0):
     return np.mean(values, axis=axis)
 
 
+# function to get averaged decoder attention from attention values
 def avg_attention(attention_values):
     attention = attention_values.decoder_attentions[0][0].detach().numpy()
     return np.mean(attention, axis=0)

utils/modelling.py

@@ -1,26 +1,28 @@
-# module for modelling utilities
+# modelling util module providing formatting functions for model functionalities
 
 # external imports
 import gradio as gr
 
 
+# function that limits the prompt to contain model runtime
+# tries to keep as much as possible, always keeping at least message and system prompt
 def prompt_limiter(
     tokenizer, message: str, history: list, system_prompt: str, knowledge: str = ""
 ):
-    # initializing the prompt history empty
+    # initializing the new prompt history empty
     prompt_history = []
-    # getting the token count for the message, system prompt, and knowledge
+    # getting the current token count for the message, system prompt, and knowledge
     pre_count = (
         token_counter(tokenizer, message)
         + token_counter(tokenizer, system_prompt)
         + token_counter(tokenizer, knowledge)
     )
 
-    # validating the token count
-    # check if token count already too high
+    # validating the token count against threshold of 1024
+    # check if token count already too high without history
     if pre_count > 1024:
 
-        # check if token count too high even without knowledge
+        # check if token count too high even without knowledge and history
         if (
             token_counter(tokenizer, message) + token_counter(tokenizer, system_prompt)
             > 1024
@@ -32,11 +34,14 @@ def prompt_limiter(
                 "Message and system prompt are too long. Please shorten them."
             )
 
-        # show warning and remove knowledge
-        gr.Warning("Knowledge is too long. It has been removed to keep model running.")
+        # show warning and return with empty history and empty knowledge
+        gr.Warning("""
+                   Input too long.
+                   Knowledge and conversation history have been removed to keep model running.
+                   """)
         return message, prompt_history, system_prompt, ""
 
-    # if token count small enough, add history
+    # if token count small enough, adding history bit by bit
     if pre_count < 800:
         # setting the count to the precount
         count = pre_count
@@ -46,7 +51,7 @@ def prompt_limiter(
         # iterating through the history
         for conversation in history:
 
-            # checking the token count with the current conversation
+            # checking the token count i´with the current conversation
             count += token_counter(tokenizer, conversation[0]) + token_counter(
                 tokenizer, conversation[1]
             )
@@ -57,7 +62,7 @@ def prompt_limiter(
             else:
                 break
 
-    # return the message, prompt history, system prompt, and knowledge
+    # return the message, adapted, system prompt, and knowledge
     return message, prompt_history, system_prompt, knowledge