title	emoji	colorFrom	colorTo	sdk	sdk_version	app_file	pinned	license	short_description
QuizSmith	💜	indigo	purple	gradio	6.1.0	app.py	false	mit	Quiz Generator & AI Study Companion

🎯 QuizSmith - AI Study Companion

An AI-powered quiz generator that creates personalized study materials from your notes. Built for CS4990 Prompt Engineering Final Project.

🚀 Live Demo: https://huggingface.co/spaces/aerika/QuizSmith

---

🎓 Problem Statement

Students struggle to:

• Create effective practice questions from their study materials
• Get personalized feedback while they study
• Study efficiently with adaptive difficulty
• Retain information through active recall

QuizSmith solves this by using AI to generate customized quizzes with intelligent learning assistance.

---

✨ Features

• 📄 Multi-format Input: Text or PDF upload
• 🎯 Two Study Modes: Multiple Choice Questions & Flashcards
• 🎚️ Adaptive Difficulty: Easy, Medium, or Hard (5-50 questions)
• 🔀 Always Shuffled: Questions randomized every time for better learning
• 💡 AI Learning Tips: Personalized feedback when you get answers wrong
• 🧠 Memory Tricks: AI-generated mnemonics for difficult flashcards
• 📊 Performance Tracking: Score tracking with personalized study recommendations
• ⏹️ Exit Anytime: Leave quiz and start fresh whenever needed

---

🧠 Prompt Engineering Techniques

This project demonstrates 4 advanced prompt engineering patterns:

1. 🎭 Persona Pattern

Establishes "QuizSmith" as an expert educational content creator with defined expertise:

SYSTEM_PERSONA = """You are QuizSmith, an expert educational content creator
and learning scientist.

Your expertise:
- Creating clear, accurate, pedagogically sound assessments
- Adapting content difficulty to match learner needs
- Explaining concepts in multiple ways for deeper understanding
- Identifying knowledge gaps and misconceptions

Your principles:
- Base all questions strictly on provided source material
- Write unambiguous questions with one clear correct answer
- Provide explanations that teach, not just verify
- Match difficulty to learner's demonstrated understanding"""

Impact: Ensures consistent, high-quality educational content generation.

2. 📚 Few-Shot Learning

Provides JSON schema examples to ensure structured, consistent output:

FEW_SHOT_MCQ = """Return ONLY valid JSON array:
[
  {
    "question": "What is TCP's primary function?",
    "options": ["Encrypt data", "Establish reliable connections", ...],
    "correct_index": 1,
    "explanation": "TCP establishes reliable connections through handshake."
  }
]"""

Impact: Reduces hallucinations and ensures parseable, structured responses.

3. 🔄 Adaptive Difficulty

AI dynamically adjusts question complexity based on Easy/Medium/Hard setting:

prompt = f"""Content: {content}
Difficulty: {difficulty}
Generate {num} {mode} questions that match this difficulty level."""

Impact: Provides appropriate challenge level for different learner needs.

4. 🧠 Enhanced Learning Feedback

Generates personalized learning tips for incorrect answers:

def generate_learning_tip(question, correct_answer, user_answer, explanation):
    """Generate 2-3 sentence learning tip explaining why the wrong answer
    was chosen and how to remember the correct answer."""
    # Uses GPT-4o-mini with encouraging tutor persona

Impact: Transforms mistakes into learning opportunities with personalized guidance.

---

🎨 User Interface

Clean, intuitive Gradio interface featuring:

• Purple gradient theme with glowing hover effects
• Single-page flow with automatic state transitions
• Responsive UI spinner runs during 10-15 second generation
• Instant visual feedback with color-coded responses
• Progress tracking with animated progress bar

---

🛠️ Technology Stack

• AI Model: OpenAI GPT-4o-mini (fast, cost-effective, accurate)
• Framework: Gradio 6.0 (modern, responsive UI)
• PDF Processing: PyMuPDF (reliable text extraction)
• Deployment: Hugging Face Spaces (free, public hosting)
• Language: Python 3.10+

---

📝 Code Structure

QuizSmith/
├── app.py                  # Main application
├── requirements.txt        # Dependencies
├── LICENSE.txt             # MIT license
├── README.md               # This file
└── screenshots/            # App screenshots

Key Functions:

• extract_text_from_pdf() - PDF processing
• generate_learning_tip() - AI learning assistance
• generate_flashcard_tip() - Memory tricks
• process_generation() - Main quiz generation logic
• submit_answer() - Feedback & learning tips
• next_question() - Progress tracking

---

🚀 Quick Start

Try It Now

Visit the live demo: https://huggingface.co/spaces/aerika/QuizSmith

Run Locally

1 - Clone repository

git clone https://github.com/arminerika/quizsmith.git
cd quizsmith

2 - Install dependencies

pip install -r requirements.txt

3 - Set API key

export OPENAI_API_KEY='sk-your-key-here'

4 - Run app

python app.py

5 - Open browser

http://localhost:7860

---

📖 How to Use

Step 1: Upload Content

• Text: Paste your study notes directly
• PDF: Upload lecture slides or textbook chapters
• Topic (Optional): Specify focus area (e.g., "TCP/IP Networking")

Step 2: Configure Quiz

• Mode: Choose Multiple Choice or Flashcards
• Difficulty: Select Easy, Medium, or Hard (AI adapts complexity)
• Quantity: Set 5-50 questions (always shuffled)

Step 3: Study & Learn

• Answer questions: Get instant feedback
• Wrong answers: Receive personalized AI learning tips
• Flashcards: Mark "Still Learning" for memory tricks
• Track progress: See score and performance insights

Step 4: Review & Improve

• Performance breakdown: See what you got right/wrong
• Study recommendations: Get personalized improvement tips
• Exit anytime: Leave quiz and adjust settings
• Start fresh: Generate new quiz with different difficulty

---

🐛 Troubleshooting

App won't start locally?

• Check OPENAI_API_KEY is set in environment
• Verify all requirements installed: pip install -r requirements.txt

PDF not working?

• Ensure PDF contains extractable text (not scanned images)
• Try copy-pasting text instead

Questions seem too easy/hard?

• Adjust difficulty setting (Easy/Medium/Hard)
• AI adapts question complexity accordingly

Want to exit mid-quiz?

• Click "⏹️ Exit Quiz" button during any question

---

📄 License

MIT License - Free to use for educational purposes

---

🙏 Acknowledgments

• Course: CS4860 Prompt Engineering, Fall 2025
• AI Model: OpenAI GPT-4o-mini
• Framework: Gradio by Hugging Face
• Hosting: Hugging Face Spaces (free tier)

---

📍 Links

Live Demo: https://huggingface.co/spaces/aerika/QuizSmith
GitHub: github.com/arminerika/quizsmith

---