IST345 course + multi-TA, AI Quiz API doc, courseDirectory and sidebar updates

api/store.py

@@ -38,12 +38,18 @@ def seed_if_missing() -> None:
 
   if not COURSE_FILE.exists():
     courses = [
+      CourseDirectoryItem(
+        id="ist345",
+        name="IST345",
+        instructor=PersonContact(name="Yan Li", email="Yan.Li@cgu.edu"),
+        teachingAssistant=PersonContact(name="Kaijie Yu", email="Kaijie.Yu@cgu.edu"),
+      ).model_dump(),
       CourseDirectoryItem(
         id="course_ai_001",
         name="Introduction to AI",
         instructor=PersonContact(name="Dr. Smith", email="smith@uni.edu"),
         teachingAssistant=PersonContact(name="Alice", email="alice@uni.edu"),
-      ).model_dump()
+      ).model_dump(),
     ]
     _write_json(COURSE_FILE, {"items": courses})
 

docs/AI_QUIZ_API.md

@@ -0,0 +1,158 @@
+# AI Quiz API 接口文档
+
+用于与前端/其他网页进行 AI Quiz 互动的统一接口规范。所有响应均包含 `meta` 用于模型追踪与排查；题目使用 `question_id` 与 `correct_answers` 便于后端存档与追溯。
+
+---
+
+## 1. 通用：所有响应增加 meta
+
+用于排查模型问题与结果追溯，**所有成功响应**均需包含：
+
+```json
+"meta": {
+  "model": "gpt-4.1-mini",
+  "model_version": "2024-07",
+  "prompt_version": "quiz_v2",
+  "temperature": 0.4,
+  "tokens_used": 842,
+  "latency_ms": 1280
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `model` | string | 模型标识 |
+| `model_version` | string | 模型版本（可选） |
+| `prompt_version` | string | 当前 prompt 版本，便于回溯 |
+| `temperature` | number | 采样温度 |
+| `tokens_used` | number | 本次请求消耗 token 数 |
+| `latency_ms` | number | 请求耗时（毫秒） |
+
+---
+
+## 2. Generate Quiz：题目与答案结构
+
+### 2.1 删除字段
+
+- **禁止**使用 `options[].is_correct` 表示正确答案。
+
+### 2.2 新增 / 修改结构
+
+每题必须包含唯一 `question_id`，答案通过 **`correct_answers`** 数组表示，便于后端校验与存档。
+
+**题目项示例：**
+
+```json
+{
+  "question_id": "ai_q_001",
+  "type": "SINGLE_CHOICE",
+  "question_text": "What is responsible AI?",
+  "options": [
+    { "key": "A", "text": "AI that only runs on servers" },
+    { "key": "B", "text": "AI designed to be accountable and fair" },
+    { "key": "C", "text": "AI that uses no data" }
+  ],
+  "correct_answers": ["B"]
+}
+```
+
+**答案规则（后端需校验，不合法可重试）：**
+
+| 题型 | correct_answers 规则 | 备注 |
+|------|----------------------|------|
+| `SINGLE_CHOICE` | 必须 **恰好 1 个** 答案 | 如 `["B"]` |
+| `MULTIPLE_CHOICE` | **≥ 1** 个答案 | 如 `["A","C"]` |
+| `TRUE_FALSE` | 必须 **2 个选项**（True/False） | 答案为其中之一 |
+| `SHORT_ANSWER` | 不适用选项；必须返回 **`explanation`** | 用于评分与反馈 |
+
+**SHORT_ANSWER 示例：**
+
+```json
+{
+  "question_id": "ai_q_002",
+  "type": "SHORT_ANSWER",
+  "question_text": "Explain one risk of generative AI in education.",
+  "explanation": "Reference answer: e.g. over-reliance may reduce critical thinking."
+}
+```
+
+---
+
+## 3. 标准错误返回
+
+当 AI 输出不合法、超时或服务失败时，统一使用以下结构（**非 2xx**）：
+
+```json
+{
+  "code": 422,
+  "error": {
+    "type": "INVALID_GENERATION",
+    "reason": "multiple_correct_answers"
+  }
+}
+```
+
+### 3.1 错误码与 type
+
+| HTTP code | error.type | 说明 |
+|-----------|------------|------|
+| **422** | `INVALID_GENERATION` | AI 输出不合法（如单选多答、缺少必填字段等），`reason` 可细化 |
+| **429** | `RATE_LIMIT` | 请求频率超限 |
+| **500** | `MODEL_ERROR` | 模型/上游服务错误 |
+| **504** | `TIMEOUT` | 请求超时 |
+
+### 3.2 reason 示例（422）
+
+- `multiple_correct_answers`：单选题返回了多个正确答案
+- `missing_question_id`：缺少 `question_id`
+- `missing_correct_answers`：缺少 `correct_answers` 或不符合题型规则
+- `invalid_short_answer`：SHORT_ANSWER 缺少 `explanation`
+
+---
+
+## 4. Grade Quiz：每题解释
+
+批改接口响应中，**新增** `per_question_feedback`，对每题给出分数与简要理由：
+
+```json
+{
+  "overall_score": 75,
+  "per_question_feedback": [
+    {
+      "question_id": "ai_q_001",
+      "score": 10,
+      "reasoning": "Correct choice; full marks."
+    },
+    {
+      "question_id": "ai_q_002",
+      "score": 7,
+      "reasoning": "Concept correct but example missing."
+    }
+  ],
+  "meta": {
+    "model": "gpt-4.1-mini",
+    "model_version": "2024-07",
+    "prompt_version": "grade_v1",
+    "temperature": 0.2,
+    "tokens_used": 520,
+    "latency_ms": 890
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `question_id` | string | 对应题目 ID，与 Generate 阶段一致 |
+| `score` | number | 该题得分 |
+| `reasoning` | string | 简短批改理由 |
+
+---
+
+## 5. 课程信息（参考）
+
+- **Course**: IST345（来自 syllabus）
+- **Instructor**: Yan Li — Yan.Li@cgu.edu
+- **TA**: Kaijie Yu — Kaijie.Yu@cgu.edu  
+- **TA**: Yongjia Sun — Yongjia.Sun@cgu.edu  
+
+前端展示 Instructor 与多位 TA 时，可依此配置。

web/src/App.tsx

@@ -99,6 +99,7 @@ export interface CourseInfo {
   name: string;
   instructor: { name: string; email: string };
   teachingAssistant: { name: string; email: string };
+  teachingAssistants?: { name: string; email: string }[];
 }
 
 export interface Workspace {
@@ -243,6 +244,16 @@ function App() {
   });
 
   const availableCourses: CourseInfo[] = [
+    {
+      id: "ist345",
+      name: "IST345",
+      instructor: { name: "Yan Li", email: "Yan.Li@cgu.edu" },
+      teachingAssistant: { name: "Kaijie Yu", email: "Kaijie.Yu@cgu.edu" },
+      teachingAssistants: [
+        { name: "Kaijie Yu", email: "Kaijie.Yu@cgu.edu" },
+        { name: "Yongjia Sun", email: "Yongjia.Sun@cgu.edu" },
+      ],
+    },
     {
       id: "course1",
       name: "Introduction to AI",

web/src/components/sidebar/CourseInfoSection.tsx

@@ -125,8 +125,10 @@ export function CourseInfoSection({
   const instructorName = (courseInfo as any)?.instructor?.name ?? "N/A";
   const instructorEmail = String((courseInfo as any)?.instructor?.email ?? "").trim();
 
-  const taName = (courseInfo as any)?.teachingAssistant?.name ?? "N/A";
-  const taEmail = String((courseInfo as any)?.teachingAssistant?.email ?? "").trim();
+  const teachingAssistants = (courseInfo as any)?.teachingAssistants as { name?: string; email?: string }[] | undefined;
+  const taList = Array.isArray(teachingAssistants) && teachingAssistants.length > 0
+    ? teachingAssistants
+    : [(courseInfo as any)?.teachingAssistant ?? { name: "N/A", email: "" }];
 
   return (
     <div className="w-full">
@@ -169,25 +171,33 @@ export function CourseInfoSection({
           )}
         </div>
 
-        {/* TA */}
-        <div className="text-sm text-muted-foreground">
-          TA:&nbsp;
-          {taEmail ? (
-            <a
-              href={gmailComposeLink(
-                taEmail,
-                `[Clare] Help request for ${courseName}`,
-                `Hi ${taName},\n\nI need help with ${courseName}:\n\n(Write your question here)\n\nThanks,\n`
-              )}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-primary hover:underline"
-            >
-              {taName}
-            </a>
-          ) : (
-            <span className="text-muted-foreground/60">{taName}</span>
-          )}
+        {/* TA(s) */}
+        <div className="text-sm text-muted-foreground space-y-1">
+          {taList.map((ta, i) => {
+            const name = ta?.name ?? "N/A";
+            const email = String(ta?.email ?? "").trim();
+            return (
+              <div key={i}>
+                TA:&nbsp;
+                {email ? (
+                  <a
+                    href={gmailComposeLink(
+                      email,
+                      `[Clare] Help request for ${courseName}`,
+                      `Hi ${name},\n\nI need help with ${courseName}:\n\n(Write your question here)\n\nThanks,\n`
+                    )}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-primary hover:underline"
+                  >
+                    {name}
+                  </a>
+                ) : (
+                  <span className="text-muted-foreground/60">{name}</span>
+                )}
+              </div>
+            );
+          })}
         </div>
       </div>
 

web/src/components/sidebar/LeftSidebar.tsx

@@ -259,8 +259,10 @@ export function LeftSidebar(props: Props) {
   const instructorName = (courseInfo as any)?.instructor?.name ?? "N/A";
   const instructorEmail = String((courseInfo as any)?.instructor?.email ?? "").trim();
 
-  const taName = (courseInfo as any)?.teachingAssistant?.name ?? "N/A";
-  const taEmail = String((courseInfo as any)?.teachingAssistant?.email ?? "").trim();
+  const teachingAssistants = (courseInfo as any)?.teachingAssistants as { name?: string; email?: string }[] | undefined;
+  const taList = Array.isArray(teachingAssistants) && teachingAssistants.length > 0
+    ? teachingAssistants
+    : [(courseInfo as any)?.teachingAssistant ?? { name: "N/A", email: "" }];
 
   return (
     <div className="h-full w-full flex flex-col min-h-0 bg-background text-foreground">
@@ -421,25 +423,31 @@ export function LeftSidebar(props: Props) {
             )}
           </div>
 
-          <div className="text-muted-foreground">
-            TA:&nbsp;
-            {taEmail ? (
-              <a
-                href={gmailComposeLink(
-                  taEmail,
-                  `[Clare] Help request for ${courseName}`,
-                  `Hi ${taName},\n\nI need help with ${courseName}:\n\n(Write your question here)\n\nThanks,\n`
+          {taList.map((ta, i) => {
+            const name = ta?.name ?? "N/A";
+            const email = String(ta?.email ?? "").trim();
+            return (
+              <div key={i} className="text-muted-foreground">
+                TA:&nbsp;
+                {email ? (
+                  <a
+                    href={gmailComposeLink(
+                      email,
+                      `[Clare] Help request for ${courseName}`,
+                      `Hi ${name},\n\nI need help with ${courseName}:\n\n(Write your question here)\n\nThanks,\n`
+                    )}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-primary hover:underline"
+                  >
+                    {name}
+                  </a>
+                ) : (
+                  <span className="text-muted-foreground/60">{name}</span>
                 )}
-                target="_blank"
-                rel="noopener noreferrer"
-                className="text-primary hover:underline"
-              >
-                {taName}
-              </a>
-            ) : (
-              <span className="text-muted-foreground/60">{taName}</span>
-            )}
-          </div>
+              </div>
+            );
+          })}
         </div>
       </div>
 

web/src/lib/courseDirectory.ts

@@ -8,16 +8,26 @@ export type Person = {
 export type CourseDirectoryItem = {
   id: string;
   name: string;
-  instructor?: Person; // optional: some courses may not have info yet
-  teachingAssistant?: Person; // optional
+  instructor?: Person;
+  teachingAssistant?: Person;
+  /** Optional: when multiple TAs (display all) */
+  teachingAssistants?: Person[];
 };
 
 /**
- * NOTE:
- * - Fill in missing names/emails here once confirmed.
- * - Keep emails empty ("") or undefined if you don't have them yet.
+ * IST345 from syllabus; Instructor and TAs from course info.
  */
 export const COURSE_DIRECTORY: CourseDirectoryItem[] = [
+  {
+    id: "ist345",
+    name: "IST345",
+    instructor: { name: "Yan Li", email: "Yan.Li@cgu.edu" },
+    teachingAssistant: { name: "Kaijie Yu", email: "Kaijie.Yu@cgu.edu" },
+    teachingAssistants: [
+      { name: "Kaijie Yu", email: "Kaijie.Yu@cgu.edu" },
+      { name: "Yongjia Sun", email: "Yongjia.Sun@cgu.edu" },
+    ],
+  },
   {
     id: "intro_ai",
     name: "Introduction to AI",