Convert any HTML tutorial page, PDF, or image into MCQ questions using AI

These details have not been verified by PyPI

Project links

Project description

html2mcq

Convert any HTML tutorial page, PDF, or image into MCQ questions using AI.

Install

pip install html2mcq

Everything is included — HTML extraction, PDF support, OCR, all AI providers.

Quick Start

from html2mcq import MCQGenerator

gen = MCQGenerator(
    api_key="sk-or-v1-...",
    provider="openrouter",
    mcq_model="google/gemini-2.5-flash-lite",
)

# From an HTML tutorial page
mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=15)

# From a PDF URL
mcq = gen.from_pdf_urls("https://example.com/tutorial.pdf", n=10)

# From a local PDF file
mcq = gen.from_pdf_paths("/path/to/notes.pdf", n=10)

# From image files (OCR → MCQ in one step)
mcq = gen.from_image_paths("screenshot.png", n=5)

# From image URLs (vision model direct)
mcq = gen.from_image_urls("https://example.com/diagram.png", n=5)

print(mcq.to_json())
print(mcq.to_pretty_str())

Input Methods

Input	Method	Batch support
HTML tutorial page URL	`from_url(url)`	❌ single URL
Raw HTML string	`from_html(html)`	❌ single string
PDF via URL	`from_pdf_urls(url)`	✅ `list[str]`
Local PDF file	`from_pdf_paths(path)`	✅ `list[str]`
Image files (local)	`from_image_paths(path)`	✅ `list[str]`
Image URLs	`from_image_urls(url)`	✅ `list[str]`
Pre-built content blocks	`from_blocks(blocks)`	❌ single list

Examples (10+)

1. Basic — HTML tutorial page

from html2mcq import MCQGenerator

gen = MCQGenerator(api_key="sk-or-v1-...")
mcq = gen.from_url("https://docs.python.org/3/tutorial/introduction.html", n=5)
print(mcq.to_pretty_str())

2. Raw HTML string

html_string = """
<html><body>
<h1>Python Lists</h1>
<p>Lists are ordered, mutable collections. Items are indexed from 0.</p>
<pre><code>fruits = ["apple", "banana", "cherry"]
fruits.append("date")
</code></pre>
</body></html>
"""
mcq = gen.from_html(html_string, n=3)
print(mcq.to_json())

3. Multiple PDF URLs in batch

mcq = gen.from_pdf_urls([
    "https://example.com/chapter1.pdf",
    "https://example.com/chapter2.pdf",
    "https://example.com/chapter3.pdf",
], n=20)

4. Local PDF files

mcq = gen.from_pdf_paths([
    "C:/Users/Me/Documents/lecture_notes.pdf",
    "C:/Users/Me/Documents/textbook_ch5.pdf",
], n=15)

5. Image files with OCR (two-step)

gen = MCQGenerator(
    api_key="sk-or-v1-...",
    method="twostep",
    ocr_model="google/gemini-2.5-flash-lite",
    save_ocr_path="ocr_output.txt",
)
mcq = gen.from_image_paths("screenshot.png", n=5)

6. Image URLs via vision model (direct)

gen = MCQGenerator(
    api_key="sk-or-v1-...",
    method="images2mcq",
)
mcq = gen.from_image_urls("https://example.com/diagram.png", n=5)

7. Batch image files

mcq = gen.from_image_paths([
    "slide01.png",
    "slide02.png",
    "slide03.png",
], n=15)

8. Generate as many questions as possible

# When n=999, the AI covers every distinct topic in the content
mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=999)
print(f"Generated {len(mcq.questions)} questions")

9. Difficulty mix and topic focus

mcq = gen.from_url(
    "https://docs.python.org/3/tutorial/",
    n=20,
    difficulty_mix="50% easy, 30% medium, 20% hard",
    focus_topics=["lists", "dictionaries", "loops"],
)

10. Custom instructions per call

mcq = gen.from_url(
    "https://docs.python.org/3/tutorial/",
    n=10,
    custom_instructions="All questions must be code-based. Include the code snippet in the question.",
)

11. Pre-extracted content blocks

from html2mcq import MCQGenerator, ContentExtractor

extractor = ContentExtractor()
title, blocks = extractor.from_url("https://docs.python.org/3/tutorial/")

