README.md

metadata

title: Quizify
emoji: 🧠
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

✦ Quizify — AI Quiz Generator

A Retrieval-Augmented Generation (RAG) powered quiz application that automatically generates quizzes from your documents using Google's Gemini AI. Upload any study material and the app produces contextually relevant questions, validates answers with semantic similarity, and provides AI-generated explanations — all through a sleek React + Vite frontend.

---

✨ Features

• Multi-format Ingestion — Upload PDF, DOCX, PPTX, TXT, or MD files; parsed, chunked, and stored in a FAISS vector index
• Dynamic Quiz Generation — Generates MCQ, True/False, or Short Answer questions directly from document content
• Anti-Repetition — Tracks previously asked questions to avoid duplicates within a session
• Smart Answer Validation — Exact match for MCQ/True-False; semantic cosine similarity for short answers
• AI Explanations — Wrong answers trigger a contextual explanation pulled from the document
• Modern React UI — Glassmorphism dark theme built with React + Vite, zero UI-library dependencies
• REST API — Clean FastAPI backend, fully decoupled from the frontend

---

🖥️ Tech Stack

Layer	Technology
Frontend	React 19, Vite, Vanilla CSS (glassmorphism)
Backend	FastAPI, Python 3.10+
AI / LLM	Google Gemini (gemini-embedding-001)
Vector Store	FAISS (local persistence)
PDF Parsing	Docling
Semantic Similarity	all-MiniLM-L6-v2 via sentence-transformers

---

🗂️ Project Structure

Quizify/
│
├── backend/
│   ├── core/
│   │   ├── cache.py               # In-memory quiz session cache
│   │   ├── config.py              # Vector DB path + chunking config
│   │   └── llm.py                 # Gemini LLM + embeddings
│   │
│   ├── faiss_index/               # Persisted FAISS vector store (auto-generated)
│   │
│   ├── feedback/
│   │   └── explainer.py           # LLM-based explanation generation
│   │
│   ├── models/
│   │   └── schemas.py             # Pydantic request/response schemas
│   │
│   ├── quiz/
│   │   ├── generator.py           # LLM-based quiz question generation
│   │   ├── semantic.py            # Sentence-transformer cosine similarity
│   │   └── validator.py           # Answer validation (exact + semantic)
│   │
│   ├── rag/
│   │   ├── parser.py              # Document → markdown → FAISS chunks
│   │   ├── retriever.py           # Random diverse context retrieval
│   │   └── vector_store.py        # FAISS load/save helpers
│   │
│   ├── utils/
│   │   └── text_utils.py          # Text normalization utilities
│   │
│   └── main.py                    # FastAPI app + route handlers
│
├── frontend/                      # React + Vite frontend
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   └── src/
│       ├── main.jsx
│       ├── App.jsx                # Main app (wizard state machine)
│       ├── App.css                # Component-level styles
│       ├── index.css              # Global tokens, resets, animations
│       ├── api.js                 # Fetch-based API client
│       └── components/
│           ├── DropZone.jsx       # Drag & drop file uploader
│           ├── StepHeader.jsx     # Animated step badge
│           ├── QuestionCard.jsx   # MCQ radio + text answer card
│           ├── ResultsView.jsx    # Score hero + per-question review
│           └── Alert.jsx          # Warning / error / success alerts
│
├── .gitignore
├── .env.example                   # Copy to backend/core/.env and add your API key
└── requirements.txt               # Backend Python dependencies

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• A Google AI API key from https://aistudio.google.com

---

1. Clone the repository

git clone https://github.com/hetsheta/Quizify.git
cd Quizify

2. Create and activate a Python virtual environment

python -m venv venv
# macOS / Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

3. Install backend dependencies

pip install -r requirements.txt

4. Set up your API key

Open the .env.example file at the root of the repo and add your Google AI API key:

GOOGLE_API_KEY=your-google-ai-api-key-here

Get your key at aistudio.google.com. It is already covered by .gitignore — never commit it.

5. Run the backend server

cd backend
uvicorn main:app --reload

The API will be available at http://localhost:8000.
Interactive API docs: http://localhost:8000/docs

6. Run the frontend

Open a new terminal:

cd frontend
npm install
npm run dev

The app will open at http://localhost:5173

---

🔌 API Endpoints

POST /parse-document

Upload a document to build the vector index.

Content-Type: multipart/form-data
Body: file=<your_file>

Response:

{ "status": "success" }

---

POST /generate-quiz

Generate a quiz from the uploaded document.

Request body:

{
  "topic": "full document",
  "num_questions": 5,
  "difficulty": "Medium",
  "question_type": "MCQ"
}

• question_type: "MCQ" | "True/False" | "Short Answer"
• difficulty: "Easy" | "Medium" | "Hard"

Response:

{
  "quiz_id": "uuid-string",
  "questions": [
    {
      "question": "What is supervised learning?",
      "options": ["A) ...", "B) ...", "C) ...", "D) ..."]
    }
  ]
}

---

POST /submit-quiz

Submit answers and receive scored results with explanations.

Request body:

{
  "quiz_id": "uuid-string",
  "answers": [
    { "question_index": 0, "user_answer": "A) ..." },
    { "question_index": 1, "user_answer": "True" }
  ]
}

Response:

{
  "score": 3,
  "total": 5,
  "results": [
    {
      "question": "...",
      "user_answer": "...",
      "correct_answer": "...",
      "correct": false,
      "similarity_score": 0.42,
      "explanation": "The correct answer is ... because ...",
      "concept": "..."
    }
  ]
}

---

⚙️ Configuration

Environment Variables (.env.example)

Variable	Description
GOOGLE_API_KEY	Your Gemini API key — loaded by core/llm.py via python-dotenv

App Settings (backend/core/config.py)

Variable	Default	Description
VECTOR_DB_PATH	faiss_index	Local path for FAISS persistence
CHUNK_SIZE	900	Characters per document chunk
CHUNK_OVERLAP	200	Overlap between adjacent chunks

---

🧠 How It Works

1. Parse — Document is converted to markdown via docling, split into overlapping chunks, embedded using gemini-embedding-001, and stored in a FAISS index.
2. Generate — On quiz request, diverse chunks are retrieved using randomised query sampling. Gemini generates questions strictly from that content.
3. Validate — MCQ/True-False answers use normalised letter matching. Short answers use all-MiniLM-L6-v2 cosine similarity with a 0.50 threshold.
4. Explain — Incorrect answers trigger an LLM explanation grounded in the document context (max 120 words, difficulty-appropriate).

---

📦 Key Dependencies

Backend

Package	Purpose
fastapi	REST API framework
langchain + langchain-google-genai	LLM orchestration
google-genai	Gemini LLM & embeddings
faiss-cpu	Vector similarity search
docling	Document → structured markdown parsing
sentence-transformers	Short-answer semantic validation
scikit-learn	Cosine similarity computation
python-dotenv	Loads API key from .env at runtime

Frontend

Package	Purpose
react + react-dom	UI framework
vite	Dev server & build tool

---

📝 License

MIT License. See LICENSE for details.