This project is an AI-powered platform designed to enhance the teaching and learning experience for both teachers and students. It combines quiz generation, individual and group feedback analysis for both teacher and students , correction automation, embeddings for knowledge retrieval, and chatbot tutoring into one ecosystem.
- Automatically generate quizzes from PDFs with AI.
- Track student progress & performance trends.
- Identify common mistakes and topics to re-explain.
- Get individual, student-group, and class-wide feedback.
- Take adaptive AI-generated quizzes.
- Track personal progress over time.
- Compete with classmates on a leaderboard.
- Use an AI-powered chatbot for hints, summaries, and personalized learning support.
src
├── .env.example # Example environment file for setup
├── .gitignore # Ignore unnecessary files in Git
├── main.py # FastAPI entry point (runs the API server)
├── Requirements.txt # Python dependencies
├── __init__.py
│
├── controller # Core business logic
│ ├── ChatbotController.py # Handles chatbot interactions
│ ├── ContextRetriever.py # Retrieves PDF context from vector DB
│ ├── GroupFeedback.py # Logic for generating group-level feedback
│ ├── PDFReader.py # Extracts and processes text from PDFs
│ ├── QuestionCorrection.py # Auto-grades and corrects answers
│ ├── QuestionGenerator.py # Creates quiz questions using LLM
│ ├── QuestionSelector.py # Selects and balances question types
│ ├── QuestionSpliter.py # Splits text into chunks for processing
│ ├── SummaryFeedbackStd.py # Generates student-level feedback
│ ├── SummaryFeedbackTeacher.py # Generates teacher-level feedback
│ └── __init__.py
│
├── data # Sample documents for testing
│
├── helpers
│ ├── config.py # Application configuration (env, paths, constants)
│ └── __init__.py
│
├── models # Data models & schemas
│ ├── feedback_std.py # Model for student feedback
│ ├── feedback_teacher.py # Model for teacher feedback
│ ├── quiz.py # Model for quiz and questions
│ ├── __init__.py
│ │
│ ├── db_schemes # Database-related schemas
│ │ ├── RetrieveDocument.py # Schema for document retrieval from DB
│ │ └── __init__.py
│ │
│ └── enums # Enumerations
│ ├── QuestionTypeEnum.py # Enum for question types (MCQ, TF, Written)
│ └── __init__.py
│
├── notebooks # Jupyter notebooks for testing & experiments
│ ├── Group Feadback.ipynb
│ ├── Prefinal_Create_Quizes.ipynb
│ └── Writen correction.ipynb
│
├── routes # FastAPI routes (endpoints)
│ ├── chatbot.py # Chatbot API
│ ├── embedding.py # Save PDFs into vector DB
│ ├── feedback_std_api.py # Student feedback API
│ ├── feedback_teacher_api.py # Teacher feedback API
│ ├── generate_quiz.py # Quiz generation API
│ ├── group_feedback.py # Group feedback API
│ ├── written_correction.py # Auto-grading API
│ ├── __init__.py
│ │
│ └── schema # Pydantic schemas for API validation
│ ├── Chatbot.py
│ ├── CorrectionQuiz.py
│ ├── Embedding.py
│ ├── FeedbackStd.py
│ ├── FeedbackTeacher.py
│ ├── GroupFeedback.py
│ ├── Quiz.py
│ └── __init__.py
│
├── stores # Services layer (connects controller & LLM/vector DB)
│ ├── __init__.py
│ │
│ ├── llm # Large Language Model service handlers
│ │ ├── correction_service.py # Service for auto-correction logic
│ │ ├── group_feedback_service.py # Service for group feedback
│ │ ├── quiz_service.py # Service for quiz generation
│ │ ├── __init__.py
│ │ │
│ │ └── templates # Prompt templates for LLM
│ │ ├── template_parser.py # Loads and parses prompt templates
│ │ ├── __init__.py
│ │ │
│ │ └── locales # Multi-language prompts
│ │ ├── __init__.py
│ │ ├── ar
│ │ │ ├── prompt.py # Arabic prompts
│ │ │ └── __init__.py
│ │ └── en
│ │ ├── prompt.py # English prompts
│ │ └── __init__.py
│ │
│ └── Vectordb # Vector DB (Qdrant) integration
│ ├── VectorDBInterface.py # Abstract interface for vector DB
│ ├── __init__.py
│ │
│ └── providers
│ ├── QdrantDBProvider.py # Qdrant implementation of vector DB
│ └── __init__.py
-
Clone the repo:
git clone https://github.com/khaledzakarya/Create-Quiz-App.git cd Create-Quiz-App -
Create a virtual environment:
python -m venv venv source venv/bin/activate # Linux / Mac venv\Scripts\activate # Windows
-
Setup the environment variables
$ cp .env.example .env
-
Install dependencies:
pip install -r Requirements.txt
-
Run FastAPI server:
uvicorn main:app --reload
POST /ai/generate_quiz/Generates a quiz from a PDF document. Supports multi-language prompts (English/Arabic), different question types (MCQ, True/False, Written), and customizable ratios. You can generate quizzes from the entire document or focus on specific pages.
{
"pdf_path": "uploads/sample.pdf",
"level": "medium",
"language": "en",
"n_focus": 10,
"focus_pages": [1, 2],
"n_remain": 5,
"remain_pages": [3, 4],
"f_mcq_ratio": 0.6,
"f_tf_ratio": 0.2,
"f_written_ratio": 0.2,
"r_mcq_ratio": 0.8,
"r_tf_ratio": 0.1,
"r_written_ratio": 0.1
}[
{
"type": "MCQ",
"question": "What is ...?",
"options": ["A", "B", "C", "D"],
"answer": "B"
},
{
"type": "TrueFalse",
"question": "X is correct?",
"options": [],
"answer": "True"
},
{
"type": "Written",
"question": "Explain Y?",
"options": [],
"answer": "Y is ..."
}
]POST /ai/feedback_studentAnalyzes a single student’s quiz attempt, comparing their answers with correct answers. Generates personalized feedback including strengths, weaknesses, and improvement tips.
[
{
"attempt_id": "ATTEMPT123",
"answers": [
{
"answer_id": 1,
"question": "What is the capital of ...?",
"student_answer": "Cairo",
"correct_answer": "Paris",
"type": "MCQ",
"options": ["Cairo", "Paris", "London", "Rome"],
"score": 0,
"q_weight": 1
},
{
"answer_id": 2,
"question": "X is correct?",
"student_answer": "True",
"correct_answer": "False",
"type": "TrueFalse",
"options": [],
"score": 0,
"q_weight": 1
}
]
}
]
[
{
"attempt_id": "ATTEMPT123",
"results": [
{
"answer_id": 1,
"feedback": "The correct answer is Paris. Review European capitals."
},
{
"answer_id": 2,
"feedback": "False is correct. Remember the rule about X."
}
],
"summary": "You need to review geography and rules about X.",
"good_points": ["Good effort on written explanations"],
"weak_points": ["Confusion in MCQs", "Misunderstood True/False logic"]
}
]
POST /ai/feedback_teacherProvides progress insights for a student across multiple quiz attempts, showing score trends, improvement/decline, and teaching recommendations.
{
"student_id": "STUDENT42",
"history": [
{
"attempt_id": "ATTEMPT1",
"score": 6,
"max_score": 10,
"strong_points": ["Good recall of facts"],
"weak_points": ["Weak in reasoning"]
},
{
"attempt_id": "ATTEMPT2",
"score": 8,
"max_score": 10,
"strong_points": ["Improved reasoning"],
"weak_points": ["Still struggles with details"]
}
]
}
{
"student_id": "STUDENT42",
"teacher_id": "TEACHER9",
"progress": "Improving",
"summary_feedback": "The student shows consistent improvement, especially in reasoning.",
"strong_points": ["Reasoning skills", "Retention of knowledge"],
"weak_points": ["Attention to detail"],
"improved_points": ["Reasoning compared to first attempt"],
"declined_points": [],
"score_trend": [6, 8],
"risk_level": "Low",
"teaching_recommendation": "Encourage more detailed analysis in answers."
}
POST /ai/group_feedback/Generates a class-level summary by analyzing quiz results across students, identifying difficult questions, strengths, weaknesses, and overall performance trends.
{
"most_wrong_questions": ["Define Y?", "What is Z?"],
"avg_score_this_quiz": 70,
"avg_score_prev": [65, 68],
"success_rate_this_quiz": 75,
"success_rate_prev": [60, 72],
"individual_feedback": [
{
"student_id": "STUDENT1",
"summary": "Improved in definitions, weak in problem-solving.",
"strengths": ["Definitions"],
"weaknesses": ["Problem-solving"]
},
{
"student_id": "STUDENT2",
"summary": "Stable performance, needs focus on details.",
"strengths": ["Reasoning"],
"weaknesses": ["Details"]
}
]
}{
"group_summary": "The group shows overall improvement compared to the previous quiz.",
"common_strengths": ["Reasoning", "Definitions"],
"common_weaknesses": ["Attention to detail", "Problem-solving"],
"wrong_question_topics": ["Topic Y", "Topic Z"],
"comparison": "Average score increased by 5 points compared to last quiz.",
"recommendations": [
"Focus more on problem-solving activities.",
"Provide exercises targeting details and accuracy."
]
}POST /ai/correct_quiz/Automatically grades student answers against the correct ones for any quiz, returning marks and corrections.
{
"max_grade": 3,
"questions": [
{
"question_id": "q1",
"student_id": "s1",
"group_id": "g1",
"exam_id": "e1",
"question_text": "Explain AI?",
"correct_answer": "AI is ...",
"student_answer": "Artificial Intelligence is ..."
}
]
}
[
{
"question_id": "q1",
"student_id": "s1",
"group_id": "g1",
"exam_id": "e1",
"score": 3
}
]POST /ai/embedding/upload-documentSaves a PDF into the vector database (Qdrant) by generating embeddings. This allows later context-aware quiz generation and chatbot responses.
{
"group_id": "g1",
"pdf_path": "uploads/sample.pdf"
}{
"message": "File uploaded and processed successfully",
"group_id": "g1"
}
POST /ai/chatbot/askA chatbot that answers student questions using stored PDF embeddings. Supports personalized learning, lesson summaries, and concept explanations.
{
"group_id": "g1",
"student_id": "s1",
"session_id": "sess123",
"user_query": "Explain neural networks"
}{
"response": {
"answer": "A neural network is ...",
"history": [
{
"question": "Explain neural networks",
"answer": "A neural network is ..."
}
]
},
"session_id": "sess123"
}
- Python
- FastAPI
- Qdrant DB
- Ollama
- Gemini API
- langchain