Update app.py

app.py

@@ -7,6 +7,13 @@ import time
 # --- Constants ---
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
+# Sample questions for offline testing
+SAMPLE_QUESTIONS = [
+    {"task_id": "sample_1", "question": "What is 2 + 2?"},
+    {"task_id": "sample_2", "question": "What is the capital of France?"},
+    {"task_id": "sample_3", "question": "Who wrote 'Romeo and Juliet'?"},
+]
+
 # --- Basic Agent Definition ---
 # 👉 You can customize this class with your own logic or tools
 class BasicAgent:
@@ -21,55 +28,82 @@ class BasicAgent:
         return fixed_answer
 
 
-def check_api_status(api_url: str) -> tuple[bool, str]:
-    """Check if the API is accessible"""
-    try:
-        # Try to access the base URL or a health check endpoint
-        response = requests.get(api_url, timeout=10)
-        if response.status_code == 200:
-            return True, "API is accessible"
-        else:
-            return False, f"API returned status code: {response.status_code}"
-    except requests.exceptions.Timeout:
-        return False, "API request timed out"
-    except requests.exceptions.ConnectionError:
-        return False, "Cannot connect to API (connection error)"
-    except Exception as e:
-        return False, f"API check failed: {str(e)}"
+def check_api_health(api_url: str) -> tuple[bool, str, dict]:
+    """Check if the API endpoints are accessible"""
+    endpoints_to_check = [
+        ("Base URL", api_url),
+        ("Questions", f"{api_url}/questions"),
+        ("Docs", f"{api_url}/docs"),
+    ]
+    
+    results = {}
+    for name, url in endpoints_to_check:
+        try:
+            response = requests.get(url, timeout=10)
+            results[name] = {
+                "status_code": response.status_code,
+                "accessible": response.status_code in [200, 307],
+                "url": url
+            }
+        except requests.exceptions.Timeout:
+            results[name] = {"status_code": "Timeout", "accessible": False, "url": url}
+        except requests.exceptions.ConnectionError:
+            results[name] = {"status_code": "Connection Error", "accessible": False, "url": url}
+        except Exception as e:
+            results[name] = {"status_code": str(e), "accessible": False, "url": url}
+    
+    # Check if any endpoint is accessible
+    any_accessible = any(r["accessible"] for r in results.values())
+    
+    status_msg = "API Health Check:\n"
+    for name, result in results.items():
+        status = "✅" if result["accessible"] else "❌"
+        status_msg += f"{status} {name}: {result['status_code']}\n"
+    
+    return any_accessible, status_msg, results
 
 
-def run_and_submit_all(profile: gr.OAuthProfile | None):
+def run_and_submit_all(profile: gr.OAuthProfile | None, use_offline_mode: bool = False):
     """
     Fetch all questions, run the agent, submit answers, and show results.
     """
     space_id = os.getenv("SPACE_ID")  # Hugging Face Space ID
 
-    if profile:
-        username = profile.username
-        print(f"👤 User logged in: {username}")
+    if not use_offline_mode:
+        if profile:
+            username = profile.username
+            print(f"👤 User logged in: {username}")
+        else:
+            print("❌ User not logged in.")
+            return "❌ Please login to Hugging Face first (or use offline test mode).", None
     else:
-        print("❌ User not logged in.")
-        return "❌ Please login to Hugging Face first.", None
+        username = "offline_test_user"
+        print("🧪 Running in offline test mode")
 
     api_url = DEFAULT_API_URL
     questions_url = f"{api_url}/questions"
     submit_url = f"{api_url}/submit"
 
