Update app.py With Proper UI Enhancements

app.py

@@ -1,196 +1,493 @@
-
+# FILE: app.py
+# FINAL REFACTORED VERSION WITH ADVANCED UI/UX
 
 import gradio as gr
-import logging
 import os
-from typing import List, Dict, Any, Optional
+import logging
+from typing import Dict, Any, List, Optional
+from dotenv import load_dotenv
 
-# --- 1. CONFIGURATION FIRST ---
-from config import initialize_dspy
-custom_lm = initialize_dspy()
+# --- Backend & Configuration Imports ---
+load_dotenv()
 
-# --- 2. Now Import Other Modules ---
+import dspy
 from config import (
-    API_KEY, STATE_STAGE, STATE_HISTORY, STAGE_START, STAGE_EXPLAINING,
-    STATE_EXPLAINER_PROMPT
+    initialize_dspy, RateLimiter,
+    STATE_STAGE, STATE_HISTORY, STATE_CURRENT_TITLE, STATE_GENERATED_TITLE,
+    STATE_EXPLAINER_PROMPT, STATE_TRANSITION_EXPLAINER_FLAG, STAGE_START,
+    STATE_IS_FIRST_TURN, DEFAULT_CHAT_TITLE,
 )
+from orchestrator import process_chat_message, initialize_orchestrator_modules
 from resource_processor import process_uploaded_files
-from orchestrator import process_chat_message
 
-# Setup basic logging
-logging.basicConfig(level=logging.INFO, format='{levelname} {asctime} [%(name)s]: {message}', style='{')
+# --- Setup Logging ---
+logging.basicConfig(level=logging.INFO, format='{levelname} {asctime} {name}: {message}', style='{')
 logger = logging.getLogger(__name__)
 
