Spaces:
Sleeping
Sleeping
| 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+ | | |