lnet_tutor/exam_system/AUTO_SCORING_GUIDE.md

Automatic Scoring Guide

✅ Automatic Scoring Implemented!

The system now automatically scores exams that contain ONLY single choice and true/false questions.

How It Works

Scoring Rules

Automatic scoring is activated when:

• Exam contains ONLY single_choice questions
• OR exam contains ONLY true_false questions
• OR exam contains a mix of ONLY single_choice AND true_false questions

Automatic scoring is NOT activated when:

• Exam contains essay questions
• Exam contains code_simple questions
• Exam contains code_exercise questions
• Exam has any mix with non-auto-gradable types

Scoring Calculation

For auto-scorable exams:

• Each correct answer earns full points for that question
• Each incorrect answer earns 0 points
• Total score = sum of earned points
• Percentage = (total score / max score) × 100
• Passing threshold = 70%

What You See

When you submit an auto-scored exam:

1. Immediate score display
2. Percentage shown in large circle
3. Total points (e.g., "40 / 50")
4. PASSED or NOT PASSED status
5. Number of correct answers
6. Question-by-question breakdown in output JSON

When you submit a manually-graded exam:

1. Submission confirmation
2. Message: "Manual grading required for some questions"
3. No immediate score
4. Results saved for later review

Current Exam

Python Fundamentals - Easy Level

Exam Details:

• Subject: Python
• Difficulty: Easy
• Duration: 45 minutes
• Total Points: 50
• Auto-Scored: ✓ Yes

Questions:

• 5 Multiple Choice (5 points each = 25 points)
• 5 True/False (5 points each = 25 points)
• Total: 10 questions, 50 points

Question Breakdown

Multiple Choice Questions (25 points):

1. How to create a list? → Answer: A
2. Type of 'hello'? → Answer: B
3. Keyword for function? → Answer: B
4. What does len() return? → Answer: A
5. Valid variable name? → Answer: C

True/False Questions (25 points): 6. Python is case-sensitive → True 7. Lists are immutable → False 8. print() displays output → True 9. Python uses {} for blocks → False 10. # for comments → True

Perfect Score Example

If you answer all correctly:

• Score: 50 / 50
• Percentage: 100%
• Status: ✓ PASSED

Passing Score

• Need: 35 / 50 points (70%)
• That's: 7 out of 10 questions correct

Testing the System

Via Browser

1. Login:

   • Go to http://localhost/login
   • Use: testuser / test123

2. Take Exam:

   • Click "Start Exam" on "Python Fundamentals - Easy Level"
   • Answer all 10 questions
   • Click "Submit Exam"

3. See Score:

   • Large circle showing percentage
   • Green = Passed (≥70%)
   • Red = Not Passed (<70%)
   • Total points displayed
   • Correct count shown

4. View in History:

   • Click "View History"
   • See your attempt with score
   • Click "View Results" to see details

Score Display Features

Score Circle:

• Green background if passed
• Red background if not passed
• Large percentage number
• Points fraction below

Additional Info:

• Correct answers count
• Pass/fail status
• Attempt ID
• Links to history and home

Creating Auto-Scored Exams

Template

{
  "examId": "your-exam-id",
  "subject": "your-subject",
  "title": "Your Exam Title",
  "difficulty": "easy",
  "durationMinutes": 30,
  "sections": [
    {
      "id": "mcq",
      "title": "Multiple Choice",
      "questions": [
        {
          "id": "q1",
          "type": "single_choice",
          "prompt": "Your question?",
          "choices": [
            { "key": "A", "text": "Option A" },
            { "key": "B", "text": "Option B" }
          ],
          "answer": "A",
          "points": 10
        }
      ]
    },
    {
      "id": "tf",
      "title": "True/False",
      "questions": [
        {
          "id": "q2",
          "type": "true_false",
          "prompt": "Statement here.",
          "answer": true,
          "points": 10
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "totalPoints": 20,
    "autoScored": true
  }
}

Important:

• Use ONLY single_choice and true_false types
• Include answer field for each question
• Don't include essay or code questions

Output Format

Auto-Scored Output

The output JSON includes a score field in the attempt:

{
  "exam": { ... },
  "attempt": {
    "attemptId": "...",
    "userId": "1",
    "examId": "python-easy-v1",
    "status": "finished",
    "startedAt": "...",
    "submittedAt": "...",
    "answers": [ ... ],
    "score": {
      "totalScore": 40,
      "maxScore": 50,
      "percentage": 80.0,
      "passed": true,
      "byQuestion": [
        {
          "questionId": "q1",
          "earned": 5,
          "max": 5,
          "correct": true
        },
        {
          "questionId": "q2",
          "earned": 0,
          "max": 5,
          "correct": false
        }
      ]
    }
  }
}

Manually-Graded Output

No score field in attempt:

{
  "exam": { ... },
  "attempt": {
    "attemptId": "...",
    "status": "finished",
    "answers": [ ... ]
    // No score field
  }
}

Examples

Example 1: Auto-Scored Exam

• 10 MCQ questions
• Result: Immediate score

Example 2: Mixed Exam

• 5 MCQ questions
• 5 True/False questions
• Result: Immediate score

Example 3: Not Auto-Scored

• 5 MCQ questions
• 1 Essay question
• Result: No immediate score (essay requires manual grading)

Example 4: Not Auto-Scored

• 5 MCQ questions
• 1 Coding exercise
• Result: No immediate score (code requires evaluation)

Tips

1. For quizzes: Use only MCQ and T/F for instant scoring
2. For comprehensive exams: Mix in essay/code, accept manual grading
3. Check exam type before taking to know if you'll get instant feedback
4. Metadata hint: Add "autoScored": true to exam metadata (optional, for reference)

Current Status

• ✅ Auto-scoring logic implemented
• ✅ Score calculation working
• ✅ Frontend displays score
• ✅ Python Easy exam created (auto-scored)
• ✅ 10 questions (5 MCQ + 5 T/F)
• ✅ 50 total points
• ✅ 70% passing threshold

Ready to test! Go to http://localhost and take the exam! 🎯