docs: Docstrings, comments and type hints added

Also moved the prompt and user instructions to new files prompt.txt and
user_instructions.txt to de-clutter the app.py.

app.py

@@ -1,104 +1,114 @@
-import gradio as gr
-import os
-import pandas as pd
-from openai import OpenAI
-import openpyxl
-import json
+# Import necessary modules
+import gradio as gr # For creating the interactive user interface
+import os # For accessing environment variables
+import pandas as pd # For easier data handling
+from openai import OpenAI # For sending the quotes to OpenAI for tagging
+import openpyxl # Requirement for reading Excel files into pandas Dataframes
+import json # For conversion of OpenAI responses into json/dictionary objects so the contents can be extracted
 
+# Import prompt for requesting the tags from OpenAI
+with open("prompt.txt", "r") as prompt_file:
+    PROMPT = prompt_file.read()
+
+# Import user instructions for display on screen
+with open("user_instructions.txt", "r") as user_instruction_file:
+    INSTRUCTIONS = user_instruction_file.read()
+
+#Initialising the OpenAI client
 client = OpenAI(
   api_key=os.getenv('OPENAI_KEY'),
   organization=os.getenv('ORG_KEY'),
   project=os.getenv('PROJ_KEY')
 )
 
-#need to give info on how to convert to CSV
-title = "Automated Research Code Tagger"
-description = """
-ABOUT:\n
-This automated tagger takes in a list of tags and a list of input quotes. Each input quote is individually fed to OpenAI's ChatGPT together with the list of tags, 
-and ChatGPT will respond with the subset of the input tags which are related to the content of the quote.\n
-
-HOW TO USE:\n
-1)Upload a single sheet Excel file containing quotes in a column.(It is ok for the file to contain other data also)\n
-2)Type in the name of the column where the quotes are located\n
-3)Type in a list of tags separated by commas. For proper names/slogans/other tags that should be treated as an inseparable unit eg. Nike's "Just Do It", add a * in front of the tag eg. tag1, *Just Do It, tag3, etc.
-This will ensure only quotes containing "Just Do It" exactly are tagged and not other quotes about doing other things.\n
-4)All the responses from ChatGPT will be collated and displayed in the table on the right, together with the original quotes.
-You may then copy them into an Excel file for further processing. Please allow 5-10 min for processing, especially if you are giving upwards of 100 quotes!\n
-
-Please bear in mind that the tags are AI generated so check your results to ensure they make sense before using them. 
-I will not be responsible for mistakes made by the AI, but I can try to fix them if you alert me.
--Kenneth
-"""
-
-prompt = """
-Given the quote below and the regular tag list below, evaluate each tag in the tag list and determine if the meaning of the quote can be described by that tag topic.
-If so, return the relevant tag in your response. Use only the tags provided in the list. Under no circumstances should you create new tag names.
-
-For the tags starting with a *, these tags should be treated as proper nouns(usually product names or slogans) and should not be used unless the quote explicitly contains the entire tag.
-For quotes with meanings that are more ambiguous and can relate to multiple tags, make no assumptions about their meanings and only add tags if the topic of the tag is actually mentioned in the quote.
-If there are no relevant tags to the quote, return an empty list.
-
-Quote:
-{quote}
-
-Tag list:
-{tags_list}
-
-Respond in the following format:
-{{
-  "tags":[<tagName1>, <tagName2>]
-}}
-"""
-def tag_quote(quote, tags_list):
+# Function to send the prompt with quote and tag list to OpenAI and get the tags for that quote back
+def tag_quote(quote: str, tags_list: list) -> list:
+    """
+    Generates a list of tags for a given quote based on a predefined list of potential tags.
+
+    This function uses a GPT-based language model to analyze the input quote and determine 
+    the most relevant tags from the provided list. The response is parsed from the JSON 
+    output of the model and returned as a list of tags.
+
+    Args:
+        quote (str): The quote or text to be analyzed.
+        tags_list (list): A list of potential tags to match against the quote.
+
+    Returns:
+        list: A list of tags that are relevant to the quote, as determined by the model.
+    """
     response = client.chat.completions.create(
         model = "gpt-4o-mini",
         response_format={"type": "json_object"},
         messages=[
             {"role": "system", "content": "You are a helpful assistant designed to output JSON."},
-            {"role": "user", "content": prompt.format(tags_list=tags_list,  quote=quote)}
+            {"role": "user", "content": PROMPT.format(tags_list=tags_list,  quote=quote)}
         ]
     )
-    print(response.choices[0].message.content)
     return json.loads(response.choices[0].message.content)['tags']
-    
-def process_quotes(quotes_file_path, quotes_col_name, tags_string):
-    print(quotes_file_path)
-    print(quotes_col_name)
-    print(tags_string)
+
+# Function that takes in a list of tags and an Excel file of quotes, calls tag_quote() on each quote, and returns all the quotes and tags in a DataFrame     
+def process_quotes(quotes_file_path: str, quotes_col_name: str, tags_string: str) -> pd.DataFrame:
+    """
+    Processes quotes from an Excel file and assigns relevant tags to each quote.
+
+    This function reads an Excel file containing quotes, validates the column containing
+    the quotes, and applies the `tag_quote` function to assign tags to each quote.
+    The tags are derived from a user-provided comma-separated string.
+
+    Args:
+        quotes_file_path (str): Path to the Excel file containing the quotes.
+        quotes_col_name (str): The name of the column containing the quotes.
+        tags_string (str): A comma-separated string of potential tags.
+
+    Returns:
+        pd.DataFrame: A DataFrame with two columns:
+            - The original column containing the quotes.
+            - A new column 'Tags' with the tags assigned to each quote.
+
+    Raises:
+        gr.Error: If the specified column name does not exist or is not unique.
+
+    Example:
+        >>> process_quotes("quotes.xlsx", "Quote", "inspirational, funny, motivational")
+        Outputs a DataFrame with 'Quote' and 'Tags' columns indicating which tags are assigned to which quotes.
+    """
     tags_list = tags_string.split(',')
     tags_list = [tag.strip() for tag in tags_list]
 