-    # Check API status first
-    print("🔍 Checking API status...")
-    api_ok, api_msg = check_api_status(api_url)
-    if not api_ok:
-        error_msg = (
-            f"⚠️ API Status Check Failed\n\n"
-            f"Issue: {api_msg}\n\n"
-            f"Possible solutions:\n"
-            f"1. The scoring API at {api_url} may be down or moved\n"
-            f"2. Check if the API URL is correct\n"
-            f"3. The Hugging Face Space might need to be restarted\n"
-            f"4. Try again in a few minutes\n\n"
-            f"You can verify the API status by visiting: {api_url}"
-        )
-        return error_msg, None
+    # Check API health
+    if not use_offline_mode:
+        print("🔍 Checking API health...")
+        api_ok, health_msg, health_results = check_api_health(api_url)
+        print(health_msg)
+        
+        # If API is completely inaccessible, suggest offline mode
+        if not api_ok:
+            error_msg = (
+                f"⚠️ API Health Check Failed\n\n"
+                f"{health_msg}\n"
+                f"🔧 Troubleshooting Options:\n\n"
+                f"1. **Try Offline Test Mode**: Enable the checkbox below to test your agent locally\n"
+                f"2. **Wait and Retry**: The Hugging Face Space may be starting up (can take 1-2 minutes)\n"
+                f"3. **Check Space Status**: Visit https://huggingface.co/spaces/agents-course/agents-course-unit4-scoring\n"
+                f"4. **Use Alternative Template**: Try the official template at https://huggingface.co/spaces/agents-course/Final_Assignment_Template\n"
+                f"5. **Contact Course Support**: Check the course Discord or GitHub for updates\n\n"
+                f"💡 The API scoring system might be temporarily unavailable or undergoing maintenance."
+            )
+            return error_msg, None
 
     # 1️⃣ Create Agent
     try:
@@ -81,40 +115,45 @@ def run_and_submit_all(profile: gr.OAuthProfile | None):
     print(f"📁 Agent code link: {agent_code}")
 
     # 2️⃣ Fetch Questions
-    try:
-        print("📡 Fetching questions...")
-        response = requests.get(questions_url, timeout=15)
-        
-        if response.status_code == 404:
-            error_msg = (
-                f"⚠️ Questions endpoint not found (404)\n\n"
-                f"The endpoint {questions_url} is not available.\n\n"
-                f"Possible issues:\n"
-                f"1. The API structure may have changed\n"
-                f"2. The scoring service might be under maintenance\n"
-                f"3. You may need to update the API URL\n\n"
-                f"Please check the course materials or contact the instructor for the correct API endpoint."
-            )
-            return error_msg, None
-        
-        response.raise_for_status()
-        questions_data = response.json()
-        
-        if not questions_data:
-            return "⚠️ Fetched question list is empty or invalid.", None
-        
-        print(f"✅ Retrieved {len(questions_data)} questions.")
-        
-    except requests.exceptions.Timeout:
-        return f"⏱️ Request timed out while fetching questions from {questions_url}", None
-    except requests.exceptions.ConnectionError:
-        return f"🔌 Connection error: Cannot reach {questions_url}", None
-    except requests.exceptions.HTTPError as e:
-        return f"❌ HTTP Error fetching questions: {e}", None
-    except ValueError as e:
-        return f"❌ Invalid JSON response from questions endpoint: {e}", None
-    except Exception as e:
-        return f"❌ Error fetching questions: {e}", None
+    if use_offline_mode:
+        print("🧪 Using sample questions for offline testing")
+        questions_data = SAMPLE_QUESTIONS
+    else:
+        try:
+            print("📡 Fetching questions from API...")
+            response = requests.get(questions_url, timeout=30)
+            
+            if response.status_code == 404:
+                error_msg = (
+                    f"⚠️ Questions endpoint returned 404\n\n"
+                    f"The endpoint {questions_url} is not found.\n\n"
+                    f"This might mean:\n"
+                    f"• The Hugging Face Space is still starting up (try waiting 60 seconds)\n"
+                    f"• The Space has been moved or the API structure changed\n"
+                    f"• The Space is in a sleep/stopped state\n\n"
+                    f"🔧 Solutions:\n"
+                    f"1. Enable 'Offline Test Mode' below to test locally\n"
+                    f"2. Visit the Space directly: https://huggingface.co/spaces/agents-course/agents-course-unit4-scoring\n"
+                    f"3. Check the official template: https://huggingface.co/spaces/agents-course/Final_Assignment_Template\n"
+                    f"4. Join the course Discord for real-time help\n\n"
+                    f"💡 Tip: Offline mode lets you test your agent logic without needing the API!"
+                )
+                return error_msg, None
+            
+            response.raise_for_status()
+            questions_data = response.json()
+            
+            if not questions_data:
+                return "⚠️ Fetched question list is empty.", None
+            
+            print(f"✅ Retrieved {len(questions_data)} questions from API.")
+            
+        except requests.exceptions.Timeout:
+            return f"⏱️ Request timed out. The API might be slow to respond. Try enabling offline test mode.", None
+        except requests.exceptions.ConnectionError:
+            return f"🔌 Cannot connect to API. Try offline test mode or check your internet connection.", None
+        except Exception as e:
+            return f"❌ Error fetching questions: {e}\n\nTry using offline test mode to test your agent locally.", None
 
     # 3️⃣ Run Agent
     results_log = []
