UI v31

app.py

@@ -12,12 +12,14 @@ try:
 except ImportError:
     print("Error: Could not import VectorDatabase from vector_db.py.")
     print("Please ensure vector_db.py exists in the same directory and is correctly defined.")
+    # Exit if critical dependency is missing at import time
     exit(1)
 
 try:
     from langchain_openai import ChatOpenAI
 except ImportError:
     print("Error: langchain-openai not found. Please install it: pip install langchain-openai")
+    # Exit if critical dependency is missing at import time
     exit(1)
 
 from langchain.prompts import PromptTemplate
@@ -35,7 +37,7 @@ logging.basicConfig(
     format='%(asctime)s - %(levelname)s - [%(filename)s:%(lineno)d] - %(message)s'
 )
 
-# --- RAGSystem Class (Processing Logic - KEPT INTACT) ---
+# --- RAGSystem Class (Processing Logic - KEPT INTACT AS REQUESTED) ---
 class RAGSystem:
     def __init__(self, vector_db: Optional[VectorDatabase] = None):
         logging.info("Initializing RAGSystem")
@@ -146,7 +148,7 @@ Answer:"""
                     context_parts.append(f"**Source: State Summary (State: {state_label})**\n{state_doc_content}")
 
             if context_parts:
-                context = "\n\n---\n\n". தலைமையில்".join(context_parts)
+                context = "\n\n---\n\n".join(context_parts)
                 logging.info(f"Constructed context with {len(context_parts)} parts. Length: {len(context)} chars.")
                 try:
                     statutes_from_context = self.extract_statutes(context)
@@ -171,7 +173,7 @@ Answer:"""
 
             if not answer_text:
                 logging.warning("LLM returned an empty answer.")
-                answer_text = "<div class='error-message'>The AI model returned an empty response. This might be due to the query, context limitations, or temporary issues. Please try rephrasing your question or try again later.</div>"
+                answer_text = "<div class='error-message'><span class='error-icon'>⚠️</span>The AI model returned an empty response. This might be due to the query, context limitations, or temporary issues. Please try rephrasing your question or try again later.</div>"
             else:
                 logging.info("LLM generated answer successfully.")
 
@@ -194,7 +196,7 @@ Answer:"""
                 error_message = "Error: The request to the AI model timed out. The service might be busy."
                 details = "Please try again in a few moments."
 
-            formatted_error = f"<div class='error-message'>{error_message}</div>"
+            formatted_error = f"<div class='error-message'><span class='error-icon'>❌</span>{error_message}</div>"
             if details:
                 formatted_error += f"<div class='error-details'>{details}</div>"
 
@@ -222,6 +224,7 @@ Answer:"""
             raise FileNotFoundError(f"PDF file not found: {pdf_path}")
         try:
             logging.info(f"Attempting to load/verify data from PDF: {pdf_path}")
+            # Assuming process_and_load_pdf is part of VectorDatabase and correctly implemented
             num_states_processed = self.vector_db.process_and_load_pdf(pdf_path)
             doc_count = self.vector_db.document_collection.count()
             state_count = self.vector_db.state_collection.count()
@@ -239,35 +242,40 @@ Answer:"""
             logging.error(f"Failed to load or process PDF '{pdf_path}': {str(e)}", exc_info=True)
             raise RuntimeError(f"Failed to process PDF '{pdf_path}': {e}") from e
 
-    # --- GRADIO INTERFACE (PROFESSIONAL DESIGN) ---
+    # --- GRADIO INTERFACE (NEW UI DESIGN) ---
     def gradio_interface(self):
         def query_interface_wrapper(api_key: str, query: str, state: str) -> str:
+            # Basic client-side validation for immediate feedback (redundant but good UX)
             if not api_key or not api_key.strip() or not api_key.startswith("sk-"):
-                return "<div class='error-message'>Please provide a valid OpenAI API key (starting with 'sk-'). <a href='https://platform.openai.com/api-keys' target='_blank'>Get one free from OpenAI</a>.</div>"
+                return "<div class='error-message'><span class='error-icon'>⚠️</span>Please provide a valid OpenAI API key (starting with 'sk-'). <a href='https://platform.openai.com/api-keys' target='_blank'>Get one free from OpenAI</a>.</div>"
             if not state or state == "Select a state..." or "Error" in state:
-                return "<div class='error-message'>Please select a valid state from the dropdown.</div>"
+                return "<div class='error-message'><span class='error-icon'>⚠️</span>Please select a valid state from the dropdown.</div>"
             if not query or not query.strip():
-                return "<div class='error-message'>Please enter your question in the text box.</div>"
+                return "<div class='error-message'><span class='error-icon'>⚠️</span>Please enter your question in the text box.</div>"
 
+            # Call the core processing logic
             result = self.process_query(query=query, state=state, openai_api_key=api_key)
-            answer = result.get("answer", "<div class='error-message'>An unexpected error occurred.</div>")
+            answer = result.get("answer", "<div class='error-message'><span class='error-icon'>⚠️</span>An unexpected error occurred.</div>")
 
+            # Check if the answer already contains an error message (from deeper within process_query)
             if "<div class='error-message'>" in answer:
+                # Error messages are returned directly as they contain their own styling
                 return answer
             else:
-                formatted_response_content = gr.Markdown.format(
-                    f"<div class='response-header'><span class='response-icon'>📜</span>Response for {state}</div><hr class='divider'>{answer}"
-                )
+                # Wrap successful response in a div with an animation class
+                formatted_response_content = f"<div class='response-header'><span class='response-icon'>📜</span>Response for {state}</div><hr class='divider'>{answer}"
                 return f"<div class='animated-output-content'>{formatted_response_content}</div>"
 
         try:
             available_states_list = self.get_states()
+            # Ensure "Select a state..." is always the first option
             dropdown_choices = ["Select a state..."] + (available_states_list if available_states_list and "Error" not in available_states_list[0] else ["Error: States unavailable"])
-            initial_value = dropdown_choices[0]
-        except Exception:
+            initial_value = dropdown_choices[0] # Set initial value to the prompt
+        except Exception: # Catch-all for safety
             dropdown_choices = ["Error: Critical failure loading states"]
             initial_value = dropdown_choices[0]
 
+        # Define example queries, filtering based on available states
         example_queries_base = [
             ["What are the rules for security deposit returns?", "California"],
             ["Can a landlord enter my apartment without notice?", "New York"],
@@ -278,303 +286,313 @@ Answer:"""
         example_queries = []
         if available_states_list and "Error" not in available_states_list[0] and len(available_states_list) > 0:
             loaded_states_set = set(available_states_list)
