feat: integrate AI grading functionality

- Added OpenAI package to backend dependencies for AI grading.
- Implemented new grading routes and services to handle AI grading requests.
- Updated admin settings to include AI provider configuration options.
- Enhanced frontend components to support AI grading, including UI for testing AI connection and displaying AI feedback.
- Updated results component to allow for AI-assisted grading and display of suggested grades.
- Added internationalization support for new AI grading features in both English and Dutch.

backend/src/index.ts

@@ -9,6 +9,7 @@ import examRoutes from './routes/exams.js'
 import resultRoutes from './routes/results.js'
 import adminRoutes from './routes/admin.js'
 import setupRoutes from './routes/setup.js'
+import gradeRoutes from './routes/grade.js'
 import { errorHandler } from './middleware/error.js'
 import { config } from './config.js'
 import path from 'path'
@@ -60,6 +61,7 @@ app.use('/api/setup', setupRoutes)
 app.use('/api/auth', authRoutes)
 app.use('/api/exams', examRoutes)
 app.use('/api/results', resultRoutes)
+app.use('/api/grade', gradeRoutes)
 app.use('/api/admin', adminRoutes)
 
 // Health check with subsystem status

backend/src/routes/grade.ts

@@ -0,0 +1,29 @@
+import { Router } from 'express'
+import { z } from 'zod'
+import { validateBody } from '../middleware/validate.js'
+import { asyncHandler } from '../utils/asyncHandler.js'
+import { requireAuth } from '../middleware/auth.js'
+import { gradeQuestionWithAI } from '../services/aiGrading.js'
+
+const gradeRequestSchema = z.object({
+  type: z.enum(['essay', 'short-answer', 'translation', 'math', 'ordering', 'match']),
+  question: z.record(z.unknown()),
+  answer: z.unknown(),
+  language: z.string().min(1),
+})
+
+const router = Router()
+
+router.use(requireAuth)
+
+router.post(
+  '/',
+  validateBody(gradeRequestSchema),
+  asyncHandler(async (req, res) => {
+    const { type, question, answer, language } = req.body as z.infer<typeof gradeRequestSchema>
+    const result = await gradeQuestionWithAI({ type, question, answer, language })
+    res.json(result)
+  }),
+)
+
+export default router

backend/src/services/aiGrading.ts