@@ -131,27 +170,42 @@ def run_and_submit_all(profile: gr.OAuthProfile | None):
             continue
         
         try:
-            print(f"Processing question {i+1}/{len(questions_data)}: {task_id}")
+            print(f"Processing {i+1}/{len(questions_data)}: {task_id}")
             submitted_answer = agent(question_text)
             answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
             results_log.append({
                 "Task ID": task_id,
                 "Question": question_text[:100] + "..." if len(question_text) > 100 else question_text,
-                "Submitted Answer": submitted_answer[:100] + "..." if len(str(submitted_answer)) > 100 else submitted_answer
+                "Your Answer": str(submitted_answer)[:100] + "..." if len(str(submitted_answer)) > 100 else str(submitted_answer)
             })
         except Exception as e:
-            error_msg = f"AGENT ERROR: {e}"
+            error_msg = f"ERROR: {e}"
             print(f"❌ {error_msg} for task {task_id}")
             results_log.append({
                 "Task ID": task_id,
                 "Question": question_text[:100] + "..." if len(question_text) > 100 else question_text,
-                "Submitted Answer": error_msg
+                "Your Answer": error_msg
             })
 
     if not answers_payload:
         return "⚠️ No answers generated by the agent.", pd.DataFrame(results_log)
 
-    # 4️⃣ Submit Answers
+    results_df = pd.DataFrame(results_log)
+
+    # 4️⃣ Submit Answers (skip in offline mode)
+    if use_offline_mode:
+        final_status = (
+            f"🧪 Offline Test Mode - Agent Run Complete!\n\n"
+            f"✅ Successfully generated {len(answers_payload)} answers\n"
+            f"📝 Review your answers in the table below\n\n"
+            f"ℹ️ To submit for real scoring:\n"
+            f"1. Disable offline test mode\n"
+            f"2. Wait for the API to be available\n"
+            f"3. Run the evaluation again\n\n"
+            f"💡 Your agent logic is working! Just needs API connection for scoring."
+        )
+        return final_status, results_df
+
     submission_data = {
         "username": username.strip(),
         "agent_code": agent_code,
@@ -159,37 +213,39 @@ def run_and_submit_all(profile: gr.OAuthProfile | None):
     }
 
     try:
-        print("📤 Submitting answers...")
-        response = requests.post(submit_url, json=submission_data, timeout=60)
+        print("📤 Submitting answers to API...")
+        response = requests.post(submit_url, json=submission_data, timeout=90)
         
         if response.status_code == 404:
             error_msg = (
                 f"⚠️ Submit endpoint not found (404)\n\n"
-                f"Generated {len(answers_payload)} answers but cannot submit them.\n"
-                f"The endpoint {submit_url} is not available.\n\n"
-                f"Your answers are shown in the table below for reference."
+                f"✅ Good news: Your agent generated {len(answers_payload)} answers!\n"
+                f"❌ Bad news: Cannot submit them - API endpoint unavailable\n\n"
+                f"Your answers are saved in the table below.\n\n"
+                f"Next steps:\n"
+                f"• Try again in a few minutes (Space might be starting)\n"
+                f"• Use the official submission template\n"
+                f"• Contact course instructors for API status"
             )
-            return error_msg, pd.DataFrame(results_log)
+            return error_msg, results_df
         
         response.raise_for_status()
         result_data = response.json()
         
         final_status = (
-            f"✅ Submission Successful!\n"
-            f"👤 User: {result_data.get('username')}\n"
+            f"🎉 Submission Successful!\n\n"
+            f"👤 Username: {result_data.get('username')}\n"
             f"🏁 Score: {result_data.get('score', 'N/A')}% "
-            f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n"
-            f"📝 Message: {result_data.get('message', 'No message received.')}"
+            f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n\n"
+            f"📝 {result_data.get('message', 'No message received.')}\n\n"
+            f"🔗 Check the leaderboard to see your ranking!"
         )
-        results_df = pd.DataFrame(results_log)
         return final_status, results_df
         
     except requests.exceptions.Timeout:
