🎓 AI Question Generator

Transform any document into high-quality educational questions automatically using advanced AI. Perfect for educators, content creators, and e-learning platforms.

📋 Overview

This Apify Actor analyzes documents (PDF, DOCX, TXT, Markdown) and generates various types of educational questions tailored to your specifications. Powered by Google's Gemini AI, it understands context, extracts key concepts, and creates pedagogically sound questions with appropriate difficulty levels.

✨ Key Features

• 🤖 AI-Powered Analysis: Uses Google Gemini to understand document content and extract key concepts
• 📄 Multiple Document Formats: Supports PDF, DOCX, TXT, and Markdown files
• 🎯 Question Variety: Generate multiple choice, true/false, essay, and fill-in-the-blank questions
• 📊 Customizable Difficulty: Choose from easy, medium, or hard difficulty levels
• 📤 Flexible Export Options: Export to JSON, CSV, or Moodle XML formats
• ⚡ Fast Processing: Generate questions in seconds from document URLs
• 🎨 Quality Assurance: Built-in validation ensures questions are clear, accurate, and educationally valuable

🚀 Quick Start

Basic Usage

1. Provide a document URL (must be publicly accessible)
2. Configure your preferences (question type, difficulty, quantity)
3. Run the Actor
4. Download generated questions in your preferred format

Example Input

{
  "document_url": "https://arxiv.org/pdf/1706.03762.pdf",
  "num_questions": 10,
  "difficulty": "medium",
  "question_types": ["multiple_choice"],
  "export_formats": ["json"]
}

Example Output

{
  "success": true,
  "document_url": "https://arxiv.org/pdf/1706.03762.pdf",
  "questions_generated": 10,
  "quality_score": 8.5,
  "questions": [
    {
      "question": "What is the primary advantage of the Transformer architecture over RNNs?",
      "options": [
        "Parallel processing capability",
        "Lower memory requirements",
        "Simpler implementation",
        "Better performance on small datasets"
      ],
      "correctAnswer": "Parallel processing capability",
      "explanation": "The Transformer can process all positions simultaneously, unlike RNNs which process sequentially.",
      "difficulty": "medium",
      "topic": "Transformer Architecture"
    }
  ],
  "metadata": {
    "question_types": ["multiple_choice"],
    "difficulty": "medium",
    "requested_questions": 10
  }
}

📥 Input Parameters

Parameter	Type	Required	Default	Description
document_url	String	✅ Yes	-	Public URL to the document (PDF, DOCX, TXT, MD)
num_questions	Integer	No	10	Number of questions to generate (1-50)
difficulty	String	No	"medium"	Difficulty level: "easy", "medium", or "hard"
question_types	Array	No	["multiple_choice"]	Types: "multiple_choice", "true_false", "essay", "fill_in_blank"
export_formats	Array	No	["json"]	Export formats: "json", "csv", "moodle_xml"

Input Schema Details

document_url

• Must be a publicly accessible URL
• Supported formats: .pdf, .docx, .txt, .md
• The document should contain educational or informational content
• Maximum recommended size: 50MB

num_questions

• Minimum: 1
• Maximum: 50
• The Actor will generate up to this number based on available content
• Actual number may be less if document is short

difficulty

• easy: Basic recall, definitions, simple facts
• medium: Application, analysis, connecting concepts
• hard: Synthesis, evaluation, complex problem-solving

question_types

Choose one or more from:

• multiple_choice: 4-option questions with one correct answer
• true_false: Binary true/false statements
• essay: Open-ended questions requiring detailed responses
• fill_in_blank: Sentences with missing key terms

export_formats

• json: Structured JSON with full question data (recommended)
• csv: Simple spreadsheet format
• moodle_xml: Compatible with Moodle LMS

📤 Output

The Actor stores results in the dataset and key-value store:

Dataset Output

