Add gradeQuiz Function

Signed-off-by: Tal Jacob <taljacob2@gmail.com>

Author: taljacob2

nextstep-backend/src/controllers/quizzes_controller.ts

@@ -30,4 +30,20 @@ const getGeneratedQuizBySubject = async (req: Request, res: Response): Promise<v
     }
 };
 
-export default { getQuizzesByTags, getGeneratedQuizBySubject };
+const getGradedQuizByAnsweredQuiz = async (req: Request, res: Response): Promise<void> => {
+    try {
+        const answeredQuiz = req.body;
+
+        if (!answeredQuiz) {
+            res.status(400).json({ error: 'Missing required fields' });
+            return;
+        }
+
+        const gradedQuiz = await companiesService.gradeQuiz(answeredQuiz);
+        res.json(gradedQuiz);
+    } catch (err) {
+        handleError(err, res);
+    }
+};
+
+export default { getQuizzesByTags, getGeneratedQuizBySubject, getGradedQuizByAnsweredQuiz };

nextstep-backend/src/openapi/swagger.yaml

@@ -1164,14 +1164,50 @@ paths:
               properties:
                 subject:
                   type: string
-                  description: The subject of the quiz to be generated
+                  description: The subject of the quiz to be generated (e.g., "Java Spring Boot Microservices")
+                  example: "Java Spring Boot Microservices"
       responses:
         '200':
           description: A generated quiz custom-tailored for the targeted subject.
           content:
             application/json:
               schema:
-                type: object # TODO:
+                $ref: '#/components/schemas/GeneratedQuiz'
+        '400':
+          description: Bad request - Missing required fields
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    description: Error message indicating missing fields
+        '401':
+          description: Unauthorized
+        '500':
+          description: Internal server error
+
+  /quiz/grade:
+    post:
+      tags:
+        - Quizzes
+      summary: Grade a quiz answered by the user.
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnsweredQuiz'           
+      responses:
+        '200':
+          description: A graded quiz with tips.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GradedQuiz'
         '400':
           description: Bad request - Missing required fields
           content:
@@ -1413,6 +1449,207 @@ components:
           format: uri
           example: "http://www.forum.com/f/..."
 
