image2mcq 1.0.0__tar.gz

image2mcq-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 image2mcq
+
+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.

image2mcq-1.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: image2mcq
+Version: 1.0.0
+Summary: Convert images (screenshots, scanned pages, diagrams) into MCQ questions using AI
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/manjur-ai/image2mcq
+Project-URL: Issues, https://github.com/manjur-ai/image2mcq/issues
+Keywords: mcq,quiz,ai,education,image,ocr,vision,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 :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.25
+Requires-Dist: openai>=1.30
+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
+
+# image2mcq
+
+Convert images — screenshots, scanned pages, diagrams, charts, and photographs — into high-quality MCQ questions using AI.
+
+Built on top of **html2mcq**'s image pipeline, extracted as a standalone library focused purely on image-to-MCQ generation.
+
+---
+
+## Features
+
+- **Two processing methods:**
+  - `twostep` (default) — OCR image text, then generate MCQs from extracted text
+  - `images2mcq` — send images directly to a vision LLM for MCQ generation
+- **Multiple AI providers:** OpenRouter, Anthropic, OpenAI, Ollama
+- **Auto model failover:** if one model fails (e.g. quota exhausted), automatically tries the next
+- **Local OCR fallback:** Tesseract OCR when vision APIs are unavailable
+- **CLI & Python API** — use from terminal or integrate into your code
+
+---
+
+## Quick Start
+
+### CLI
+
+```bash
+# Single image file
+image2mcq --image-path diagram.png -n 5
+
+# Multiple image URLs
+image2mcq --image-url https://example.com/chart1.png --image-url https://example.com/chart2.png
+
+# Scan a folder of images
+image2mcq --image-folder ./lecture-slides/ --method images2mcq
+
+# Output as JSON
+image2mcq --image-path notes.png -o questions.json --format json
+
+# Use n=999 to generate as many as the content supports
+image2mcq --image-path textbook-page.png
+```
+
+### Python API
+
+```python
+from image2mcq import ImageMCQGenerator
+
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    provider="openrouter",
+    mcq_model="google/gemini-2.5-flash-lite",
+)
+
+# From local files
+mcq = gen.from_image_paths("screenshot.png", n=5)
+print(mcq.to_pretty_str())
+
+# From URLs
+mcq = gen.from_image_urls("https://example.com/diagram.png", n=3)
+print(mcq.to_json())
+
+# From multiple images
+mcq = gen.from_image_paths(["page1.png", "page2.png", "page3.png"])
+```
+
+### Two-Step (OCR → MCQ)
+
+```python
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    method="twostep",  # default
+)
+mcq = gen.from_image_paths("scanned-page.png", n=10)
+```
+
+### Images2MCQ (Vision Direct)
+
+```python
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    method="images2mcq",
+    mcq_model="openai/gpt-4o",  # vision model
+)
+mcq = gen.from_image_paths("architecture-diagram.png", n=5)
+```
+
+### Custom Instructions
+
+```python
+mcq = gen.from_image_paths(
+    "graph.png",
+    n=5,
+    difficulty_mix="50% easy, 50% hard",
+    focus_topics=["data structures", "time complexity"],
+    custom_instructions="Make answers very close and confusing",
+)
+```
+
+### Auto Model Selection
+
+```python
+gen = ImageMCQGenerator(
+    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 |
+| `IMAGE2MCQ_MCQ_MODELS` | Comma-separated MCQ model priority list for `model="auto"` |
+| `IMAGE2MCQ_OCR_MODELS` | Comma-separated OCR model priority list for `ocr_model="auto"` |
+
+---
+
+## Output Format
+
+```python
+# Pretty-print
+print(mcq.to_pretty_str())
+
+# JSON
+print(mcq.to_json())
+# {
+#   "total_exam_time": 20,
+#   "questions": [
+#     {
+#       "question_html": "What is the time complexity of binary search?",
+#       "options": ["O(n)", "O(log n)", "O(n^2)", "O(1)"],
+#       "answers": [1],
+#       "multi": false,
+#       "marks": 1.0,
+#       "negative_marks": 0.25,
+#       "difficulty": "easy",
+#       "explaination": "Binary search halves the search space each iteration."
+#     }
+#   ]
+# }
+```
+
+---
+
+## Installation
+
+```bash
+pip install image2mcq
+```
+
+For OCR support, also install [Tesseract](https://github.com/tesseract-ocr/tesseract).
+
+---
+
+## License
+
+MIT

image2mcq-1.0.0/README.md

@@ -0,0 +1,162 @@
+# image2mcq
+
+Convert images — screenshots, scanned pages, diagrams, charts, and photographs — into high-quality MCQ questions using AI.
+
+Built on top of **html2mcq**'s image pipeline, extracted as a standalone library focused purely on image-to-MCQ generation.
+
+---
+
+## Features
+
+- **Two processing methods:**
+  - `twostep` (default) — OCR image text, then generate MCQs from extracted text
+  - `images2mcq` — send images directly to a vision LLM for MCQ generation
+- **Multiple AI providers:** OpenRouter, Anthropic, OpenAI, Ollama
+- **Auto model failover:** if one model fails (e.g. quota exhausted), automatically tries the next
+- **Local OCR fallback:** Tesseract OCR when vision APIs are unavailable
+- **CLI & Python API** — use from terminal or integrate into your code
+
+---
+
+## Quick Start
+
+### CLI
+
+```bash
+# Single image file
+image2mcq --image-path diagram.png -n 5
+
+# Multiple image URLs
+image2mcq --image-url https://example.com/chart1.png --image-url https://example.com/chart2.png
+
+# Scan a folder of images
+image2mcq --image-folder ./lecture-slides/ --method images2mcq
+
+# Output as JSON
+image2mcq --image-path notes.png -o questions.json --format json
+
+# Use n=999 to generate as many as the content supports
+image2mcq --image-path textbook-page.png
+```
+
+### Python API
+
+```python
+from image2mcq import ImageMCQGenerator
+
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    provider="openrouter",
+    mcq_model="google/gemini-2.5-flash-lite",
+)
+
+# From local files
+mcq = gen.from_image_paths("screenshot.png", n=5)
+print(mcq.to_pretty_str())
+
+# From URLs
+mcq = gen.from_image_urls("https://example.com/diagram.png", n=3)
+print(mcq.to_json())
+
+# From multiple images
+mcq = gen.from_image_paths(["page1.png", "page2.png", "page3.png"])
+```
+
+### Two-Step (OCR → MCQ)
+
+```python
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    method="twostep",  # default
+)
+mcq = gen.from_image_paths("scanned-page.png", n=10)
+```
+
+### Images2MCQ (Vision Direct)
+
+```python
+gen = ImageMCQGenerator(
+    api_key="sk-or-v1-...",
+    method="images2mcq",
+    mcq_model="openai/gpt-4o",  # vision model
+)
+mcq = gen.from_image_paths("architecture-diagram.png", n=5)
+```
+
+### Custom Instructions
+
+```python
+mcq = gen.from_image_paths(
+    "graph.png",
+    n=5,
+    difficulty_mix="50% easy, 50% hard",
+    focus_topics=["data structures", "time complexity"],
+    custom_instructions="Make answers very close and confusing",
+)
+```
+
+### Auto Model Selection
+
+```python
+gen = ImageMCQGenerator(
+    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 |
+| `IMAGE2MCQ_MCQ_MODELS` | Comma-separated MCQ model priority list for `model="auto"` |
+| `IMAGE2MCQ_OCR_MODELS` | Comma-separated OCR model priority list for `ocr_model="auto"` |
+
+---
+
+## Output Format
+
+```python
+# Pretty-print
+print(mcq.to_pretty_str())
+
+# JSON
+print(mcq.to_json())
+# {
+#   "total_exam_time": 20,
+#   "questions": [
+#     {
+#       "question_html": "What is the time complexity of binary search?",
+#       "options": ["O(n)", "O(log n)", "O(n^2)", "O(1)"],
+#       "answers": [1],
+#       "multi": false,
+#       "marks": 1.0,
+#       "negative_marks": 0.25,
+#       "difficulty": "easy",
+#       "explaination": "Binary search halves the search space each iteration."
+#     }
+#   ]
+# }
+```
+
+---
+
+## Installation
+
+```bash
+pip install image2mcq
+```
+
+For OCR support, also install [Tesseract](https://github.com/tesseract-ocr/tesseract).
+
+---
+
+## License
+
+MIT

image2mcq-1.0.0/image2mcq/__init__.py

@@ -0,0 +1,13 @@
+from .generator import ImageMCQGenerator
+from .image_ocr import ImageOCRExtractor
+from .models import MCQQuestion, MCQSet, ContentBlock
+
+__version__ = "1.0.0"
+__author__ = "image2mcq"
+__all__ = [
+    "ImageMCQGenerator",
+    "ImageOCRExtractor",
+    "MCQQuestion",
+    "MCQSet",
+    "ContentBlock",
+]

image2mcq-1.0.0/image2mcq/cli.py

@@ -0,0 +1,199 @@
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tiff", ".tif", ".webp"}
+
+
+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="image2mcq",
+        description="Convert images (screenshots, scanned pages, diagrams) 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("--image-url", metavar="URL", action="append", default=[],
+                             help="Image URL (repeatable: --image-url url1 --image-url url2)")
+    input_group.add_argument("--image-path", metavar="FILE", action="append", default=[],
+                             help="Local image file path (repeatable)")
+    input_group.add_argument("--image-folder", metavar="DIR", default="",
+                             help="Scan folder for images (.png, .jpg, .jpeg, .gif, .bmp, .tiff, .webp)")
+
+    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 IMAGE2MCQ_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.")
+
+    ocr_group = parser.add_argument_group("OCR & image processing")
+    ocr_group.add_argument("--ocr-model", default="pytesseract",
+                           help="OCR backend: 'pytesseract', 'auto', or any OpenRouter model ID "
+                                "(e.g. 'openai/gpt-4o'). (default: pytesseract)")
+    ocr_group.add_argument("--ocr-models", default="",
+                           help="Comma-separated priority model list for --ocr-model auto. "
+                                "E.g. 'gpt-4o,gemma-27b,gemma-12b,pytesseract'")
+    ocr_group.add_argument("--method", default="twostep", choices=["twostep", "images2mcq"],
+                           help="Image processing: 'twostep' (OCR->MCQ) or 'images2mcq' (vision direct). "
+                                "(default: twostep)")
+    ocr_group.add_argument("--save-ocr-path", default="",
+                           help="File path to save OCR text when method=twostep")
+    ocr_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 image2mcq import __version__
+        except ImportError:
+            __version__ = "unknown"
+        print(f"image2mcq v{__version__}")
+        sys.exit(0)
+
+    if args.image_folder:
+        args.image_path.extend(_glob_files(args.image_folder, _IMAGE_EXTENSIONS))
+
+    has_input = bool(args.image_url or args.image_path)
+    if not has_input:
+        parser.print_help()
+        print("\nError: at least one input source is required "
+              "(--image-url, --image-path, --image-folder)", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        from image2mcq import ImageMCQGenerator
+    except ImportError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    api_key = _get_api_key(args)
+    ocr_models = None
+    if args.ocr_models:
+        ocr_models = [m.strip() for m in args.ocr_models.split(",") if m.strip()]
+    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 = ImageMCQGenerator(
+            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,
+            ocr_model=args.ocr_model,
+            ocr_models=ocr_models,
+            method=args.method,
+            save_ocr_path=args.save_ocr_path or None,
+            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.image_url and args.image_path:
+            print("Error: specify either --image-url or --image-path, not both.", file=sys.stderr)
+            sys.exit(1)
+        if args.image_url:
+            mcq_set = gen.from_image_urls(args.image_url, n=n, difficulty_mix=difficulty,
+                                          focus_topics=topics, custom_instructions=instructions)
+        if args.image_path:
+            mcq_set = gen.from_image_paths(args.image_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()