docs/AI_QUIZ_API.md

# 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 时，可依此配置。

---

## 6. 外部网站调用方式（Generate Quiz）

其他网站/前端可通过 HTTP 调用 Clare 后端的 **生成 Quiz** 接口，无需登录、无会话依赖。

### 6.1 接口地址

- **方法**: `POST`
- **URL**: `https://你的Clare后端域名/api/quiz/generate`  
  例如部署在 Hugging Face Space 则为：`https://xxx.huggingface.co/api/quiz/generate`

### 6.2 CORS

后端已配置 `allow_origins=["*"]`，任意域名的网页均可通过浏览器 `fetch` 直接请求该接口（跨域可行）。

### 6.3 请求体（JSON）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `topic` | string | 是 | 测验主题，如 "Responsible AI"、"IST345 Module 10" |
| `num_questions` | int | 否 | 题目数量，默认 3，范围 1–10 |
| `language` | string | 否 | 题目语言：`en`（英语）或 `zh`（中文），默认 `en` |

### 6.4 请求头（可选）

若你在后端环境变量中设置了 **`QUIZ_API_KEY`**，则请求必须在 Header 中带上：

- **Header 名**: `X-API-Key`
- **值**: 与 `QUIZ_API_KEY` 一致

未设置 `QUIZ_API_KEY` 时，无需该 Header。

### 6.5 成功响应（200）

```json
{
  "questions": [
    {
      "question_id": "ai_q_001",
      "type": "SINGLE_CHOICE",
      "question_text": "What is responsible AI?",
      "options": [
        { "key": "A", "text": "..." },
        { "key": "B", "text": "AI designed to be accountable and fair" }
      ],
      "correct_answers": ["B"]
    }
  ],
  "meta": {
    "model": "gpt-4.1-mini",
    "prompt_version": "quiz_generate_v1",
    "temperature": 0.4,
    "tokens_used": 842,
    "latency_ms": 1280
  }
}
```

### 6.6 错误响应

- **422**：主题为空或 AI 输出不合法，body 含 `code`、`error.type`、`error.reason`
- **429**：未带或错误的 `X-API-Key`（当已设置 `QUIZ_API_KEY` 时）
- **500**：模型/服务异常

### 6.7 前端调用示例（fetch）

```javascript
// 将 BASE 换成你的 Clare 后端地址，例如 https://your-space.hf.space
const BASE = "https://your-clare-api.com";

async function generateQuiz(topic, numQuestions = 3, language = "en") {
  const res = await fetch(`${BASE}/api/quiz/generate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    // 若设置了 QUIZ_API_KEY，加上: "X-API-Key": "你的密钥"
    body: JSON.stringify({ topic, num_questions: numQuestions, language }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err?.error?.reason || res.statusText);
  }
  return res.json(); // { questions, meta }
}

// 使用
generateQuiz("Responsible AI", 3, "en").then((data) => {
  console.log(data.questions);
  console.log(data.meta.latency_ms);
});
```

### 6.8 部署时建议

- 若只允许自家站点调用，可在后端设置 **`QUIZ_API_KEY`**，并在调用方请求头中携带 `X-API-Key`。
- 若需限流，可在后端对 ` /api/quiz/generate` 做频率限制（或依赖 HF/网关的限流）。