# Filter to only code blocks
code_blocks = [b for b in blocks if b.type == "code"]
mcq = gen.from_blocks(code_blocks, n=5)

12. Save output to JSON file

import json

mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=10)
with open("quiz.json", "w") as f:
    json.dump(mcq.to_json(), f, indent=2)

13. Filter questions by difficulty

mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=20)
easy = mcq.filter_by_difficulty("easy")
medium = mcq.filter_by_difficulty("medium")
hard = mcq.filter_by_difficulty("hard")
print(f"Easy: {len(easy)}, Medium: {len(medium)}, Hard: {len(hard)}")

14. Different AI provider — Anthropic

gen = MCQGenerator(
    api_key="sk-ant-...",
    provider="anthropic",
    mcq_model="claude-3-5-sonnet-20241022",
)
mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=10)

15. Local Ollama (no API key needed)

gen = MCQGenerator(
    provider="ollama",
    mcq_model="qwen2.5:7b",
    ollama_base_url="http://localhost:11434/v1",
)
mcq = gen.from_url("https://docs.python.org/3/tutorial/", n=5)

Constructor

gen = MCQGenerator(
    provider="openrouter",                         # default, also: "anthropic" | "openai" | "ollama"
    api_key="sk-or-v1-...",                        # or set env var OPENROUTER_API_KEY
    api_key_override="sk-or-v1-...",               # override key for this instance
    mcq_model="google/gemini-2.5-flash-lite",      # model for ALL MCQ generation
    mcq_model_list=["model1", "model2"],           # fallback list for mcq_model="auto"
    ocr_model="pytesseract",                       # OCR for HTML images: "pytesseract" | "auto" | model ID
    ocr_models=["model1", "pytesseract"],          # priority list for ocr_model="auto"
    method="twostep",                              # "twostep" (OCR→MCQ) | "images2mcq" (vision direct)
    save_ocr_path="ocr_output.txt",                # save OCR text when method=twostep
    prompt_log_path="stdout",                      # dump prompts: file path | "stdout" | "-"
    batch_size=10,
    max_tokens=4096,
    custom_instructions="Make answers tricky",
)

New in v2

Parameter	What it does
`mcq_model`	Single source of truth for all MCQ generation (text + vision). Renamed from `model`.
`mcq_model="auto"`	Tries `mcq_model_list` in order until one succeeds.
`mcq_model_list`	Priority-ordered models for auto mode. Runtime-reloadable via `HTML2MCQ_MCQ_MODELS` env var.
`ocr_model`	OCR backend: `"pytesseract"` (default), `"auto"` (priority list), or any OpenRouter model ID.
`ocr_model="auto"`	Tries `ocr_models` priority list.
`ocr_models`	Priority list for auto OCR. Reloadable via `HTML2MCQ_OCR_MODELS` env var.
`method`	`"twostep"` (OCR images → text → MCQs) or `"images2mcq"` (vision model direct).
`prompt_log_path`	Dump full prompts to file or terminal. Use `"stdout"` or `"-"` for terminal.
`api_key_override`	Override key for this instance
`save_ocr_path`	Save OCR text to file when method=twostep

Two-Step Image Pipeline (`method="twostep"`)

When method="twostep" (default), from_image_paths() and from_image_urls() automatically:

OCR — extract text from images using ocr_model
Generate — feed text into text-based MCQ generation

Optionally save the OCR text with save_ocr_path:

gen = MCQGenerator(method="twostep", ocr_model="google/gemini-2.5-flash-lite",
                   save_ocr_path="ocr_output.txt")

# OCR → save to file → generate MCQs
gen.from_image_paths("chart.png", n=5)

Per-Call Overrides

All 7 public methods accept api_key_override and prompt_log_path:

mcq = gen.from_url(
    "https://example.com/",
    n=10,
    api_key_override="sk-or-v1-...",       # different key for this call
    prompt_log_path="debug_prompt.txt",    # log prompts for this call only
)

Output Schema

{
  "total_exam_time": 20,
  "questions": [
    {
      "question_html": "Which of these are non-mutating array methods?",
      "options": ["push()", "map()", "filter()", "pop()"],
      "answers": [1, 2],
      "multi": true,
      "marks": 1,
      "negative_marks": 0,
      "difficulty": "medium",
      "explaination": "map() and filter() return new arrays without modifying the original."
    }
  ]
}