+            # Filter for examples whose state is in the loaded states
             example_queries = [ex for ex in example_queries_base if ex[1] in loaded_states_set]
+            # Add a generic example if no specific state examples match or if list is empty
             if not example_queries:
+                # Add one example using the first available state, or a common one if no states
                 example_queries.append(["What basic rights do tenants have?", available_states_list[0] if available_states_list else "California"])
-        else:
+        else: # Fallback if states list is problematic (e.g., empty or error)
             example_queries.append(["What basic rights do tenants have?", "California"])
 
 
-        # Custom CSS for a professional, clean, light, dynamic dashboard
+        # Custom CSS for better UI design, clear boundaries, and text alignment for HuggingFace
         custom_css = """
         /* Import legible fonts from Google Fonts */
         @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Poppins:wght@600;700;800&display=swap');
         
-        /* Root variables for consistent theming */
+        /* Root variables for consistent theming - adjusted for very light calm_seafoam feel */
         :root {
-            --primary-color: hsl(210, 70%, 45%); /* Professional deep blue */
-            --primary-hover: hsl(210, 70%, 35%);
-            --secondary-accent-color: hsl(40, 80%, 55%); /* Warm amber/gold for highlights */
-            --secondary-accent-hover: hsl(40, 80%, 45%);
-            
-            --background-app: hsl(200, 20%, 96%); /* Very light blue-gray for overall background */
-            --background-header: linear-gradient(135deg, hsl(200, 40%, 90%) 0%, hsl(210, 40%, 85%) 100%); /* Light blue gradient for header */
-            --background-card: hsl(0, 0%, 100%); /* Pure white for content cards */
-            --background-input: hsl(0, 0%, 100%); /* Pure white for input/output elements */
-            
-            --text-dark: hsl(210, 20%, 20%); /* Dark charcoal for primary text */
-            --text-muted: hsl(210, 10%, 45%); /* Medium gray for secondary info/placeholders */
-            --text-light: hsl(0, 0%, 100%); /* White for text on colored backgrounds */
-            
-            --border-card: hsl(210, 10%, 88%); /* Very light gray border for cards */
-            --border-input: hsl(210, 10%, 80%); /* Slightly darker gray for input borders */
-            --border-focus: var(--primary-color); /* Primary color for input focus */
-
+            --primary-color: #3cb371; /* Medium Sea Green (vibrant seafoam) */
+            --primary-hover: #339966;
+            --background-primary: hsl(180, 100%, 98%); /* Very light seafoam for main cards */
+            --background-secondary: hsl(180, 100%, 96%); /* Slightly darker for overall app background */
+            --text-primary: hsl(210, 20%, 20%); /* Dark blue-gray for main text */
+            --text-secondary: hsl(210, 10%, 45%); /* Muted blue-gray for secondary text */
+            --border-color: hsl(180, 30%, 85%); /* Subtle seafoam gray for borders */
+            --border-focus: #3cb371; /* Focus color matches primary */
             --shadow-sm: 0 1px 3px rgba(0,0,0,0.08);
-            --shadow-md: 0 4px 10px rgba(0,0,0,0.15);
-            --shadow-lg: 0 8px 20px rgba(0,0,0,0.25);
-            
-            --error-bg: hsl(0, 80%, 95%);
-            --error-border: hsl(0, 70%, 80%);
-            --error-text: hsl(0, 70%, 40%);
-            
-            --button-secondary-bg: hsl(210, 10%, 90%); /* Light gray for secondary button */
-            --button-secondary-text: var(--text-dark); /* Dark text for secondary button */
+            --shadow-md: 0 4px 10px rgba(0,0,0,0.1);
+            --shadow-lg: 0 10px 20px rgba(0,0,0,0.15);
+            --error-bg: #FFEBEB;
+            --error-border: #FFCACA;
+            --error-text: #D32F2F;
         }
         
-        /* Base container and typography */
-        body {
-            background-color: var(--background-app) !important;
-        }
+        /* Dark mode variables - for consistency if a dark mode toggle were present */
+        body.dark {
+            --background-primary: #1F303A; /* Dark blue-green */
+            --background-secondary: #2C404B;
+            --text-primary: #E0F2F1;
+            --text-secondary: #A7C5C8;
+            --border-color: #5F7C8A;
+            --primary-color: #66BB6A; /* Brighter green for dark mode */
+            --primary-hover: #5cb85f;
+            --error-bg: #3F1D1D;
+            --error-border: #5A1A1A;
+            --error-text: #FF7070;
+        }
+
+        /* Base container improvements */
         .gradio-container {
-            max-width: 900px !important;
-            margin: 0 auto !important;
+            max-width: 900px !important; /* Slightly smaller for focused content */
+            margin: 0 auto !important; /* Center the whole app */
             padding: 1.5rem !important;
             font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif !important;
-            background-color: var(--background-app) !important;
-            box-shadow: none !important;
-            border-radius: 16px !important;
+            background-color: var(--background-secondary) !important; /* Overall background */
+            box-shadow: none !important; /* Remove default gradio container shadow */
+        }
+        /* Ensure all main content sections have primary background */
+        .main-dashboard-container > * {
+            background-color: var(--background-primary) !important;
         }
 
-        /* Header Styling (distinct background) */
+        /* Header styling - centered and prominent */
         .app-header-wrapper {
-            background: var(--background-header) !important;
-            border: 2px solid var(--border-card) !important;
+            background: linear-gradient(135deg, var(--background-primary) 0%, var(--background-secondary) 100%) !important;
+            border: 2px solid var(--border-color) !important;
             border-radius: 16px !important;
-            padding: 2.5rem 1.5rem !important;
+            padding: 2.5rem 1.5rem !important; /* More vertical padding */
             margin-bottom: 1.5rem !important;
-            text-align: center !important;
+            text-align: center !important; /* Center text within header */
             box-shadow: var(--shadow-md) !important;
-            position: relative;
-            overflow: hidden;
-            color: var(--text-dark) !important;
+            position: relative; /* For potential pseudo-element effects */
+            overflow: hidden; /* For any overflow animations */
         }
-        .app-header-wrapper::before { /* Subtle background pattern */
+        .app-header-wrapper::before { /* Subtle background pattern for dynamism */
             content: '';
             position: absolute;
             top: 0;
             left: 0;
             width: 100%;
             height: 100%;
-            background: radial-gradient(circle at top left, hsla(210, 70%, 45%, 0.05) 0%, transparent 40%),
-                        radial-gradient(circle at bottom right, hsla(210, 70%, 45%, 0.05) 0%, transparent 40%);
+            background: radial-gradient(circle at top left, rgba(60,179,113,0.05) 0%, transparent 40%),
+                        radial-gradient(circle at bottom right, rgba(60,179,113,0.05) 0%, transparent 40%);
             z-index: 0;
             opacity: 0.8;
             pointer-events: none;
         }
+
         .app-header-logo {
-            font-size: 4.5rem !important;
+            font-size: 4.5rem !important; /* Larger icon */
             margin-bottom: 0.75rem !important;
             display: block !important;
-            color: var(--primary-color) !important;
+            color: var(--primary-color) !important; /* Theme color */
             position: relative;
-            z-index: 1;
+            z-index: 1; /* Bring icon to front of pseudo-element */
+            /* Animation for dynamism */
             animation: float-icon 3s ease-in-out infinite alternate;
         }
+        /* Keyframes for floating icon */
         @keyframes float-icon {
             0% { transform: translateY(0px); }
             50% { transform: translateY(-5px); }
             100% { transform: translateY(0px); }
         }
+
         .app-header-title {
             font-family: 'Poppins', sans-serif !important;
-            font-size: 3rem !important;
-            font-weight: 800 !important;
-            color: var(--primary-color) !important;
+            font-size: 3rem !important; /* Even larger title */
+            font-weight: 800 !important; /* Bolder */
+            color: var(--text-primary) !important;
             margin: 0 0 0.75rem 0 !important;
             line-height: 1.1 !important;
-            letter-spacing: -0.03em !important;
+            letter-spacing: -0.03em !important; /* Tighter spacing */
             position: relative;
             z-index: 1;
         }
         .app-header-tagline {
-            font-size: 1.25rem !important;
-            color: var(--text-muted) !important;
+            font-size: 1.25rem !important; /* Slightly larger tagline */
+            color: var(--text-secondary) !important;
             font-weight: 400 !important;
             margin: 0 !important;
-            max-width: 700px;
+            max-width: 700px; /* Constrain tagline width */
             margin-left: auto;
             margin-right: auto;
             position: relative;
             z-index: 1;
         }
 
-        /* Main Dashboard Container & Card Sections (White Backgrounds) */
+        /* Main container with consistent spacing */
         .main-dashboard-container {
             display: flex !important;
             flex-direction: column !important;
-            gap: 1.25rem !important;
+            gap: 1.25rem !important; /* Consistent spacing between cards */
         }
+        /* Card sections with clear boundaries (boundeyes) and subtle dynamic effects */
         .dashboard-card-section {
-            background: var(--background-card) !important; /* Pure white for content cards */
-            border: 2px solid var(--border-card) !important;
+            background: var(--background-primary) !important;
+            border: 2px solid var(--border-color) !important; /* Distinct border */
             border-radius: 12px !important;
-            padding: 1.75rem !important;
-            box-shadow: var(--shadow-sm) !important;
-            transition: all 0.3s ease-out !important;
-            cursor: default;
-            color: var(--text-dark) !important; /* Dark text on white cards */
+            padding: 1.75rem !important; /* Consistent padding */
+            box-shadow: var(--shadow-sm) !important; /* Subtle shadow */
+            transition: all 0.3s ease-out !important; /* Smoother transition */
+            cursor: default; /* Indicate not directly clickable (unless examples) */
         }
         .dashboard-card-section:hover {
             box-shadow: var(--shadow-md) !important;
-            transform: translateY(-5px) !important;
+            transform: translateY(-3px) !important; /* More pronounced lift */
         }
 
-        /* Section Titles (Centered & Bold) */
+        /* Centered section titles with improved typography */
         .sub-section-title {
             font-family: 'Poppins', sans-serif !important;
-            font-size: 1.7rem !important;
-            font-weight: 700 !important;
-            color: var(--primary-color) !important;
-            text-align: center !important; /* Centered */
-            margin: 0 0 1.25rem 0 !important;
+            font-size: 1.7rem !important; /* Slightly larger */
+            font-weight: 700 !important; /* Bolder */
+            color: var(--text-primary) !important;
+            text-align: center !important; /* Centered text */
+            margin: 0 0 1.25rem 0 !important; /* More space below title */
             padding-bottom: 0.75rem !important;
-            border-bottom: 2px solid var(--border-card) !important; /* Subtle separator line */
+            border-bottom: 2px solid var(--border-color) !important; /* Underline effect */
             display: block !important;
             letter-spacing: -0.01em !important;
         }
+        
+        /* Specific styling for the welcome/disclaimer markdown content */
         .dashboard-card-section p {
             line-height: 1.7 !important;
-            color: var(--text-dark) !important;
+            color: var(--text-primary) !important;
             font-size: 1rem !important;
         }
         .dashboard-card-section strong {
-            color: var(--primary-color) !important; /* Default strong text uses primary color */
-        }
-        .dashboard-card-section p > span { /* For specific highlights like 'Disclaimer:' */
-            color: var(--secondary-accent-color) !important;
-            font-weight: 600 !important;
+            color: var(--primary-color) !important; /* Highlight strong text with primary color */
         }
 
-        /* Input Styling (Pure White Backgrounds) */
+        /* Improved input styling with clear boundaries and focus */
+        .gradio-textbox, .gradio-dropdown {
+            margin-bottom: 0.75rem !important;
+        }
         .gradio-textbox textarea,
         .gradio-textbox input,
-        .gradio-dropdown > div > input[type="text"],
-        .gradio-dropdown .primary-wrap,
-        .gradio-dropdown .scroll-hide {
-            background: var(--background-input) !important; /* Pure white background for inputs */
-            border: 2px solid var(--border-input) !important; /* Light gray border */
+        .gradio-dropdown > div > input[type="text"], /* Target dropdown input for custom values */
+        .gradio-dropdown .primary-wrap, /* Target dropdown wrapper */
+        .gradio-dropdown .scroll-hide /* Target dropdown list container for consistency */
+        {
+            background: var(--background-primary) !important;
+            border: 2px solid var(--border-color) !important; /* Clear border */
             border-radius: 8px !important;
-            padding: 0.85rem 1rem !important;
+            padding: 0.85rem 1rem !important; /* Slightly more padding */
             font-size: 0.98rem !important;
             font-family: 'Inter', sans-serif !important;
-            color: var(--text-dark) !important;
-            transition: border-color 0.2s ease, box-shadow 0.2s ease !important;
+            color: var(--text-primary) !important;
+            transition: border-color 0.2s ease, box-shadow 0.2s ease !important; /* Smooth transitions */
             box-shadow: var(--shadow-sm) !important;
         }
-        .gradio-textbox textarea::placeholder,
-        .gradio-textbox input::placeholder {
-            color: var(--text-muted) !important;
-            opacity: 0.8;
-        }
         .gradio-textbox textarea:focus,
         .gradio-textbox input:focus,
         .gradio-dropdown > div > input[type="text"]:focus,
-        .gradio-dropdown .primary-wrap.focused {
+        .gradio-dropdown .primary-wrap.focused { /* Apply focus style to dropdown wrap */
             outline: none !important;
-            border-color: var(--border-focus) !important;
-            box-shadow: 0 0 0 4px hsla(210, 70%, 45%, 0.2) !important; /* Primary color glow */
+            border-color: var(--border-focus) !important; /* Distinct border on focus */
+            box-shadow: 0 0 0 4px rgba(60, 179, 113, 0.2) !important; /* Broader, softer glow on focus */
         }
+
+        /* Label styling for better readability */
         .gradio-textbox label,
         .gradio-dropdown label {
-            font-weight: 600 !important;
-            color: var(--text-dark) !important;
+            font-weight: 600 !important; /* Bolder labels */
+            color: var(--text-primary) !important;
             font-size: 1rem !important;
             margin-bottom: 0.6rem !important;
             display: block !important;
         }
+        /* Info text styling below inputs */
         .gradio-textbox .gr-form,
         .gradio-dropdown .gr-form {
             font-size: 0.9rem !important;
-            color: var(--text-muted) !important;
-            margin-top: 0.4rem !important;
+            color: var(--text-secondary) !important;
+            margin-top: 0.4rem !important; /* More space for info text */
         }
+        /* Input row layout improvements */
         .input-row {
             display: flex !important;
-            gap: 1.25rem !important;
+            gap: 1.25rem !important; /* Consistent gap between query and state */
             margin-bottom: 0.5rem !important;
         }
         .input-field {
             flex: 1 !important;
         }
 
-        /* Button Styling */
+        /* Button styling improvements with active state for dynamism */
         .button-row {
             display: flex !important;
             gap: 1rem !important;
-            justify-content: flex-end !important;
-            margin-top: 1.5rem !important;
+            justify-content: flex-end !important; /* Align buttons to the right */
+            margin-top: 1.5rem !important; /* More space above buttons */
         }
         .gradio-button {
-            padding: 0.85rem 1.8rem !important;
-            border-radius: 9px !important;
-            font-weight: 600 !important;
+            padding: 0.85rem 1.8rem !important; /* More padding for bigger buttons */
+            border-radius: 9px !important; /* Slightly more rounded */
+            font-weight: 600 !important; /* Bolder text */
             font-size: 1rem !important;
-            transition: all 0.2s ease-out !important;
+            transition: all 0.2s ease-out !important; /* Smooth transition for hover/active */
             cursor: pointer !important;
             border: 2px solid transparent !important;
-            text-align: center !important;
+            text-align: center !important; /* Ensure button text is centered */
         }
         .gr-button-primary {
-            background: var(--primary-color) !important; /* Deep blue button */
+            background: var(--primary-color) !important;
             color: white !important;
             box-shadow: var(--shadow-sm) !important;
         }
         .gr-button-primary:hover {
             background: var(--primary-hover) !important;
             box-shadow: var(--shadow-md) !important;
-            transform: translateY(-2px) !important;
+            transform: translateY(-2px) !important; /* Subtle lift effect on hover */
         }
-        .gr-button-primary:active {
-            transform: translateY(1px) !important; /* Press effect */
+        .gr-button-primary:active { /* Press down effect on click */
+            transform: translateY(1px) !important;
             box-shadow: none !important;
         }
         .gr-button-secondary {
-            background: var(--button-secondary-bg) !important; /* Light gray button */
-            color: var(--button-secondary-text) !important;
-            border-color: var(--border-input) !important;
+            background: transparent !important;
+            color: var(--text-primary) !important;
+            border-color: var(--border-color) !important;
         }
         .gr-button-secondary:hover {
-            background: hsl(210, 10%, 85%) !important;
+            background: var(--background-secondary) !important;
             border-color: var(--primary-color) !important;
             transform: translateY(-2px) !important;
         }
-        .gr-button-secondary:active {
+        .gr-button-secondary:active { /* Press down effect on click */
             transform: translateY(1px) !important;
             box-shadow: none !important;
         }
 
-        /* Output Styling (Pure White Background) */
+        /* Output styling with clear boundaries (boundeyes are clear) and dynamic fade-in */
         .output-content-wrapper {
-            background: var(--background-input) !important; /* Pure white background for output box */
-            border: 2px dashed var(--border-input) !important;
+            background: var(--background-primary) !important;
+            border: 2px solid var(--border-color) !important; /* Clear border */
             border-radius: 8px !important;
             padding: 1.5rem !important;
-            min-height: 150px !important;
-            color: var(--text-dark) !important;
+            min-height: 150px !important; /* More space for output */
+            color: var(--text-primary) !important;
+            /* Ensure the inner animated content fits well */
             display: flex;
             flex-direction: column;
-            justify-content: center;
-            align-items: center;
+            justify-content: center; /* Center content vertically if small */
+            align-items: center; /* Center content horizontally if small */
         }
+        /* The div holding the actual response content, enabling fade-in animation */
         .animated-output-content {
             opacity: 0;
-            animation: fadeInAndSlideUp 0.7s ease-out forwards;
-            width: 100%;
+            animation: fadeInAndSlideUp 0.7s ease-out forwards; /* More pronounced animation */
+            width: 100%; /* Take full width of parent */
+            /* Preserve formatting within the animated content */
             white-space: pre-wrap;
             overflow-wrap: break-word;
             word-break: break-word;
-            text-align: left !important;
-            color: var(--text-dark) !important;
+            text-align: left !important; /* Ensure text is left-aligned within this div */
         }
         @keyframes fadeInAndSlideUp {
             from { opacity: 0; transform: translateY(15px); }
             to { opacity: 1; transform: translateY(0); }
         }
+
         .response-header {
             font-size: 1.3rem !important;
             font-weight: 700 !important;
-            color: var(--primary-color) !important;
+            color: var(--primary-color) !important; /* Matches primary color */
             margin-bottom: 0.75rem !important;
             display: flex !important;
             align-items: center !important;
@@ -586,9 +604,10 @@ Answer:"""
         }
         .divider {
             border: none !important;
-            border-top: 1px dashed var(--border-input) !important;
+            border-top: 1px dashed var(--border-color) !important; /* Dashed divider for visual separation */
             margin: 1rem 0 !important;
         }