-def respond(
-    user_message: str, # The content from the textbox
-    chat_history_ui: List[Dict[str, str]],
-    app_state: Dict[str, Any],
+# --- Application Mode & UI Configuration ---
+APP_MODE = os.getenv("APP_MODE", "visitor").lower()
+if APP_MODE not in ["admin", "visitor"]:
+    raise ValueError("APP_MODE environment variable must be 'admin' or 'visitor'")
+
+UI_FEEDBACK_MAP = {
+    "PROCESSING_INPUT": "🧠 Thinking...",
+    "ANALYZING_RESOURCES_INITIAL": "📄 Analyzing your documents...",
+    "GENERATING_SYLLABUS": "✍️ Crafting syllabus...",
+    "EXPLAINER_RESPONSE": "💬 Tutor is responding...",
+    # NOTE: The UI will use these for more granular feedback in the future if needed.
+    # For now, we use a general "Thinking..." message for stability during backend processing.
+}
+
+# --- Helper & Core Functions ---
+
+def initialize_session_state() -> Dict[str, Any]:
+    """Creates a fresh session state dictionary, including the initial greeting."""
+    initial_history = [{'role': 'model', 'parts': [{'text': "Hello! I'm ready to help build a personalized syllabus. What topic are you interested in learning about?"}]}]
+    return {
+        STATE_STAGE: STAGE_START,
+        STATE_HISTORY: initial_history,
+        STATE_CURRENT_TITLE: DEFAULT_CHAT_TITLE,
+        STATE_IS_FIRST_TURN: True,
+    }
+
+def start_session(api_key: str, api_tier: str):
+    """
+    (Visitor Mode) Validates API, initializes backends, and transitions UI.
+    ADDED: Debugging print statements to trace the authentication flow.
+    """
+    # --- START OF DEBUG BLOCK ---
+    print("\n--- [start_session] Function Entered ---")
+    # Use slicing to avoid printing the full secret key in logs
+    print(f"[start_session] Received API Key ending in: '...{api_key[-4:] if len(api_key) > 4 else api_key}'")
+    print(f"[start_session] Received API Tier: {api_tier}")
+    # --- END OF DEBUG BLOCK ---
+
+    # --- Case 1: Empty API Key ---
+    if not api_key.strip():
+        print("[start_session] DEBUG: Condition MET - API Key is empty or whitespace.")
+        error_msg = "<p style='color:red;'>API Key cannot be empty. Please provide a valid key.</p>"
+        yield (gr.update(visible=True), gr.update(visible=False), None, gr.update(value=error_msg, visible=True))
+        print("--- [start_session] END ---\n")
+        return
+
+    # --- Case 2: Authentication with DSPy Fails ---
+    print("[start_session] DEBUG: Attempting to call initialize_dspy...")
+    # Store the result in a variable so we can print it
+    auth_result = initialize_dspy(api_key=api_key)
+    print(f"[start_session] DEBUG: Result from initialize_dspy is: '{auth_result}' (Type: {type(auth_result)})")
+
+    if not isinstance(auth_result, list) :
+        #
+        print("[start_session] DEBUG: Condition MET - `if not auth_result` is TRUE. Authentication failed.")
+        error_msg = "<p style='color:red;'>Authentication failed. The provided API key is invalid or has expired. Please check the key and try again.</p>"
+        yield (gr.update(visible=True), gr.update(visible=False), None, gr.update(value=error_msg, visible=True))
+        print("--- [start_session] END ---\n")
+        return
+    
+    print("[start_session] DEBUG: Condition SKIPPED - `if not auth_result` is FALSE. Assuming auth succeeded.")
+
+    # --- Case 3: Backend Module Initialization Fails ---
+    print("[start_session] DEBUG: Attempting to call initialize_orchestrator_modules...")
+    modules_result = initialize_orchestrator_modules()
+    print(f"[start_session] DEBUG: Result from initialize_orchestrator_modules is: {modules_result}")
+    
+    if not modules_result:
+        print("[start_session] DEBUG: Condition MET - Backend module initialization failed.")
+        error_msg = "<p style='color:red;'>Failed to initialize backend AI modules after authentication. Please contact support.</p>"
+        yield (gr.update(visible=True), gr.update(visible=False), None, gr.update(value=error_msg, visible=True))
+        print("--- [start_session] END ---\n")
+        return
+
+    # --- Case 4: Success ---
+    print("[start_session] DEBUG: All checks passed. Proceeding to success case.")
+    max_calls = 7 if "Free" in api_tier else 1000
+    limiter = RateLimiter(max_calls=max_calls, time_period=60)
+    
+    yield (
+        gr.update(visible=False), # Hide API view
+        gr.update(visible=True),  # Show chat view
+        limiter,                  # Set the rate limiter state
+        gr.update(visible=False), # Hide the error message
+    )
+    print("--- [start_session] END: UI transitioned successfully. ---\n")
+# FILE: app.py
+# REPLACE the existing function with this new "consumer" version.
+
+def handle_user_interaction(
+    user_message: str,
     uploaded_files: Optional[List[Any]],
-    explainer_prompt_display: str
+    current_state: Dict[str, Any],
+    file_names_state: List[str],
+    limiter: Optional[RateLimiter],
+    modified_explainer_prompt: str
 ):
     """
-    Core backend function. Receives UI state, calls orchestrator, and returns updated UI state.
-    This version also handles clearing the input textbox directly.
+    Main generator function, refactored for cleaner history management and clarity
+    while consuming the stream of updates from the orchestrator.
     """
-    # Guard clause: If user sends an empty message, do nothing.
-    if not user_message.strip():
-        # Return all components unchanged, including the uncleared textbox
-        return chat_history_ui, app_state, gr.update(), gr.update(), gr.update(), user_message
-
-    # Guard clause: If the API key is missing, the app won't work.
-    if not custom_lm:
-        error_msg = "FATAL ERROR: AI Backend is not configured. Please check your .env file for a valid GOOGLE_API_KEY."
-        chat_history_ui.append({"role": "user", "content": user_message})
-        chat_history_ui.append({"role": "assistant", "content": error_msg})
-        # Keep file uploader visible on error, but clear the textbox.
-        yield chat_history_ui, app_state, gr.update(visible=True), gr.update(), gr.update(), ""
-        return
+    # --- 1. PREPARATION AND UI UPDATE (YIELD 1) ---
+    
+    # Get the *current* UI-compatible history from the state for a clean start
+    # We will build on top of this for all UI updates
+    ui_history = []
+    for msg in current_state.get(STATE_HISTORY, []):
+        if msg.get('message_type') != "internal_resource_summary":
+            role = "assistant" if msg.get("role") == "model" else "user"
+            content = msg.get("content", "") or (msg.get("parts")[0].get("text", "") if msg.get("parts") else "")
+            ui_history.append({"role": role, "content": content})
 
-    # --- Step 1: Update UI and State with User's Message ---
-    chat_history_ui.append({"role": "user", "content": user_message})
-    app_state[STATE_HISTORY].append({'role': 'user', 'parts': [{'text': user_message}]})
-    chat_history_ui.append({"role": "assistant", "content": ""}) # Placeholder for bot response
+    # Add the new user message in the clean UI format
+    ui_history.append({"role": "user", "content": user_message})
+    # Add the initial placeholder for the bot's response/status
+    ui_history.append({"role": "assistant", "content": f"*{UI_FEEDBACK_MAP['PROCESSING_INPUT']}*"})
 
-    # First yield for immediate UI update. Hide file uploader, but don't clear textbox yet.
-    yield chat_history_ui, app_state, gr.update(visible=False), gr.update(), gr.update(), user_message
+    # Update the backend-formatted history in the state for the orchestrator
+    backend_history = current_state.get(STATE_HISTORY, [])
+    backend_history.append({'role': 'user', 'parts': [{'text': user_message}]})
+    current_state[STATE_HISTORY] = backend_history
+    
+    # Handle file display logic (this part remains the same)
+    all_file_names = sorted(list(set(file_names_state + [f.name for f in uploaded_files or []])))
+    file_display_md = "#### Uploaded Resources:\n" + "\n".join([f"- `{os.path.basename(name)}`" for name in all_file_names]) if all_file_names else ""
+    file_uploader_visible = not bool(all_file_names)
+    file_display_visible = bool(all_file_names)
 
-    # --- Step 2: Handle File Uploads ---
-    processed_file_data = None
-    if app_state.get(STATE_STAGE) == STAGE_START and uploaded_files:
-        logger.info(f"Processing {len(uploaded_files)} files for new chat session.")
-        processed_file_data = process_uploaded_files(uploaded_files)
+    print("YIELD 1: Displaying user message and initial status.")
+    yield (
+        gr.update(value=ui_history), # Use the cleanly built UI history
+        gr.update(value=""),
+        current_state,
+        gr.update(visible=file_uploader_visible),
+        gr.update(interactive=False),
+        gr.update(), gr.update(),
+        gr.update(value=file_display_md, visible=file_display_visible),
+        all_file_names,
+        gr.update(visible=False),
+        gr.update(), gr.update()
+    )
 
-    # --- Step 3: Call the Main Agent Logic (The Orchestrator) ---
+    # --- 2. BACKEND PROCESSING (CONSUMER LOOP) ---
+    orchestrator_kwargs = {
+        "user_message_text": user_message,
+        "current_session_state": current_state,
+        "modified_explainer_prompt": modified_explainer_prompt or None,
+        "uploaded_resource_data": process_uploaded_files(uploaded_files) if uploaded_files else None
+    }
+    current_state[STATE_IS_FIRST_TURN] = False
+    if limiter: limiter.wait_if_needed()
+
+    final_state = None
     try:
-        final_user_facing_reply, new_state = process_chat_message(
-            user_message_text=user_message,
-            current_session_state=app_state,
-            uploaded_resource_data=processed_file_data,
-            modified_explainer_prompt=explainer_prompt_display
-        )
-        app_state = new_state
+        # This loop consumes the `yield`ed updates from the backend orchestrator
+        for update_type, payload in process_chat_message(**orchestrator_kwargs):
+            if update_type == "status":
+                status_message = UI_FEEDBACK_MAP.get(payload, "Processing...")
+                # Update the last message in the chat (our status placeholder)
+                ui_history[-1]['content'] = f"*{status_message}*"
+                print(f"YIELD (Status Update): {status_message}")
+                # Yield a UI update with the new status message
+                yield (
+                    gr.update(value=ui_history),
+                    gr.update(), gr.update(), gr.update(), gr.update(),
+                    gr.update(), gr.update(), gr.update(), gr.update(),
+                    gr.update(), gr.update(), gr.update()
+                )
+            elif update_type == "final_result":
+                final_state = payload
+                break
+
     except Exception as e:
-        logger.error(f"Critical error in orchestrator call: {e}", exc_info=True)
-        final_user_facing_reply = f"[SYSTEM ERROR: An exception occurred in the agent's logic. Please check the logs. Details: {e}]"
-
-    # --- Step 4: Update the UI with the AI's Final Response ---
-    syllabus_flag_data = app_state.get("display_syllabus_flag")
-    if syllabus_flag_data:
-        syllabus_content = syllabus_flag_data.get("content", "Error displaying syllabus.")
-        chat_history_ui[-1] = {"role": "assistant", "content": syllabus_content}
-        chat_history_ui.append({"role": "assistant", "content": final_user_facing_reply})
-        app_state.pop("display_syllabus_flag", None)
-    else:
-        chat_history_ui[-1]['content'] = final_user_facing_reply
-
-    # --- Step 5: Determine visibility of explainer prompt box for the final return ---
-    prompt_update = gr.update(visible=False)
-    header_update = gr.update(visible=False)
-    if new_state.get(STATE_STAGE) == STAGE_EXPLAINING:
-        prompt_value = explainer_prompt_display if explainer_prompt_display else new_state.get(STATE_EXPLAINER_PROMPT)
-        prompt_update = gr.update(value=prompt_value, visible=True)
-        header_update = gr.update(visible=True)
-
-    # Final yield: return all component states AND an empty string to clear the textbox.
-    yield chat_history_ui, app_state, gr.update(visible=False), header_update, prompt_update, ""
-
-def start_new_session():
-    """ Resets the chat history, internal state, and all UI components for a new conversation. """
-    logger.info("UI action: Starting new session.")
-    initial_state = {
-        STATE_STAGE: STAGE_START,
-        STATE_HISTORY: [{'role': 'model', 'parts': [{'text': 'Hello! What would you like to learn about today?'}]}]
-    }
-    initial_chat_history_ui = [{"role": "assistant", "content": "Hello! What would you like to learn about today?"}]
-    
-    return (
-        initial_chat_history_ui,
-        initial_state,
-        gr.update(value=[], visible=True), # File uploader
-        gr.update(visible=False),           # Prompt header
-        gr.update(value="", visible=False),  # Prompt textbox
-        ""                                  # Clear the main textbox
+        logger.error(f"Orchestrator stream error: {e}", exc_info=True)
+        current_state[STATE_HISTORY].append({'role': 'model', 'parts': [{'text': "An error occurred during processing."}]})
+        final_state = current_state
+
+    # --- 3. FINAL UI UPDATE (YIELD 2) ---
+    if not final_state:
+        logger.error("Processing finished without a final state.")
+        current_state[STATE_HISTORY].append({'role': 'model', 'parts': [{'text': "A critical error occurred."}]})
+        final_state = current_state
+
+    # --- Final Robust Translator ---
+    final_ui_history = []
+    for message in final_state.get(STATE_HISTORY, []):
+        if message.get('message_type') == "internal_resource_summary": continue
+        role = "assistant" if message.get("role") == "model" else "user"
+        content = message.get('content', '') or (message.get("parts")[0].get("text", "") if message.get("parts") else "")
+        final_ui_history.append({"role": role, "content": content})
+
+    # Logic for Suggested Replies and Tab Switching
+    looks_good_btn_update = gr.update(visible=False)
+    if final_ui_history and "what are your thoughts?" in final_ui_history[-1]['content'].lower():
+        looks_good_btn_update = gr.update(visible=True)
+
+    explainer_accordion_update, explainer_box_update, app_tabs_update, documentation_update = (gr.update(),)*4
+    if final_state.get(STATE_TRANSITION_EXPLAINER_FLAG):
+        explainer_accordion_update = gr.update(visible=True, open=True)
+        explainer_prompt_value = final_state.get(STATE_EXPLAINER_PROMPT, "")
+        explainer_box_update = gr.update(value=explainer_prompt_value)
+        app_tabs_update = gr.update(selected="doc_tab")
+        full_documentation_text = f"""
+# Generated Tutor Persona
+*This document contains the complete system prompt, including the finalized syllabus, that defines the AI tutor's behavior, personality, and knowledge base. You can copy this for reference or use in other applications.*
+***
+{explainer_prompt_value}
+"""
+        documentation_update = gr.update(value=full_documentation_text)
+
+    print("YIELD 2: Displaying final AI response.")
+    yield (
+        gr.update(value=final_ui_history),
+        gr.update(value=""),
+        final_state,
+        gr.update(visible=file_uploader_visible),
+        gr.update(interactive=True),
+        explainer_accordion_update,
+        explainer_box_update,
+        gr.update(value=file_display_md, visible=file_display_visible),
+        all_file_names,
+        looks_good_btn_update,
+        app_tabs_update,
+        documentation_update,
     )
+custom_css = """
+/* --- Overall Page & Theme --- */
+.gradio-container {
+    background: #F9FAFB; /* Soft off-white/light gray background */
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif !important;
+    padding-top: 0 !important; /* Remove top padding to let header be flush */
+}
 
-# --- 3. Gradio Interface Definition ---
-with gr.Blocks(theme=gr.themes.Soft(), title="Forge Guide AI Tutor") as demo:
-    gr.Markdown("# Forge Guide: AI Syllabus Architect")
-    gr.Markdown("Start a new conversation by describing what you want to learn. For new chats, you can also upload resources like PDFs or text files.")
+/* --- Hero Header Section --- */
+#app-header-container {
+    background: white;
+    border-bottom: 1px solid #E5E7EB;
+    padding: 1.5rem 2rem !important;
+    margin-bottom: 1.5rem !important;
+}
+#app-header h1 {
+    text-align: center;
+    font-size: 2.25rem !important;
+    font-weight: 800 !important;
+    color: #1F2937; /* Very dark gray for high contrast */
+    margin-bottom: 0.5rem !important;
+}
+#app-header p {
+    text-align: center;
+    font-size: 1.1rem !important;
+    color: #4B5563; /* Softer gray for subtitle */
+    margin-bottom: 0 !important;
+}
 
-    app_state = gr.State({
-        STATE_STAGE: STAGE_START,
-        STATE_HISTORY: [{'role': 'model', 'parts': [{'text': 'Hello! What would you like to learn about today?'}]}]
-    })
-
-    with gr.Row():
-        with gr.Column(scale=4):
-            chatbot = gr.Chatbot(
-                [{"role": "assistant", "content": "Hello! What would you like to learn about today?"}],
-                elem_id="chatbot",
-                height=650,
-                render_markdown=True,
-                avatar_images=(None, "https://i.imgur.com/3pyR0Vf.png"),
-                type='messages',
-                latex_delimiters=[{"left": "$$", "right": "$$", "display": True}, {"left": "$", "right": "$", "display": False}]
+/* --- Main Application Tabs --- */
+#app-tabs .tab-nav button {
+    font-size: 1.1rem !important;
+    font-weight: 600 !important;
+    border-radius: 8px 8px 0 0 !important;
+    border-bottom: 3px solid transparent !important;
+    transition: all 0.2s ease-in-out;
+    background: transparent !important;
+}
+#app-tabs .tab-nav button.selected {
+    border-bottom-color: #4F46E5 !important; /* A strong indigo accent color */
+    background: white !important;
+    color: #4F46E5 !important;
+}
+
+/* --- Compact & Styled Buttons --- */
+.sm-button {
+    min-width: 0 !important;
+    padding: 0.2rem 0.6rem !important;
+    height: 34px !important;
+    line-height: 1 !important;
+    align-self: center !important;
+    margin: 0 !important;
+    border-radius: 8px !important;
+    border: 1px solid #D1D5DB !important;
+    background: white !important;
+    color: #4B5563 !important;
+    box-shadow: 0 1px 2px 0 rgba(0,0,0,0.05);
+    transition: background-color 0.2s ease;
+}
+.sm-button:hover { background: #F9FAFB !important; }
+
+/* --- Chat Interface Polish --- */
+.chat-input-row { margin-top: 10px; }
+#chatbot {
+    min-height: 600px;
+    box-shadow: none !important;
+    border: 1px solid #E5E7EB !important;
+    background-color: white !important;
+}
+"""
+# --- Gradio UI Definition ---
+# --- Gradio UI Definition ---
+# --- Gradio UI Definition ---
+with gr.Blocks(theme=gr.themes.Soft(), css=custom_css, title="AI Syllabus Architect") as demo:
+    
+    # --- State Management ---
+    session_state = gr.State(value=initialize_session_state)
+    rate_limiter_state = gr.State(value=None)
+    uploaded_file_names_state = gr.State([])
+    header_visibility_state = gr.State(value=True)
+
+    # --- TOP LEVEL HEADER (Collapsible) ---
+    with gr.Column(visible=True) as header_view:
+        gr.Markdown(
+            """
+            # AI Syllabus Architect
+            *Your personal guide to creating structured learning paths from any resource.*
+            """,
+            elem_id="app-header"
+        )
+    toggle_header_btn = gr.Button("⬆️", elem_classes="sm-button")
+    
+    # --- UI for Visitor Mode (API Key Entry) ---
+    with gr.Column(visible=(APP_MODE == 'visitor'), elem_id="api_setup_view") as api_setup_view:
+        gr.Markdown("### 🔑 Please enter your Google AI API Key below to begin. You can get your free key from [Google AI Studio](https://aistudio.google.com/app/apikey).")
+
+        api_key_input = gr.Textbox(label="Google API Key", placeholder="Enter your API key here...", type="password")
+        api_tier_radio = gr.Radio(["Free Tier (7 calls/min)", "Paid Tier (1000 calls/min)"], label="Select API Tier", value="Free Tier (7 calls/min)")
+        api_key_submit_button = gr.Button("Start Session", variant="primary")
+        api_error_output = gr.Markdown(visible=False)
+
+    # ===================================================================
+    # CORRECTED MAIN UI: Top-level tabs and proper nesting
+    # ===================================================================
+    with gr.Tabs(elem_id="app-tabs", visible=(APP_MODE == 'admin')) as app_tabs:
+        
+        # --- TAB 1: The Main Chat Interface ---
+        with gr.Tab("Chat Interface", id="chat_tab"):
+            with gr.Row(equal_height=False):
+                # --- MAIN CHAT COLUMN ---
+                with gr.Column(scale=7) as chat_column:
+                    open_sidebar_btn = gr.Button("Show Resources & Persona ➡️", elem_classes="sm-button", visible=False)
+                    initial_chat_ui = [{"role": "assistant", "content": "Hello! I'm ready to help build a personalized syllabus. What topic are you interested in learning about?"}]
+                    chatbot = gr.Chatbot(initial_chat_ui, elem_id="chatbot", type="messages", show_label=False, render_markdown=True, avatar_images=(None, "https://i.imgur.com/3pyR0Vf.png"), latex_delimiters=[{"left": "$$", "right": "$$", "display": True}, {"left": "$", "right": "$", "display": False}])
+                    with gr.Row(elem_classes="chat-input-row"):
+                        looks_good_btn = gr.Button("looks good", size="sm", visible=False)
+                    with gr.Row():
+                        user_input_textbox = gr.Textbox(scale=4, show_label=False, placeholder="Type your message or upload files and press Enter...", container=False)
+                        send_button = gr.Button("Send", variant="primary", scale=1, min_width=150)
+                
+                # --- TOOLS SIDEBAR COLUMN (Correctly nested inside the Chat Tab's Row) ---
+                with gr.Column(scale=3, visible=True) as tools_sidebar:
+                    close_sidebar_btn = gr.Button("⬅️ Close Sidebar", elem_classes="sm-button")
+                    with gr.Accordion("🛠️ Session Content", open=True):
+                        gr.Markdown("### 📄 Resources")
+                        file_uploader = gr.File(label="Upload Learning Materials (First Turn Only)", file_count="multiple", file_types=[".pdf", ".docx", ".txt"], interactive=True)
+                        file_display = gr.Markdown(visible=False)
+                        with gr.Accordion("View/Edit AI Tutor Persona", open=False, visible=False) as explainer_prompt_accordion:
+                            explainer_prompt_box = gr.Textbox(label="Tutor Persona System Prompt", lines=15, interactive=True, show_copy_button=True, info="You can view and modify the AI Tutor's persona here.")
+        
+        # --- TAB 2: How to Use Guide ---
+        with gr.Tab("How to Use"):
+            gr.Markdown(
+                """
+                ### Quick Start Guide
+                
+                **1. Start a Conversation:**
+                Begin by telling the AI what you want to learn. Be specific! 
+                *Example: "I want to learn about building a RAG pipeline from scratch using Python."*
+
+                **2. Upload Resources (Optional):**
+                For a more tailored syllabus, upload relevant documents (`.pdf`, `.txt`, `.docx`) in your first message. The AI will use these as context.
+
+                **3. Negotiate the Syllabus:**
+                The AI will propose a syllabus. You can ask for changes, additions, or removals. 
+                *Example: "Can you add a section on vector databases?"*
+
+                **4. Finalize and Learn:**
+                Once you're happy with the syllabus, tell the AI to finalize it (e.g., "This looks good, let's finalize it."). This will generate the tutor's persona and move to the learning phase.
+
+                **5. Interact with the Tutor:**
+                You can edit the tutor's persona at any time in the "Session Content" section to change its teaching style.
+
+                ---
+
+                ### Pro-User Guide: For a More Advanced Session
+
+                This is for users who want to architect a superior learning experience. Your prompts are the blueprints.
+
+                **1. On Architecting the Syllabus**
+
+                To get a truly calibrated result, you need to be precise.
+                
+                *   **Pinpoint Everything:** The key is to **pinpoint to every thing**. The more extra information you give, the better the AI can calibrate the syllabus to your exact needs.
+                *   **Request Specific comparison :** Don't be afraid to demand more. For instance, you can **ask it for "the advanced version that contrasts one concept with another."**
+                    *   *Example:* `"For the data analysis module, I want the advanced version that contrasts the performance of Pandas with Polars for datasets over 10GB."*
+
+                **2. On Commanding the Tutor Persona**
+
+                This is the most important part. A well-defined persona yields a far more convincing and effective tutor.
+                
+                *   **The Core Principle:** When handling the Persona, **just don't ask the AI what persona you need.** A power user doesn't ask for a persona, they command one. You must *instruct* the AI on who it needs to be.
+                
+                *   **Advanced Techniques for Persona Prompts:**
+                    *   **First-Principles Thinking:** To force deep, foundational understanding.
+                        *   *Prompt Example:* `"Adopt the persona of a modern-day Feynman who thinks from first principles. When I ask about 'RAG pipelines,' start from the fundamental problem: 'How does a machine retrieve relevant information from a vast text library?' and build up from there."`
+                    *   **The Socratic Method:** To challenge your own thinking.
+                        *   *Prompt Example:* `"Become a Socratic tutor. Never give me a direct answer. Instead, relentlessly question my assumptions to lead me to the answer myself. If I say 'A vector database is faster,' your first response should be 'What do you mean by 'faster,' and compared to what?'"`
+                    *   **Key Figures from History:** To get a unique and powerful perspective.
+                        *   *Prompt Example:* `"Teach me chess as if you are Bobby Fischer preparing me for a world championship. Your tone should be intense, obsessive, and focused on total dominance. We will analyze unorthodox openings, drill methods to exploit opponent weaknesses, and master endgame precision. Every lesson is a step toward crushing the competition."`
+                
+                Once your syllabus is perfected, finalize it. The AI will then adopt the persona you've engineered, and your advanced learning session will begin.
+                """
             )
             
-            with gr.Row():
-                txt_input = gr.Textbox(
-                    scale=4,
-                    show_label=False,
-                    placeholder="e.g., 'I want to build a RAG pipeline from scratch'",
-                    container=False,
-                )
-                submit_btn = gr.Button("Send", variant="primary", scale=1, min_width=100)
-
-        with gr.Column(scale=1):
-            gr.Markdown("### Resources")
-            file_uploader = gr.File(
-                file_count="multiple",
-                label="Upload for New Chat (Optional)",
-                file_types=[".pdf", ".txt", ".docx"],
-                visible=True,
-                interactive=True,
-            )
-            new_session_btn = gr.Button("Start New Session", variant="secondary")
-            tutor_prompt_header = gr.Markdown("### Tutor Persona Prompt", visible=False)
-            explainer_prompt_display = gr.Textbox(
-                label="You can modify the tutor's persona and instructions here:",
-                lines=15,
-                interactive=True,
-                visible=False,
-            )
+        
 
-    # --- 4. Event Listeners: Wiring the UI to the Backend ---
-    submit_actions = [txt_input, chatbot, app_state, file_uploader, explainer_prompt_display]
-    output_components = [chatbot, app_state, file_uploader, tutor_prompt_header, explainer_prompt_display, txt_input]
 
-    submit_btn.click(
-        fn=respond,
-        inputs=submit_actions,
-        outputs=output_components,
-    )
+        # --- TAB 3: Generated Persona Documentation ---
+        with gr.Tab("Explainer Persona Prompt", id="doc_tab"):
+            # This is the new, more descriptive placeholder.
+            brief_documentation_display = gr.Markdown(
+                """
+                ## Tutor Persona Prompt
+                
+                This Prompt will be generated after you finalize the syllabus in the chat.
 
-    txt_input.submit(
-        fn=respond,
-        inputs=submit_actions,
-        outputs=output_components,
-    )
+                It will contain the complete persona and system prompt that guides the AI tutor's teaching style, personality, and knowledge base.
 
-    new_session_btn.click(
-        fn=start_new_session,
-        inputs=[],
-        outputs=output_components
-    )
+                ---
+                *Waiting for syllabus to be finalized...*
+                """
+            )    
+    
+    api_key_submit_button.click(fn=start_session, inputs=[api_key_input, api_tier_radio], outputs=[api_setup_view, app_tabs, rate_limiter_state, api_error_output])
 
-# --- 5. Launch the App ---
+    def toggle_header(current_visibility_state):
+        new_visibility = not current_visibility_state
+        new_button_icon = "⬇️ Show Header" if not new_visibility else "⬆️ Hide Header"
+        return new_visibility, gr.update(visible=new_visibility), gr.update(value=new_button_icon)
+    toggle_header_btn.click(toggle_header, inputs=[header_visibility_state], outputs=[header_visibility_state, header_view, toggle_header_btn])
+
+    def close_sidebar():
+        return {tools_sidebar: gr.update(visible=False), open_sidebar_btn: gr.update(visible=True), chat_column: gr.update(scale=10)}
+    def open_sidebar():
+        return {tools_sidebar: gr.update(visible=True), open_sidebar_btn: gr.update(visible=False), chat_column: gr.update(scale=7)}
+    close_sidebar_btn.click(close_sidebar, outputs=[tools_sidebar, open_sidebar_btn, chat_column])
+    open_sidebar_btn.click(open_sidebar, outputs=[tools_sidebar, open_sidebar_btn, chat_column])
+    
+    chat_inputs = [user_input_textbox, file_uploader, session_state, uploaded_file_names_state, rate_limiter_state, explainer_prompt_box]
+    chat_outputs = [chatbot, user_input_textbox, session_state, file_uploader, send_button, explainer_prompt_accordion, explainer_prompt_box, file_display, uploaded_file_names_state, looks_good_btn, app_tabs, brief_documentation_display]
+    
+    user_input_textbox.submit(fn=handle_user_interaction, inputs=chat_inputs, outputs=chat_outputs)
+    send_button.click(fn=handle_user_interaction, inputs=chat_inputs, outputs=chat_outputs)
+    
+    looks_good_btn.click(lambda: "looks good", inputs=[], outputs=[user_input_textbox]).then(
+        fn=handle_user_interaction,
+        inputs=chat_inputs,
+        outputs=chat_outputs
+    )
 if __name__ == "__main__":
-    if not API_KEY:
-        print("\n" + "="*60)
-        print("CRITICAL ERROR: Cannot launch Gradio app.")
-        print("Your GOOGLE_API_KEY is not set in the .env file.")
-        print("="*60 + "\n")
+    # This section remains unchanged
+    if APP_MODE == 'admin':
+        logger.info("Starting in ADMIN mode.")
+        if initialize_dspy() and initialize_orchestrator_modules():
+            logger.info("Admin mode ready.")
+        else:
+            logger.critical("FATAL: Could not initialize DSPy or orchestrator modules in Admin mode.")
     else:
-        print("Launching Gradio app...")
-        demo.queue().launch(debug=True)
-
+        logger.info("Starting in VISITOR mode. Waiting for user to provide API key.")
+    demo.queue().launch(debug=True)
+