+    GeneratedQuiz:
+      type: object
+      required:
+        - _id
+        - title
+        - tags
+        - content
+        - job_role
+        - company_name_en
+        - company_name_he
+        - process_details
+        - question_list
+        - answer_list
+        - keywords
+        - interviewer_mindset
+      properties:
+        _id:
+          type: string
+          description: Unique identifier for the generated quiz (e.g., "generated_[TIMESTAMP]").
+          example: "generated_1701234567890"
+        title:
+          type: string
+          description: A concise and relevant title for the generated quiz.
+          example: "ראיון לתפקיד מפתח Java Fullstack בחברת טכנולוגיה מובילה"
+        tags:
+          type: array
+          description: Highly relevant technical and role-based tags.
+          items:
+            type: string
+          example: ["Java", "Spring Boot", "Microservices", "Developer", "ראיון"]
+        content:
+          type: string
+          description: A comprehensive narrative combining the interview process and specific questions.
+          example: "תהליך ראיון למפתח Java Fullstack בחברת טכנולוגיה גדולה. הראיון כלל מספר שלבים: ראיון טלפוני קצר... (full content of the generated quiz)"
+        job_role:
+          type: string
+          description: The inferred job role for the quiz.
+          example: "מפתח Java Fullstack"
+        company_name_en:
+          type: string
+          description: English name of the company for the quiz.
+          example: "Leading Tech Company"
+        company_name_he:
+          type: string
+          description: Hebrew name of the company for the quiz.
+          example: "חברת טכנולוגיה מובילה"
+        process_details:
+          type: string
+          description: A concise summary of a typical interview process for this role/company type.
+          example: "ראיון טלפוני קצר לבדיקת התאמה כללית וציפיות שכר. משימת בית קצרה..."
+        question_list:
+          type: array
+          description: A parsed list of individual interview questions.
+          items:
+            type: string
+          example: ["איך היית מתכנן מערכת מיקרו-שירותים?", "הסבר את הקשר בין Spring Boot ל-Spring Framework."]
+        answer_list:
+          type: array
+          description: A corresponding list of ideal or reference answers for each question.
+          items:
+            type: string
+          example: ["בתכנון מערכת מיקרו-שירותים גדולה, הייתי מתחיל בהגדרת גבולות הקונטקסט...", "Spring Boot הוא פרויקט מעל Spring Framework שמטרתו לפשט את תהליך הפיתוח..."]
+        keywords:
+          type: array
+          description: Additional relevant technical or conceptual keywords for preparation.
+          items:
+            type: string
+          example: ["REST API", "Scalability", "Design Patterns", "Concurrency"]
+        interviewer_mindset:
+          type: string
+          description: A description of the soft skills, characteristics, and professional attributes an interviewer looks for.
+          example: "מחפשים מועמד עם סקרנות טכנולוגית גבוהה, יכולת פתרון בעיות יצירתית, תקשורת ברורה ותמציתית, וגישה פרואקטיבית לשיתוף פעולה בצוות."
+
+    AnsweredQuiz:
+      type: object
+      required:
+        - _id
+        - title
+        - tags
+        - content
+        - job_role
+        - company_name_en
+        - company_name_he
+        - process_details
+        - question_list
+        - answer_list
+        - keywords
+        - interviewer_mindset
+      properties:
+        _id:
+          type: string
+          description: Unique identifier for the generated quiz (e.g., "generated_[TIMESTAMP]").
+          example: "generated_1701234567890"
+        title:
+          type: string
+          description: A concise and relevant title for the generated quiz.
+          example: "ראיון לתפקיד מפתח Java Fullstack בחברת טכנולוגיה מובילה"
+        tags:
+          type: array
+          description: Highly relevant technical and role-based tags.
+          items:
+            type: string
+          example: ["Java", "Spring Boot", "Microservices", "Developer", "ראיון"]
+        content:
+          type: string
+          description: A comprehensive narrative combining the interview process and specific questions.
+          example: "תהליך ראיון למפתח Java Fullstack בחברת טכנולוגיה גדולה. הראיון כלל מספר שלבים: ראיון טלפוני קצר... (full content of the generated quiz)"
+        job_role:
+          type: string
+          description: The inferred job role for the quiz.
+          example: "מפתח Java Fullstack"
+        company_name_en:
+          type: string
+          description: English name of the company for the quiz.
+          example: "Leading Tech Company"
+        company_name_he:
+          type: string
+          description: Hebrew name of the company for the quiz.
+          example: "חברת טכנולוגיה מובילה"
+        process_details:
+          type: string
+          description: A concise summary of a typical interview process for this role/company type.
+          example: "ראיון טלפוני קצר לבדיקת התאמה כללית וציפיות שכר. משימת בית קצרה..."
+        question_list:
+          type: array
+          description: A parsed list of individual interview questions.
+          items:
+            type: string
+          example: ["איך היית מתכנן מערכת מיקרו-שירותים?", "הסבר את הקשר בין Spring Boot ל-Spring Framework."]
+        answer_list:
+          type: array
+          description: A corresponding list of ideal or reference answers for each question.
+          items:
+            type: string
+          example: ["בתכנון מערכת מיקרו-שירותים גדולה, הייתי מתחיל בהגדרת גבולות הקונטקסט...", "Spring Boot הוא פרויקט מעל Spring Framework שמטרתו לפשט את תהליך הפיתוח..."]
+        user_answer_list:
+          type: array
+          description: A corresponding list of user answers for each question.
+          items:
+            type: string
+          example: ["בתכנון מערכת מיקרו-שירותים גדולה, הייתי מתחיל בהגדרת גבולות הקונטקסט...", "Spring Boot הוא פרויקט מעל Spring Framework שמטרתו לפשט את תהליך הפיתוח..."]
+        keywords:
+          type: array
+          description: Additional relevant technical or conceptual keywords for preparation.
+          items:
+            type: string
+          example: ["REST API", "Scalability", "Design Patterns", "Concurrency"]
+        interviewer_mindset:
+          type: string
+          description: A description of the soft skills, characteristics, and professional attributes an interviewer looks for.
+          example: "מחפשים מועמד עם סקרנות טכנולוגית גבוהה, יכולת פתרון בעיות יצירתית, תקשורת ברורה ותמציתית, וגישה פרואקטיבית לשיתוף פעולה בצוות."
+
+    GradedQuiz:
+      type: object
+      required:
+        - graded_answers
+        - final_quiz_grade
+        - final_summary_tip
+      properties:
+        graded_answers:
+          type: array
+          description: A list of individual questions with the user's answer, grade, and a tip for improvement.
+          items:
+            type: object
+            required:
+              - question
+              - user_answer
+              - grade
+              - tip
+            properties:
+              question:
+                type: string
+                description: The original question from the quiz.
+                example: "איך היית מתכנן מערכת מיקרו-שירותים (Microservices) גדולה שמטפלת במיליוני בקשות ביום?"
+              user_answer:
+                type: string
+                description: The user's provided answer to the question.
+                example: "אני חושב שהייתי משתמש בקאפקה וסרביס דיסקברי. זה עוזר עם סקאלינג."
+              grade:
+                type: number
+                format: int32
+                minimum: 0
+                maximum: 100
+                description: The grade for the user's answer (0-100).
+                example: 85
+              tip:
+                type: string
+                description: A professional tip for the user to improve their answer.
+                example: "Consider elaborating on the specific design patterns (e.g., API Gateway, Service Discovery) and communication protocols (e.g., REST, gRPC) you would use."
+        final_quiz_grade:
+          type: number
+          format: int32
+          minimum: 0
+          maximum: 100
+          description: The overall average grade for all answered questions in the quiz (0-100).
+          example: 78
+        final_summary_tip:
+          type: string
+          description: A comprehensive tip for the user to improve their overall interview performance.
+          example: "Overall, your technical understanding is solid. For future interviews, focus on articulating your thoughts more structured, perhaps using the STAR method for behavioral questions, and always relate your technical solutions back to business value or team collaboration, demonstrating the 'interviewer mindset' we discussed."
+
   securitySchemes:
     BearerAuth:
       type: http