+        /* Error message styling */
         .error-message {
             background: var(--error-bg) !important;
             border: 2px solid var(--error-border) !important;
@@ -601,9 +620,9 @@ Answer:"""
             font-size: 0.95rem !important;
             font-weight: 500 !important;
             line-height: 1.6 !important;
-            text-align: left !important;
-            width: 100%;
-            box-sizing: border-box;
+            text-align: left !important; /* Ensure error message text is left aligned */
+            width: 100%; /* Take full width of parent */
+            box-sizing: border-box; /* Include padding/border in width */
         }
         .error-message a {
             color: var(--error-text) !important;
@@ -620,22 +639,23 @@ Answer:"""
             margin-top: 0.5rem !important;
             opacity: 0.8;
         }
+        /* Placeholder styling for empty output */
         .placeholder {
-            background: var(--background-input) !important;
-            border: 2px dashed var(--border-input) !important;
+            background: var(--background-secondary) !important;
+            border: 2px dashed var(--border-color) !important;
             border-radius: 8px !important;
             padding: 2.5rem 1.5rem !important;
             text-align: center !important;
-            color: var(--text-muted) !important;
+            color: var(--text-secondary) !important;
             font-style: italic !important;
             font-size: 1.1rem !important;
-            width: 100%;
-            box-sizing: border-box;
+            width: 100%; /* Ensure it takes full width of parent */
+            box-sizing: border-box; /* Include padding/border in width */
         }
 
