Quiz Pool is a web app for authoring validated question banks, generating exam variants, printing OMR-ready PDFs, viewing saved exam sets, and grading completed papers.

Requirements

• Python 3.12+
• uv for dependency management
• lualatex on PATH for printable PDF export
• pdftoppm on PATH for grading and annotated-PDF workflows

Install

Install Python dependencies:

uv sync

Install the required system tools:

• TeX Live users should install a LuaLaTeX-capable setup with the standard LaTeX collections used by the templates, at minimum collection-luatex, collection-latexrecommended, and collection-latexextra

• Debian/Ubuntu example:

sudo apt install texlive-luatex texlive-latex-recommended texlive-latex-extra poppler-utils

• Mac users can install TeX Live with Homebrew:

brew install --cask mactex
brew install poppler

Additional notes:

• The project uses lualatex to build printable PDFs
• Latin Modern text and math fonts are vendored under tex_templates/fonts, so they do not need to be installed separately
• The omr dependency generates OMR sheets directly, while grading and annotation rasterize PDFs through pdftoppm from Poppler

Run

Run directly from GitHub without cloning the repository:

uvx --from git+https://github.com/CompGenomeLab/quiz-pool.git \
  quiz_pool --project path/to/course.quizpool

The same system tools listed above are still required for PDF export, grading, and annotation.

Run from a local clone:

uv run quiz_pool --project sample_quiz.quizpool

Then open http://127.0.0.1:8000.

Useful CLI flags:

uv run quiz_pool \
  --project path/to/course.quizpool \
  --host 127.0.0.1 \
  --port 8000

The app stores normal work in the .quizpool project database: quiz content, generated exam sets, the exam-generator draft, and uploaded question images. A new project starts empty. Use the Editor's import action to bulk import a quiz JSON into the active project.

Web Interface

• Welcome: choose the active .quizpool project DB for the current server session
• Editor: edit quiz metadata, upload quiz JSON for bulk import, learning objectives, questions, choices, points, explanations, and references
• Exam Generator: filter the pool, generate saved exam sets, and preview variants
• Exam Viewer: reopen saved exam sets, edit printable metadata, inspect variants, and download the printable ZIP
• Grading: upload completed PDFs, run omr-grade, review mismatches, export CSV, and download annotated PDFs generated with omr-annotate

Math And Printables

Printable output is built in two parts:

• the shared question-pool document is rendered with lualatex
• each student variant is rendered with lualatex, then combined with an OMR answer sheet generated by omr

Inline math is written with [math]...[/math].

Examples:

• [math]A = \pi r^{2}[/math]
• [math]\hat{p} \approx \mu / s[/math]

The same markup works across the editor preview and the LaTeX printables. Question text, choice text, and explanations can all contain inline math.

Question Model

Each question supports:

• 2 to 5 contiguous choices from A to E
• one or more correct answers
• points
• difficulty
• one or more linked learning objectives
• one or more references
• optional explanation
• optional PNG/JPEG images attached to each question

Learning objectives are editable in the Editor and use IDs like LO1, LO2, LO3, ...

Grading

The grading workflow checks more than raw OMR output. It validates:

• OMR errors returned by omr-grade
• missing or invalid QR payloads
• unknown variants
• question count mismatches
• invalid marked choices for a variant
• duplicate student IDs across multiple graded PDFs

It also:

• computes earned points and possible points
• exports the student summary table to CSV
• packages annotated PDFs named like rowIndex-studentId-annotated.pdf into a download ZIP

For grading and annotation, make sure pdftoppm is installed and available on PATH.

Notes

• A new project DB starts with an empty quiz and no generated exams
• Quiz JSON import happens from the Editor and copies the quiz into the active project DB
• Invalid quiz edits are rejected on save and shown in the UI
• The browser shows a native warning for tab close or reload when the Editor has unsaved changes
• If printable export fails with a LaTeX error, check that lualatex is installed and that the vendored assets under tex_templates/ are still present