README.md

---
title: Quiz Generator V3
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.32.1
app_file: app.py
pinned: false
license: apache-2.0
---

# AI Course Assessment Generator

An AI-powered tool that creates learning objectives and multiple-choice quiz questions from course materials. Supports both **automatic generation** from uploaded content and **manual entry** of learning objectives, producing fully enriched outputs with correct and incorrect answer suggestions ready for quiz generation.

---

## Features

### Tab 1 — Generate Learning Objectives

**Two modes of operation:**

- **Generate from course materials** — Upload course files and let the AI extract and generate learning objectives automatically through a multi-run, multi-stage pipeline.
- **Use my own learning objectives** — Enter your own learning objectives in a text field (one per line). The app searches the uploaded course materials for relevant source references, generates a correct answer for each objective, and produces incorrect answer options — the same full pipeline as automatic generation.

**Always-visible controls:**
- Mode selector (Generate / Use my own)
- Upload Course Materials
- Number of Learning Objectives per Run *(generate mode)* / Learning Objectives text field *(manual mode)*
- Generate Learning Objectives / Process Learning Objectives button
- Generate all button *(works in both modes)*

**Advanced Options** *(collapsible, closed by default):*
- Number of Generation Runs
- Model
- Model for Incorrect Answer Suggestions
- Temperature

**Shared capabilities (both modes):**
- All output in the same JSON format, ready to feed directly into Tab 2
- "Generate all" button runs the full end-to-end pipeline (learning objectives → quiz questions) in a single click, in either mode

### Tab 2 — Generate Questions

- Takes the learning objectives JSON produced in Tab 1 as input
- Generates multiple-choice questions with 4 options, per-option feedback, and source references
- Automatic ranking and grouping of generated questions by quality
- Outputs: ranked best-in-group questions, all grouped questions, and a human-readable formatted quiz

**Always-visible controls:**
- Learning Objectives JSON input
- Number of questions
- Generate Questions button

**Advanced Options** *(collapsible, closed by default):*
- Model
- Temperature
- Number of Question Generation Runs

### Tab 3 — Propose / Edit Question

- Load the formatted quiz from Tab 2 or upload a `.md` / `.yml` quiz file *(file upload is inside a collapsible section)*
- Review and edit questions one at a time with Previous / Accept & Next navigation
- Download the final edited quiz

---

## Generation Pipeline (Learning Objectives)

### Automatic generation mode

