AI Quizzer API

This project is a comprehensive, AI-powered microservice for a quiz application, built with Django and the Django REST Framework. It features a robust set of functionalities including dynamic quiz generation, adaptive difficulty, asynchronous email notifications, performance caching, and a filterable leaderboard. The entire application is containerized with Docker for seamless setup and deployment.

Features

Core Functionalities (Mandatory)

• Mock JWT Authentication: A secure, token-based authentication system using djangorestframework-simplejwt. It accepts any username/password for mock login and issues a JWT for authenticating subsequent API requests.
• AI-Powered Quiz Generation: Dynamically generates new quizzes based on subject, grade, and difficulty using the Groq AI API.
• AI-Assisted Evaluation: Submissions are scored locally for accuracy, and the AI provides personalized, actionable suggestions for improvement based on the user's incorrect answers.
• Adaptive Difficulty: The system analyzes a user's historical performance (average score) in a specific subject and grade to intelligently adjust the difficulty profile for newly generated quizzes.
• AI Hint Generation: Provides on-demand, contextual hints for any quiz question.
• Comprehensive Quiz History: Users can retrieve their entire submission history, with powerful filtering options for subject, grade, score, and date ranges.

Bonus Functionalities

• Asynchronous Email Notifications: Utilizes Celery and Redis to send quiz results to users via email as a background task. This ensures the API remains fast and responsive, as it doesn't wait for the email to be sent.
• Performance Caching Layer: Implements a Redis caching layer for expensive, read-heavy API endpoints like the leaderboard and quiz details. This dramatically reduces database load and improves API latency.
• Filterable Leaderboard API: A dedicated endpoint to display the top 10 user scores. The leaderboard is dynamic and can be filtered by subject or grade, showing each user's single best performance within the filtered context.

AI Integration Details

This project leverages the Groq AI API for its speed and power across several key features:

• AI Provider: Groq

• Model Used: moonshotai/kimi-k2-instruct-0905 (or as configured in .env)

• AI-Powered Features:

  1. Quiz Generation: Creates questions, options, and correct answers from scratch based on user-provided criteria.
  2. Adaptive Difficulty: The AI is instructed with a specific difficulty profile (e.g., 70% EASY, 30% MEDIUM) that is calculated based on the user's past performance.
  3. Result Suggestions: Analyzes a user's incorrect answers and generates personalized tips for improvement.
  4. Hint Generation: Provides a helpful hint for a specific question without giving away the answer.
  5. Email Content: Generates a warm, personalized, and encouraging email body to deliver the quiz results.

Technology Stack

• Backend: Django, Django REST Framework
• Database: PostgreSQL
• Asynchronous Tasks: Celery
• Message Broker & Caching: Redis
• Containerization: Docker, Docker Compose
• API Documentation: drf-spectacular (for Swagger UI)

API Documentation

The API is self-documenting using Swagger UI. Once the application is running, you can access the interactive documentation in your browser.

• Swagger UI URL: http://localhost:8000/api/schema/swagger-ui/

Additionally, a Postman Collection (AI Quizzer.postman_collection.json) is included in the final submission zip file. It contains pre-configured requests for all endpoints, allowing for immediate testing.

Local Setup and Installation

The entire application is containerized, so all you need is Docker to run it.

Prerequisites

• Docker
• Docker Compose

Instructions

1. Create the Environment File

   In the project's root directory, create a file named .env. This file stores all necessary configurations and secrets. Copy the template below and replace the placeholder values.

   # .env file
   
   # Django Settings
   SECRET_KEY=your-super-secret-django-key
   DEBUG=True
   ALLOWED_HOSTS=localhost,127.0.0.1
   
   # Database URL (Docker networking uses the service name 'db' as the host)
   DATABASE_URL='postgres://postgres:your_db_password@db:5432/ai_quizzer_db'
   
   # Redis URL (Docker networking uses the service name 'redis' as the host)
   # Database /0 is for Celery, /1 is for Caching
   CELERY_BROKER_URL='redis://redis:6379/0'
   CACHE_URL='redis://redis:6379/1'
   
   # Groq AI API Key and Model
   GROQ_API_KEY='your-groq-api-key'
   GROQ_MODEL='llama-3.1-70b-versatile'
   
   # Gmail Settings for Email Notifications
   EMAIL_HOST_USER="your-email@gmail.com"
   EMAIL_HOST_PASSWORD="your-16-digit-gmail-app-password"

   Note: You must also update the POSTGRES_PASSWORD in the docker-compose.yml file to match the password you set in DATABASE_URL.

2. Run the Application

   Open a terminal in the project's root directory and run the following command. This will build the Docker images, create the database schema via the entrypoint.sh script, and start all services.

   docker-compose up --build

The API will now be running and available at http://localhost:8000. The entrypoint.sh script automatically handles database migrations on startup.

Known Issues

• When running Celery locally on a Windows machine (without using Docker), the default concurrency pool is incompatible. The fix is to use the -P gevent flag when starting the worker (celery -A quizzer_api worker -l info -P gevent). This issue is automatically handled by the configuration in the provided docker-compose.yml file.