=== 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.6
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 (secondary fallback) — [Get API key](https://openrouter.ai/keys)
* Groq (final fallback) — [Get API key](https://console.groq.com/keys)

Cascade order for reliability: Gemini → OpenRouter → Groq. If one provider or model fails, the next is tried automatically.

**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.

== 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.

== 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.

== Our Other Plugins ==

1. [WPZoomy](https://wpzoomy.com/)
2. [Virtual Classroom for WordPress (Free)](https://elearningevolve.com/products/virtual-classroom-wordpress-free/)
3. [Virtual Classroom for WordPress (Pro)](https://elearningevolve.com/products/wp-virtual-classroom/)
4. [LearnDash Student Voice](https://elearningevolve.com/products/learndash-student-voice/)
5. [Simple Email Scheduler](https://wordpress.org/plugins/simple-email-scheduler/)
6. [UpdateGuard](https://wordpress.org/plugins/updateguard/)
7. [Topbar Buddy](https://wordpress.org/plugins/topbar-buddy/)
8. [Add From Server Reloaded](https://wordpress.org/plugins/add-from-server-reloaded/)
9. [LD to Lifter](https://wordpress.org/plugins/evolve-learndash-to-lifter/)
10. [Zoomy Automator Integration](https://wordpress.org/plugins/zoomy-automator-integration/)

== Changelog ==

= 1.0.6 =
* Fix: Updated Gemini model support for current Google API projects. Older model IDs (including Gemini 2.5 Flash Lite) are no longer accepted for many new API keys; the plugin now prefers Gemini 3.5 / 3.1 Flash models and can follow Google’s suggested replacement model automatically.
* Fix: Restored reliable provider cascade order — Gemini first, then OpenRouter, then Groq — so quiz generation continues when the primary provider or a specific model fails.
* Fix: Refreshed OpenRouter and Groq model lists after upstream free/production model changes (retired Groq Llama IDs and rotating OpenRouter free endpoints).
* Fix: Fast mode no longer pins generation to a single retired Gemini model ID.

= 1.0.5 =
* Added: Edit your generated quiz questions (text, answers, hints) before downloading or creating the LearnDash quiz.
* Improved: The number of questions is always kept within 3–5 (no unexpected snapping).
* Improved: Your saved changes are used automatically for every download format and LearnDash creation.

= 1.0.4 =
Improved : the loading experience to make quiz generation feel faster and more responsive.

= 1.0.3 =
* Updated: Readme optimised with UK SEO keywords for WordPress quiz plugin, AI quiz generator, trivia, and assessment tool searches.


= 1.0.2 =
* Updated: Plugin readme with professional SEO-optimized content, expanded FAQs, How It Works section, and improved WordPress.org discoverability.

= 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.6 =
Important update: refreshes Gemini / OpenRouter / Groq model support after upstream model retirements, and restores the Gemini → OpenRouter → Groq cascade so quiz generation keeps working when a provider fails.

= 1.0.0 =
Initial release.