{
  "success": true,
  "document_url": "string",
  "questions_generated": "number",
  "quality_score": "number (0-10)",
  "questions": [
    {
      "question": "string",
      "options": ["array of strings"] // for MCQ
      "correctAnswer": "string",
      "explanation": "string",
      "difficulty": "string",
      "topic": "string",
      "bloom_level": "string"
    }
  ],
  "exports": {
    "json": "string",
    "csv": "string",
    "moodle_xml": "string"
  },
  "metadata": {
    "question_types": ["array"],
    "difficulty": "string",
    "requested_questions": "number"
  }
}

Key-Value Store

Exported files are stored with keys like:

• questions_json
• questions_csv
• questions_moodle_xml

💡 Use Cases

1. Educators & Teachers

• Create quiz questions from lecture notes or textbooks
• Generate practice questions for students
• Build question banks for assessments
• Prepare homework and test materials

2. E-Learning Platforms

• Automate quiz generation from course content
• Create adaptive learning assessments
• Build interactive study materials
• Generate practice questions at scale

3. Corporate Training

• Create employee assessment questions from training manuals
• Generate compliance test questions
• Build certification exam questions
• Develop knowledge check materials

4. Content Creators

• Generate discussion questions for blog posts
• Create interactive content from articles
• Build engagement tools for educational content
• Develop study guides for courses

5. Students

• Generate practice questions from study materials
• Create self-assessment tools
• Build flashcards from textbooks
• Prepare for exams

🎯 Best Practices

Document Quality

• Use well-structured documents with clear headings and sections
• Ensure sufficient content (minimum 500 words recommended)
• Provide context-rich material rather than lists or tables only
• Use academic or educational sources for best results

Question Configuration

• Start with fewer questions (5-10) to evaluate quality
• Mix difficulty levels for comprehensive assessments
• Use appropriate question types for the content (e.g., MCQ for factual content, essays for analysis)
• Review generated questions before using in production

Performance Optimization

• Use specific, focused documents rather than entire books
• Limit to 20-30 pages for optimal processing time
• Consider document complexity when setting question count
• Use JSON export for programmatic access to question data

🔧 Advanced Usage

Using with Apify API

const ApifyClient = require('apify-client');

const client = new ApifyClient({
    token: 'YOUR_APIFY_TOKEN',
});

const input = {
    document_url: "https://example.com/document.pdf",
    num_questions: 15,
    difficulty: "hard",
    question_types: ["multiple_choice", "essay"],
    export_formats: ["json", "moodle_xml"]
};

const run = await client.actor('YOUR_ACTOR_ID').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(items[0].questions);

Integrating with Learning Management Systems

Moodle Integration:

1. Generate questions with export_formats: ["moodle_xml"]
2. Download the Moodle XML file from key-value store
3. Import into Moodle: Question Bank → Import → Moodle XML format

Custom LMS Integration:

1. Use JSON export format
2. Parse the structured question data
3. Transform to your LMS's required format
4. Import programmatically via your LMS API

Batch Processing

Process multiple documents:

const documents = [
    "https://example.com/chapter1.pdf",
    "https://example.com/chapter2.pdf",
    "https://example.com/chapter3.pdf"
];

for (const doc of documents) {
    await client.actor('YOUR_ACTOR_ID').call({
        document_url: doc,
        num_questions: 10,
        difficulty: "medium"
    });
}

📊 Quality Assurance

The Actor implements multiple quality checks:

Content Validation

• ✅ Questions are factually accurate based on source material
• ✅ No information is fabricated or assumed
• ✅ Questions test understanding, not trivial details
• ✅ Language is clear and unambiguous

Question Quality

• ✅ Multiple choice distractors are plausible but incorrect
• ✅ Questions have only one correct answer (objective types)
• ✅ Appropriate cognitive level for difficulty setting
• ✅ Diverse coverage of document topics

Safety & Ethics

