Update app.py

app.py

@@ -3,80 +3,75 @@ import time
 from typing import Dict, Any
 import gradio as gr
 
-# --- 模擬環境變數與 Firebase/API 設置 ---
-# 在 Hugging Face 上部署時，我們使用模擬呼叫，避免 API Key 洩露和複雜的網路配置。
+# --- Simulation Setup for LLM API ---
+# This section simulates the core AI generation logic without requiring a live API key.
 LLM_MODEL = "gemini-2.5-flash-preview-09-2025"
-API_KEY = "MOCK_KEY"
-# API_URL_TEMPLATE = f"https://generativelanguage.googleapis.com/v1beta/models/{LLM_MODEL}:generateContent?key={API_KEY}" # 實際 API URL
-
-# --- 模擬 LLM API 呼叫 (保留原有的模擬邏輯) ---
-# 為了讓 Gradio 應用程式在沒有實際 API 密鑰和網路連線的情況下也能運行，
-# 這裡保留了對結構化 JSON 的模擬輸出。
+API_KEY = "MOCK_KEY" # Placeholder
 
 def simulate_gemini_api_call(payload: Dict[str, Any], fields: Dict[str, Any]) -> Dict[str, Any]:
     """
-    模擬對 Gemini API 的 POST 呼叫，返回預設的結構化 JSON 輸出。
+    Simulates a structured response from the Gemini API based on the task type.
     
     Args:
-        payload: 準備傳送給 API 的 JSON 負載。
-        fields: 用戶輸入的欄位，用於客製化模擬輸出。
+        payload: The constructed API payload (used for extracting system instructions).
+        fields: User input fields for customizing the mock output.
         
     Returns:
-        一個模擬的 API 回應 JSON 結構。
+        A dictionary simulating the API's JSON response structure.
     """
     
     user_query = payload['contents'][0]['parts'][0]['text']
-    system_instruction = payload.get('systemInstruction', {}).get('parts', [{}])[0].get('text', '無系統指令')
+    system_instruction = payload.get('systemInstruction', {}).get('parts', [{}])[0].get('text', 'No system instruction')
     
-    # 根據指令內容返回不同的模擬結果
+    # Check system instruction to determine the output type (Admin or Teaching)
     if "台灣中學學務處行政書記" in system_instruction:
-        # 模擬 行政 Copilot (會議記錄) 的結構化輸出
+        # Simulate Admin Copilot (Meeting Minutes) output
         mock_text_result = json.dumps({
-            "文件類型": "學務處會議記錄",
+            "文件類型 (Document Type)": "學務處會議記錄 (Academic Affairs Meeting Minutes)",
             "meeting_info": {
                 "date": fields.get('date', '2025-01-10'),
-                "location": fields.get('location', '學務處會議室'),
+                "location": fields.get('location', '會議室'),
                 "topic": fields.get('topic', '模擬會議主題')
             },
-            "attendees": ["校長", "主任", "學務處全體同仁"],
+            "attendees": ["Principal", "Director", "All Faculty"],
             "key_points": [
-                "期末獎懲核定程序已完成，共計 30 案。",
-                "新生訓練籌備進度達 80%，需確認場地佈置事宜。"
+                "End-of-term commendation process finalized, 30 cases approved.",
+                "New student orientation preparation is 80% complete; venue setup confirmed."
             ],
             "resolutions": [
-                {"item": "請人事室發佈獎懲公告。", "responsible": "人事組", "deadline": "2025-01-15"},
-                {"item": "新生訓練場地桌椅於活動前一日完成配置。", "responsible": "總務處", "deadline": "2025-08-20"}
+                {"item": "Issue official commendation announcement.", "responsible": "HR", "deadline": "2025-01-15"},
+                {"item": "Venue setup for orientation completed one day prior.", "responsible": "General Affairs", "deadline": "2025-08-20"}
             ],
-            "audit_note": "本文件依據校內「會議記錄書寫規範」生成，符合 MVP 規格 3.3 節規範。"
+            "audit_note": "Document generated per internal school writing guidelines."
         }, ensure_ascii=False, indent=2)
         
     elif "台灣國高中資深教師與課程設計師" in system_instruction:
