Update app.py

app.py

@@ -1,78 +1,246 @@
 ############################################################################################################
-# Importing Libraries
+# Importing Libraries - Core dependencies for the Schema Study App
+#
+# This app helps students learn biology concepts through interactive conversations
+# with an AI tutor, guided by course-specific terms and schemas.
+############################################################################################################
 
-import streamlit as st
-import hmac
-import pandas as pd
-import random
-import os
-import time
-import base64
-import logging
-import io
-import config
-from openai import OpenAI
+import streamlit as st          # Web app framework
+import hmac                     # Secure password validation
+import pandas as pd             # Data handling
+import os                       # File operations
+import logging                  # Logging functionality
+import config                   # Local configuration module
+from openai import OpenAI       # OpenAI API client
 
-# Set up logging
+# Set up logging to track app activity
 logging.basicConfig(filename='app.log', level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S')
 
 ############################################################################################################
-# Password protection
+# Theme Configuration - UI appearance and layout settings
+############################################################################################################
 
-def check_credentials():
-    """Returns `True` if the user had the correct username and password."""
+# Set page layout, icon, and meta information
+st.set_page_config(
+    layout="wide",
+    initial_sidebar_state="collapsed",
+    page_title="Schema Study - BILD 5",
+    page_icon="📚",
+    menu_items={
+        'Get Help': 'https://keefereuther.com',
+        'Report a bug': "mailto:kdreuther@ucsd.edu",
+        'About': "# Schema Study\n An AI-enhanced study app for biology students."
+    }
+)
+
+# Apply custom CSS for better visual appearance
+st.markdown("""
+    <style>
+        /* Overall app styling */
+        .main .block-container {
+            padding-top: 1rem;
+        }
+        
+        /* Chat container styling */
+        .stChatMessage {
+            padding: 1rem;
+            border-radius: 0.5rem;
+            margin-bottom: 1rem;
+            border: 1px solid rgba(38, 70, 83, 0.1);
+        }
+        
+        /* User message styling */
+        .stChatMessage[data-testid="user"] {
+            background-color: rgba(231, 111, 81, 0.1);
+            color: #264653;
+            border-left: 4px solid #E76F51;
+        }
+        
+        /* Assistant message styling */
+        .stChatMessage[data-testid="assistant"] {
+            background-color: rgba(42, 157, 143, 0.1);
+            color: #264653;
+            border-left: 4px solid #2A9D8F;
+        }
+        
+        /* Success message styling */
+        .stSuccess {
+            background-color: rgba(42, 157, 143, 0.2);
+            border-left: 4px solid #2A9D8F;
+            color: #264653;
+        }
+        
+        /* Warning message styling */
+        .stWarning {
+            background-color: rgba(233, 196, 106, 0.2);
+            border-left: 4px solid #E9C46A;
+            color: #264653;
+        }
+        
+        /* Error message styling */
+        .stError {
+            background-color: rgba(231, 111, 81, 0.2);
+            border-left: 4px solid #E76F51;
+            color: #264653;
+        }
+        
+        /* Chat input box styling */
+        .stChatInputContainer {
+            background-color: rgba(42, 157, 143, 0.05);
+            border-radius: 0.5rem;
+            padding: 0.5rem;
+        }
+        
+        .stTextInput input {
+            border: 1px solid #2A9D8F !important;
+        }
+        
+        /* Template button styling */
+        .stButton button {
+            border: 1px solid #2A9D8F !important;
+            border-radius: 6px !important;
+            background-color: rgba(42, 157, 143, 0.1) !important;
+            color: #264653 !important;
+            font-weight: 500 !important;
+            box-shadow: none !important;
+            width: 100%;
+            text-align: center;
+            transition: all 0.2s ease;
+        }
+        
+        /* Button hover effect */
+        .stButton button:hover {
+            background-color: rgba(42, 157, 143, 0.2) !important;
+            border-color: #2A9D8F !important;
+            transform: translateY(-1px);
+            box-shadow: 0 2px 4px rgba(42, 157, 143, 0.2) !important;
+        }
+        
+        /* Specific button for clear chat */
+        [data-testid="baseButton-secondary"] {
+            border-color: #F4A261 !important;
+            background-color: rgba(244, 162, 97, 0.1) !important;
+            color: #264653 !important;
+        }
+        
+        [data-testid="baseButton-secondary"]:hover {
+            background-color: rgba(244, 162, 97, 0.2) !important;
+            border-color: #F4A261 !important;
+        }
+        
+        /* Sidebar styling */
+        .st-emotion-cache-16txtl3 {
+            background-color: rgba(38, 70, 83, 0.03);
+        }
+        
+        /* Header and subheader styling */
+        h1, h2, h3 {
+            color: #264653;
+        }
+        
+        /* Expander styling */
+        .streamlit-expanderHeader {
+            background-color: rgba(233, 196, 106, 0.1);
+            border-radius: 4px;
+            border: none;
+            color: #264653;
+        }
+        
+        .streamlit-expanderHeader:hover {
+            background-color: rgba(233, 196, 106, 0.2);
+        }
+        
+        /* Selectbox styling */
+        .stSelectbox label {
+            color: #264653;
+        }
+        
+        .stSelectbox div[data-baseweb="select"] > div {
+            background-color: rgba(42, 157, 143, 0.05);
+            border-color: #2A9D8F;
+        }
+    </style>
+""", unsafe_allow_html=True)
+
+############################################################################################################
+# Initialize all session state variables - Persistent data between app reruns
+############################################################################################################
+
+# Initialize core session state variables if they don't exist
+if 'selected_term' not in st.session_state:
+    st.session_state.selected_term = None        # Currently selected term
+if 'selected_context' not in st.session_state:
+    st.session_state.selected_context = None     # Context for the selected term
+if 'display_messages' not in st.session_state:
+    st.session_state.display_messages = []       # Chat history
+if 'display_term' not in st.session_state:
+    st.session_state.display_term = False        # Whether to display the term
+if 'initial_message_displayed' not in st.session_state:
+    st.session_state.initial_message_displayed = False  # Initial message flag
+if 'old_term' not in st.session_state:
+    st.session_state.old_term = None             # Previously selected term
+if 'seen_terms' not in st.session_state:
+    st.session_state.seen_terms = set()          # Set of viewed terms
+if 'openai_model' not in st.session_state:
+    st.session_state.openai_model = config.ai_model  # AI model being used
+
+############################################################################################################
+# Password protection - User authentication functionality
+############################################################################################################
 
+def check_credentials():
+    """Verifies username and password against stored credentials.
+    
+    Returns:
+        bool: True if credentials are valid, False otherwise.
+    """
     def credentials_entered():
-        """Checks whether the entered username and password are correct."""
+        """Callback for when credentials are entered by the user."""
         if (
             hmac.compare_digest(st.session_state["username"], st.secrets["username"]) and
             hmac.compare_digest(st.session_state["password"], st.secrets["password"])
         ):
             st.session_state["credentials_correct"] = True
-            del st.session_state["username"]  # Don't store the username.
-            del st.session_state["password"]  # Don't store the password.
+            del st.session_state["username"]  # Remove for security
+            del st.session_state["password"]  # Remove for security
         else:
             st.session_state["credentials_correct"] = False
 
-    # Return True if the credentials are validated.
+    # Return True if already validated in this session
     if st.session_state.get("credentials_correct", False):
         return True
 
-    # Show input for username and password.
+    # Display login form
     st.text_input("Username", on_change=credentials_entered, key="username")
     st.text_input("Password", type="password", on_change=credentials_entered, key="password")
     
+    # Log invalid login attempts for security monitoring
     if "credentials_correct" in st.session_state:
-        logging.warning("Invalid login attempt")  # Log invalid login attempts
+        logging.warning("Invalid login attempt")  
     return False
 
+# Validate user credentials before proceeding
 if not check_credentials():
-    st.stop()  # Do not continue if check_credentials is not True.
+    st.stop()  # Stop execution if authentication fails
 else:
     logging.info("Successful login")  # Log successful logins
 
 ############################################################################################################
-# Streamlit app layout
-
-# Set the page to wide or centered mode
-st.set_page_config(
-    layout="wide",
-    initial_sidebar_state="collapsed"   # ✨ keeps sidebar closed on first load
-)
-
-# Load the terms file into a DataFrame
-df = pd.read_csv(config.default_terms_csv)
-
-# Streamlit app layout
-st.title(config.app_title)
-st.markdown(config.intro_para)
-st.caption(config.app_author)
-
+# Loading Terms - Data loading and preparation functions
 ############################################################################################################
-# Loading Terms
+
+# Load the terms file
+terms = pd.read_csv(config.default_terms_csv)
 
 def load_terms(file_path):
-    """Loads the CSV from the directory."""
+    """Loads terms from a CSV file containing terms and definitions.
+    
+    Args:
+        file_path (str): Path to the CSV file.
+        
+    Returns:
+        DataFrame: Loaded terms data or empty DataFrame on error.
+    """
     try:
         return pd.read_csv(file_path)
     except Exception as e:
@@ -80,195 +248,214 @@ def load_terms(file_path):
         logging.exception(f"Error loading file: {e}")
         return pd.DataFrame()
 
-# Function to extract the first column values
 def get_first_column_values(local_df):
+    """Extracts values from the first column of a DataFrame.
+    
+    Args:
+        local_df (DataFrame): DataFrame containing terms.
+        
+    Returns:
+        list: List of terms from the first column.
+    """
     if not local_df.empty:
         return local_df.iloc[:, 0].tolist()
     else:
         return []
 
-
-############################################################################################################
-# Prepare terms (no user file uploader anymore—only config.default_terms_csv)
-
+# Prepare terms for the app
 terms = load_terms(config.default_terms_csv)
 term_list = get_first_column_values(terms)
 
-
 ############################################################################################################
-# Term Selection and session state
-
-# Initialize the session state variables for selected term, context, and display messages
-if 'selected_term' not in st.session_state:
-    st.session_state.selected_term = None
-if 'selected_context' not in st.session_state:
-    st.session_state.selected_context = None
-if 'display_messages' not in st.session_state:
-    st.session_state.display_messages = []
-
-# Initialize session states for the selected term, counter, and display flag
-if 'display_term' not in st.session_state:
-    st.session_state.display_term = False
-if 'initial_message_displayed' not in st.session_state:
-    st.session_state.initial_message_displayed = False
-
-# Initialize state to track the previously selected term
-if 'old_term' not in st.session_state:
-    st.session_state.old_term = None
+# Streamlit app layout - Main UI components and interaction logic
+############################################################################################################
 
-# Dropdown menu for selecting a term
-selected_term = st.selectbox('**SELECT FROM THE DROPDOWN MENU**', term_list)
+# Create two columns with a 1:2 ratio for the main layout
+left_col, right_col = st.columns([1, 2])
 
-if selected_term:
-    # If a new term is selected (including first time selection), reset or show the message
-    if selected_term != st.session_state.old_term:
-        user_message = f"What is one thing you know about '{selected_term}'? What do you want to know about it? This could include a definition, examples, misconceptions, associations with other course terms, opinions, etc."
-        st.session_state["display_messages"].append({"role": "user", "content": user_message})
-        # Update old_term in session state
-        st.session_state.old_term = selected_term
+# Left column for app info, term selection, current term, prompt templates, and instructions
+with left_col:
+    # App header
+    st.header(config.app_title)
+    st.markdown("---")
     
-    selected_context = terms.loc[terms['TERM'] == selected_term, 'CONTEXT'].values[0]
-    st.session_state.selected_term = selected_term
-    st.session_state.selected_context = selected_context
-    st.session_state.display_term = True
+    # Term selection dropdown
+    selected_term = st.selectbox('**SELECT FROM THE DROPDOWN MENU**', term_list)
+    if selected_term:
+        # Display selected term
+        st.markdown(f"### {selected_term}")
+        
+        # Handle new term selection
+        if selected_term != st.session_state.old_term:
+            # Get context for the selected term
+            term_context = terms[terms.iloc[:, 0] == selected_term].iloc[:, 1].values[0] if not terms.empty else ""
+            
+            # Update session state
+            st.session_state.selected_context = term_context
+            st.session_state.selected_term = selected_term
+            
+            # Create initial user message
+            user_message = f"What is one thing you know about '{selected_term}'? What do you want to know about it? This could include a definition, examples, misconceptions, associations with other course terms, opinions, etc. You may also choose one of the template buttons on the left to help you get started."
+            st.session_state["display_messages"].append({"role": "user", "content": user_message})
+            
+            # Save current term as previous term
+            st.session_state.old_term = selected_term
+            st.rerun()
+            
+    # Template buttons section
+    st.markdown("**Prompt Templates:**")
     
-    # Update the prompt for the API
-    updated_prompt = config.term_prompt(st.session_state.selected_term, st.session_state.selected_context, term_list)
+    # Calculate layout for template buttons (3 per row)
+    buttons_per_row = 3
+    num_rows = (len(config.prompt_templates) + buttons_per_row - 1) // buttons_per_row
     
-else:
-    # If nothing is selected or the selection is cleared, reset the old_term
-    st.session_state.old_term = None
-
-# Display the selected term and its context
-if st.session_state.display_term and st.session_state.selected_term:
-    st.header(st.session_state.selected_term)
-
-with st.expander("INSTRUCTIONS FOR STUDENTS:"):
-    st.markdown(config.instructions)
-
-############################################################################################################
-# ChatGPT
-# Initialize the OpenAI client
-client = OpenAI(api_key=st.secrets["OPENAI_API_KEY"])
-
-# Initialize the session state variables if they don't exist
-if "openai_model" not in st.session_state:
-    st.session_state["openai_model"] = config.ai_model
-
-if "display_messages" not in st.session_state:
-    st.session_state.display_messages = []
-
-# Update initial_context with the latest selected term and context
-if st.session_state.get('selected_term') and st.session_state.get('selected_context'):
-    updated_prompt = config.term_prompt(st.session_state.selected_term, st.session_state.selected_context, term_list)
-    # Replace the initial context in display_messages with the updated prompt
-    if st.session_state.display_messages:
-        st.session_state.display_messages[0]["content"] = updated_prompt
-    else:
-        st.session_state.display_messages = [{"role": "system", "content": updated_prompt}]
-
-# Get user input
-prompt = st.chat_input("What do you know? What do you want to know?")
-
-# Input for new messages
-if prompt:
-    # Ensure the initial context is in the session state, add the user's message
-    if not st.session_state["display_messages"]:
-        st.session_state["display_messages"].append(initial_context)
-    st.session_state["display_messages"].append({"role": "user", "content": prompt})
-
-# Function to reset all chat-related session state
-def reset_chat_history():
-    st.session_state["display_messages"] = []
-    # Reset other chat-related session states if they exist
-    if 'selected_term' in st.session_state:
-        st.session_state.selected_term = None
-    if 'selected_context' in st.session_state:
-        st.session_state.selected_context = None
-    if 'display_term' in st.session_state:
-        st.session_state.display_term = False
-    st.rerun()
-
-# Main chat container
-with st.container(height=400, border=True):
-    # Display chat history in reverse order including new messages
-    for message in st.session_state["display_messages"][1:]:
-        if message["role"] == "user":
-            with st.chat_message("user"):
-                st.markdown(message["content"])
-        else:
-            with st.chat_message("assistant"):
-                st.markdown(message["content"])
-
-# Generate assistant's response and add it to the messages
-    if prompt:
-        with st.chat_message("assistant"):
+    # Emoji mapping for templates
+    template_emojis = {
+        "Misconception Check": "❓",
+        "Two Truths & a Lie": "🎮",
+        "Connect Terms": "🔄",
+        "Schema Map": "🗺️",
+        "Create a Study Plan": "📚"
+    }
+    
+    # Create rows of template buttons
+    for row in range(num_rows):
+        # Create columns for this row
+        start_idx = row * buttons_per_row
+        end_idx = min(start_idx + buttons_per_row, len(config.prompt_templates))
+        btn_cols = st.columns(end_idx - start_idx)
+        
+        # Add buttons for this row
+        for i, template in enumerate(config.prompt_templates[start_idx:end_idx]):
+            template_name = template["name"]
+            # Add emoji to template name
+            button_text = f"{template_emojis.get(template_name, '')} {template_name}"
+            
+            # Create button and handle click
+            if btn_cols[i].button(button_text, key=f"btn_{row}_{i}"):
+                # Format template with appropriate variables
+                if "term_list" in template["template"]:
+                    formatted_content = template["template"].format(term=selected_term, term_list=term_list)
+                else:
+                    formatted_content = template["template"].format(term=selected_term)
+                
+                # Add to chat messages and trigger LLM response
+                st.session_state.display_messages.append({"role": "user", "content": formatted_content})
+                st.session_state["trigger_llm"] = True
+                st.rerun()
+                
+    # Instructions for students
+    with st.expander("INSTRUCTIONS FOR STUDENTS:"):
+        st.markdown(config.instructions)
+
+# Right column for chat window and input
+with right_col:
+    # Main chat container - displays conversation history
+    with st.container(height=450, border=True):
+        # Display previous chat messages
+        for message in st.session_state["display_messages"][1:]:
+            if message["role"] == "user":
+                with st.chat_message("user"):
+                    st.markdown(message["content"])
+            else:
+                with st.chat_message("assistant"):
+                    st.markdown(message["content"])
+
+        # Generate and display AI response when triggered
+        if st.session_state.get("trigger_llm", False):
             try:
+                # Initialize OpenAI client
+                client = OpenAI(api_key=st.secrets["OPENAI_API_KEY"])
+                
+                # Generate system message with term context
+                system_message = config.term_prompt(
+                    selected_term=st.session_state.selected_term,
+                    selected_context=st.session_state.selected_context,
+                    term_list=term_list
+                )
+                
+                # Prepare messages for API call
+                messages = [{"role": "system", "content": system_message}] + [
+                    {"role": m["role"], "content": m["content"]} 
+                    for m in st.session_state["display_messages"]
+                ]
+                
+                # Create streaming completion
                 stream = client.chat.completions.create(
                     model=st.session_state["openai_model"],
-                    messages=[
-                        {"role": m["role"], "content": m["content"]}
-                        for m in st.session_state["display_messages"]
-                    ],
+                    messages=messages,
                     stream=True,
                     temperature=config.temperature,
                     max_tokens=config.max_tokens,
                     frequency_penalty=config.frequency_penalty,
                     presence_penalty=config.presence_penalty,
                 )
-                response = st.write_stream(stream)
-                # Append the full response to the session state for display
-                st.session_state["display_messages"].append(
-                    {"role": "assistant", "content": response}
-                )
-                logging.info(f"User prompt: {prompt}")  # Log user prompts
-                logging.info(f"Assistant response: {response}")  # Log assistant responses
+                
+                # Display streaming response
+                with st.chat_message("assistant"):
+                    response = st.write_stream(stream)
+                    # Save response to chat history
+                    st.session_state["display_messages"].append({"role": "assistant", "content": response})
+                    # Log the exchange
+                    logging.info(f"User prompt: {st.session_state['display_messages'][-2]['content']}")
+                    logging.info(f"Assistant response: {response}")
             except Exception as e:
+                # Handle errors
                 st.error(f"An error occurred: {str(e)}")
-                logging.exception(f"Error generating response: {e}")  # Log errors
+                logging.exception(f"Error generating response: {e}")
+            
+            # Reset trigger flag after response is generated
+            st.session_state["trigger_llm"] = False
 
-# Add Clear Chat History button between container and warning message
-if st.button("Clear Chat History"):
-    reset_chat_history()
-    logging.info("Chat history cleared")  # Log when chat history is cleared
+    # Chat input field
+    prompt = st.chat_input("What do you know? What do you want to know?")
+    if prompt:
+        # Add user message to chat and trigger LLM response
+        st.session_state.display_messages.append({"role": "user", "content": prompt})
+        st.session_state["trigger_llm"] = True
+        st.rerun()
 
-st.markdown(config.warning_message, unsafe_allow_html=True)
+    # Clear chat history button
+    if st.button("Clear Chat History"):
+        st.session_state["display_messages"] = []
+        st.session_state["trigger_llm"] = False
+        st.rerun()
 
-############################################################################################################
+    # Warning message about AI limitations
+    st.markdown(config.warning_message, unsafe_allow_html=True)
 
-# Resources and About Sections in the Sidebar
+############################################################################################################
+# Sidebar Content - Resources and information
+############################################################################################################
 
+# Resources section
 st.sidebar.title("Resources")
 
+# Display each resource
 for resource in config.resources:
-    with st.sidebar:
-        with st.sidebar:
-            with st.expander(resource["title"]):
-                st.markdown(f"Description: {resource['description']}")
-                if "url" in resource:
-                    st.markdown(f"[{resource['title']}]({resource['url']})")
-                if "file_path" in resource:
-                    file_path = resource["file_path"]
-                    if os.path.exists(file_path):
-                        with open(file_path, "rb") as file:
-                            file_bytes = file.read()
-                        with st.spinner(f"Loading {resource['title']}..."):
-                            st.download_button(
-                                label=resource["title"],
-                                data=file_bytes,
-                                file_name=os.path.basename(file_path),
-                                mime="application/octet-stream",
-                                help=resource["description"],
-                            )
-                    else:
-                        st.warning(f"File not found: {file_path}")
-
-# Footer
-with st.sidebar:
-    st.markdown("---")
-
-    st.title("About")
-
-   # Using the config objects in your Streamlit app
-    st.markdown(config.app_creation_message, unsafe_allow_html=True)
-    st.markdown(config.app_repo_license_message, unsafe_allow_html=True)
+    st.sidebar.markdown(f"### {resource['title']}")
+    st.sidebar.markdown(resource['description'])
+    
+    # Add URL link if available
+    if "url" in resource:
+        st.sidebar.markdown(f"[Open Link]({resource['url']})")
+    
+    # Add file download button if available
+    if "file_path" in resource:
+        with open(resource["file_path"], "rb") as file:
+            btn = st.sidebar.download_button(
+                label=f"Download {resource['title']}",
+                data=file,
+                file_name=os.path.basename(resource["file_path"]),
+                mime="application/pdf"
+            )
+    
+    # Separator between resources
+    st.sidebar.markdown("---")
+
+# About section
+st.sidebar.markdown("### About")
+st.sidebar.markdown(config.app_creation_message)
+st.sidebar.markdown("---")
+st.sidebar.markdown(config.app_repo_license_message)
+st.sidebar.markdown("---")