=== MasterQuiz AI ===
Contributors: elearningevolve
Tags: quiz, pdf, learndash, ai, quiz-generator
Requires at least: 5.8
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate AI-powered quizzes from PDF documents with LearnDash LMS integration and 9 export formats.

== Description ==

MasterQuiz AI uses artificial intelligence to automatically generate quizzes from your PDF documents. Upload any PDF and the plugin will analyze the content to create high-quality quiz questions including multiple choice, true/false, and essay questions.

**Key Features:**

* **AI-Powered Quiz Generation** — Upload a PDF and get a complete quiz with questions, answers, and explanations.
* **Multiple Question Types** — Supports multiple choice (MCQ), true/false, and essay questions with model answers.
* **LearnDash Integration** — Automatically create LearnDash quizzes and questions with one click.
* **9 Export Formats** — Export quizzes as JSON, XML, CSV, Plain Text, Moodle GIFT, QTI 1.2, Aiken, LearnDash CSV, or LearnDash XML.
* **Points System** — AI assigns points to each question, normalized to 100 total.
* **Bloom's Taxonomy** — Questions are tagged with cognitive levels (Remember, Understand, Apply, Analyze, Evaluate, Create).
* **Background Processing** — Quiz generation runs in the background so you can continue working.
* **Shortcode Support** — Display the quiz generator on any page with `[masterquiz_ai]`.

**AI Providers:**

This plugin connects to external AI services to generate quiz questions. You need at least one API key:

