pdf2mcq 1.0.0__tar.gz

pdf2mcq-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pdf2mcq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf2mcq-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pdf2mcq
+Version: 1.0.0
+Summary: Convert PDF files (text, scanned, mixed) into MCQ questions using AI
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/manjur-ai/pdf2mcq
+Project-URL: Issues, https://github.com/manjur-ai/pdf2mcq/issues
+Keywords: mcq,quiz,ai,education,pdf,ocr,llm,openrouter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.25
+Requires-Dist: openai>=1.30
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pytesseract>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# pdf2mcq
+
+Convert PDF files — text PDFs, scanned books, mixed documents — into high-quality MCQ questions using AI.
+
+Built on top of **html2mcq**'s PDF pipeline, extracted as a standalone library focused purely on PDF-to-MCQ generation.
+
+---
+
+## Features
+
+- **Smart PDF detection** — automatically detects text PDFs, scanned PDFs, and mixed documents
+- **Text PDFs** — fast extraction via PyMuPDF with chunking at sentence boundaries
+- **Scanned PDFs** — renders pages as images → vision API OCR (or pytesseract fallback)
+- **Mixed PDFs** — text pages via PyMuPDF + scanned pages via OCR, combined intelligently
+- **Multiple AI providers:** OpenRouter, Anthropic, OpenAI, Ollama
+- **Auto model failover** for MCQ generation
+- **CLI & Python API**
+
+---
+
+## Quick Start
+
+### CLI
+
+```bash
+# Single PDF
+pdf2mcq --pdf-path textbook.pdf -n 10
+
+# Multiple PDF URLs
+pdf2mcq --pdf-url https://example.com/chapter1.pdf --pdf-url https://example.com/chapter2.pdf
+
+# Scan a folder of PDFs
+pdf2mcq --pdf-folder ./textbooks/
+
+# Output as JSON
+pdf2mcq --pdf-path notes.pdf -o questions.json --format json
+```
+
+### Python API
+
+```python
+from pdf2mcq import PDFMCQGenerator
+
+gen = PDFMCQGenerator(
+    api_key="sk-or-v1-...",
+    provider="openrouter",
+    mcq_model="google/gemini-2.5-flash-lite",
+)
+
+# From local PDF
+mcq = gen.from_pdf_paths("textbook.pdf", n=5)
+print(mcq.to_pretty_str())
+
+# From URL
+mcq = gen.from_pdf_urls("https://example.com/notes.pdf", n=3)
+print(mcq.to_json())
+
+# Multiple PDFs
+mcq = gen.from_pdf_paths(["chapter1.pdf", "chapter2.pdf", "chapter3.pdf"])
+```
+
+### Custom Instructions
+
+```python
+mcq = gen.from_pdf_paths(
+    "lecture-notes.pdf",
+    n=10,
+    difficulty_mix="50% easy, 50% hard",
+    focus_topics=["machine learning", "neural networks"],
+    custom_instructions="Focus on mathematical derivations",
+)
+```
+
+### Auto Model Selection
+
+```python
+gen = PDFMCQGenerator(
+    api_key="sk-or-v1-...",
+    mcq_model="auto",
+    mcq_model_list=[
+        "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+        "google/gemma-4-31b-it:free",
+    ],
+)
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `OPENROUTER_API_KEY` | Default API key for OpenRouter |
+| `ANTHROPIC_API_KEY` | API key for Anthropic |
+| `OPENAI_API_KEY` | API key for OpenAI |
+| `PDF2MCQ_MCQ_MODELS` | Comma-separated MCQ model priority list for `mcq_model="auto"` |
+| `PDF2MCQ_OCR_MODELS` | Comma-separated OCR model priority list for scanned PDFs |
+
+---
+
+## Output Format
+
+```python
+# Pretty-print
+print(mcq.to_pretty_str())
+
+# JSON
+print(mcq.to_json())
+# {
+#   "total_exam_time": 20,
+#   "questions": [
+#     {
+#       "question_html": "What is gradient descent?",
+#       "options": ["...", "...", "...", "..."],
+#       "answers": [0],
+#       "multi": false,
+#       "marks": 1.0,
+#       "negative_marks": 0.25,
+#       "difficulty": "easy",
+#       "explaination": "..."
+#     }
+#   ]
+# }
+```
+
+---
+
+## Installation
+
+```bash
+pip install pdf2mcq
+```
+
+Requires **PyMuPDF** (fitz) — installed automatically as a dependency.
+
+For scanned PDF OCR, also install [Tesseract](https://github.com/tesseract-ocr/tesseract).
+
+---
+
+## License
+
+MIT

pdf2mcq-1.0.0/README.md

@@ -0,0 +1,140 @@
+# pdf2mcq
+
+Convert PDF files — text PDFs, scanned books, mixed documents — into high-quality MCQ questions using AI.
+
+Built on top of **html2mcq**'s PDF pipeline, extracted as a standalone library focused purely on PDF-to-MCQ generation.
+
+---
+
+## Features
+
+- **Smart PDF detection** — automatically detects text PDFs, scanned PDFs, and mixed documents
+- **Text PDFs** — fast extraction via PyMuPDF with chunking at sentence boundaries
+- **Scanned PDFs** — renders pages as images → vision API OCR (or pytesseract fallback)
+- **Mixed PDFs** — text pages via PyMuPDF + scanned pages via OCR, combined intelligently
+- **Multiple AI providers:** OpenRouter, Anthropic, OpenAI, Ollama
+- **Auto model failover** for MCQ generation
+- **CLI & Python API**
+
+---
+
+## Quick Start
+
+### CLI
+
+```bash
+# Single PDF
+pdf2mcq --pdf-path textbook.pdf -n 10
+
+# Multiple PDF URLs
+pdf2mcq --pdf-url https://example.com/chapter1.pdf --pdf-url https://example.com/chapter2.pdf
+
+# Scan a folder of PDFs
+pdf2mcq --pdf-folder ./textbooks/
+
+# Output as JSON
+pdf2mcq --pdf-path notes.pdf -o questions.json --format json
+```
+
+### Python API
+
+```python
+from pdf2mcq import PDFMCQGenerator
+
+gen = PDFMCQGenerator(
+    api_key="sk-or-v1-...",
+    provider="openrouter",
+    mcq_model="google/gemini-2.5-flash-lite",
+)
+
+# From local PDF
+mcq = gen.from_pdf_paths("textbook.pdf", n=5)
+print(mcq.to_pretty_str())
+
+# From URL
+mcq = gen.from_pdf_urls("https://example.com/notes.pdf", n=3)
+print(mcq.to_json())
+
+# Multiple PDFs
+mcq = gen.from_pdf_paths(["chapter1.pdf", "chapter2.pdf", "chapter3.pdf"])
+```
+
+### Custom Instructions
+
+```python
+mcq = gen.from_pdf_paths(
+    "lecture-notes.pdf",
+    n=10,
+    difficulty_mix="50% easy, 50% hard",
+    focus_topics=["machine learning", "neural networks"],
+    custom_instructions="Focus on mathematical derivations",
+)
+```
+
+### Auto Model Selection
+
+```python
+gen = PDFMCQGenerator(
+    api_key="sk-or-v1-...",
+    mcq_model="auto",
+    mcq_model_list=[
+        "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+        "google/gemma-4-31b-it:free",
+    ],
+)
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `OPENROUTER_API_KEY` | Default API key for OpenRouter |
+| `ANTHROPIC_API_KEY` | API key for Anthropic |
+| `OPENAI_API_KEY` | API key for OpenAI |
+| `PDF2MCQ_MCQ_MODELS` | Comma-separated MCQ model priority list for `mcq_model="auto"` |
+| `PDF2MCQ_OCR_MODELS` | Comma-separated OCR model priority list for scanned PDFs |
+
+---
+
+## Output Format
+
+```python
+# Pretty-print
+print(mcq.to_pretty_str())
+
+# JSON
+print(mcq.to_json())
+# {
+#   "total_exam_time": 20,
+#   "questions": [
+#     {
+#       "question_html": "What is gradient descent?",
+#       "options": ["...", "...", "...", "..."],
+#       "answers": [0],
+#       "multi": false,
+#       "marks": 1.0,
+#       "negative_marks": 0.25,
+#       "difficulty": "easy",
+#       "explaination": "..."
+#     }
+#   ]
+# }
+```
+
+---
+
+## Installation
+
+```bash
+pip install pdf2mcq
+```
+
+Requires **PyMuPDF** (fitz) — installed automatically as a dependency.
+
+For scanned PDF OCR, also install [Tesseract](https://github.com/tesseract-ocr/tesseract).
+
+---
+
+## License
+
+MIT

pdf2mcq-1.0.0/pdf2mcq/__init__.py

@@ -0,0 +1,13 @@
+from .generator import PDFMCQGenerator
+from .pdf import PDFExtractor
+from .models import MCQQuestion, MCQSet, ContentBlock
+
+__version__ = "1.0.0"
+__author__ = "pdf2mcq"
+__all__ = [
+    "PDFMCQGenerator",
+    "PDFExtractor",
+    "MCQQuestion",
+    "MCQSet",
+    "ContentBlock",
+]

pdf2mcq-1.0.0/pdf2mcq/cli.py

@@ -0,0 +1,187 @@
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+_PDF_EXTENSION = ".pdf"
+
+
+def _glob_files(folder: str, extensions: set) -> list:
+    folder = Path(folder)
+    if not folder.is_dir():
+        print(f"Error: folder not found: {folder}", file=sys.stderr)
+        sys.exit(1)
+    files = []
+    for ext in extensions:
+        files.extend(folder.glob(f"*{ext}"))
+        files.extend(folder.glob(f"*{ext.upper()}"))
+    seen = set()
+    unique = []
+    for f in sorted(files, key=lambda p: p.name.lower()):
+        if f.suffix.lower() in extensions and f.name not in seen:
+            seen.add(f.name)
+            unique.append(str(f))
+    return unique
+
+
+def _get_api_key(args):
+    key = args.api_key or ""
+    if key:
+        return key
+    env_vars = {
+        "openrouter": "OPENROUTER_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+        "openai": "OPENAI_API_KEY",
+        "ollama": "",
+    }
+    env_key = env_vars.get(args.provider, "")
+    if env_key:
+        return os.environ.get(env_key, "")
+    return ""
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="pdf2mcq",
+        description="Convert PDF files (text, scanned, mixed) into MCQ questions using AI.",
+    )
+
+    parser.add_argument("--version", action="store_true", help="Show version and exit")
+
+    input_group = parser.add_argument_group("Input sources (at least one required)")
+    input_group.add_argument("--pdf-url", metavar="URL", action="append", default=[],
+                             help="PDF URL (repeatable: --pdf-url url1 --pdf-url url2)")
+    input_group.add_argument("--pdf-path", metavar="FILE", action="append", default=[],
+                             help="Local PDF file path (repeatable)")
+    input_group.add_argument("--pdf-folder", metavar="DIR", default="",
+                             help="Scan folder for PDF files (.pdf)")
+
+    gen_group = parser.add_argument_group("Generation options")
+    gen_group.add_argument("-n", "--n", type=int, default=999,
+                           help="Number of questions (default: 999 = as many as content supports)")
+    gen_group.add_argument("--difficulty", default=None,
+                           help='E.g. "30%% easy, 40%% medium, 30%% hard"')
+    gen_group.add_argument("--topics", nargs="*", help="Focus topics")
+    gen_group.add_argument("--instructions", "-i", default="",
+                           help='Custom instructions e.g. "Make answers very close and confusing"')
+    gen_group.add_argument("--batch-size", type=int, default=10,
+                           help="Questions per API call (default: 10)")
+
+    ai_group = parser.add_argument_group("AI provider")
+    ai_group.add_argument("--provider", default="openrouter",
+                          choices=["anthropic", "openai", "openrouter", "ollama"],
+                          help="AI provider (default: openrouter). Use 'ollama' for local LLM.")
+    ai_group.add_argument("--mcq-model", default="",
+                          help="MCQ generation model (or 'auto' to try --mcq-models)")
+    ai_group.add_argument("--mcq-models", default="",
+                          help="Comma-separated priority model list for --mcq-model auto. "
+                               "Runtime-reloadable via PDF2MCQ_MCQ_MODELS env var.")
+    ai_group.add_argument("--api-key", default="",
+                          help="API key. Falls back to OPENROUTER_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY env var.")
+    ai_group.add_argument("--ollama-base-url", default="http://localhost:11434/v1",
+                          help="Ollama API base URL (default: http://localhost:11434/v1). "
+                               "Only used when --provider ollama.")
+
+    pdf_group = parser.add_argument_group("PDF processing")
+    pdf_group.add_argument("--pdf-backend", default="auto_detect",
+                           choices=["auto_detect", "pymupdf", "image"],
+                           help="PDF extraction backend (default: auto_detect)")
+    pdf_group.add_argument("--scanned-max-pages", type=int, default=50,
+                           help="Max pages to OCR for scanned PDFs (default: 50)")
+    pdf_group.add_argument("--prompt-log-path", default="",
+                           help="Dump prompts to file, or 'stdout' / '-' for terminal")
+
+    out_group = parser.add_argument_group("Output")
+    out_group.add_argument("--output", "-o", default="",
+                           help="Output file (.json or .txt). Default: stdout")
+    out_group.add_argument("--format", choices=["json", "pretty"], default="pretty",
+                           help="Output format (default: pretty)")
+
+    args = parser.parse_args()
+
+    if args.version:
+        try:
+            from pdf2mcq import __version__
+        except ImportError:
+            __version__ = "unknown"
+        print(f"pdf2mcq v{__version__}")
+        sys.exit(0)
+
+    if args.pdf_folder:
+        args.pdf_path.extend(_glob_files(args.pdf_folder, {_PDF_EXTENSION}))
+
+    has_input = bool(args.pdf_url or args.pdf_path)
+    if not has_input:
+        parser.print_help()
+        print("\nError: at least one input source is required "
+              "(--pdf-url, --pdf-path, --pdf-folder)", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        from pdf2mcq import PDFMCQGenerator
+    except ImportError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    api_key = _get_api_key(args)
+    mcq_model_list = None
+    if args.mcq_models:
+        mcq_model_list = [m.strip() for m in args.mcq_models.split(",") if m.strip()]
+
+    try:
+        gen = PDFMCQGenerator(
+            api_key=api_key or None,
+            provider=args.provider,
+            mcq_model=args.mcq_model,
+            mcq_model_list=mcq_model_list,
+            batch_size=args.batch_size,
+            pdf_backend=args.pdf_backend,
+            pdf_scanned_max_pages=args.scanned_max_pages,
+            prompt_log_path=args.prompt_log_path or None,
+            ollama_base_url=args.ollama_base_url,
+        )
+    except ValueError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    n = args.n
+    difficulty = args.difficulty
+    topics = args.topics
+    instructions = args.instructions or None
+
+    mcq_set = None
+
+    try:
+        if args.pdf_url:
+            print(f"Fetching PDFs: {args.pdf_url}", file=sys.stderr)
+            mcq_set = gen.from_pdf_urls(args.pdf_url, n=n, difficulty_mix=difficulty,
+                                        focus_topics=topics, custom_instructions=instructions)
+        if args.pdf_path:
+            print(f"Reading PDFs: {args.pdf_path}", file=sys.stderr)
+            mcq_set = gen.from_pdf_paths(args.pdf_path, n=n, difficulty_mix=difficulty,
+                                         focus_topics=topics, custom_instructions=instructions)
+    except Exception as e:
+        print(f"Generation failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if mcq_set is None or not mcq_set.questions:
+        print("No questions were generated.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.format == "json":
+        output = mcq_set.to_json()
+    else:
+        output = mcq_set.to_pretty_str()
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output)
+        print(f"Saved {mcq_set.total_questions} questions to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+
+if __name__ == "__main__":
+    main()