-    #next 3 lines are necessary as pd.read_excel will rename duplicate columns found in the excel file eg foo -> foo.1, hence we need to extract the first row alone and not as header, and then set it as header for the rest of the DF later.
-    quotes_df_cols= pd.read_excel(quotes_file_path, header=None, nrows=1).values[0] #creates a df without header from the excel and takes the first row
-    quotes_df = pd.read_excel(quotes_file_path, header=None, skiprows=1) # converts row 2 onwards into the DF, without specifying a header
-    quotes_df.columns = quotes_df_cols # sets the first row of excel file as header
+    # Transfer quotes data from Excel file into pandas DataFrame, handling potential duplicate column names in the Excel file
+    # pd.read_excel will rename duplicates eg foo -> foo.1, causing a mismatch between quotes_col_name and the actual column name
+    # Extract the first row(the actual header for the DataFrame) as a DataFrame without header.
+    quotes_df_cols= pd.read_excel(quotes_file_path, header=None, nrows=1).values[0] 
+    # Extract all the other rows of the Excel file as a DataFrame without header
+    quotes_df = pd.read_excel(quotes_file_path, header=None, skiprows=1) 
+    # Set the extracted first row as the header for the DataFrame resultant from the other rows
+    quotes_df.columns = quotes_df_cols
 
+    # Check that the column name given by the user exists and is unique
     count = quotes_df.columns.tolist().count(quotes_col_name)
     if count == 0:
         raise gr.Error("No columns with this name found")
     elif count > 1:
-        print("Count>1!!")
         raise gr.Error("Multiple columns with this name found, please rename to something unique")
     quotes_data = quotes_df[quotes_col_name]
+    
+    # Tag all the quotes one by one using tag_quote function
     quotes_df['Tags'] = quotes_data.apply(tag_quote, args=(tags_list,))
+
+    # Return only the quotes column and the new tags column
     return quotes_df[[quotes_col_name, 'Tags']]
 
 demo = gr.Interface(
     fn=process_quotes, 
     inputs=[
-        gr.File(label="Quotes Excel File"), # File as generated by TFT software
-        gr.Textbox(label="Name of quotes column"), # use this to identify the col with the quotes 
-        gr.Textbox(label = "List of tags separated by commas")
+        gr.File(label="Quotes Excel File"),
+        gr.Textbox(label="Name of quotes column"),
+        gr.Textbox(label = "List of tags separated by commas") 
     ],
     outputs=gr.Dataframe(headers=["Quote", "Tags"], column_widths=["70%", "30%"], scale=2),
-    title=title,
-    description=description 
+    title="Automated Research Code Tagger",
+    description=INSTRUCTIONS 
     )
 
 demo.launch()
-
-# For later when I enable usage of own API key
-# api_key = gr.Textbox(
-#         type="password", label="Enter your OpenAI API key here (Optional for Perceptech users)"
-#     )

prompt.txt

@@ -0,0 +1,17 @@
+Given the quote below and the regular tag list below, evaluate each tag in the tag list and determine if the meaning of the quote can be described by that tag topic.
+If so, return the relevant tag in your response. Use only the tags provided in the list. Under no circumstances should you create new tag names.
+
+For the tags starting with a *, these tags should be treated as proper nouns(usually product names or slogans) and should not be used unless the quote explicitly contains the entire tag.
+For quotes with meanings that are more ambiguous and can relate to multiple tags, make no assumptions about their meanings and only add tags if the topic of the tag is actually mentioned in the quote.
+If there are no relevant tags to the quote, return an empty list.
+
+Quote:
+{quote}
+
+Tag list:
+{tags_list}
+
+Respond in the following format:
+{{
+  "tags":[<tagName1>, <tagName2>]
+}}

user_instructions.txt

@@ -0,0 +1,15 @@
+ABOUT:
+This automated tagger takes in a list of tags and a list of input quotes. Each input quote is individually fed to OpenAI's ChatGPT together with the list of tags, 
+and ChatGPT will respond with the subset of the input tags which are related to the content of the quote.
+
+HOW TO USE:
+1)Upload a single sheet Excel file containing quotes in a column.(It is ok for the file to contain other data also)
+2)Type in the name of the column where the quotes are located
+3)Type in a list of tags separated by commas. For proper names/slogans/other tags that should be treated as an inseparable unit eg. Nike's "Just Do It", add a * in front of the tag eg. tag1, *Just Do It, tag3, etc.
+This will ensure only quotes containing "Just Do It" exactly are tagged and not other quotes about doing other things.
+4)All the responses from ChatGPT will be collated and displayed in the table on the right, together with the original quotes.
+You may then copy them into an Excel file for further processing. Please allow 5-10 min for processing, especially if you are giving upwards of 100 quotes!
+
+Please bear in mind that the tags are AI generated so check your results to ensure they make sense before using them. 
+I will not be responsible for mistakes made by the AI, but I can try to fix them if you alert me.
+-Kenneth