AI Providers

# OpenRouter (default) — 100+ models
gen = MCQGenerator(api_key="sk-or-...", provider="openrouter",
                   mcq_model="google/gemini-2.5-flash-lite")

# Anthropic Claude
gen = MCQGenerator(api_key="sk-ant-...", provider="anthropic")

# OpenAI
gen = MCQGenerator(api_key="sk-...", provider="openai", mcq_model="gpt-4o")

# Ollama (local, no API key needed)
gen = MCQGenerator(provider="ollama", mcq_model="qwen2.5:7b",
                   ollama_base_url="http://localhost:11434/v1")

OCR Priority (when `ocr_model="auto"`)

The default priority list is:

google/gemini-2.5-flash-lite (fast, cheap)
google/gemma-3-27b-it (free)
google/gemma-3-12b-it (free)
openai/gpt-4o (paid)
pytesseract (local fallback)

Override via ocr_models parameter or HTML2MCQ_OCR_MODELS env var.

MCQ Model Priority (when `mcq_model="auto"`)

Tries mcq_model_list in order. Override via HTML2MCQ_MCQ_MODELS env var (comma-separated):

export HTML2MCQ_MCQ_MODELS="model1,model2,model3"

Custom Instructions

# Apply to every call
gen = MCQGenerator(
    provider="openrouter",
    custom_instructions="Make answers very close and confusing."
)

# Or per individual call
mcq = gen.from_url("https://example.com/", n=10,
    custom_instructions="All questions must be code-based.")

API Reference

`MCQGenerator`

Parameter	Default	Description
`provider`	`"openrouter"`	`"openrouter"`
`api_key`	`None`	API key or env var
`api_key_override`	`None`	Override key for this instance
`mcq_model`	`""`	Model for all MCQ generation. `"auto"` tries `mcq_model_list`
`mcq_model_list`	`None`	Fallback models for auto mode
`ocr_model`	`"pytesseract"`	OCR backend: `"pytesseract"`
`ocr_models`	`None`	Priority list for auto OCR
`method`	`"twostep"`	`"twostep"` (OCR→MCQ)
`prompt_log_path`	`None`	Dump prompts to file/terminal
`batch_size`	`10`	Questions per API call
`custom_instructions`	`None`	Global custom instructions

Method	Description
`from_url(url, n, ...)`	HTML page
`from_html(html, n, ...)`	Raw HTML string
`from_pdf_urls(urls, n, ...)`	PDF via URL (str or list)
`from_pdf_paths(paths, n, ...)`	Local PDF file (str or list)
`from_image_urls(urls, n, ...)`	Image URLs → MCQ via vision
`from_image_paths(paths, n, ...)`	Local image files → MCQ
`from_blocks(blocks, n, ...)`	Pre-extracted `ContentBlock` list

All methods accept api_key_override, prompt_log_path, difficulty_mix, focus_topics, custom_instructions.

`MCQSet`

Property / Method	Description
`.questions`	`List[MCQQuestion]`
`.total_exam_time`	Minutes — auto-calculated as n × 2
`.to_json()`	Exam-ready JSON
`.to_pretty_str()`	Human-readable output
`.filter_by_difficulty(d)`	Filter by `"easy"` / `"medium"` / `"hard"`

CLI

# Basic
html2mcq https://example.com/tutorial --n 20

# All options
html2mcq https://example.com/tutorial \
    --n 20 \
    --provider openrouter \
    --mcq-model google/gemini-2.5-flash-lite \
    --ocr-model auto \
    --difficulty "40% easy, 40% medium, 20% hard" \
    --topics variables functions \
    --output quiz.json \
    --format json

# Generate as many as possible
html2mcq https://example.com/tutorial --n 999 --output all_topics.json

Project Structure

html2mcq/
├── html2mcq/
│   ├── __init__.py
│   ├── extractor.py        # HTML parser
│   ├── generator.py        # MCQGenerator — main API
│   ├── image_ocr.py        # OCR (pytesseract + vision API)
│   ├── models.py           # ContentBlock, MCQQuestion, MCQSet
│   ├── pdf.py              # PDF extractor
│   ├── prompts.py          # System + user prompt builders
│   └── cli.py              # CLI entry point
├── tests/
│   ├── test_html2mcq.py    # Unit tests (fully mocked)
│   └── scripts/            # Debug / scratch scripts
├── pyproject.toml
├── README.md
└── CHANGELOG.md

