Create app.py

app.py

@@ -0,0 +1,293 @@
+import gradio as gr
+from llama_index.core import VectorStoreIndex, Document  # Imports VectorStoreIndex for semantic search and Document class for text storage
+from llama_index.llms.openai import OpenAI  # Imports OpenAI language model integration from LlamaIndex
+from llama_index.core import Settings  # Imports Settings to configure global LlamaIndex parameters
+import os  # Imports OS module for interacting with the operating system (file paths, environment variables)
+import pdfplumber  # Imports pdfplumber library for extracting text from PDF files
+from docx import Document as DocxDocument  # Imports Document class from python-docx, renamed to avoid conflict with LlamaIndex's Document
+import json  # Imports JSON module for parsing and creating JSON data
+from datetime import datetime  # Imports datetime class for working with dates and times
+import hashlib  # Imports hashlib for creating hash functions (MD5, SHA, etc.) for data integrity/unique identifiers
+
+# Global variables
+chat_engine = None  # Stores the LlamaIndex chat engine instance; None until initialized with documents
+conversation_history = []  # Empty list to store all chat messages (user questions and AI responses)
+current_user_id = None  # Stores hashed identifier for current user based on their API key
+
+# Function to generate user ID from API key
+def get_user_id(api_key):  # Defines function that takes API key string as input
+    if not api_key:  # Checks if api_key is None, empty string, or falsy value
+        return None  # Returns None if no API key provided
+    return hashlib.sha256(api_key.encode()).hexdigest()[:16]  # Encodes key to bytes, creates SHA-256 hash, converts to hex string, returns first 16 characters as unique user ID
+
+# Function to get user-specific filename
+def get_user_file(api_key):  # Defines function that generates unique filename for each user
+    user_id = get_user_id(api_key)  # Calls get_user_id to generate unique identifier from API key
+    if not user_id:  # Checks if user_id is None (happens when api_key is invalid/empty)
+        return None  # Returns None if no valid user ID could be generated
+    return f"conversations_{user_id}.json"  # Returns formatted string with user-specific filename for storing conversation history
+
+# Function to read PDF files
+def read_pdf(file_path):  # Defines function that takes a file path string as parameter
+    with pdfplumber.open(file_path) as pdf:  # Opens PDF file using context manager (auto-closes after use)
+        text = ''  # Initializes empty string to accumulate extracted text
+        for page in pdf.pages:  # Loops through each page object in the PDF
+            text += page.extract_text() + '\n'  # Extracts text from current page and appends it with newline character
+    return text  # Returns the complete concatenated text from all pages
+
+# Function to read DOCX files
+def read_docx(file_path):  # Defines function that takes a file path string as parameter
+    doc = DocxDocument(file_path)  # Creates a Document object by loading the .docx file
+    text = ''  # Initializes empty string to store extracted text
+    for paragraph in doc.paragraphs:  # Iterates through each paragraph object in the document
+        text += paragraph.text + '\n'  # Extracts text from current paragraph and appends with newline
+    return text  # Returns the complete text from all paragraphs
+
+# Function to load and index documents
+def load_data(files, api_key):  # Defines function that accepts uploaded files list and API key string
+    global chat_engine, current_user_id  # Declares these as global so changes persist outside function scope
+    
+    if not api_key:  # Checks if API key is missing, empty, or None
+        return "Please provide your OpenAI API key first."  # Returns error message prompting for API key
+    
+    if not files:  # Checks if files list is empty, None, or falsy
+        return "Please upload files to proceed."  # Returns error message prompting for file upload
+    
+    try:  # Begins try block to catch any errors during document processing
+        # Set current user
+        current_user_id = get_user_id(api_key)  # Generates and stores unique user ID from API key in global variable
+        
+        docs = []  # Initializes empty list to store Document objects
+        for file in files:  # Loops through each uploaded file object in the files list
+            if file.name.endswith('.pdf'):  # Checks if filename ends with .pdf extension
+                text = read_pdf(file.name)  # Extracts all text from PDF using previously defined function
+                docs.append(Document(text=text))  # Creates LlamaIndex Document object from text and adds to list
+            elif file.name.endswith('.docx'):  # Checks if filename ends with .docx extension
+                text = read_docx(file.name)  # Extracts all text from Word document using previously defined function
+                docs.append(Document(text=text))  # Creates Document object from extracted text and appends to list
+        
+        # Set OpenAI API key
+        os.environ["OPENAI_API_KEY"] = api_key  # Sets environment variable so OpenAI library can automatically access the API key
+        
+        Settings.llm = OpenAI(  # Configures the global LLM (Large Language Model) settings for LlamaIndex
+            model="gpt-5-nano",  # Specifies which OpenAI model to use (GPT-4 optimized mini version)
+            temperature=0.5,  # Sets randomness level (0=deterministic/focused, 1=creative/random); 0.5 is balanced
+            api_key=api_key,  # Passes API key directly to OpenAI client for authentication
+            system_prompt="You are a helpful AI assistant that answers questions based on the provided documents. Always base your answers on the content of the uploaded documents. If the answer cannot be found in the documents, clearly state that. Be accurate, concise, and cite specific information from the documents when possible."  # Instructions that guide the AI's behavior, response style, and constrain it to document content
+        )
+        
+        index = VectorStoreIndex.from_documents(docs)  # Creates vector embeddings of all documents for semantic similarity search
+        chat_engine = index.as_chat_engine(chat_mode="condense_question", verbose=True)  # Converts index to conversational chat interface; condense_question mode reformulates follow-up questions using conversation context; verbose=True prints debug info
+        
+        return "Documents loaded and indexed successfully! You can now start chatting."  # Returns success message to display to user
+    except Exception as e:  # Catches any error that occurred anywhere in the try block
+        return f"Error loading documents: {str(e)}"  # Returns formatted error message with details of what went wrong
+
+# Function to handle chat
+def chat_with_docs(message, history, api_key):  # Defines function that takes user's message, chat history list, and API key as parameters
+    global chat_engine, conversation_history, current_user_id  # Declares global variables so function can read/modify them
+    
+    if not api_key:  # Checks if API key is missing, empty, or None
+        return history + [{"role": "assistant", "content": "Please enter your OpenAI API key first."}]  # Returns existing history plus error message as assistant response
+    
+    # Update current user
+    current_user_id = get_user_id(api_key)  # Generates unique user ID from API key and stores in global variable
+    
+    if chat_engine is None:  # Checks if chat_engine hasn't been initialized (no documents loaded yet)
+        return history + [  # Returns history with two new messages added to the list
+            {"role": "user", "content": message},  # Adds user's question to history as dictionary
+            {"role": "assistant", "content": "Please upload and load documents first before asking questions."}  # Adds assistant's error response
+        ]
+    
+    try:  # Begins try block to catch errors during chat interaction
+        response = chat_engine.chat(message)  # Sends user message to chat engine, which searches documents and generates response
+        conversation_history.append({"role": "user", "content": message})  # Adds user message to global conversation history list
+        conversation_history.append({"role": "assistant", "content": response.response})  # Adds AI response to global conversation history (response.response extracts text from response object)
+        
+        return history + [  # Returns updated history by concatenating existing history with new messages
+            {"role": "user", "content": message},  # Adds current user message
+            {"role": "assistant", "content": response.response}  # Adds AI's response text
+        ]
+    except Exception as e:  # Catches any error that occurred during chat processing
+        return history + [  # Returns history with error message instead of crashing
+            {"role": "user", "content": message},  # Still adds user's message to show what they asked
+            {"role": "assistant", "content": f"Error: {str(e)}"}  # Adds error details as assistant response for debugging
+        ]
+
+# Function to save conversation (user-specific)
+def save_conversation(api_key):  # Defines function that saves conversation to user-specific file
+    global conversation_history  # Accesses global conversation_history variable
+    
+    if not api_key:  # Checks if API key is missing or empty
+        return "Please enter your OpenAI API key first."  # Returns error message and exits function
+    
+    if not conversation_history:  # Checks if conversation_history list is empty (no messages to save)
+        return "No conversation to save."  # Returns message indicating nothing to save
+    
+    try:  # Begins try block to handle file writing errors
+        user_file = get_user_file(api_key)  # Generates unique filename based on user's API key (e.g., "conversations_abc123.json")
+        timestamp = datetime.now().strftime(%Y-%m-%d_%H-%M-%S")  # Gets current date/time and formats as string (e.g., "2026-01-14_15-30-45")
+        
+        with open(user_file, "a") as f:  # Opens user's file in append mode ("a" means add to end without overwriting); auto-closes when done
+            conv_data = {  # Creates dictionary to structure the conversation data
+                "timestamp": timestamp,  # Stores when conversation was saved
+                "messages": conversation_history  # Stores all messages from current conversation
+            }
+            json.dump(conv_data, f)  # Converts dictionary to JSON format and writes to file
+            f.write("\n")  # Adds newline character so each saved conversation is on separate line in file
+        return "Conversation saved successfully!"  # Returns success message to display to user
+    except Exception as e:  # Catches any errors during file operations (permission issues, disk full, etc.)
+        return f"Error saving conversation: {str(e)}"  # Returns formatted error message with details
+
+# Function to delete all conversations (user-specific)
+def delete_all_conversations(api_key):  # Defines function to permanently delete user's conversation file
+    if not api_key:  # Checks if API key is missing or empty
+        return "Please enter your OpenAI API key first."  # Returns error message requiring API key
+    
+    try:  # Begins try block to handle file deletion errors
+        user_file = get_user_file(api_key)  # Generates filename for this user's conversations
+        if os.path.exists(user_file):  # Checks if file actually exists before attempting deletion
+            os.remove(user_file)  # Deletes the file from disk permanently
+            return "All your conversations deleted successfully!"  # Returns success confirmation message
+        return "No conversations to delete."  # Returns message if file doesn't exist (nothing to delete)
+    except Exception as e:  # Catches errors like permission denied, file in use, etc.
+        return f"Error deleting conversations: {str(e)}"  # Returns error message with details for debugging
+
+# Function to load previous conversations (user-specific)
+def load_conversations(api_key):  # Defines function that retrieves and displays user's saved conversations
+    if not api_key:  # Checks if API key is missing, empty, or None
+        return "Please enter your OpenAI API key first to view your conversations."  # Returns error message prompting for API key
+    
+    user_file = get_user_file(api_key)  # Generates unique filename for this user based on their API key (e.g., "conversations_abc123.json")
+    
+    if os.path.exists(user_file):  # Checks if the user's conversation file actually exists on disk
+        try:  # Begins try block to handle file reading and parsing errors
+            with open(user_file, "r") as f:  # Opens user's file in read mode; auto-closes when done
+                conversations = [json.loads(line) for line in f]  # List comprehension: reads each line, parses JSON, creates list of conversation dictionaries
+            
+            conv_text = ""  # Initializes empty string to build formatted conversation display
+            for i, conv in enumerate(conversations):  # Loops through conversations with index (i) and conversation data (conv)
+                conv_text += f"\n{'='*50}\nConversation {i + 1}\n{'='*50}\n"  # Adds separator line (50 equals signs), conversation number header, and another separator
+                timestamp = conv.get("timestamp", "Unknown time")  # Retrieves timestamp from conversation dict; defaults to "Unknown time" if key doesn't exist
+                conv_text += f"Timestamp: {timestamp}\n\n"  # Adds timestamp to output with two newlines for spacing
+                
+                messages = conv.get("messages", conv)  # Gets messages list from conversation; if "messages" key doesn't exist, uses entire conv dict as fallback
+                for message in messages:  # Loops through each message dictionary in the messages list
+                    role = message.get('role', 'unknown')  # Extracts role (user/assistant); defaults to 'unknown' if not found
+                    content = message.get('content', '')  # Extracts message content; defaults to empty string if not found
+                    conv_text += f"{role.upper()}: {content}\n\n"  # Adds formatted message with role in uppercase, content, and spacing
+            
+            return conv_text if conv_text else "No previous conversations found."  # Returns formatted text if any exists; otherwise returns "not found" message (ternary operator)
+        except Exception as e:  # Catches any errors during file reading or JSON parsing
+            return f"Error loading conversations: {str(e)}"  # Returns error message with exception details
+    return "No previous conversations found for your account."  # Returns message if file doesn't exist (user has no saved conversations)
+
+# Function to clear current conversation
+def clear_conversation():  # Defines function to reset the current chat session
+    global conversation_history  # Accesses global conversation_history variable to modify it
+    conversation_history = []  # Resets conversation_history to empty list, clearing all messages
+    return []  # Returns empty list to clear the Gradio chat interface display
+
+# Create Gradio interface
+with gr.Blocks(title="Chat with Documents 💬 📚", theme=gr.themes.Ocean()) as demo:  # Creates Gradio app using Blocks API (custom layout); sets browser tab title and applies Ocean color theme; assigns to 'demo' variable
+    gr.Markdown("# Chat with Documents 💬 📚")  # Displays large heading text using Markdown syntax (# = h1)
+    gr.Markdown("Upload PDF or DOCX files and chat with them using AI!")  # Displays instruction text as second line
+    gr.Markdown("**Privacy Notice:** Your conversations are private and tied to your API key. Only you can see your saved conversations.")  # Displays privacy notice in bold (**text** = bold in Markdown)
+    
+    with gr.Row():  # Creates horizontal row container to arrange elements side-by-side
+        with gr.Column(scale=2):  # Creates column inside row with scale=2 (takes 2/3 of width when combined with scale=1 column later)
+            api_key_input = gr.Textbox(  # Creates text input box for API key
+                label="OpenAI API Key",  # Sets label displayed above the textbox
+                type="password",  # Masks input characters with dots/asterisks for security
+                placeholder="Enter your OpenAI API key here..."  # Shows gray hint text when box is empty
+            )
+            
+            file_upload = gr.File(  # Creates file upload widget
+                label="Upload PDF or DOCX files",  # Sets label above file upload area
+                file_count="multiple",  # Allows user to select multiple files at once
+                file_types=[".pdf", ".docx"]  # Restricts file picker to only show PDF and DOCX files
+            )
+            
+            load_btn = gr.Button("Load Documents", variant="primary")  # Creates button with text "Load Documents"; variant="primary" makes it blue/highlighted
+            load_status = gr.Textbox(label="Status", interactive=False)  # Creates read-only textbox to display status messages; interactive=False prevents user editing
+            
+            load_btn.click(  # Defines what happens when load_btn is clicked
+                fn=load_data,  # Calls load_data function when button clicked
+                inputs=[file_upload, api_key_input],  # Passes file_upload and api_key_input values as arguments to load_data
+                outputs=load_status  # Displays return value from load_data in load_status textbox
+            )
+    
+    with gr.Row():  # Creates another horizontal row below the first one
+        with gr.Column(scale=3):  # Creates column with scale=3 (takes 3/4 width; main chat area)
+            chatbot = gr.Chatbot(  # Creates chatbot interface component for displaying conversation
+                label="Chat",  # Sets label above chat window
+                height=400  # Sets chat window height to 400 pixels
+            )
+            msg = gr.Textbox(  # Creates text input for user to type questions
+                label="Your Question",  # Label displayed above input box
+                placeholder="Ask a question about your documents..."  # Hint text shown when empty
+            )
+            
+            with gr.Row():  # Creates row inside column for button group
+                submit_btn = gr.Button("Send", variant="primary")  # Creates primary (highlighted) Send button
+                clear_btn = gr.Button("Clear Chat")  # Creates Clear Chat button with default styling
+            
+            with gr.Row():  # Creates another row for save functionality
+                save_btn = gr.Button("Save Conversation")  # Creates button to save chat history
+                save_status = gr.Textbox(label="Save Status", interactive=False)  # Read-only textbox for save confirmation messages
+        
+        with gr.Column(scale=1):  # Creates sidebar column with scale=1 (takes 1/4 width; for conversation history)
+            gr.Markdown("### Your Previous Conversations")  # Displays h3 heading (### = h3 in Markdown)
+            load_convs_btn = gr.Button("Load Your Conversations")  # Creates button to retrieve saved conversations
+            convs_display = gr.Textbox(  # Creates large textbox for displaying conversation history
+                label="Conversation History",  # Label above the textbox
+                lines=20,  # Sets textbox height to 20 lines of text
+                interactive=False  # Makes textbox read-only (user cannot edit)
+            )
+            delete_all_btn = gr.Button("Delete All Your Conversations", variant="stop")  # Creates red warning-style button for deletion; variant="stop" makes it red
+            delete_status = gr.Textbox(label="Delete Status", interactive=False)  # Read-only textbox for deletion confirmation messages
+    
+    # Event handlers
+    submit_btn.click(  # Defines behavior when Send button is clicked
+        fn=chat_with_docs,  # Calls chat_with_docs function
+        inputs=[msg, chatbot, api_key_input],  # Passes message text, current chat history, and API key as arguments
+        outputs=chatbot  # Updates chatbot display with return value (new conversation history)
+    ).then(  # Chains another action after the first completes
+        lambda: "",  # Anonymous function that returns empty string
+        outputs=msg  # Clears the message input box after sending
+    )
+    
+    msg.submit(  # Defines behavior when user presses Enter key in message textbox
+        fn=chat_with_docs,  # Calls same chat function as submit button
+        inputs=[msg, chatbot, api_key_input],  # Same inputs as submit button
+        outputs=chatbot  # Updates chat display
+    ).then(  # Chains follow-up action
+        lambda: "",  # Returns empty string
+        outputs=msg  # Clears message box after Enter is pressed
+    )
+    
+    clear_btn.click(  # Defines behavior when Clear Chat button clicked
+        fn=clear_conversation,  # Calls clear_conversation function (resets conversation_history to [])
+        outputs=chatbot  # Updates chatbot display with empty list (clears visible chat)
+    )
+    
+    save_btn.click(  # Defines behavior when Save Conversation button clicked
+        fn=save_conversation,  # Calls save_conversation function to write to JSON file
+        inputs=[api_key_input],  # Passes API key to identify which user's file to save to
+        outputs=save_status  # Displays success/error message in save_status textbox
+    )
+    
+    load_convs_btn.click(  # Defines behavior when Load Your Conversations button clicked
+        fn=load_conversations,  # Calls load_conversations function to read from user's JSON file
+        inputs=[api_key_input],  # Passes API key to identify which user's file to load
+        outputs=convs_display  # Displays formatted conversation history in convs_display textbox
+    )
+    
+    delete_all_btn.click(  # Defines behavior when Delete All button clicked
+        fn=delete_all_conversations,  # Calls delete_all_conversations function to remove user's file
+        inputs=[api_key_input],  # Passes API key to identify which file to delete
+        outputs=delete_status  # Displays confirmation/error message in delete_status textbox
+    )
+
+if __name__ == "__main__":  # Python idiom: only runs code below if script is executed directly (not imported as module)
+    demo.launch()  # Starts Gradio web server and opens app in browser; makes app accessible at local URL (e.g., http://127.0.0.1:7860)