Refactor app.py for improved readability and organization; streamline comments and enhance Gradio interface styling

app.py

@@ -12,25 +12,24 @@ import gradio as gr
 from openai import OpenAI
 from dotenv import load_dotenv
 
-# Load environment variables - supports both local .env and Hugging Face Spaces
+# Load environment variables
 try:
     load_dotenv('api_keys.env')
 except:
-    pass  # Gracefully handle missing .env file
+    pass
 
-# Initialize OpenAI client with API key validation
+# Initialize OpenAI client
 openai_api_key = os.getenv("OPENAI_API_KEY")
 if not openai_api_key:
     raise ValueError("OPENAI_API_KEY not found. Please set it in your environment variables or .env file.")
 
-# Configure OpenAI client with settings optimized for Hugging Face Spaces
 client = OpenAI(
     api_key=openai_api_key,
-    timeout=60.0,  # Longer timeout for HF Spaces network
-    max_retries=3  # Retry on connection failures
+    timeout=60.0,
+    max_retries=3
 )
 
-# Explanation complexity levels with clear descriptions
+# Configuration
 EXPLANATION_LEVELS = {
     1: "like I'm 5 years old - use simple words and analogies",
     2: "like I'm 10 years old - basic concepts with examples", 
@@ -39,10 +38,8 @@ EXPLANATION_LEVELS = {
     5: "like an expert in the field - professional level with technical depth",
 }
 
-# Supported languages for explanations
 LANGUAGES = ["English", "Russian", "German", "Spanish", "French", "Italian"]
 
-# Example questions for quick selection
 EXAMPLE_QUESTIONS = [
     "Why is the sky blue?",
     "How does the internet work?",
@@ -51,34 +48,28 @@ EXAMPLE_QUESTIONS = [
 
 def explain_concept(question, level, language):
     """
-    Generate a comprehensive explanation for a given concept at the specified complexity level.
-    Supports streaming for real-time response generation.
+    Generate an explanation for a given concept with streaming.
     
     Args:
-        question (str): The concept or question to explain
-        level (int): Complexity level (1-5)
-        language (str): Language for the explanation
+        question: The concept or question to explain
+        level: Complexity level (1-5)
+        language: Language for the explanation
         
     Yields:
-        str: The generated explanation chunks or error message
+        Explanation text chunks or error message
     """
-    # Input validation
     if not question.strip():
         yield "❌ Please enter a concept to explain."
         return
     
-    # Get explanation level description
     level_desc = EXPLANATION_LEVELS.get(level, "clearly and comprehensively")
     
-    # Language validation with fallback
     if language not in LANGUAGES:
         language = "English"
     
-    # Professional system prompt for focused explanations
     system_prompt = f"""You are an expert educator. Explain the given concept {level_desc} in {language}. Provide a clear, accurate response in under 200 words. Ensure you use bold text to emphasize the key points. Do not include introductions, conclusions, or extra commentary - just the explanation."""
 
     try:
-        # Generate streaming explanation using OpenAI API
         stream = client.chat.completions.create(
             model="gpt-4.1-mini",
             messages=[
@@ -87,10 +78,9 @@ def explain_concept(question, level, language):
             ],
             temperature=0.7,
             max_tokens=1000,
-            stream=True  # Enable streaming
+            stream=True
         )
         
-        # Proper word-by-word streaming with partial accumulation
         partial = ""
         for chunk in stream:
             delta = getattr(chunk.choices[0].delta, "content", None)
@@ -99,11 +89,9 @@ def explain_concept(question, level, language):
                 yield partial
                 
     except Exception as e:
-        # Provide more specific error messages for common issues
         error_msg = str(e).lower()
         error_type = type(e).__name__
         
-        # Log full error for debugging (visible in HF Spaces logs)
         print(f"❌ API Error [{error_type}]: {str(e)}")
         
         if "connection" in error_msg or "timeout" in error_msg or "ssl" in error_msg:
@@ -128,39 +116,44 @@ def explain_concept(question, level, language):
         else:
             yield f"❌ **Error**: `[{error_type}]` {str(e)}"
 
-# Create enhanced Gradio interface with modern styling
+# Build Gradio interface
 with gr.Blocks(
-    theme=gr.themes.Soft(),  # Modern, clean theme
+    theme=gr.themes.Soft(),
     title="AI Concept Explainer",
     css="""
     .gradio-container {
         max-width: 900px !important;
         margin: auto !important;
     }
+    /* Light mode styling */
     .explanation-box {
         background: linear-gradient(135deg, #e0e7ff 0%, #f3e8ff 100%);
         color: #222;
         padding: 20px;
         border-radius: 10px;
         margin: 10px 0;
+        border: 1px solid #d0d7f7;
+    }
+    /* Dark mode styling */
+    .dark .explanation-box {
+        background: linear-gradient(135deg, #1e293b 0%, #312e81 100%);
+        color: #e2e8f0;
+        border: 1px solid #475569;
     }
     """
 ) as app:
-    # Header with description
     gr.Markdown("""
     # 🧠 AI Concept Explainer
     
     Get clear, personalized explanations of any concept at your preferred complexity level and language.
     """)
     
-    # Example selection section
     gr.Markdown("### 💡 Quick Examples")
     with gr.Row():
         example_btn1 = gr.Button("Why is the sky blue?", size="sm", variant="secondary")
         example_btn2 = gr.Button("How does the internet work?", size="sm", variant="secondary")
         example_btn3 = gr.Button("What is artificial intelligence?", size="sm", variant="secondary")
     
-    # Input section with improved layout
     with gr.Row():
         with gr.Column(scale=2):
             question = gr.Textbox(
@@ -184,25 +177,22 @@ with gr.Blocks(
                 info="Choose your preferred language"
             )
     
-    # Action button with enhanced styling
     explain_btn = gr.Button(
         "🚀 Explain Concept", 
         variant="primary",
         size="lg"
     )
     
-    # Output section with better formatting
     output = gr.Markdown(
         label="📝 Explanation",
         elem_classes=["explanation-box"]
     )
     
-    # Connect example buttons to populate question field
+    # Wire up event handlers
     example_btn1.click(lambda: EXAMPLE_QUESTIONS[0], outputs=question)
     example_btn2.click(lambda: EXAMPLE_QUESTIONS[1], outputs=question)
     example_btn3.click(lambda: EXAMPLE_QUESTIONS[2], outputs=question)
     
-    # Connect button click to explanation function with streaming
     explain_btn.click(
         explain_concept, 
         inputs=[question, level, language], 
@@ -210,52 +200,32 @@ with gr.Blocks(
     )
 
 def signal_handler(signum, frame):
-    """Handle graceful shutdown signals for local development."""
+    """Handle graceful shutdown for local development."""
     print(f"Received signal {signum}, shutting down gracefully...")
     exit(0)
 
 if __name__ == "__main__":
-    # Detect environment - Hugging Face Spaces vs local development
     is_space = os.getenv('SPACE_ID') is not None
     
-    # Set up signal handler for local development only
     if not is_space:
         signal.signal(signal.SIGINT, signal_handler)
     
     print("🚀 Starting AI Concept Explainer...")
-    print(f"Environment: {'Hugging Face Spaces' if is_space else 'Local Development'}")
     print(f"API Key configured: {'✅ Yes' if openai_api_key else '❌ No'}")
-    if openai_api_key:
-        print(f"API Key starts with: {openai_api_key[:10]}...")
-    
-    # Test OpenAI connection at startup (HF Spaces only)
-    if is_space:
-        try:
-            print("\n🔍 Testing OpenAI API connection...")
-            # Simple API test
-            test_models = client.models.list()
-            print("✅ OpenAI API connection successful!")
-        except Exception as e:
-            print(f"⚠️  WARNING: OpenAI API connection test failed!")
-            print(f"   Error: [{type(e).__name__}] {str(e)}")
-            print(f"   The app will start, but API calls may fail.")
-            print(f"   Check: 1) OPENAI_API_KEY secret is set, 2) API key is valid")
     
     if is_space:
-        # Production configuration for Hugging Face Spaces
         app.launch(
-            server_name="0.0.0.0",  # Accept external connections
-            server_port=7860,       # Standard Spaces port
-            show_error=True,        # Display errors in UI
-            quiet=False             # Show startup logs
+            server_name="0.0.0.0",
+            server_port=7860,
+            show_error=True,
+            quiet=False
         )
     else:
-        # Development configuration for local use
         app.launch(
-            share=False,            # No public sharing
-            server_name="127.0.0.1", # Localhost only
-            server_port=7860,       # Consistent port
-            inbrowser=True,         # Auto-open browser
-            show_error=True,        # Display errors in UI
-            quiet=False             # Show startup logs
+            share=False,
+            server_name="127.0.0.1",
+            server_port=7860,
+            inbrowser=True,
+            show_error=True,
+            quiet=False
         )