✨ QuizGen — LLM-Powered MCQ Generator

Turn any document into ready-to-use multiple-choice quizzes with Llama 3.1, LangChain, and a two-stage generate-and-review pipeline.

Upload a PDF or TXT, pick a subject + difficulty, get a clean CSV of quiz questions back —
each one generated AND reviewed by Llama 3.1 before it reaches you.

LangChain MCQ generators are everywhere. This one earns its place through four engineering choices:

• 🔗 Two-stage SequentialChain — generation and review are separate LLM passes; the second pass critiques the first and fixes unsuitable questions before the user ever sees them
• 📐 Structured output enforcement — strict JSON schema injected into the prompt (RESPONSE_JSON) makes the LLM output parseable every time, no regex cleanup needed
• 📦 Production packaging — proper src/mcqgenerator/ Python package with setup.py, logging module, and utility separation — not a notebook dump
• 🎨 Polished UI — custom Streamlit theme with gradient hero, card-based MCQ display, and color-coded answer reveals — not the default look

┌──────────────────────────────────────────────┐
│       User uploads PDF / TXT + settings      │
│   (subject, difficulty, number of MCQs)      │
└─────────────────────┬────────────────────────┘
                      │
                      ▼
        ┌──────────────────────────┐
        │   Stage 1 — Quiz Chain   │  Llama 3.1 generates N MCQs
        │   PromptTemplate +       │  with strict JSON schema
        │   LLMChain               │  Output → quiz (JSON string)
        └─────────────┬────────────┘
                      │
                      ▼
        ┌──────────────────────────┐
        │  Stage 2 — Review Chain  │  Llama 3.1 critiques the quiz
        │  Same LLM, new prompt    │  for difficulty + suitability
        │  Rewrites unsuitable Qs  │  Output → review + corrections
        └─────────────┬────────────┘
                      │
                      ▼
        ┌──────────────────────────┐
        │   JSON parsing → table   │  Structured to: MCQ | Choices | Correct
        └─────────────┬────────────┘
                      │
                      ▼
        ┌──────────────────────────┐
        │   Streamlit UI + CSV     │  Preview + one-click download
        └──────────────────────────┘

The SequentialChain orchestrates both stages — Stage 1's output feeds Stage 2 as input, all in one call from the Streamlit app.

Upload a document, configure subject/difficulty, hit generate. That's it.

Each MCQ renders as its own card with numbered badge, choices, and a color-coded correct answer reveal:

The two-stage pipeline ensures every question gets reviewed before display:

After generation, the AI's own quality review is shown alongside a one-click CSV export:

Input: sample_ml_fundamentals.txt (a 6 KB article on machine learning basics) Settings: Subject = Machine Learning, Difficulty = Medium, Number = 6

A few of the generated questions:

Plus an AI quality review: "Moderate difficulty. No changes needed."

The LLM is given the source text plus a strict instruction to return only valid JSON matching a schema:

TEMPLATE_QUIZ = """
{system_msg}
Context: {text}
Your task is to write exactly {number} multiple-choice questions based on the
above content. The questions should be appropriate for {subject} students and
written in a {difficulty} difficulty.
Return ONLY a JSON object matching the format shown in RESPONSE_JSON below.
Do not include any extra explanation.

### RESPONSE_JSON
{response_json}
"""

The RESPONSE_JSON (loaded from Response.json) gives the model a concrete schema to mimic:

{
  "1": {
    "mcq": "multiple choice question",
    "options": {"a": "choice", "b": "choice", "c": "choice", "d": "choice"},
    "correct": "correct answer"
  }
}

This pattern — show the model the exact output shape — is dramatically more reliable than describing the format in prose.

The generated quiz is fed back into the LLM with a new prompt:

TEMPLATE_REVIEW = """
{system_msg}
Below is a quiz for {subject} students. Review its difficulty in no more
than 50 words. If any question is not suitable, rewrite only the problem
parts in a suitable difficulty.

Quiz:
{quiz}
"""

This catches questions that are too easy, too obscure, or off-topic — a critical safety net for educational content.

Both chains are wired together so a single call produces both outputs:

combined_chain = SequentialChain(
    chains=[quiz_chain, review_chain],
    input_variables=["system_msg", "text", "number", "subject",
                     "difficulty", "response_json"],
    output_variables=["quiz", "review"],
    verbose=True
)

quizgen/
├── src/
│   └── mcqgenerator/
│       ├── __init__.py
│       ├── MCQgenerator.py    # SequentialChain definition
│       ├── utils.py           # read_file, get_table_data
│       └── logger.py          # Logging setup
├── docs/
│   └── images/                # Screenshots for this README
├── app.py                     # Streamlit web interface
├── mcq.ipynb                  # Pipeline development notebook
├── test.py                    # Logging test
├── data.txt                   # Sample input
├── Response.json              # JSON schema template
├── quiz.csv                   # Sample output
├── requirements.txt
├── setup.py
└── .env                       # HUGGING_FACE_API_KEY (git-ignored)

git clone https://github.com/houdhoudGH/quizgen.git
cd quizgen

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Create a .env file:

HUGGING_FACE_API_KEY=your-hf-token

Get a free token at huggingface.co/settings/tokens.

streamlit run app.py

Open http://localhost:8501 🚀

1. Upload a PDF or TXT file
2. Pick subject, difficulty (Simple/Medium/Hard), and number of MCQs
3. Click Generate MCQs
4. Review the generated quiz on screen
5. Download the result as CSV

The app ships as a working two-stage LLM pipeline. Five directions for production hardening:

• Containerization — Dockerfile + docker-compose.yml for one-command deployment
• CI/CD — GitHub Actions workflow for automated testing and linting
• Question variety — extend beyond MCQs to true/false, fill-in-the-blank, and short-answer
• Interactive mode — let users actually take the quiz in-app, with scoring
• Multilingual — generate quizzes in Arabic, French, English from the same source
• Export formats — Anki deck, Kahoot CSV, Google Forms import

MIT — see LICENSE for details.