-        # 模擬 教學設計器 (教案) 的結構化輸出
+        # Simulate Teaching Designer (Lesson Plan & Rubric) output
         mock_text_result = json.dumps({
-            "文件類型": "單元教案與評量規準",
-            "lesson_plan_title": f"【{fields.get('subject', 'N/A')}】探索 {fields.get('topic', 'N/A')} 的奧秘 (共 {fields.get('hours', 0)} 節)",
+            "文件類型 (Document Type)": "單元教案與評量規準 (Lesson Plan & Rubric)",
+            "lesson_plan_title": f"【{fields.get('subject', 'N/A')}】Exploring {fields.get('topic', 'N/A')} ({fields.get('hours', 0)} sessions)",
             "grade_level": fields.get('grade', 'N/A'),
-            "curriculum_alignment": ["A2 邏輯運算與推理 (108 課綱素養)", "B3 獨立思考"],
-            "learning_objectives": ["學生能解釋...。", "學生能應用...。"],
+            "curriculum_alignment": ["A2 Logical Reasoning (Curriculum Competency)", "B3 Independent Thinking"],
+            "learning_objectives": ["Students can explain X.", "Students can apply Y."],
             "activities": [
-                {"time_min": 15, "stage": "前導", "method": "提問法", "description": "利用日常生活案例引導學生思考主題的相關性。"},
-                {"time_min": 30, "stage": "活動一", "method": "合作學習", "description": "分組討論並進行實作練習。"},
+                {"time_min": 15, "stage": "Introduction", "method": "Inquiry", "description": "Use real-life examples to introduce the core concept."},
+                {"time_min": 30, "stage": "Activity One", "method": "Collaborative Learning", "description": "Group project and practical exercise."},
             ],
             "rubric": {
-                "title": "單元評量規準 (Rubric) - 4 等第 x 4 指標",
+                "title": "Unit Assessment Rubric (4 Levels x 4 Indicators)",
                 "criteria": [
-                    {"name": "概念理解", "A": "能清晰、準確地解釋所有核心概念。", "D": "僅能回答部分簡單問題。"},
-                    {"name": "團隊合作", "A": "積極參與並領導團隊完成任務。", "D": "不參與討論，需老師催促。"}
+                    {"name": "Conceptual Understanding", "A": "Clearly and accurately explains all core concepts.", "D": "Answers only simple questions."},
+                    {"name": "Teamwork", "A": "Actively leads the team to complete the task.", "D": "Does not participate in discussion."}
                 ]
             },
-            "differentiation_advice": "針對英語程度較弱學生，提供雙語關鍵字卡。"
+            "differentiation_advice": "Provide bilingual vocabulary cards for students with lower English proficiency."
         }, ensure_ascii=False, indent=2)
         
     else:
         mock_text_result = json.dumps({"error": "Unknown or missing task instruction."})
 
 