License

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

3.3.12

Jun 26, 2026

3.3.11

Jun 19, 2026

3.3.10

Jun 19, 2026

3.3.9

Jun 19, 2026

3.3.8

Jun 19, 2026

3.3.7

Jun 18, 2026

3.3.6

Jun 16, 2026

3.3.5

Jun 16, 2026

3.3.4

Jun 16, 2026

3.3.3

Jun 15, 2026

3.3.2

Jun 14, 2026

3.3.1

Jun 10, 2026

3.3.0

Jun 10, 2026

3.2.0

Jun 10, 2026

3.1.1

Jun 10, 2026

3.1.0

Jun 10, 2026

3.0.0

Jun 10, 2026

2.7.1

Jun 9, 2026

2.7.0

Jun 9, 2026

2.6.0

Jun 9, 2026

2.5.1

Jun 9, 2026

2.5.0

Jun 9, 2026

2.4.0

Jun 9, 2026

2.3.0

Jun 9, 2026

2.2.0

Jun 9, 2026

2.1.0

Jun 9, 2026

2.0.4

Jun 9, 2026

This version

2.0.3

Jun 9, 2026

2.0.2

Jun 9, 2026

2.0.1

Jun 9, 2026

2.0.0

Jun 8, 2026

1.3.1

Jun 7, 2026

1.3.0

Jun 7, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

html2mcq-2.0.3.tar.gz (49.7 kB view details)

Uploaded Jun 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

html2mcq-2.0.3-py3-none-any.whl (38.5 kB view details)

Uploaded Jun 9, 2026 Python 3

File details

Details for the file html2mcq-2.0.3.tar.gz.

File metadata

Download URL: html2mcq-2.0.3.tar.gz
Upload date: Jun 9, 2026
Size: 49.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.6

File hashes

Hashes for html2mcq-2.0.3.tar.gz
Algorithm	Hash digest
SHA256	`d71cca5b15483dd1c969dd6dd0ee14ebf81ad676e6975c8c24005cd09294de07`
MD5	`5c1eb33ef835778c7ca1bb76c763c230`
BLAKE2b-256	`4703848fbc03a1b0f271867033db271c926e3fa81c6eecf2faa202cbbbb351e1`

See more details on using hashes here.

File details

Details for the file html2mcq-2.0.3-py3-none-any.whl.

File metadata

Download URL: html2mcq-2.0.3-py3-none-any.whl
Upload date: Jun 9, 2026
Size: 38.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.6

File hashes

Hashes for html2mcq-2.0.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`92282635f07a4f2e92cfcf8b074c6853c2f325cb439ed1eafaa938c8e38da56f`
MD5	`16bb65b889eb98f07fcf90dccc486ea9`
BLAKE2b-256	`353975b005c51b576e6f8ed8e983493b32bed34dc8860ffd4204f92e7a9acf75`

See more details on using hashes here.

html2mcq 2.0.3

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

html2mcq

Install

Quick Start

Input Methods

Examples (10+)

1. Basic — HTML tutorial page

2. Raw HTML string

3. Multiple PDF URLs in batch

4. Local PDF files

5. Image files with OCR (two-step)

6. Image URLs via vision model (direct)

7. Batch image files

8. Generate as many questions as possible

9. Difficulty mix and topic focus

10. Custom instructions per call

11. Pre-extracted content blocks

12. Save output to JSON file

13. Filter questions by difficulty

14. Different AI provider — Anthropic

15. Local Ollama (no API key needed)

Constructor

New in v2

Two-Step Image Pipeline (method="twostep")

Per-Call Overrides

Output Schema

AI Providers

OCR Priority (when ocr_model="auto")

MCQ Model Priority (when mcq_model="auto")

Custom Instructions

API Reference

MCQGenerator

MCQSet

CLI

Project Structure

License

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

Two-Step Image Pipeline (`method="twostep"`)

OCR Priority (when `ocr_model="auto"`)

MCQ Model Priority (when `mcq_model="auto"`)

`MCQGenerator`

`MCQSet`