-        /* Examples Table Styling (Pure White Background Rows) */
+        /* Examples table styling with dynamic hover */
         .examples-section .gr-samples-table {
-            border: 2px solid var(--border-card) !important;
+            border: 2px solid var(--border-color) !important;
             border-radius: 8px !important;
             overflow: hidden !important;
             margin-top: 1rem !important;
@@ -645,59 +665,56 @@ Answer:"""
             padding: 0.9rem !important;
             border: none !important;
             font-size: 0.95rem !important;
-            text-align: left !important;
+            text-align: left !important; /* Ensure example text is left-aligned */
         }
         .examples-section .gr-samples-table th {
-            background: var(--background-card) !important;
+            background: var(--background-secondary) !important;
             font-weight: 700 !important;
-            color: var(--primary-color) !important;
+            color: var(--text-primary) !important;
         }
         .examples-section .gr-samples-table td {
-            background: var(--background-input) !important; /* Pure white for rows */
-            color: var(--text-dark) !important;
-            border-top: 1px solid var(--border-input) !important;
+            background: var(--background-primary) !important;
+            color: var(--text-primary) !important;
+            border-top: 1px solid var(--border-color) !important;
             cursor: pointer !important;
-            transition: background 0.2s ease, transform 0.1s ease !important;
+            transition: background 0.2s ease, transform 0.1s ease !important; /* Smooth transitions */
         }
         .examples-section .gr-samples-table tr:hover td {
-            background: hsl(0, 0%, 95%) !important; /* Slightly darker white on hover */
-            transform: translateX(8px);
+            background: var(--background-secondary) !important;
+            transform: translateX(5px); /* Subtle slide on hover */
         }
+        /* Hide Gradio default elements for examples for cleaner look */
         .gr-examples .gr-label,
         .gr-examples .label-wrap,
         .gr-examples .gr-accordion-header {
             display: none !important;
         }
         
-        /* Footer Styling */
+        /* Footer styling - centered text */
         .app-footer-wrapper {
-            background: var(--background-card) !important;
-            border: 2px solid var(--border-card) !important;
+            background: var(--background-secondary) !important;
+            border: 2px solid var(--border-color) !important;
             border-radius: 12px !important;
             padding: 1.75rem !important;
             margin-top: 1.5rem !important;
-            text-align: center !important;
-            color: var(--text-muted) !important;
+            text-align: center !important; /* Centered footer text */
         }
         .app-footer p {
             margin: 0.6rem 0 !important;
             font-size: 0.95rem !important;
-            color: var(--text-muted) !important;
+            color: var(--text-secondary) !important;
             line-height: 1.6 !important;
         }
         .app-footer a {
-            color: var(--primary-color) !important; /* Links use primary accent color */
+            color: var(--primary-color) !important;
             text-decoration: none !important;
             font-weight: 600 !important;
-            transition: text-decoration 0.2s ease, color 0.2s ease !important; /* Smooth color transition */
         }
         .app-footer a:hover {
             text-decoration: underline !important;
-            text-decoration-color: var(--primary-hover) !important;
-            color: var(--primary-hover) !important;
         }
 
-        /* Responsive Design */
+        /* Responsive design for smaller screens */
         @media (max-width: 768px) {
             .gradio-container {
                 padding: 1rem !important;
@@ -712,13 +729,13 @@ Answer:"""
                 font-size: 1.4rem !important;
             }
             .input-row {
-                flex-direction: column !important;
+                flex-direction: column !important; /* Stack inputs vertically */
             }
             .button-row {
-                flex-direction: column !important;
+                flex-direction: column !important; /* Stack buttons vertically */
             }
             .gradio-button {
-                width: 100% !important;
+                width: 100% !important; /* Full width buttons */
             }
             .dashboard-card-section {
                 padding: 1.25rem !important;
@@ -733,8 +750,11 @@ Answer:"""
         }
         """
 
+        # Using gr.Blocks with the specified theme and custom CSS
         with gr.Blocks(theme="shivi/calm_seafoam", css=custom_css, title="Landlord-Tenant Rights Assistant") as demo:
+            # Header Section - uses gr.Group for distinct card-like styling
             with gr.Group(elem_classes="app-header-wrapper"):
+                # Markdown used for flexible styling and auto-centering via CSS
                 gr.Markdown(
                     """
                     <div class="app-header">
@@ -745,33 +765,37 @@ Answer:"""
                     """
                 )
 
+            # Main Dashboard Container - acts as a column to stack various sections
             with gr.Column(elem_classes="main-dashboard-container"):
 
+                # Introduction and Disclaimer Card
                 with gr.Group(elem_classes="dashboard-card-section"):
-                    gr.Markdown("<h3 class='sub-section-title'>Welcome & Disclaimer</h3>")
+                    gr.Markdown("<h3 class='sub-section-title'>Welcome & Disclaimer</h3>") # Centered by CSS
                     gr.Markdown(
                         """
                         Navigate landlord-tenant laws with ease. This assistant provides detailed, state-specific answers grounded in legal authority.
                         
-                        <span style="color: var(--secondary-accent-color);">**Disclaimer:**</span> This tool is for informational purposes only and does not constitute legal advice. For specific legal guidance, always consult a licensed attorney in your jurisdiction.
+                        **Disclaimer:** This tool is for informational purposes only and does not constitute legal advice. For specific legal guidance, always consult a licensed attorney in your jurisdiction.
                         """
                     )
 
+                # OpenAI API Key Input Card
                 with gr.Group(elem_classes="dashboard-card-section"):
-                    gr.Markdown("<h3 class='sub-section-title'>OpenAI API Key</h3>")
+                    gr.Markdown("<h3 class='sub-section-title'>OpenAI API Key</h3>") # Centered by CSS
                     api_key_input = gr.Textbox(
                         label="API Key",
-                        type="password",
+                        type="password", # Hides the input for security
                         placeholder="Enter your OpenAI API key (e.g., sk-...)",
                         info="Required to process your query. Get one from OpenAI: platform.openai.com/api-keys",
                         lines=1,
-                        elem_classes=["input-field-group"]
+                        elem_classes=["input-field-group"] # Custom class for input styling
                     )
 
+                # Query Input and State Selection Card
                 with gr.Group(elem_classes="dashboard-card-section"):
-                    gr.Markdown("<h3 class='sub-section-title'>Ask Your Question</h3>")
-                    with gr.Row(elem_classes="input-row"):
-                        with gr.Column(elem_classes="input-field", scale=3):
+                    gr.Markdown("<h3 class='sub-section-title'>Ask Your Question</h3>") # Centered by CSS
+                    with gr.Row(elem_classes="input-row"): # Row for side-by-side query and state
+                        with gr.Column(elem_classes="input-field", scale=3): # Query text area takes more space
                             query_input = gr.Textbox(
                                 label="Your Question",
                                 placeholder="E.g., What are the rules for security deposit returns in my state?",
@@ -779,7 +803,7 @@ Answer:"""
                                 max_lines=8,
                                 elem_classes=["input-field-group"]
                             )
-                        with gr.Column(elem_classes="input-field", scale=1):
+                        with gr.Column(elem_classes="input-field", scale=1): # State dropdown takes less space
                             state_input = gr.Dropdown(
                                 label="Select State",
                                 choices=dropdown_choices,
@@ -787,29 +811,32 @@ Answer:"""
                                 allow_custom_value=False,
                                 elem_classes=["input-field-group"]
                             )
-                    with gr.Row(elem_classes="button-row"):
+                    with gr.Row(elem_classes="button-row"): # Row for action buttons
                         clear_button = gr.Button("Clear", variant="secondary", elem_classes=["gr-button-secondary"])
                         submit_button = gr.Button("Submit Query", variant="primary", elem_classes=["gr-button-primary"])
 
+                # Output Display Card - Using gr.HTML for better animation control
                 with gr.Group(elem_classes="dashboard-card-section"):
-                    gr.Markdown("<h3 class='sub-section-title'>Legal Assistant's Response</h3>")
-                    output = gr.HTML(
+                    gr.Markdown("<h3 class='sub-section-title'>Legal Assistant's Response</h3>") # Centered by CSS
+                    output = gr.HTML( # Changed to gr.HTML to wrap content with animation class
                         value="<div class='placeholder'>The answer will appear here after submitting your query.</div>",
-                        elem_classes="output-content-wrapper"
+                        elem_classes="output-content-wrapper" # Custom class for output styling
                     )
 
+                # Example Questions Section
                 with gr.Group(elem_classes="dashboard-card-section examples-section"):
-                    gr.Markdown("<h3 class='sub-section-title'>Example Questions</h3>")
+                    gr.Markdown("<h3 class='sub-section-title'>Example Questions</h3>") # Centered by CSS
                     if example_queries:
                         gr.Examples(
                             examples=example_queries,
                             inputs=[query_input, state_input],
                             examples_per_page=5,
-                            label=""
+                            label="" # Hide default Gradio label for examples to use our custom title
                         )
                     else:
                         gr.Markdown("<div class='placeholder'>Sample questions could not be loaded. Please ensure the vector database is populated.</div>")
 
+            # Footer Section - contains disclaimer and developer info
             with gr.Group(elem_classes="app-footer-wrapper"):
                 gr.Markdown(
                     """
@@ -818,19 +845,20 @@ Answer:"""
                     """
                 )
 
+            # Event Listeners for buttons
             submit_button.click(
                 fn=query_interface_wrapper,
                 inputs=[api_key_input, query_input, state_input],
                 outputs=output,
-                api_name="submit_query"
+                api_name="submit_query" # Useful for debugging / external calls
             )
             
             clear_button.click(
                 fn=lambda: (
-                    "",
-                    "",
-                    initial_value,
-                    "<div class='placeholder'>Inputs cleared. Ready for your next question.</div>"
+                    "", # Clear API key input
+                    "", # Clear query input
+                    initial_value, # Reset state dropdown to default prompt
+                    "<div class='placeholder'>Inputs cleared. Ready for your next question.</div>" # Reset output message
                 ),
                 inputs=[],
                 outputs=[api_key_input, query_input, state_input, output]
@@ -849,32 +877,36 @@ if __name__ == "__main__":
         PDF_PATH = os.getenv("PDF_PATH", DEFAULT_PDF_PATH)
         VECTOR_DB_PATH = os.getenv("VECTOR_DB_PATH", DEFAULT_DB_PATH)
 
+        # Ensure vector DB directory exists before initialization
         os.makedirs(os.path.dirname(VECTOR_DB_PATH), exist_ok=True)
 
         logging.info(f"Attempting to load PDF from: {PDF_PATH}")
         if not os.path.exists(PDF_PATH):
             logging.error(f"FATAL: PDF file not found at the specified path: {PDF_PATH}")
             print(f"\n--- CONFIGURATION ERROR ---\nPDF file ('{os.path.basename(PDF_PATH)}') not found at: {PDF_PATH}.\nPlease ensure it exists or set 'PDF_PATH' environment variable.\n---------------------------\n")
-            exit(1)
+            exit(1) # Correctly exits if PDF is not found
 
         if not os.access(PDF_PATH, os.R_OK):
             logging.error(f"FATAL: PDF file at '{PDF_PATH}' exists but is not readable. Check file permissions.")
             print(f"\n--- PERMISSION ERROR ---\nPDF file ('{os.path.basename(PDF_PATH)}') found but not readable at: {PDF_PATH}\nPlease check file permissions (e.g., using 'chmod +r' in terminal).\n---------------------------\n")
-            exit(1)
+            exit(1) # Correctly exits if PDF is unreadable
 
         logging.info(f"PDF file '{os.path.basename(PDF_PATH)}' found and is readable.")
 
+        # Initialize VectorDatabase and RAGSystem
         vector_db_instance = VectorDatabase(persist_directory=VECTOR_DB_PATH)
         rag = RAGSystem(vector_db=vector_db_instance)
 
+        # Load PDF data into the vector DB (or verify it's already loaded)
         rag.load_pdf(PDF_PATH)
 
+        # Get the Gradio interface object
         app_interface = rag.gradio_interface()
-        SERVER_PORT = int(os.getenv("PORT", 7860))
+        SERVER_PORT = int(os.getenv("PORT", 7860)) # Use PORT env var for Hugging Face Spaces
 
         logging.info(f"Launching Gradio app on http://0.0.0.0:{SERVER_PORT}")
         print(f"\n--- Gradio App Running ---\nAccess at: http://localhost:{SERVER_PORT} or your public Spaces URL\n--------------------------\n")
-        app_interface.launch(server_name="0.0.0.0", server_port=SERVER_PORT, share=False)
+        app_interface.launch(server_name="0.0.0.0", server_port=SERVER_PORT, share=False) # share=False is typical for Spaces
 
     except ModuleNotFoundError as e:
         if "vector_db" in str(e):