Initialize standalone Quiz_Generation service repo

.gitignore

@@ -1,85 +1,13 @@
-# compiled output
-/dist
-/node_modules
-/build
-
-# Logs
-logs
-*.log
-npm-debug.log*
-pnpm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# OS
-.DS_Store
-
-# Tests
-/coverage
-/.nyc_output
-
-# IDEs and editors
-/.idea
-.project
-.classpath
-.c9/
-*.launch
-.settings/
-*.sublime-workspace
-
-# IDE - VSCode
-.vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-
-
-# Aiven / cloud DB TLS (local only; never commit real certs)
-ca.pem
-
-.env
-.env.local
-.env.aiven
-.env.*.local
-.env.test.local
-.env.production.local
-# temp directory
-.temp
-.tmp
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-!.env.example
-
-# Python (AI microservices and bytecode)
-__pycache__/
-*.py[cod]
-*$py.class
 .venv/
-venv/
-ENV/
-ai-services/**/__pycache__/
-ai-services/**/.venv/
-ai-services/**/venv/
-ai-services/**/*.pyc
-# Local test images (not committed). README stays tracked so the folder exists in the repo.
-ai-services/attendance/dataset/*
-!ai-services/attendance/dataset/README.txt
-ai-services/attendance/Attendance/
-ai-services/attendance/temp_*
+__pycache__/
+*.pyc
+*.pyo
 
-# Quiz generator local runtime state (upload registry + stored quizzes)
-ai-services/quiz-generator/quizzes.json
-ai-services/quiz-generator/uploads.json
+# Runtime/local state
+uploads.json
+quizzes.json
+results/
 
-# Runtime uploads should never be versioned
-uploads/
+# OS/editor artifacts
+.DS_Store
+Thumbs.db

README.md

@@ -13,8 +13,10 @@ A FastAPI-based microservice that generates quizzes from uploaded
 documents using an AI model.
 
 The API accepts PDF, DOCX, or TXT files, extracts their text, and
-generates different types of questions such as: - Multiple Choice
-Questions (MCQ) - Fill in the Blank - Explanation Questions
+generates different types of questions such as:
+- Multiple Choice Questions (MCQ)
+- Fill in the Blank
+- Explanation Questions
 
 The questions are generated using the Groq LLM (Llama 3.3 70B) via
 LangChain.
@@ -40,21 +42,13 @@ INSTALLATION
 
 ---
 
-1.  Clone the repository
-
-git clone cd ai-exam-generator
-
-2.  Create a virtual environment
-
-python -m venv .venv
-
-3.  Activate the environment
-
-Windows (PowerShell) .venv
-
-4.  Install dependencies
-
-pip install -r requirements.txt
+1. Clone the repository
+2. Create a virtual environment
+   `python -m venv .venv`
+3. Activate the environment (Windows PowerShell)
+   `.\.venv\Scripts\Activate.ps1`
+4. Install dependencies
+   `pip install -r requirements.txt`
 
 ---
 
@@ -62,9 +56,9 @@ ENVIRONMENT VARIABLES
 
 ---
 
-Create a .env file in the project root:
+Create a `.env` file in the project root:
 
-MY_API_KEY=your_groq_api_key_here
+`MY_API_KEY=your_groq_api_key_here`
 
 This key is required to access the Groq LLM.
 
@@ -76,15 +70,15 @@ RUNNING THE API
 
 Start the server:
 
-uvicorn app.main:app –reload
+`uvicorn app.main:app --reload`
 
 The API will run at:
 
-http://127.0.0.1:8000
+`http://127.0.0.1:8000`
 
 Interactive API documentation:
 
-http://127.0.0.1:8000/docs
+`http://127.0.0.1:8000/docs`
 
 ---
 
@@ -92,40 +86,12 @@ API ENDPOINTS
 
 ---
 
-POST /api/v1/upload Upload a document (PDF, DOCX, TXT)
-
-Example response:
-
-{ uploadId: 1234-uuid, status: text_extracted,
-total_characters: 5000 }
-
----
-
-POST /api/v1/generate
-
-Form parameters: uploadId numQuestions questionType difficulty
-saveAsFiles
-
-Example response:
-
-{ quizId: uuid, status: completed, numQuestions: 5 }
-
----
-
-GET /api/v1/quiz/{quiz_id} Returns the generated quiz with questions and
-answer key.
-
----
-
-GET /api/v1/download/{filename} Download the generated quiz file.
-
----
-
-GET /api/v1/uploads List all uploaded documents.
-
----
-
-DELETE /api/v1/upload/{upload_id} Delete an uploaded document.
+- `POST /api/v1/upload` Upload a document (PDF, DOCX, TXT)
+- `POST /api/v1/generate` Generate questions from uploaded text
+- `GET /api/v1/quiz/{quiz_id}` Returns generated quiz with answer key
+- `GET /api/v1/download/{filename}` Download generated quiz file
+- `GET /api/v1/uploads` List uploaded documents
+- `DELETE /api/v1/upload/{upload_id}` Delete uploaded document
 
 ---
 
@@ -133,9 +99,9 @@ EXAMPLE WORKFLOW
 
 ---
 
-1.  Upload a file
-2.  Generate a quiz
-3.  Retrieve the quiz results
+1. Upload a file
+2. Generate a quiz
+3. Retrieve the quiz results
 
 ---
 
@@ -143,8 +109,8 @@ TECHNOLOGIES USED
 
 ---
 
-FastAPI LangChain Groq LLM (Llama 3.3 70B) Python pdfplumber python-docx
-FPDF
+FastAPI, LangChain, Groq LLM (Llama 3.3 70B), Python, pdfplumber,
+python-docx, FPDF
 
 ---
 

app/services/quiz_service.py

@@ -16,16 +16,21 @@ def format_standard_question(index: int, body: str) -> str:
         text = text[m.end() :].strip()
     return f"Question {index + 1}: {text}"
 
+
 llm = ChatGroq(
     api_key=MY_API_KEY,
     model="llama-3.3-70b-versatile",
-    temperature=0.0
+    # Non-zero temperature reduces repeated identical outputs
+    # when the same source file is generated multiple times.
+    temperature=1.1,
 )
 
 mcq_prompt = PromptTemplate(
-    input_variables=["context", "num_questions"],
+    input_variables=["context", "num_questions", "difficulty"],
     template="""
-Generate {num_questions} multiple-choice questions from the following text. 
+Generate {num_questions} multiple-choice questions from the following text.
+Target difficulty: {difficulty}.
+Vary the selected concepts and phrasing across questions, and avoid repeating near-identical question stems.
 List all questions first, then provide a complete answer key at the end.
 
 Text:
@@ -51,13 +56,15 @@ D) [Option D]
 Question 1: [The letter of the correct option]
 Question 2: [The letter of the correct option]
 ...and so on.
-"""
+""",
 )
 
 fill_blank_prompt = PromptTemplate(
-    input_variables=["context", "num_questions"],
+    input_variables=["context", "num_questions", "difficulty"],
     template="""
 Generate {num_questions} fill-in-the-blank questions from the following text.
+Target difficulty: {difficulty}.
+Vary the selected concepts and sentence structures, and avoid repeating near-identical stems.
 List all questions first, then provide a complete answer key at the end.
 
 Text:
@@ -73,13 +80,15 @@ Question 2: [Another sentence with a _____ blank]
 Question 1: [The word that fills the blank]
 Question 2: [The word that fills the blank]
 ...and so on.
-"""
+""",
 )
 
 explain_prompt = PromptTemplate(
-    input_variables=["context", "num_questions"],
+    input_variables=["context", "num_questions", "difficulty"],
     template="""
 Generate {num_questions} explanation questions from the following text. These should require a detailed answer.
+Target difficulty: {difficulty}.
+Vary concepts and wording, and avoid near-duplicate question stems.
 
 Text:
 {context}
@@ -95,7 +104,7 @@ Reference: [A relevant quote or fact from the text]
 
 …continue until you have {num_questions} "## Explanation Question" blocks.
 Each question line must start with "Question N:" where N matches the block order (1, 2, 3, …).
-"""
+""",
 )
 
 mcq_chain = mcq_prompt | llm | StrOutputParser()
@@ -103,27 +112,35 @@ fill_blank_chain = fill_blank_prompt | llm | StrOutputParser()
 explain_chain = explain_prompt | llm | StrOutputParser()
 
 
-def generate_quiz_from_text(text: str, num_questions: int, question_type: str, difficulty: str):
+def generate_quiz_from_text(
+    text: str, num_questions: int, question_type: str, difficulty: str
+):
     final_questions = []
     answer_key = []
     raw_ai_output = ""
 
     if question_type == "MCQ":
-        raw_ai_output = mcq_chain.invoke({"context": text, "num_questions": num_questions})
+        raw_ai_output = mcq_chain.invoke(
+            {
+                "context": text,
+                "num_questions": num_questions,
+                "difficulty": difficulty,
+            }
+        )
         if "--- ANSWER KEY ---" not in raw_ai_output:
             raise ValueError("AI did not provide a separate answer key.")
 
         questions_block, answers_block = raw_ai_output.split("--- ANSWER KEY ---")
 
         answers_map = {}
-        for line in answers_block.strip().split('\n'):
+        for line in answers_block.strip().split("\n"):
             if ":" in line:
                 q_id, answer = line.split(":", 1)
                 answers_map[q_id.strip()] = answer.strip()
 
         question_chunks = questions_block.strip().split("Question")[1:]
         for i, chunk in enumerate(question_chunks):
-            lines = chunk.strip().split('\n')
+            lines = chunk.strip().split("\n")
             stem = (
                 lines[0].split(":", 1)[1].strip()
                 if lines and ":" in lines[0]
@@ -138,26 +155,36 @@ def generate_quiz_from_text(text: str, num_questions: int, question_type: str, d
 
             q_id = f"Question {i+1}"
             if question_text and options and q_id in answers_map:
-                final_questions.append({
-                    "type": "MCQ",
-                    "difficulty": difficulty,
-                    "question": question_text,
-                    "options": options
-                })
-                answer_key.append({
-                    "questionId": q_id,
-                    "correctAnswer": answers_map[q_id]
-                })
+                final_questions.append(
+                    {
+                        "type": "MCQ",
+                        "difficulty": difficulty,
+                        "question": question_text,
+                        "options": options,
+                    }
+                )
+                answer_key.append(
+                    {
+                        "questionId": q_id,
+                        "correctAnswer": answers_map[q_id],
+                    }
+                )
 
     elif question_type == "FillBlank":
-        raw_ai_output = fill_blank_chain.invoke({"context": text, "num_questions": num_questions})
+        raw_ai_output = fill_blank_chain.invoke(
+            {
+                "context": text,
+                "num_questions": num_questions,
+                "difficulty": difficulty,
+            }
+        )
         if "--- ANSWER KEY ---" not in raw_ai_output:
             raise ValueError("AI did not provide a separate answer key.")
 
         questions_block, answers_block = raw_ai_output.split("--- ANSWER KEY ---")
 
         answers_map = {}
-        for line in answers_block.strip().split('\n'):
+        for line in answers_block.strip().split("\n"):
             if ":" in line:
                 q_id, answer = line.split(":", 1)
                 answers_map[q_id.strip()] = answer.strip()
@@ -167,27 +194,41 @@ def generate_quiz_from_text(text: str, num_questions: int, question_type: str, d
             # Chunk may start with " 1: ..." after splitting on "Question"; strip that
             # number so we do not produce "Question 3: 3: ...".
             first_line = chunk.strip().split("\n", 1)[0]
-            stem = first_line.split(":", 1)[1].strip() if ":" in first_line else first_line.strip()
+            stem = (
+                first_line.split(":", 1)[1].strip()
+                if ":" in first_line
+                else first_line.strip()
+            )
             rest = chunk.strip().split("\n", 1)
             body = stem + ("\n" + rest[1] if len(rest) > 1 else "")
             question_text = format_standard_question(i, body)
 
             q_id = f"Question {i+1}"
             if question_text and q_id in answers_map:
-                final_questions.append({
-                    "type": "FillBlank",
-                    "difficulty": difficulty,
-                    "question": question_text
-                })
-                answer_key.append({
-                    "questionId": q_id,
-                    "answer": answers_map[q_id]
-                })
+                final_questions.append(
+                    {
+                        "type": "FillBlank",
+                        "difficulty": difficulty,
+                        "question": question_text,
+                    }
+                )
+                answer_key.append(
+                    {
+                        "questionId": q_id,
+                        "answer": answers_map[q_id],
+                    }
+                )
 
     else:
-        raw_ai_output = explain_chain.invoke({"context": text, "num_questions": num_questions})
+        raw_ai_output = explain_chain.invoke(
+            {
+                "context": text,
+                "num_questions": num_questions,
+                "difficulty": difficulty,
+            }
+        )
         for i, item in enumerate(raw_ai_output.split("## Explanation Question")[1:]):
-            lines = item.strip().split('\n')
+            lines = item.strip().split("\n")
             q_body = ""
             q_ref = ""
             for line in lines:
@@ -200,14 +241,19 @@ def generate_quiz_from_text(text: str, num_questions: int, question_type: str, d
             if q_body:
                 q_id = f"Question {i+1}"
                 question_text = format_standard_question(i, q_body)
-                final_questions.append({
-                    "type": "Explain",
-                    "difficulty": difficulty,
-                    "question": question_text
-                })
-                answer_key.append({
-                    "questionId": q_id,
-                    "reference": q_ref
-                })
-
-    return final_questions, answer_key, raw_ai_output
+                final_questions.append(
+                    {
+                        "type": "Explain",
+                        "difficulty": difficulty,
+                        "question": question_text,
+                    }
+                )
+                answer_key.append(
+                    {
+                        "questionId": q_id,
+                        "reference": q_ref,
+                    }
+                )
+
+    return final_questions, answer_key, raw_ai_output
+