gradeQuiz

Grades a multiple-choice quiz by comparing submitted option indices to each question's correctAnswer. No model call — scoring is deterministic.

Usage

import { createQuiz, gradeQuiz } from "edu-sdk";

const quiz = await createQuiz({
  model: "google/gemini-3.6-flash",
  content,
  count: 10
});

const result = gradeQuiz({
  questions: quiz.content,
  answers: [0, 2, null, 1]
});

Options

answers must be the same length as questions. Each entry is a zero-indexed option, or null for unanswered.

Each QuizQuestion needs a required id. Optional topics on questions enable a per-topic breakdown in the result.

Returns

GradeQuizResult

{
  score: number;
  total: number;
  percentage: number;
  results: Array<{
    questionIndex: number;
    selectedAnswer: number | null;
    correctAnswer: number;
    isCorrect: boolean;
    isAnswered: boolean;
  }>;
  byTopic?: Array<{
    topic: string;
    correct: number;
    total: number;
    percentage: number;
  }>;
}

percentage is 0–100, rounded to the nearest integer. Unanswered questions count as incorrect (isCorrect: false, isAnswered: false).

byTopic is included only when at least one question has topics. A question tagged with multiple topics counts toward each of those topics. When no questions have topics, byTopic is omitted (not an empty array).

GradeQuizTopicResult is the type of each byTopic entry.

Example

import { gradeQuiz } from "edu-sdk";

const result = gradeQuiz({
  questions,
  answers: [0, 1, 2]
});

console.log(`${result.score} / ${result.total} (${result.percentage}%)`);
if (result.byTopic) {
  console.log(result.byTopic);
}

Invalid input throws InvalidInputError.

For attempt lifecycle (id, startedAt, completedAt), see Assessment. For feeding byTopic into the next generation, see Personalization.