QuEstAI - AI-Powered Exam Question Generator

QuEstAI is an intelligent exam question generator designed for the Indian education system (CBSE-style). It uses advanced NLP techniques to analyze educational content and generate Bloom's taxonomy-aligned questions with source context tracking.

🌐 Live Demo: https://quest-ai-green.vercel.app/login

🌟 Key Features

AI-Powered Question Generation: Uses spaCy and T5 transformer models
Multiple Question Types: MCQ, Short Answer, and True/False questions
Bloom's Taxonomy Alignment: Questions categorized by cognitive levels
Source Context Tracking: "Why is this wrong?" feature shows original text
Printable Exports: Generate Word documents for classroom use
User Authentication: JWT-based secure authentication
Data Isolation: Users only see their own quizzes

🛠️ Tech Stack

Backend

FastAPI (Python 3.11) - Modern, fast web framework
SQLite with SQLAlchemy ORM - Database management
spaCy (en_core_web_sm) - Natural language processing
HuggingFace Transformers (T5-small) - Question generation
PyMuPDF - PDF text extraction with page tracking
python-docx - Word document generation
JWT with Passlib - Authentication and security

Frontend

React 18 with Vite - Modern React development
Tailwind CSS - Utility-first styling
React Router - Client-side routing
Axios - HTTP client
Lucide React - Beautiful icons
Recharts - Data visualization
React Hot Toast - Notifications

🚀 Quick Start

Prerequisites

Python 3.11+
Node.js 18+
npm or yarn

Backend Setup

Navigate to backend directory
```
cd backend
```

Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```
Download spaCy model
```
python -m spacy download en_core_web_sm
```

Set up environment variables

# Update .env file with your settings
SECRET_KEY=your-super-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL=sqlite:///./questai.db

Run the backend server
```
python run.py
```
The API will be available at http://localhost:8000

Frontend Setup

Navigate to frontend directory
```
cd frontend
```
Install dependencies
```
npm install
```
Start development server
```
npm run dev
```
The frontend will be available at http://localhost:3000

📖 Usage Guide

1. User Registration & Login

Create an account with username, email, and password
Login to access the dashboard

2. Generate Quiz

Click "Generate New Quiz" from dashboard
Upload a PDF file (educational content)
Configure question types and counts:
- Multiple Choice Questions (4 options each)
- Short Answer Questions (open-ended)
- True/False Questions (binary choice)
Click "Generate Quiz" and wait for AI processing

3. Take Quiz

Navigate through questions using the sidebar
Answer questions in any order
Submit when complete

4. View Results

See overall score and performance metrics
View Bloom's taxonomy breakdown
For incorrect answers, click "Why is this wrong?" to see source context
Export results or retake quiz

5. Export for Teachers

Download Word documents with:
- Formatted exam paper with answer spaces
- Separate answer key with source references
- Professional layout ready for printing

🏗️ Architecture

Database Models

User: Authentication and user management
Quiz: Quiz metadata and scoring
Question: Individual questions with source tracking

NLP Pipeline

Text Extraction: PyMuPDF extracts text with page numbers
Content Analysis: spaCy processes text for entities and complexity
Question Generation:
- Rule-based approach for MCQ and True/False
- T5 transformer for Short Answer questions
Source Mapping: Track which text generated each question

Authentication Flow

JWT tokens for stateless authentication
Password hashing with bcrypt
Protected routes with user isolation

🔧 Configuration

Question Generation Settings

config = {
    "mcq_count": 5,
    "short_answer_count": 3,
    "true_false_count": 2,
    "difficulty_distribution": {"Easy": 30, "Medium": 50, "Hard": 20},
    "bloom_levels": ["Remember", "Understand", "Apply", "Analyze"]
}

Environment Variables

SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL=sqlite:///./questai.db

🧪 API Endpoints

Authentication

POST /auth/register - User registration
POST /auth/login - User login

Quiz Management

POST /quiz/generate - Generate quiz from PDF
GET /quiz/ - Get user's quizzes
GET /quiz/{id} - Get specific quiz
POST /quiz/{id}/submit - Submit quiz answers
GET /quiz/{id}/export/docx - Export as Word document

🎯 Educational Features

Bloom's Taxonomy Integration

Remember: Factual recall questions
Understand: Comprehension and explanation
Apply: Using knowledge in new situations
Analyze: Breaking down complex information

CBSE-Style Formatting

Professional exam paper layout
Proper marking scheme
Answer key with source references
Space for student details

🔒 Security Features

JWT-based authentication
Password hashing with bcrypt
User data isolation
Input validation and sanitization
CORS protection

🚀 Deployment

Production Setup

Update environment variables for production
Use PostgreSQL instead of SQLite (recommended for cloud deployments)
Set up reverse proxy (nginx) or use a managed load balancer
Enable HTTPS
Configure proper CORS origins

Docker Deployment (Recommended)

This repository is pre-configured with Docker for both backend and frontend and a docker-compose.yml to run everything together.

1. Create backend environment file

In the backend directory, create a .env file:

SECRET_KEY=your-production-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL=sqlite:///./questai.db  # Or your PostgreSQL URL in production

# Comma-separated list of allowed frontend URLs (for CORS)
FRONTEND_ORIGINS=http://localhost,http://localhost:80,https://your-frontend-domain.com

2. Build and run with Docker Compose

From the project root:

docker-compose build
docker-compose up -d

Backend API will be available at http://localhost:8000
Frontend UI will be available at http://localhost

You can now point your browser to the frontend URL and it will talk to the backend container.

3. Deploying to a VPS or cloud host

On a server (Ubuntu, etc.):

Install Docker and Docker Compose
Clone this repository
Set your production .env in backend/.env
Run:

docker-compose build
docker-compose up -d

Then configure your DNS to point to the server and optionally terminate HTTPS using a reverse proxy (e.g., nginx + certbot or a cloud load balancer).

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

Create an issue on GitHub
Check the documentation
Review the API endpoints

🔮 Future Enhancements

Support for more file formats (DOCX, TXT)
Advanced question types (Fill-in-the-blanks, Matching)
Collaborative quiz creation
Analytics dashboard for teachers
Integration with Learning Management Systems
Multi-language support
Advanced AI models (GPT-4, Claude)

QuEstAI - Transforming education through intelligent question generation! 🎓✨

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
frontend		frontend
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation