Assessment

Assessment helpers wrap gradeQuiz() with attempt lifecycle metadata (id, startedAt, completedAt). Use them when your app owns persistence of attempts.

<Quiz /> grades with gradeQuiz internally and does not call these helpers — use onComplete there if you only need the score, or call createQuizAttempt / completeQuizAttempt yourself when you need attempt records.

createQuizAttempt

Starts a quiz attempt.

import { createQuizAttempt } from "edu-sdk";

const attempt = createQuizAttempt();

Options

All options are optional.

Returns

QuizAttempt

{
  id: string;
  answers: (number | null)[];
  startedAt: string;
  completedAt?: string;
}

completeQuizAttempt

Finishes an attempt: grades answers with gradeQuiz and sets completedAt.

import { createQuiz, createQuizAttempt, completeQuizAttempt } from "edu-sdk";

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

const attempt = createQuizAttempt();

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

Options

Questions must include a required id on each item (same contract as gradeQuiz()).

Returns

{
  attempt: QuizAttempt;      // includes answers and completedAt
  result: AssessmentResult;  // same shape as GradeQuizResult
}

AssessmentResult is an alias of GradeQuizResult, including optional byTopic when questions carry topics.

Invalid input throws InvalidInputError.

See also gradeQuiz() for scoring without attempt records, and Personalization for using byTopic in buildLearnerContext.