README.md

metadata

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):

uv venv -p 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

Using pip:

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

python app.py

Opens the Gradio interface at 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+