-    # 模擬 API 回應的標準結構
+    # Return the simulated API response structure
     return {
         "candidates": [{
             "content": {
@@ -86,18 +81,11 @@ def simulate_gemini_api_call(payload: Dict[str, Any], fields: Dict[str, Any]) ->
         }]
     }
 
-# --- 模組 A：行政 Copilot 生成器 (Gradio Wrapper) ---
+# --- Module A: Admin Copilot Generator (Gradio Wrapper) ---
 
 def admin_copilot_generator(template_id: str, topic: str, date: str, location: str, key_input: str) -> str:
     """
-    Gradio 呼叫的行政 Copilot 函式。
-    
-    Args:
-        template_id: 模板 ID (MVP 固定為會議記錄)
-        topic, date, location, key_input: 使用者輸入的欄位。
-        
-    Returns:
-        格式化後的 JSON 字串。
+    Handles the Admin Copilot UI inputs and calls the simulation.
     """
     fields = {
         "topic": topic,
@@ -106,7 +94,7 @@ def admin_copilot_generator(template_id: str, topic: str, date: str, location: s
         "key_input": key_input
     }
 
-    # 構造系統指令和結構
+    # System Prompt and Schema defined as per spec 8.A
     system_prompt = (
         "角色：台灣中學學務處行政書記\n"
         "輸出：JSON（會議資訊、出席、重點、決議、待辦、負責人、期限）\n"
@@ -116,7 +104,7 @@ def admin_copilot_generator(template_id: str, topic: str, date: str, location: s
     response_schema = {
         "type": "OBJECT",
         "properties": {
-            "文件類型": {"type": "STRING"},
+            "文件類型 (Document Type)": {"type": "STRING"},
             "meeting_info": {"type": "OBJECT", "properties": {"date": {"type": "STRING"}, "location": {"type": "STRING"}, "topic": {"type": "STRING"}}},
             "attendees": {"type": "ARRAY", "items": {"type": "STRING"}},
             "key_points": {"type": "ARRAY", "items": {"type": "STRING"}},
@@ -145,28 +133,19 @@ def admin_copilot_generator(template_id: str, topic: str, date: str, location: s
         }
     }
 
-    # 呼叫模擬 API
     api_response = simulate_gemini_api_call(payload, fields)
     
-    # 解析結果
     try:
         json_string = api_response['candidates'][0]['content']['parts'][0]['text']
-        # 返回格式化的 JSON 字串供 Gradio 顯示
         return json_string
     except (KeyError, json.JSONDecodeError):
-        return "錯誤：無法解析 LLM 結構化輸出。"
+        return "ERROR: Failed to parse LLM structured output."
 
-# --- 模組 B：教師 AI 創新教學設計器 (Gradio Wrapper) ---
+# --- Module B: Teaching AI Designer (Gradio Wrapper) ---
 
 def lesson_plan_designer(grade: str, subject: str, topic: str, hours: int, method: str, equipment: str, class_needs: str) -> str:
     """
-    Gradio 呼叫的教學設計器函式。
-    
-    Args:
-        grade, subject, topic, hours, method, equipment, class_needs: 使用者輸入的欄位。
-        
-    Returns:
-        格式化後的 JSON 字串。
+    Handles the Teaching Designer UI inputs and calls the simulation.
     """
     fields = {
         "grade": grade,
@@ -178,7 +157,7 @@ def lesson_plan_designer(grade: str, subject: str, topic: str, hours: int, metho
         "class_needs": class_needs
     }
     
-    # 規格 8.B 系統指令
+    # System Prompt and Schema defined as per spec 8.B
     system_prompt = (
         "角色：台灣國高中資深教師與課程設計師\n"
         "輸出：JSON（教案標題、目標、課綱對齊、活動步驟、評量規準、差異化建議）\n"
@@ -186,22 +165,20 @@ def lesson_plan_designer(grade: str, subject: str, topic: str, hours: int, metho
         "對齊：請將輸出中的 'curriculum_alignment' 欄位，對齊台灣課綱的關鍵能力/素養。"
     )
     
-    # 結構化輸出 Schema 
     response_schema = {
         "type": "OBJECT",
         "properties": {
-            "文件類型": {"type": "STRING"},
+            "文件類型 (Document Type)": {"type": "STRING"},
             "lesson_plan_title": {"type": "STRING"},
             "grade_level": {"type": "STRING"},
             "curriculum_alignment": {"type": "ARRAY", "items": {"type": "STRING"}},
             "learning_objectives": {"type": "ARRAY", "items": {"type": "STRING"}},
-            "activities": {"type": "ARRAY", "items": {"type": "OBJECT"}}, # 簡化結構
-            "rubric": {"type": "OBJECT"}, # 簡化結構
+            "activities": {"type": "ARRAY", "items": {"type": "OBJECT"}},
+            "rubric": {"type": "OBJECT"},
             "differentiation_advice": {"type": "STRING"}
         }
     }
 
-    # 規格 4.1 使用者欄位組合 Query
     user_query = (
         f"請根據以下資訊設計一個單元教案、評量規準和差異化建議：\n"
         f"年級/學科/單元主題: {grade}/{subject}/{topic}\n"
@@ -211,7 +188,6 @@ def lesson_plan_designer(grade: str, subject: str, topic: str, hours: int, metho
         f"班級特性: {class_needs}"
     )
 
-    # 構造 API 請求負載
     payload = {
         "contents": [{ "parts": [{ "text": user_query }] }],
         "systemInstruction": { "parts": [{ "text": system_prompt }] },
@@ -221,52 +197,49 @@ def lesson_plan_designer(grade: str, subject: str, topic: str, hours: int, metho
         }
     }
 
-    # 呼叫模擬 API
     api_response = simulate_gemini_api_call(payload, fields)
     
-    # 解析結果
     try:
         json_string = api_response['candidates'][0]['content']['parts'][0]['text']
-        # 返回格式化的 JSON 字串供 Gradio 顯示
         return json_string
     except (KeyError, json.JSONDecodeError):
-        return "錯誤：無法解析 LLM 結構化輸出。"
+        return "ERROR: Failed to parse LLM structured output."
 
-# --- Gradio 介面定義 ---
+# --- Gradio Interface Definition ---
 
-# 模組 A 介面 (行政 Copilot)
+# Module A Interface (Admin Copilot)
 admin_copilot_interface = gr.Interface(
     fn=admin_copilot_generator,
     inputs=[
-        gr.Textbox(label="模板 ID (MVP 固定)", value="meeting_minutes_standard", interactive=False),
-        gr.Textbox(label="會議主題 (Topic)", value="學務處期末獎懲與新生訓練籌備會議"),
+        gr.Textbox(label="模板 ID (Template ID - Fixed for MVP)", value="meeting_minutes_standard", interactive=False),
+        gr.Textbox(label="會議主題 (Meeting Topic)", value="學務處期末獎懲與新生訓練籌備會議"),
         gr.Textbox(label="日期 (Date)", value="2025-01-10"),
         gr.Textbox(label="地點 (Location)", value="學務處會議室"),
-        gr.Textbox(label="輸入重點/逐字稿 (Key Input)", value="討論期末獎懲核定程序。新生訓練場地佈置、人員編組確認。", lines=5),
+        gr.Textbox(label="輸入重點/逐字稿 (Key Input/Transcript)", value="討論期末獎懲核定程序。新生訓練場地佈置、人員編組確認。", lines=5),
     ],
-    outputs=gr.JSON(label="AI 生成結構化 JSON 初稿 (將套入 DOCX 模板)"),
-    title="行政 Copilot：會議記錄生成",
+    outputs=gr.JSON(label="AI 生成結構化 JSON 初稿 (Structured JSON Draft for DOCX Templating)"),
+    title="行政 Copilot：會議記錄生成 (Admin Copilot: Meeting Minutes Generation)",
     description="🎯 模擬一鍵生成格式嚴謹的行政文件 JSON。實際系統將此 JSON 套入 DOCX 模板匯出。"
 )
 
-# 模組 B 介面 (教學設計器)
+# Module B Interface (Teaching Designer)
 lesson_plan_designer_interface = gr.Interface(
     fn=lesson_plan_designer,
     inputs=[
         gr.Dropdown(label="年級 (Grade)", choices=["國一", "高一", "小六"], value="高一"),
         gr.Textbox(label="學科 (Subject)", value="歷史"),
-        gr.Textbox(label="單元主題 (Topic)", value="從茶葉看全球化：17-19世紀的貿易網絡"),
-        gr.Slider(label="課時數 (Hours)", minimum=1, maximum=10, step=1, value=4),
-        gr.Dropdown(label="教學法偏好 (Method)", choices=["探究式、PBL", "翻轉教學", "合作學習", "講述法"], value="探究式、PBL"),
-        gr.Textbox(label="可用設備 (Equipment)", value="平板電腦、投影設備、網路"),
-        gr.Textbox(label="班級���性 (Class Needs)", value="班級組成多元，需考慮多樣化的史料呈現方式。"),
+        gr.Textbox(label="單元主題 (Unit Topic)", value="從茶葉看全球化：17-19世紀的貿易網絡"),
+        gr.Slider(label="課時數 (Number of Sessions)", minimum=1, maximum=10, step=1, value=4),
+        gr.Dropdown(label="教學法偏好 (Pedagogy Preference)", choices=["探究式、PBL", "翻轉教學", "合作學習", "講述法"], value="探究式、PBL"),
+        gr.Textbox(label="可用設備 (Available Equipment)", value="平板電腦、投影設備、網路"),
+        gr.Textbox(label="班級特性 (Class Characteristics)", value="班級組成多元，需考慮多樣化的史料呈現方式。"),
     ],
-    outputs=gr.JSON(label="AI 生成教案與評量規準 JSON"),
-    title="教學 AI 設計器：教案與 Rubric 生成",
+    outputs=gr.JSON(label="AI 生成教案與評量規準 JSON (Lesson Plan & Rubric JSON)"),
+    title="教學 AI 設計器：教案與 Rubric 生成 (Teaching AI Designer: Lesson Plan & Rubric)",
     description="📘 模擬生成符合課綱精神的單元教案結構和評量規準。實際系統將此 JSON 套入 DOCX 或 Google Slides 框架。"
 )
 
-# 整合兩個模組到一個 Tabbed Interface
+# Integrate the two modules into a Tabbed Interface
 demo = gr.TabbedInterface([admin_copilot_interface, lesson_plan_designer_interface], 
                           ["模組 A: 行政 Copilot", "模組 B: 教學設計器"], 
                           title="CampusAI Suite (台灣校園 AI 文書/教學 MVP 演示)",