nextstep-backend/src/routes/quizzes_routes.ts

@@ -7,4 +7,6 @@ router.get('/raw', Quiz.getQuizzesByTags);
 
 router.post('/generate', Quiz.getGeneratedQuizBySubject);
 
+router.post('/grade', Quiz.getGradedQuizByAnsweredQuiz);
+
 export default router;

nextstep-backend/src/services/companies_service.ts

@@ -528,4 +528,64 @@ Return ONLY the JSON, without any other text, so I could easily retrieve it.
   const parsed = JSON.parse(aiResponse.trim().replace("```json", "").replace("```", "")) as any;
 
   return parsed;
-}
+}
+
+/**
+ * @param answeredQuiz The quiz answered by the user.
+ * @returns Graded quiz with tips.
+ */
+export const gradeQuiz = async (answeredQuiz: any): Promise<any> => {
+  const GRADE_QUIZ_SYSTEM_PROMPT = "You are an AI Interview Coach, an expert in real-world interviews, and skilled in providing constructive feedback and grading. Your task is to evaluate a user's answers to an interview quiz based on the original questions, your pre-generated ideal answers, and general professional knowledge. You should grade each answer from 0-100, considering that multiple correct or valid approaches may exist (or may not). Your feedback should be actionable and focused on improvement. Base yourself only on the user's answered quiz that will be given to you.";
+
+  const prompt = `
+**Original Quiz Data with User's Answers (JSON Object):**
+${answeredQuiz}
+
+**Instructions:**
+  Base yourself on the the user_answer_list and question_list fields.
+  Also, base yourself on the answer_list and the interviewer_mindset fields.
+  Grade and tip to user's answers one by one, by the following rules:
+
+  Grade (0-100): Assign a numerical score from 0 to 100 to the user_answer_list based on:
+    Accuracy: Is the answer technically correct?
+    Completeness: Does it cover the key aspects of the question?
+    Clarity and Conciseness: Is it well-articulated and to the point?
+    Depth: Does it demonstrate a solid understanding beyond surface-level knowledge?
+    Professional Knowledge: Use your general professional knowledge to evaluate, not just keywords. Be open to multiple valid answers.
+    Context: Consider the complexity implied by the question and the job_role.
+  Generate "Tip": Provide a small, concise, and actionable tip for the user to improve that specific answer for future interviews. This tip should be professional and forward-looking. Consider:
+    Suggesting deeper dives into specific technologies or concepts (e.g., "Explore idempotent operations in distributed systems").
+    Improving explanation clarity or structure (e.g., "Next time, start with a clear definition before diving into examples").
+    Relating the answer to the interviewer_mindset (e.g., "Highlighting the trade-offs involved would demonstrate critical thinking and problem-solving skills, which are valued by interviewers.").
+    Suggesting a real-world example or scenario.
+
+Summarize Results:
+
+  final_quiz_grade: Calculate the average of all individual grade scores to get a final overall quiz grade (0-100).
+  final_summary_tip: Provide one overarching, professional tip for the user to improve their overall interview performance, drawing insights from their collective answers and directly referencing the interviewer_mindset field for behavioral/soft skill advice.
+
+**Desired Output Format (JSON)**:
+\`\`\`json
+{
+  "graded_answers": [
+    {
+      "question": "string",
+      "user_answer": "string",
+      "grade": "number (0-100)",
+      "tip": "string"
+    },
+    // ... one object for each question answered
+  ],
+  "final_quiz_grade": "number (0-100)",
+  "final_summary_tip": "string"
+}
+\`\`\`
+
+Return ONLY the JSON, without any other text, so I could easily retrieve it.
+`;
+
+  const aiResponse = await chatWithAI(GRADE_QUIZ_SYSTEM_PROMPT, [prompt]);
+  const parsed = JSON.parse(aiResponse.trim().replace("```json", "").replace("```", "")) as any;
+
+  return parsed;
+}