• ✅ No harmful, biased, or inappropriate content
• ✅ Culturally sensitive and inclusive
• ✅ Educational integrity maintained
• ✅ Privacy-respecting (no personal information)

⚙️ Technical Details

Technology Stack

• AI Model: Google Gemini 1.5 Flash
• Framework: LangGraph for workflow orchestration
• Document Processing: PyPDF2, python-docx
• Language: Python 3.13
• Platform: Apify Actor

Processing Pipeline

1. Document Download: Fetch document from provided URL
2. Text Extraction: Parse and extract text content
3. Text Chunking: Split into manageable segments
4. Content Analysis: AI analyzes and extracts key concepts
5. Question Planning: Strategic plan for question distribution
6. Question Generation: AI generates questions based on plan
7. Quality Validation: Verify question quality and accuracy
8. Export: Format and export to requested formats

Performance

• Processing Time: 15-60 seconds per document (varies by size)
• Document Size: Supports up to 50MB
• Concurrency: Can process multiple documents in parallel
• Token Usage: Approximately 10K-30K tokens per document

🔒 Privacy & Security

• No Data Storage: Your documents are processed in memory only
• Temporary Files: Downloaded documents are deleted after processing
• Secure API: Uses HTTPS for all communications
• No Training: Your data is never used to train AI models
• Configurable: All API keys are user-managed via Apify Secrets

❓ FAQ

Q: What document formats are supported?
A: PDF, DOCX, TXT, and Markdown (.md) files are currently supported.

Q: Can I use password-protected PDFs?
A: No, documents must be publicly accessible without authentication.

Q: How accurate are the generated questions?
A: Questions are based strictly on document content with AI validation. Quality score (0-10) is provided with each run.

Q: Can I generate questions in languages other than English?
A: Currently optimized for English. Other languages may work but with varying quality.

Q: What's the maximum document size?
A: Recommended maximum is 50MB or ~200 pages for optimal performance.

Q: Do I need my own Google API key?
A: No, the Actor uses a configured API key. However, you can provide your own via Apify Secrets for higher rate limits.

Q: Can I customize the system prompts?
A: The Actor uses optimized prompts. For custom requirements, you can fork and modify the Actor code.

Q: How many questions can I generate?
A: Up to 50 questions per run. For larger question banks, run the Actor multiple times.

Q: Is there a free tier?
A: Yes! Both Apify and Google Gemini offer free tiers with usage limits.

🐛 Troubleshooting

Common Issues

"Rate limit exceeded" error

• Wait a few minutes and retry
• Consider enabling billing on Google Cloud for higher limits
• Contact support for persistent issues

"Document not found" error

• Verify the URL is publicly accessible
• Check that the URL points directly to the file
• Ensure the document format is supported

"Not enough content" error

• Document may be too short (< 500 words)
• Reduce the number of requested questions
• Ensure the document contains substantial text content

Low quality score

• Document may lack clear educational content
• Try a more structured or academic source
• Consider using a different section of the document

Questions not matching difficulty

• AI adjusts based on available content
• Try requesting fewer questions
• Review the difficulty calibration in output

📞 Support

• Issues: Report bugs via Apify Actor issues
• Feature Requests: Submit via Apify platform
• Documentation: Visit Apify Documentation
• Community: Join Apify Discord

📜 License

This Actor is available for use on the Apify platform under standard Apify terms.

🔄 Version History

v0.6 (Current)

• Improved question quality with enhanced system prompts
• Added support for multiple question types
• Implemented quality scoring system
• Fixed export format issues
• Enhanced error handling

v0.5

• Added Moodle XML export format
• Improved document parsing for complex PDFs
• Better handling of edge cases

v0.4

• Initial public release
• Basic question generation functionality
• JSON and CSV export support

🙏 Credits

Built with:

• Apify Platform
• Google Gemini AI
• LangChain
• LangGraph

---

Made with ❤️ for educators worldwide

Transform your documents into engaging educational content in seconds!