AI grading

AI grading scores a submission against the assignment’s rubric and returns:

a numeric grade (grade_ai),
a per-criterion breakdown,
a markdown rationale (grading_rationale),
optional inline annotations on the student’s text.

The grade is never committed to the gradebook automatically — there is always a grade_manual field that, when set, overrides the AI grade.

Calling the grader

await hk.submissions.gradeWithAi("sub_123");

$hk->submissions->gradeWithAi('sub_123');

That call is async (it returns immediately with ai_status: "pending"). Wait for completion via polling or webhook.

What you get back

{
  "id": "sub_123",
  "ai_status": "ready",
  "grade_ai": 8.5,
  "grading_rationale": "## Clarity (4/4)\nThe student opens with...\n\n## Accuracy (3/4)\n...",
  "grading_breakdown": [
    { "criterion": "clarity", "score": 4, "max": 4 },
    { "criterion": "accuracy", "score": 3, "max": 4 },
    { "criterion": "sources", "score": 1.5, "max": 2 }
  ],
  "evaluated_at": "2026-05-10T12:34:56Z"
}

Configuring the grader

Per-assignment configuration lives on the Assignment:

await hk.assignments.configure(assignmentId, {
  ai_evaluator: {
    enabled: true,
    model: "claude-sonnet-4-6",
    rubric: {
      criteria: [
        { name: "clarity", weight: 0.4 },
        { name: "accuracy", weight: 0.4 },
        { name: "sources", weight: 0.2 },
      ],
      scale: { min: 0, max: 10 },
    },
    feedback: {
      tone: "encouraging" | "neutral" | "demanding",
      verbosity: "short" | "normal" | "detailed",
      language: "en",
    },
  },
});

$hk->assignments->configure($assignmentId, [
    'ai_evaluator' => [
        'enabled' => true,
        'model' => 'claude-sonnet-4-6',
        'rubric' => [
            'criteria' => [
                ['name' => 'clarity', 'weight' => 0.4],
                ['name' => 'accuracy', 'weight' => 0.4],
                ['name' => 'sources', 'weight' => 0.2],
            ],
            'scale' => ['min' => 0, 'max' => 10],
        ],
        'feedback' => [
            'tone' => 'encouraging',     // 'encouraging' | 'neutral' | 'demanding'
            'verbosity' => 'normal',     // 'short' | 'normal' | 'detailed'
            'language' => 'en',
        ],
    ],
]);

For one-off rubric overrides on a single submission:

await hk.submissions.gradeWithAi(submissionId, {
  rubric: { /* override */ },
});

$hk->submissions->gradeWithAi($submissionId, [
    'rubric' => [ /* override */ ],
]);

Human-in-the-loop

The recommended workflow:

// 1. AI grades
await hk.submissions.gradeWithAi(submissionId);

// 2. Teacher reviews in your UI; you show grade_ai + grading_rationale.

// 3. Teacher confirms (or edits)
await hk.submissions.update(submissionId, {
  grade_manual: 8.5,            // confirm
  grader_comments: "Solid.",
  human_review_status: "reviewed",
});

// 1. AI grades
$hk->submissions->gradeWithAi($submissionId);

// 2. Teacher reviews in your UI; you show grade_ai + grading_rationale.

// 3. Teacher confirms (or edits)
$hk->submissions->update($submissionId, [
    'grade_manual' => 8.5,             // confirm
    'grader_comments' => 'Solid.',
    'human_review_status' => 'reviewed',
]);

human_review_status flows: pending → reviewed. You can require review per assignment (human_review: "required"); when set, the grade shown to students is null until a human marks it reviewed.

Re-grading

If you change the rubric or want a second opinion, call gradeWithAi again. The new result overwrites the previous AI grade; grade_manual is untouched.

await hk.submissions.gradeWithAi(submissionId);

$hk->submissions->gradeWithAi($submissionId);

You can also ask for the AI’s reasoning without a grade — useful when the teacher wants explanations on a hand-graded submission:

await hk.submissions.explainGrade(submissionId);
// → fills `grading_rationale` based on the existing manual grade

$hk->submissions->explainGrade($submissionId);
// → fills `grading_rationale` based on the existing manual grade

What AI grading is not

Not a replacement for the teacher on consequential grades.
Not stable across model versions: pin a model if you need reproducibility.
Not suitable for grading code, math proofs, or anything where the rubric isn’t expressible in natural language. Use a custom grader and ingest the score via submissions.update({ grade_manual }) (or $hk->submissions->update($id, ['grade_manual' => ...])) instead.

Auditing

Every AI grade carries the model version, the rubric snapshot, and the prompt fingerprint in submission.evaluation_meta. That makes appeals and audits feasible.

const sub = await hk.submissions.retrieve(submissionId, {
  expand: ["evaluation_meta"],
});

// sub.evaluation_meta = { model, rubric, prompt_hash, evaluated_at }

$sub = $hk->submissions->retrieve($submissionId, [
    'expand' => ['evaluation_meta'],
]);

// $sub->evaluation_meta = { model, rubric, prompt_hash, evaluated_at }

Get started

Core concepts

Guides

Calling the grader

What you get back

Configuring the grader

Human-in-the-loop

Re-grading

What AI grading is not

Auditing

​Calling the grader

​What you get back

​Configuring the grader

​Human-in-the-loop

​Re-grading

​What AI grading is not

​Auditing

Calling the grader

What you get back

Configuring the grader

Human-in-the-loop

Re-grading

What AI grading is not

Auditing