* Google Gemini (primary) — [Get API key](https://aistudio.google.com/apikey)
* OpenRouter (fallback) — [Get API key](https://openrouter.ai/keys)
* Groq (fallback) — [Get API key](https://console.groq.com/keys)

The plugin tries providers in cascade order for maximum reliability.

**Optional RAG Service:**

For improved quiz quality with large PDFs, you can connect an optional RAG (Retrieval-Augmented Generation) microservice for intelligent text chunk selection.

**Generation Modes:**

* **Fast Mode** — 2-call generation for quick results. Produces questions with options, points, hints, and cognitive level tags.
* **Quality Mode** — 3-phase generation for deeper analysis. Adds option rationales, model answers for essays, and rubric criteria.

**Shortcode Attributes:**

`[masterquiz_ai title="My Quiz" show_header="true" show_learndash="auto" max_questions="12"]`

* `title` — Quiz generator heading (default: "PDF to Quiz Generator").
* `show_header` — Show/hide the header section (default: "true").
* `show_learndash` — Show LearnDash button: "true", "false", or "auto" (default: "auto" — auto-detects LearnDash).
* `max_questions` — Maximum questions allowed (default: from settings).

== Installation ==

1. Upload the `masterquiz-ai` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Go to **MasterQuiz AI** and enter at least one AI provider API key.
4. Add the shortcode `[masterquiz_ai]` to any page or post.

== Frequently Asked Questions ==

= Do I need LearnDash? =

No. The plugin works standalone as a quiz generator with 9 export formats. LearnDash integration is optional — when LearnDash is active, you get the added ability to auto-create LearnDash quizzes.

= Which AI provider should I use? =

Google Gemini is recommended as the primary provider. It offers free API access and high-quality quiz generation. OpenRouter and Groq serve as fallbacks.

= What PDF formats are supported? =

The plugin supports text-based PDF files. Scanned/image-based PDFs are not supported as the plugin cannot extract text from images (no OCR).

= How many questions can I generate? =

Between 3 and 12 questions per quiz, configurable from the settings page or shortcode interface.

= Is my PDF data secure? =

Uploaded PDFs are stored temporarily on your server and automatically deleted after quiz generation. The PDF text is sent to the configured AI provider for quiz generation — no data is stored externally.

== Screenshots ==

1. Quiz generator interface with drag-and-drop PDF upload.
2. Generated quiz preview with navigation.
3. Export options with 9 formats.
4. Admin settings page.

== Changelog ==

= 1.0.1 =
* Fix: LearnDash quiz creation failure on newer LearnDash versions where `WpProQuiz_Model_QuizMapper::save()` no longer returns the saved object. The mapper return value is now handled defensively so the code works on both older and newer LearnDash versions.
* Fix: Google Gemini calls failed with a 400 "Unknown name 'thinkingConfig'/'responseMimeType'/'responseSchema'" error because the plugin tried the `v1` endpoint first. Switched to `v1beta` exclusively (the only endpoint that supports these fields).
* Fix: Refreshed OpenRouter free-model list. Removed three models that returned 404 "No endpoints found" (`google/gemma-3-27b-it:free`, `mistralai/mistral-small-3.1-24b-instruct:free`, `qwen/qwen3-4b:free`) and replaced them with currently available free models.
* Fix: Removed Groq model `llama-3.1-70b-versatile` which has been decommissioned by Groq, and added current production models (`llama-4-scout-17b-16e-instruct`, `qwen/qwen3-32b`, `llama-3.1-8b-instant`).

= 1.0.0 =
* Initial release.
* AI-powered quiz generation from PDF documents.
* Support for MCQ, True/False, and Essay questions.
* LearnDash integration for auto-quiz creation.
* 9 export formats.
* Admin settings page with API key management.
* Background processing with progress tracking.

== Upgrade Notice ==

= 1.0.1 =
Bug-fix release. Restores LearnDash quiz creation on the latest LearnDash versions and fixes AI provider failures caused by upstream model and endpoint changes (Gemini API endpoint, OpenRouter free-model availability, decommissioned Groq model).

= 1.0.0 =
Initial release.

== External Services ==

This plugin relies on third-party external AI services to generate quiz questions from PDF documents. No AI processing happens locally — the extracted PDF text must be sent to an external API for quiz generation.

= Google Gemini API =

This plugin connects to the Google Gemini API to generate quiz questions using AI.

* **What it does:** Generates quiz questions (multiple choice, true/false, essay) from text content.
* **When data is sent:** Each time a user clicks "Generate Quiz" and Gemini is the selected or fallback provider.
* **What data is sent:** The extracted text content from the uploaded PDF document, along with quiz generation instructions (number of questions, question types, difficulty preferences). No personal user data is sent.
* **Service provider:** Google LLC
* **Service URL:** [https://generativelanguage.googleapis.com/](https://generativelanguage.googleapis.com/)
* **Google Gemini API Terms of Service:** [https://ai.google.dev/gemini-api/terms](https://ai.google.dev/gemini-api/terms)
* **Google Privacy Policy:** [https://policies.google.com/privacy](https://policies.google.com/privacy)
* **Google Generative AI Additional Terms:** [https://ai.google.dev/gemini-api/terms](https://ai.google.dev/gemini-api/terms)

= OpenRouter API =

This plugin connects to the OpenRouter API as a fallback AI provider for quiz generation.

* **What it does:** Generates quiz questions using various AI models available through OpenRouter.
* **When data is sent:** Each time a user clicks "Generate Quiz" and OpenRouter is the selected or fallback provider (used when the primary provider fails or is not configured).
* **What data is sent:** The extracted text content from the uploaded PDF document, along with quiz generation instructions. No personal user data is sent.
* **Service provider:** OpenRouter Inc.
* **Service URL:** [https://openrouter.ai/](https://openrouter.ai/)
* **Terms of Service:** [https://openrouter.ai/terms](https://openrouter.ai/terms)
* **Privacy Policy:** [https://openrouter.ai/privacy](https://openrouter.ai/privacy)

= Groq API =

This plugin connects to the Groq API as a fallback AI provider for quiz generation.

* **What it does:** Generates quiz questions using Groq-hosted AI models.
* **When data is sent:** Each time a user clicks "Generate Quiz" and Groq is the selected or fallback provider (used when higher-priority providers fail or are not configured).
* **What data is sent:** The extracted text content from the uploaded PDF document, along with quiz generation instructions. No personal user data is sent.
* **Service provider:** Groq Inc.
* **Service URL:** [https://api.groq.com/](https://api.groq.com/)
* **Terms of Service:** [https://groq.com/terms-of-use/](https://groq.com/terms-of-use/)
* **Privacy Policy:** [https://groq.com/privacy-policy/](https://groq.com/privacy-policy/)

= Optional RAG Microservice =

This plugin can optionally connect to a user-configured RAG (Retrieval-Augmented Generation) microservice for intelligent text chunk selection from large PDFs.

* **What it does:** Selects the most relevant text chunks from a PDF for quiz generation.
* **When data is sent:** Each time a user generates a quiz with RAG enabled in the plugin settings.
* **What data is sent:** The extracted text chunks from the uploaded PDF document. No personal user data is sent.
* **Service provider:** Self-hosted or user-configured. The URL is set by the site administrator in the plugin settings.
* **This service is disabled by default** and must be explicitly enabled and configured by the site administrator.