-        return f"⏱️ Submission timed out. Your answers:\n{len(answers_payload)} answers generated but not submitted.", pd.DataFrame(results_log)
-    except requests.exceptions.HTTPError as e:
-        return f"❌ HTTP Error during submission: {e}\nYour answers are shown below.", pd.DataFrame(results_log)
+        return f"⏱️ Submission timed out after 90 seconds.\n\n✅ Your agent generated {len(answers_payload)} answers (see table below)\n❌ But submission failed due to timeout.\n\nTry again or contact course support.", results_df
     except Exception as e:
-        return f"❌ Submission failed: {e}\nYour answers are shown below.", pd.DataFrame(results_log)
+        return f"❌ Submission failed: {e}\n\n✅ Your agent generated {len(answers_payload)} answers (see table below)\n\nTry submitting again later.", results_df
 
 
 # --- Gradio Interface ---
@@ -197,26 +253,69 @@ with gr.Blocks(theme=gr.themes.Soft()) as demo:
     gr.Markdown("# 🤖 Basic Agent Evaluation Runner")
     gr.Markdown(
         """
-        ### Instructions:
-        1️⃣ Clone this space on your Hugging Face profile.  
-        2️⃣ Modify the `BasicAgent` class with your logic.  
-        3️⃣ Log in below and run evaluation.  
+        ### 📋 Instructions:
+        1️⃣ **Clone this space** to your Hugging Face profile  
+        2️⃣ **Customize the `BasicAgent` class** with your logic (add tools, reasoning, etc.)  
+        3️⃣ **Log in** and run the evaluation  
+        
+        ---
+        
+        ### ⚠️ API Issues?
+        If you're seeing 404 errors, the scoring API might be temporarily unavailable:
+        - ✅ **Use Offline Test Mode** (checkbox below) to test your agent locally
+        - ⏰ **Wait 1-2 minutes** for the Hugging Face Space to wake up
+        - 🔗 **Check official template**: [Final Assignment Template](https://huggingface.co/spaces/agents-course/Final_Assignment_Template)
+        - 💬 **Get help**: Join the [course Discord](https://discord.gg/hugging-face) 
+        
         ---
-        The process may take time (the agent answers all questions).  
-        You can customize the agent with reasoning, search tools, or memory.
         
-        ⚠️ **Note**: If you see a 404 error, the scoring API may be temporarily unavailable.
-        Check with your instructor for the correct API endpoint.
+        ### 💡 Tips:
+        - The agent will answer ALL questions (this takes time!)
+        - Customize your agent with: reasoning, web search, calculators, file readers, etc.
+        - Aim for 30%+ score to get your certificate!
         """
     )
 
-    gr.LoginButton()
-    run_button = gr.Button("🚀 Run Evaluation & Submit All Answers", variant="primary")
+    with gr.Row():
+        gr.LoginButton()
+    
+    with gr.Row():
+        offline_mode = gr.Checkbox(
+            label="🧪 Offline Test Mode (test agent without API)", 
+            value=False,
+            info="Enable this to test your agent with sample questions when the API is unavailable"
+        )
+    
+    run_button = gr.Button("🚀 Run Evaluation & Submit", variant="primary", size="lg")
 
-    status_output = gr.Textbox(label="Run Status / Submission Result", lines=8, interactive=False)
-    results_table = gr.DataFrame(label="Questions and Agent Answers")
+    status_output = gr.Textbox(
+        label="📊 Status / Results", 
+        lines=10, 
+        interactive=False,
+        show_copy_button=True
+    )
+    
+    results_table = gr.DataFrame(
+        label="📝 Questions and Agent Answers",
+        wrap=True
+    )
 
-    run_button.click(fn=run_and_submit_all, outputs=[status_output, results_table])
+    gr.Markdown(
+        """
+        ---
+        ### 🔗 Helpful Resources:
+        - [Course Materials](https://huggingface.co/learn/agents-course)
+        - [Official Template](https://huggingface.co/spaces/agents-course/Final_Assignment_Template)
+        - [GAIA Benchmark Info](https://huggingface.co/gaia-benchmark)
+        - [Course Discord](https://discord.gg/hugging-face)
+        """
+    )
+
+    run_button.click(
+        fn=run_and_submit_all, 
+        inputs=[offline_mode],
+        outputs=[status_output, results_table]
+    )
 
 
 if __name__ == "__main__":