@@ -0,0 +1,183 @@
+import OpenAI from 'openai'
+import { getSetting } from '../repositories/settingsRepo.js'
+
+export interface GradingResult {
+  suggestedGrade: number
+  feedback: string
+  detail?: unknown
+}
+
+interface GradeRequest {
+  type: 'essay' | 'short-answer' | 'translation' | 'math' | 'ordering' | 'match'
+  question: Record<string, unknown>
+  answer: unknown
+  language: string
+}
+
+function getClient(): OpenAI | null {
+  const provider = getSetting('ai_provider')
+  const apiKey = getSetting('ai_api_key')
+  if (!provider || !apiKey) return null
+
+  const customBase = getSetting('ai_base_url')
+  const baseURL = provider === 'openai' ? undefined : (customBase || undefined)
+  return new OpenAI({ apiKey, baseURL })
+}
+
+function buildPrompt(req: GradeRequest): string {
+  const { type, question, answer, language } = req
+
+  const base = `You are an exam grading assistant. Grade the student's answer and respond ONLY with a JSON object containing:
+- "suggestedGrade": number between 0.0 and 1.0
+- "feedback": string with 1-3 sentences explaining the grade in ${language}
+- "detail": type-specific breakdown object (see below)
+
+Do not include any text outside the JSON object.`
+
+  switch (type) {
+    case 'essay': {
+      const rubric = (question.rubric as string[] | undefined) ?? []
+      return `${base}
+
+Question: ${question.prompt}
+Rubric criteria: ${rubric.join('; ') || 'None provided'}
+Student answer: ${String(answer ?? '')}
+
+Evaluate how well the essay covers the rubric criteria, structure, and quality. Provide "detail" as:
+{ "rubricBreakdown": [{ "item": string, "met": boolean }] }
+Each item should correspond to a rubric criterion.`
+    }
+
+    case 'short-answer': {
+      const accepted = [question.answer as string, ...(question.acceptedForms as string[] | undefined ?? [])].filter(Boolean)
+      return `${base}
+
+Question: ${question.prompt}
+Accepted answers: ${accepted.join(' | ')}
+Student answer: ${String(answer ?? '')}
+
+Determine if the student's answer is semantically equivalent to any accepted form. Provide "detail" as:
+{ "matchedForm": string | null, "reason": string }`
+    }
+
+    case 'translation': {
+      const accepted = [question.answer as string, ...(question.acceptedForms as string[] | undefined ?? [])].filter(Boolean)
+      const source = question.sourceLanguage as string
+      const target = question.targetLanguage as string
+      return `${base}
+
+Translate from ${source} to ${target}.
+Question: ${question.prompt}
+Accepted translations: ${accepted.join(' | ')}
+Student answer: ${String(answer ?? '')}
+
+Evaluate meaning accuracy and fluency, not literal word-for-word matching. Provide "detail" as:
+{ "accuracy": number (0-1), "fluency": number (0-1), "notes": string }`
+    }
+
+    case 'math': {
+      const accepted = [question.answer as string, ...(question.acceptedForms as string[] | undefined ?? [])].filter(Boolean)
+      return `${base}
+
+Question: ${question.prompt}
+Accepted answers (LaTeX): ${accepted.join(' | ')}
+Student answer (LaTeX): ${String(answer ?? '')}
+
+Determine if the student's LaTeX expression is mathematically equivalent to the accepted answer. Provide "detail" as:
+{ "equivalent": boolean, "explanation": string }`
+    }
+
+    case 'ordering': {
+      const correctOrder = question.answer as string[]
+      const items = question.items as Array<{ id: string; text: string }> | undefined
+      const itemMap = new Map(items?.map(i => [i.id, i.text]) ?? [])
+      const given = answer as string[]
+      const correctTexts = correctOrder.map(id => itemMap.get(id) ?? id)
+      const givenTexts = given?.map(id => itemMap.get(id) ?? id) ?? []
+      return `${base}
+
+Question: ${question.prompt}
+Correct order: ${correctTexts.join(' → ')}
+Student order: ${givenTexts.join(' → ')}
+
+Determine how many items are in the correct position. Provide "detail" as:
+{ "correctPositions": number[], "totalItems": number }
+correctPositions should be 1-based indices of items in the correct position.`
+    }
+
+    case 'match': {
+      const correctPairs = question.answer as Record<string, string>
+      const left = question.left as Array<{ id: string; text: string }> | undefined
+      const right = question.right as Array<{ id: string; text: string }> | undefined
+      const leftMap = new Map(left?.map(i => [i.id, i.text]) ?? [])
+      const rightMap = new Map(right?.map(i => [i.id, i.text]) ?? [])
+      const given = (answer as Record<string, string> | undefined) ?? {}
+      const correctPairTexts: string[] = []
+      const incorrectPairTexts: string[] = []
+      for (const [lId, rId] of Object.entries(correctPairs)) {
+        const pairText = `${leftMap.get(lId) ?? lId} → ${rightMap.get(rId) ?? rId}`
+        if (given[lId] === rId) {
+          correctPairTexts.push(pairText)
+        } else {
+          const actualR = given[lId] ? (rightMap.get(given[lId]) ?? given[lId]) : '(unanswered)'
+          incorrectPairTexts.push(`${leftMap.get(lId) ?? lId} → ${actualR} (should be ${rightMap.get(rId) ?? rId})`)
+        }
+      }
+      return `${base}
+
+Question: ${question.prompt}
+Correct pairings:
+${Object.entries(correctPairs).map(([l, r]) => `${leftMap.get(l) ?? l} → ${rightMap.get(r) ?? r}`).join('\n')}
+Student pairings:
+${Object.entries(given).map(([l, r]) => `${leftMap.get(l) ?? l} → ${rightMap.get(r) ?? r}`).join('\n')}
+
+Determine partial credit based on correct pairings. Provide "detail" as:
+{ "correctPairs": string[], "incorrectPairs": string[] }
+Use the human-readable text labels in the arrays.`
+    }
+
+    default:
+      return base
+  }
+}
+
+export async function gradeQuestionWithAI(req: GradeRequest): Promise<GradingResult> {
+  const client = getClient()
+  if (!client) {
+    throw new Error('AI grading is not configured. Please set provider and API key in admin settings.')
+  }
+
+  const model = getSetting('ai_model') || 'gpt-4o-mini'
+  const prompt = buildPrompt(req)
+
+  const completion = await client.chat.completions.create({
+    model,
+    messages: [{ role: 'user', content: prompt }],
+    response_format: { type: 'json_object' },
+    temperature: 0.2,
+    max_completion_tokens: 800,
+  })
+
+  const raw = completion.choices[0]?.message?.content
+  if (!raw) {
+    throw new Error('Empty response from AI provider')
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('Invalid JSON response from AI provider')
+  }
+
+  const obj = parsed as Record<string, unknown>
+  const suggestedGrade = typeof obj.suggestedGrade === 'number'
+    ? Math.max(0, Math.min(1, obj.suggestedGrade))
+    : 0
+
+  return {
+    suggestedGrade,
+    feedback: typeof obj.feedback === 'string' ? obj.feedback : '',
+    detail: obj.detail,
+  }
+}

backend/src/validators/adminSchemas.ts

@@ -21,6 +21,10 @@ const ALLOWED_SETTING_KEYS = [
   'smtp_secure',
   'app_url',
   'max_upload_mb',
+  'ai_provider',
+  'ai_model',
+  'ai_api_key',
+  'ai_base_url',
 ] as const
 
 export const updateSettingSchema = z.object({