1. **Content extraction** — Uploads are parsed (`.vtt`, `.srt`, `.ipynb`, `.md`) and wrapped with XML source tags for full traceability
2. **Multi-run base generation** — Multiple independent runs produce candidate objectives (Bloom's taxonomy aware, one action verb, multiple-choice assessable)
3. **Correct answer generation** — A concise correct answer (~20 words) is generated for each objective from the course content
4. **Grouping & ranking** — Similar objectives are clustered; the best representative in each group is selected
5. **Incorrect answer generation** — Three plausible distractors are generated for each best-in-group objective, matching the correct answer in length, style, and complexity
6. **Iterative improvement** — Each distractor is evaluated and regenerated until it meets quality standards

### User-provided objectives mode

1. **Objective parsing** — Text is split by newlines; common leading labels are stripped automatically:
   - Numbered: `1.`, `2)`, `3:`
   - Lettered: `a.`, `b)`, `c:`
   - Plain (no label)
2. **Source finding** — For each objective, the LLM searches the uploaded course materials to identify the most relevant source file(s)
3. **Correct answer generation** — Same function as the automatic flow, grounded in the course content
4. **Incorrect answer generation** — Same three-distractor generation as automatic flow
5. **Iterative improvement** — Same quality improvement loop
6. All objectives are treated as best-in-group (the user has already curated them), so no grouping/filtering step is applied

**Example accepted input formats:**
```
Identify key upstream and downstream collaborators for data engineers
Identify the stages of the data engineering lifecycle
Articulate a mental framework for building data engineering solutions
```
```
1. Identify key upstream and downstream collaborators for data engineers
2. Identify the stages of the data engineering lifecycle
3. Articulate a mental framework for building data engineering solutions
```
```
a. Identify key upstream and downstream collaborators for data engineers
b. Identify the stages of the data engineering lifecycle
c. Articulate a mental framework for building data engineering solutions
```

---

## Setup

### Prerequisites

- Python 3.12 (recommended) or 3.8+
- An OpenAI API key

### Installation

**Using uv (recommended):**
```bash
uv venv -p 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
```

**Using pip:**
```bash
pip install -r requirements.txt
```

### Environment variables

Create a `.env` file in the project root:
```
OPENAI_API_KEY=your_api_key_here
```

---

## Running the app

```bash
python app.py
```

Opens the Gradio interface at [http://127.0.0.1:7860](http://127.0.0.1:7860).

---

## Supported file formats

| Format | Description |
|--------|-------------|
| `.vtt` | WebVTT subtitle files (timestamps stripped) |
| `.srt` | SRT subtitle files (timestamps stripped) |
| `.ipynb` | Jupyter notebooks (markdown and code cells extracted) |
| `.md` | Markdown files |

All content is wrapped with XML source tags (`<source file="filename">…</source>`) so every generated objective and question can be traced back to its origin file.

---

## Project structure

```
quiz_generator_ECM/
│
├── app.py                              # Entry point — loads .env and launches Gradio
│
├── models/                             # Pydantic data models
│   ├── learning_objectives.py          # BaseLearningObjective → LearningObjective → Grouped*
│   ├── questions.py                    # MultipleChoiceQuestion → Ranked* → Grouped*
│   ├── assessment.py                   # Assessment (objectives + questions)
│   └── config.py                       # Model list and temperature availability map
│
├── prompts/                            # Reusable prompt components
│   ├── learning_objectives.py          # Bloom's taxonomy, quality standards, examples
│   ├── incorrect_answers.py            # Distractor guidelines and examples
│   ├── questions.py                    # Question and answer quality standards
│   └── all_quality_standards.py        # General quality standards
│
├── learning_objective_generator/       # Learning objective pipeline
│   ├── generator.py                    # LearningObjectiveGenerator orchestrator
│   ├── base_generation.py              # Base generation, correct answers, source finding
│   ├── enhancement.py                  # Incorrect answer generation
│   ├── grouping_and_ranking.py         # Similarity grouping and best-in-group selection
│   └── suggestion_improvement.py       # Iterative distractor quality improvement
│
├── quiz_generator/                     # Question generation pipeline
│   ├── generator.py                    # QuizGenerator orchestrator
│   ├── question_generation.py          # Multiple-choice question generation
│   ├── question_improvement.py         # Question quality assessment and improvement
│   ├── question_ranking.py             # Ranking and grouping of questions
│   ├── feedback_questions.py           # Feedback-based question regeneration
│   └── assessment.py                   # Assessment compilation and export
│
└── ui/                                 # Gradio interface and handlers
    ├── app.py                          # UI layout, mode toggle, event wiring
    ├── objective_handlers.py           # Handlers for both objective modes + Generate all
    ├── question_handlers.py            # Question generation handler
    ├── content_processor.py            # File parsing and XML source tagging
    ├── edit_handlers.py                # Question editing flow (Tab 3)
    ├── formatting.py                   # Quiz formatting for UI display
    ├── state.py                        # Global state (file contents, objectives)
    └── run_manager.py                  # Run tracking and output saving
```

---

## Data models

Learning objectives progress through these stages:

```
BaseLearningObjectiveWithoutCorrectAnswer
  └─ id, learning_objective, source_reference
      ↓
BaseLearningObjective
  └─ + correct_answer
      ↓
LearningObjective  (output of Tab 1, input to Tab 2)
  └─ + incorrect_answer_options, in_group, group_members, best_in_group
```

Questions follow an equivalent progression:

```
MultipleChoiceQuestion
  └─ id, question_text, options (text + is_correct + feedback),
     learning_objective_id, correct_answer, source_reference
      ↓
RankedMultipleChoiceQuestion
  └─ + rank, ranking_reasoning, in_group, group_members, best_in_group
```

---

## Model configuration

Default model: `gpt-5.2`
Default temperature: `1.0` (ignored for models that do not support it, such as `o1`, `o3-mini`, `gpt-5`, `gpt-5.1`, `gpt-5.2`)

You can set different models for the main generation step and the incorrect answer suggestion step, which is useful for using a more creative model for distractors.

---

## Requirements

| Package | Version |
|---------|---------|
| Python | 3.8+ (3.12 recommended) |
| gradio | 4.19.2+ |
| pydantic | 2.8.0+ |
| openai | 1.52.0+ |
| nbformat | 5.9.2+ |
| instructor | 1.7.9+ |
| python-dotenv | 1.0.0+ |