feat: add job retry functionality and enhance question generation with JSON schema descriptions. Update UI to allow job retries for failed or canceled jobs, and improve API handling for job input configurations. Include new utility functions for generating JSON schema descriptions for questions and passages.

apps/web/src/routes/jobs.tsx

@@ -157,6 +157,14 @@ function RouteComponent() {
     },
   });
 
+  const retryJob = useMutation({
+    ...trpc.ai.retryJob.mutationOptions(),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: trpc.ai.myJobs.queryKey() });
+      await queryClient.invalidateQueries({ queryKey: trpc.ai.getJobStatus.queryKey() });
+    },
+  });
+
   const toggleExpand = (id: string) => {
     setExpandedJobId((prev) => (prev === id ? null : id));
   };
@@ -241,6 +249,19 @@ function RouteComponent() {
                           Batalkan
                         </Button>
                       )}
+                      {(job.status === "failed" || job.status === "cancelled") && (
+                        <Button
+                          type="button"
+                          variant="outline"
+                          size="sm"
+                          className="rounded-[var(--radius-lg)] border-2 border-[var(--matcha-400)] text-xs shrink-0 text-[var(--matcha-800)]"
+                          disabled={retryJob.isPending}
+                          onClick={() => retryJob.mutate({ jobId: job.id })}
+                        >
+                          <MaterialIcon name="refresh" className="text-sm mr-1" />
+                          Retry
+                        </Button>
+                      )}
                       <div className="text-xs text-[var(--warm-charcoal)]">
                         {formatDate(job.createdAt)}
                       </div>
@@ -249,14 +270,14 @@ function RouteComponent() {
 
                   {(job.status === "running" || job.status === "pending") && (
                     <div className="mt-3">
-                      <div className="flex justify-between text-xs text-[var(--warm-charcoal)] mb-1">
-                        <span>{job.progressMessage ?? "Processing..."}</span>
-                        <span>{job.progress}%</span>
+                      <div className="flex justify-between text-xs text-[var(--warm-charcoal)] mb-1.5">
+                        <span className="truncate mr-2">{job.progressMessage ?? "Processing..."}</span>
+                        <span className="shrink-0 font-semibold">{job.progress}%</span>
                       </div>
-                      <div className="w-full h-2 bg-[var(--oat-border)] rounded-full overflow-hidden">
+                      <div className="w-full h-2.5 bg-[var(--oat-light)] rounded-full overflow-hidden border border-[var(--oat-border)]">
                         <div
-                          className="h-full bg-[var(--matcha-600)] transition-all duration-500"
-                          style={{ width: `${job.progress}%` }}
+                          className="h-full bg-[var(--matcha-600)] transition-all duration-500 rounded-full"
+                          style={{ width: `${Math.max(2, job.progress ?? 0)}%` }}
                         />
                       </div>
                     </div>
@@ -284,7 +305,7 @@ function RouteComponent() {
                     <div className="flex items-center justify-between mb-3">
                       <div className="text-sm text-[var(--warm-charcoal)]">
                         {result.questions.length} soal dihasilkan · {result.meta.model}
-                        {result.meta.tokensUsed ? ` · ${result.meta.tokensUsed} tokens` : ""}
+                        {job.tokensUsed ? ` · ${job.tokensUsed} tokens` : ""}
                         {result.meta.durationMs ? ` · ${(result.meta.durationMs / 1000).toFixed(1)}s` : ""}
                       </div>
                       <Button

bun.lock

@@ -86,6 +86,7 @@
       "name": "@labas/ai",
       "dependencies": {
         "zod": "catalog:",
+        "zod-to-json-schema": "^3.25.2",
       },
       "devDependencies": {
         "@labas/config": "workspace:*",

packages/ai/package.json

@@ -10,7 +10,8 @@
     }
   },
   "dependencies": {
-    "zod": "catalog:"
+    "zod": "catalog:",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@labas/config": "workspace:*",

packages/ai/src/agentic.ts

@@ -1,5 +1,12 @@
 import { OpenAICompatibleClient } from "./client";
 import { GenerationError } from "./errors";
+import {
+  getQuestionJsonSchemaDescription,
+  getPassageJsonSchemaDescription,
+  getValidationJsonSchemaDescription,
+  getQuestionsArrayJsonSchemaDescription,
+  getSelfValidationJsonSchemaDescription,
+} from "./schema-to-prompt";
 import { questionSchema, type GenerationInput, type GenerationResult } from "./schemas";
 
 interface AgenticStep {
@@ -43,7 +50,9 @@ function parseJsonResponse(content: string): unknown {
 async function step1GeneratePassage(
   client: OpenAICompatibleClient,
   input: GenerationInput,
+  onToken?: (token: string) => void,
 ): Promise<{ passage: string; title: string; tokensUsed: number }> {
+  const schema = getPassageJsonSchemaDescription();
   const prompt = `Generate an authentic, high-quality reading passage for ${input.examType} ${input.section.toLowerCase()} section at difficulty level ${input.difficulty}/5.
 
 Requirements:
@@ -53,21 +62,22 @@ Requirements:
 - The passage should be natural, well-structured, and appropriate for the exam level
 - Length should be suitable for ${input.questionCount} comprehension questions
 
-Return ONLY valid JSON:
-{
-  "title": "Brief title describing the passage topic",
-  "passage": "The full reading passage text..."
-}`;
-
-  const result = await client.chatCompletion({
-    model: input.apiKeyConfig.model,
-    messages: [
-      { role: "system", content: getSystemPrompt() },
-      { role: "user", content: prompt },
-    ],
-    temperature: 0.7,
-    max_tokens: input.apiKeyConfig.maxTokens,
-  });
+Return ONLY valid JSON conforming to this schema:
+${schema}`;
+
+  const result = await client.chatCompletion(
+    {
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: getSystemPrompt() },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.7,
+      max_tokens: input.apiKeyConfig.maxTokens,
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
 
   const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
   if (!parsed.passage || typeof parsed.passage !== "string") {
@@ -84,7 +94,9 @@ async function step2ValidatePassage(
   client: OpenAICompatibleClient,
   input: GenerationInput,
   passage: string,
+  onToken?: (token: string) => void,
 ): Promise<{ isValid: boolean; feedback: string; tokensUsed: number }> {
+  const schema = getValidationJsonSchemaDescription();
   const prompt = `Validate this reading passage for a ${input.examType} exam at difficulty ${input.difficulty}/5.
 
 Passage:
@@ -99,22 +111,22 @@ Check:
 4. Topic relevance: ${input.topics.join(", ")}
 5. Natural flow and coherence
 
-Return ONLY valid JSON:
-{
-  "isValid": true/false,
-  "feedback": "Brief assessment. If invalid, explain why.",
-  "score": number from 1-10
-}`;
-
-  const result = await client.chatCompletion({
-    model: input.apiKeyConfig.model,
-    messages: [
-      { role: "system", content: getSystemPrompt() },
-      { role: "user", content: prompt },
-    ],
-    temperature: 0.3,
-    max_tokens: input.apiKeyConfig.maxTokens,
-  });
+Return ONLY valid JSON conforming to this schema:
+${schema}`;
+
+  const result = await client.chatCompletion(
+    {
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: getSystemPrompt() },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.3,
+      max_tokens: input.apiKeyConfig.maxTokens,
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
 
   const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
   return {
@@ -128,30 +140,10 @@ async function step3GenerateQuestions(
   client: OpenAICompatibleClient,
   input: GenerationInput,
   passage: string,
+  onToken?: (token: string) => void,
 ): Promise<{ questions: Array<Record<string, unknown>>; tokensUsed: number }> {
-  const formats = input.formats;
-  const formatInstructions = formats
-    .map((f) => {
-      const schemas: Record<string, string> = {
-        multiple_choice: `{"format":"multiple_choice","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["..."]`,
-        true_false_not_given: `{"format":"true_false_not_given","questionText":"...","correctAnswer":"TRUE|FALSE|NOT_GIVEN","explanation":"...","difficulty":${input.difficulty},"skillTags":["..."]`,
-        fill_blank: `{"format":"fill_blank","questionText":"...","correctAnswer":"exact text","explanation":"...","difficulty":${input.difficulty},"skillTags":["..."]`,
-        synonym: `{"format":"synonym","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["vocabulary","synonym"]`,
-        grammar_in_context: `{"format":"grammar_in_context","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["grammar"]`,
-        sentence_completion: `{"format":"sentence_completion","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["..."]`,
-        cloze: `{"format":"cloze","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"serialized mapping","explanation":"...","difficulty":${input.difficulty},"skillTags":["grammar","vocabulary"]`,
-        reference: `{"format":"reference","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["reference","inference"]`,
-        author_view: `{"format":"author_view","questionText":"...","correctAnswer":"YES|NO|NOT_GIVEN","explanation":"...","difficulty":${input.difficulty},"skillTags":["inference","author_view"]`,
-        matching_headings: `{"format":"matching_headings","questionText":"Match each paragraph to a heading:","options":[{"key":"i","text":"..."},...],"correctAnswer":"serialized mapping","explanation":"...","difficulty":${input.difficulty},"skillTags":["main_idea","matching"]`,
-        kanji_reading: `{"format":"kanji_reading","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["kanji","reading"]`,
-        particle_choice: `{"format":"particle_choice","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["grammar","particle"]`,
-        article_case: `{"format":"article_case","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["grammar","article","case"]`,
-        character_reading: `{"format":"character_reading","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["character","reading"]`,
-        sentence_arrangement: `{"format":"sentence_arrangement","questionText":"...","options":[{"key":"A","text":"..."},...],"correctAnswer":"A","explanation":"...","difficulty":${input.difficulty},"skillTags":["reading","sentence_structure"]`,
-      };
-      return schemas[f] || schemas["multiple_choice"];
-    })
-    .join("\n---\n");
+  const questionSchemaDesc = getQuestionJsonSchemaDescription();
+  const wrapperSchema = getQuestionsArrayJsonSchemaDescription();
 
   const prompt = `Using the following passage, generate ${input.questionCount} reading comprehension questions for ${input.examType} exam.
 
@@ -160,8 +152,7 @@ Passage:
 ${passage}
 """
 
-Formats to generate:
-${formatInstructions}
+Formats to generate: ${input.formats.join(", ")}
 
 Rules:
 - Each question must be directly answerable from the passage
@@ -169,24 +160,27 @@ Rules:
 - Questions should test real comprehension, not surface recall
 - For multiple choice: always provide 4 options (A, B, C, D) with one clearly correct answer
 - Options must be plausible distractors
-- an explanation (explanation) - dijelaskan dengan bahasa Indonesia
-
-Return ONLY valid JSON:
-{
-  "questions": [
-    // array of question objects matching the format schemas above
-  ]
-}`;
-
-  const result = await client.chatCompletion({
-    model: input.apiKeyConfig.model,
-    messages: [
-      { role: "system", content: getSystemPrompt() },
-      { role: "user", content: prompt },
-    ],
-    temperature: 0.7,
-    max_tokens: input.apiKeyConfig.maxTokens,
-  });
+- explanation (explanation) - dijelaskan dengan bahasa Indonesia
+
+Question schema:
+${questionSchemaDesc}
+
+Return ONLY valid JSON conforming to this schema:
+${wrapperSchema}`;
+
+  const result = await client.chatCompletion(
+    {
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: getSystemPrompt() },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.7,
+      max_tokens: input.apiKeyConfig.maxTokens,
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
 
   const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
   if (!Array.isArray(parsed.questions)) {
@@ -203,11 +197,13 @@ async function step4SelfValidate(
   input: GenerationInput,
   passage: string,
   questions: Array<Record<string, unknown>>,
+  onToken?: (token: string) => void,
 ): Promise<{ correctedQuestions: Array<Record<string, unknown>>; confidence: number; tokensUsed: number }> {
   const qaPairs = questions
     .map((q, i) => `Q${i + 1}: ${q.questionText}\nA: ${q.correctAnswer}`)
     .join("\n\n");
 
+  const schema = getSelfValidationJsonSchemaDescription();
   const prompt = `You are a strict exam validator. Review these questions against the passage and identify any errors.
 
 Passage:
@@ -223,28 +219,22 @@ For each question, verify:
 2. Are there any ambiguous questions?
 3. Are distractors plausible but clearly wrong?
 
-Return ONLY valid JSON:
-{
-  "overallConfidence": number from 0-100,
-  "issues": [
+Return ONLY valid JSON conforming to this schema:
+${schema}`;
+
+  const result = await client.chatCompletion(
     {
-      "questionIndex": 0-based index,
-      "issue": "description of problem",
-      "suggestedFix": "corrected answer or explanation"
-    }
-  ],
-  "needsRevision": true/false
-}`;
-
-  const result = await client.chatCompletion({
-    model: input.apiKeyConfig.model,
-    messages: [
-      { role: "system", content: getSystemPrompt() },
-      { role: "user", content: prompt },
-    ],
-    temperature: 0.3,
-    max_tokens: input.apiKeyConfig.maxTokens,
-  });
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: getSystemPrompt() },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.3,
+      max_tokens: input.apiKeyConfig.maxTokens,
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
 
   const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
   const confidence = typeof parsed.overallConfidence === "number" ? parsed.overallConfidence : 75;
@@ -262,9 +252,74 @@ Return ONLY valid JSON:
   return { correctedQuestions: corrected, confidence, tokensUsed: result.usage?.total_tokens ?? 0 };
 }
 
+async function step4RegenerateBadQuestions(
+  client: OpenAICompatibleClient,
+  input: GenerationInput,
+  passage: string,
+  questions: Array<Record<string, unknown>>,
+  issueIndices: number[],
+  onToken?: (token: string) => void,
+): Promise<{ regenerated: Array<Record<string, unknown>>; tokensUsed: number }> {
+  const badQuestions = issueIndices.map((i) => ({
+    index: i,
+    ...questions[i],
+  }));
+
+  const questionSchemaDesc = getQuestionJsonSchemaDescription();
+  const wrapperSchema = getQuestionsArrayJsonSchemaDescription();
+
+  const prompt = `You are an expert exam question writer. The following questions were flagged as incorrect or flawed. Regenerate them to fix the issues while keeping the same format and difficulty.
+
+Passage:
+"""
+${passage}
+"""
+
+Flawed questions (with their original index):
+${JSON.stringify(badQuestions, null, 2)}
+
+Rules:
+- Regenerate ONLY the flawed questions
+- Maintain the same format, difficulty (${input.difficulty}), and exam style (${input.examType})
+- Each question must be directly answerable from the passage
+- explanation (explanation) - dijelaskan dengan bahasa Indonesia
+- Return the same number of questions in the same order as the input
+
+Question schema:
+${questionSchemaDesc}
+
+Return ONLY valid JSON conforming to this schema:
+${wrapperSchema}`;
+
+  const result = await client.chatCompletion(
+    {
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: getSystemPrompt() },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.7,
+      max_tokens: input.apiKeyConfig.maxTokens,
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
+
+  const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
+  if (!Array.isArray(parsed.questions) || parsed.questions.length !== badQuestions.length) {
+    throw new Error("Regeneration did not return the expected number of questions");
+  }
+
+  return {
+    regenerated: parsed.questions as Array<Record<string, unknown>>,
+    tokensUsed: result.usage?.total_tokens ?? 0,
+  };
+}
+
 export async function generateQuestionsAgentic(
   input: GenerationInput,
   onProgress?: (progress: AgenticProgress) => void,
+  onToken?: (token: string) => void,
 ): Promise<GenerationResult> {
   const start = Date.now();
   const client = new OpenAICompatibleClient(
@@ -292,7 +347,7 @@ export async function generateQuestionsAgentic(
   let passage: string;
   let title: string;
   try {
-    const s1 = await step1GeneratePassage(client, input);
+    const s1 = await step1GeneratePassage(client, input, onToken);
     passage = s1.passage;
     title = s1.title;
     accumulatedTokens += s1.tokensUsed;
@@ -311,7 +366,7 @@ export async function generateQuestionsAgentic(
   let isValid: boolean;
   let feedback: string;
   try {
-    const s2 = await step2ValidatePassage(client, input, passage);
+    const s2 = await step2ValidatePassage(client, input, passage, onToken);
     isValid = s2.isValid;
     feedback = s2.feedback;
     accumulatedTokens += s2.tokensUsed;
@@ -331,7 +386,7 @@ export async function generateQuestionsAgentic(
   report(2);
   let rawQuestions: Array<Record<string, unknown>>;
   try {
-    const s3 = await step3GenerateQuestions(client, input, passage);
+    const s3 = await step3GenerateQuestions(client, input, passage, onToken);
     rawQuestions = s3.questions;
     accumulatedTokens += s3.tokensUsed;
     steps[2].status = "done";
@@ -349,12 +404,40 @@ export async function generateQuestionsAgentic(
   let correctedQuestions: Array<Record<string, unknown>>;
   let confidence: number;
   try {
-    const s4 = await step4SelfValidate(client, input, passage, rawQuestions);
+    const s4 = await step4SelfValidate(client, input, passage, rawQuestions, onToken);
     correctedQuestions = s4.correctedQuestions;
     confidence = s4.confidence;
     accumulatedTokens += s4.tokensUsed;
+
+    // If validation found issues and confidence is low, actually regenerate the bad questions
+    const issueIndices = (s4.correctedQuestions as any[])
+      .map((q, i) => (q.explanation?.includes("[Validator note:") ? i : -1))
+      .filter((i) => i !== -1);
+
+    if (issueIndices.length > 0 && confidence < 85) {
+      steps[3].message = `Found ${issueIndices.length} issues. Regenerating...`;
+      report(3);
+      const regen = await step4RegenerateBadQuestions(
+        client,
+        input,
+        passage,
+        rawQuestions,
+        issueIndices,
+        onToken,
+      );
+      accumulatedTokens += regen.tokensUsed;
+
+      // Replace the bad questions with regenerated ones
+      for (let idx = 0; idx < issueIndices.length; idx++) {
+        correctedQuestions[issueIndices[idx]] = regen.regenerated[idx];
+      }
+      confidence = Math.min(100, confidence + 10);
+      steps[3].message = `Regenerated ${issueIndices.length} questions. Confidence: ${confidence}%`;
+    } else {
+      steps[3].message = `Confidence score: ${confidence}%`;
+    }
+
     steps[3].status = "done";
-    steps[3].message = `Confidence score: ${confidence}%`;
     steps[3].output = `Overall Confidence: ${confidence}%\nTotal Questions: ${correctedQuestions.length}`;
   } catch (err: any) {
     steps[3].status = "error";

packages/ai/src/index.ts

@@ -5,3 +5,10 @@ export type { AgenticProgress } from "./agentic";
 export { buildQuickModePrompt } from "./prompts";
 export * from "./schemas";
 export { GenerationError } from "./errors";
+export {
+  getQuestionJsonSchemaDescription,
+  getPassageJsonSchemaDescription,
+  getValidationJsonSchemaDescription,
+  getQuestionsArrayJsonSchemaDescription,
+  getSelfValidationJsonSchemaDescription,
+} from "./schema-to-prompt";

packages/ai/src/pipeline.ts

@@ -56,6 +56,7 @@ export async function generateQuestionsQuick(
         ],
         temperature: 0.7,
         max_tokens: input.apiKeyConfig.maxTokens,
+        response_format: { type: "json_object" },
       },
       callbacks?.onToken
         ? { onToken: callbacks.onToken }

packages/ai/src/prompts.ts

@@ -1,161 +1,10 @@
 import type { GenerationInput } from "./schemas";
+import { getQuestionJsonSchemaDescription } from "./schema-to-prompt";
 
 export function buildQuickModePrompt(input: GenerationInput): string {
   const { examType, section, formats, difficulty, topics, questionCount } = input;
 
-  const formatDescriptions: Record<string, string> = {
-    multiple_choice: `{
-      "format": "multiple_choice",
-      "passageText": "...",
-      "questionText": "...",
-      "options": [{"key": "A", "text": "..."}, {"key": "B", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["..."]
-    }`,
-    true_false_not_given: `{
-      "format": "true_false_not_given",
-      "passageText": "...",
-      "questionText": "...",
-      "correctAnswer": "TRUE" | "FALSE" | "NOT_GIVEN",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["..."]
-    }`,
-    fill_blank: `{
-      "format": "fill_blank",
-      "passageText": "...",
-      "questionText": "Fill in the blank: ...",
-      "correctAnswer": "exact text",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["..."]
-    }`,
-    synonym: `{
-      "format": "synonym",
-      "passageText": "...",
-      "questionText": "The word '___' in the passage is closest in meaning to:",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["vocabulary", "synonym"]
-    }`,
-    grammar_in_context: `{
-      "format": "grammar_in_context",
-      "passageText": "...",
-      "questionText": "...",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["grammar"]
-    }`,
-    sentence_completion: `{
-      "format": "sentence_completion",
-      "passageText": "...",
-      "questionText": "...",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["..."]
-    }`,
-    cloze: `{
-      "format": "cloze",
-      "passageText": "...",
-      "questionText": "Fill each blank with the correct option:",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "serialized mapping of blank index to option key",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["grammar", "vocabulary"]
-    }`,
-    reference: `{
-      "format": "reference",
-      "passageText": "...",
-      "questionText": "The word 'it' in paragraph X refers to:",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["reference", "inference"]
-    }`,
-    author_view: `{
-      "format": "author_view",
-      "passageText": "...",
-      "questionText": "...",
-      "correctAnswer": "YES" | "NO" | "NOT_GIVEN",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["inference", "author_view"]
-    }`,
-    matching_headings: `{
-      "format": "matching_headings",
-      "passageText": "...",
-      "questionText": "Match each paragraph to a heading:",
-      "options": [{"key": "i", "text": "..."}, ...],
-      "correctAnswer": "serialized mapping of paragraph to heading key",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["main_idea", "matching"]
-    }`,
-    kanji_reading: `{
-      "format": "kanji_reading",
-      "passageText": "...",
-      "questionText": "How is the kanji '...' read in this context?",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["kanji", "reading"]
-    }`,
-    particle_choice: `{
-      "format": "particle_choice",
-      "passageText": "...",
-      "questionText": "Which particle fits the blank?",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["grammar", "particle"]
-    }`,
-    article_case: `{
-      "format": "article_case",
-      "passageText": "...",
-      "questionText": "Which article/case fits the blank?",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["grammar", "article", "case"]
-    }`,
-    character_reading: `{
-      "format": "character_reading",
-      "passageText": "...",
-      "questionText": "How is the character '...' read in this context?",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["character", "reading"]
-    }`,
-    sentence_arrangement: `{
-      "format": "sentence_arrangement",
-      "passageText": "...",
-      "questionText": "Arrange the following sentences into the correct order:",
-      "options": [{"key": "A", "text": "..."}, ...],
-      "correctAnswer": "A",
-      "explanation": "...",
-      "difficulty": ${difficulty},
-      "skillTags": ["reading", "sentence_structure"]
-    }`,
-  };
-
-  const formatExamples = formats
-    .map((f) => formatDescriptions[f] || formatDescriptions["multiple_choice"])
-    .join("\n\n---\n\n");
+  const questionSchemaJson = getQuestionJsonSchemaDescription();
 
   return `You are an expert exam question writer for ${examType} ${section.toLowerCase()} section.
 
@@ -165,6 +14,7 @@ EXAM: ${examType}
 SECTION: ${section}
 DIFFICULTY: ${difficulty}/5
 TOPICS: ${topics.join(", ")}
+FORMATS TO GENERATE: ${formats.join(", ")}
 
 INSTRUCTIONS:
 - The reading passage must be written in the target language of the exam (${examType === "JLPT" ? "Japanese" : examType === "HSK" ? "Chinese" : examType === "GOETHE" ? "German" : "English"}).
@@ -185,7 +35,8 @@ Return ONLY a valid JSON object with this exact structure (no markdown code bloc
 
 {
   "questions": [
-${formatExamples}
+    // array of question objects. Schema:
+${questionSchemaJson.split("\n").map((l) => "    " + l).join("\n")}
   ]
 }
 

packages/ai/src/schema-to-prompt.ts

@@ -0,0 +1,106 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { questionSchema } from "./schemas";
+
+/**
+ * Generate a concise JSON-schema description of the question schema
+ * suitable for embedding into an LLM prompt.
+ */
+export function getQuestionJsonSchemaDescription(): string {
+  const jsonSchema = zodToJsonSchema(questionSchema as any, {
+    name: "Question",
+    $refStrategy: "none",
+  });
+
+  // Strip the top-level wrapper so the AI sees just the object shape
+  const defs = (jsonSchema as any).definitions?.Question ?? jsonSchema;
+
+  return JSON.stringify(defs, null, 2);
+}
+
+/**
+ * Generate a JSON schema description for a passage response.
+ */
+export function getPassageJsonSchemaDescription(): string {
+  return JSON.stringify(
+    {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Brief title describing the passage topic" },
+        passage: { type: "string", description: "The full reading passage text" },
+      },
+      required: ["title", "passage"],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Generate a JSON schema description for a validation response.
+ */
+export function getValidationJsonSchemaDescription(): string {
+  return JSON.stringify(
+    {
+      type: "object",
+      properties: {
+        isValid: { type: "boolean" },
+        feedback: { type: "string", description: "Brief assessment. If invalid, explain why." },
+        score: { type: "number", minimum: 1, maximum: 10 },
+      },
+      required: ["isValid", "feedback", "score"],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Generate a JSON schema description for the questions array wrapper.
+ */
+export function getQuestionsArrayJsonSchemaDescription(): string {
+  return JSON.stringify(
+    {
+      type: "object",
+      properties: {
+        questions: {
+          type: "array",
+          description: "Array of question objects",
+          items: { $ref: "#/$defs/Question" },
+        },
+      },
+      required: ["questions"],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Generate a JSON schema description for the self-validation response.
+ */
+export function getSelfValidationJsonSchemaDescription(): string {
+  return JSON.stringify(
+    {
+      type: "object",
+      properties: {
+        overallConfidence: { type: "number", minimum: 0, maximum: 100 },
+        issues: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              questionIndex: { type: "number" },
+              issue: { type: "string" },
+              suggestedFix: { type: "string" },
+            },
+            required: ["questionIndex", "issue", "suggestedFix"],
+          },
+        },
+        needsRevision: { type: "boolean" },
+      },
+      required: ["overallConfidence", "issues", "needsRevision"],
+    },
+    null,
+    2,
+  );
+}

packages/api/src/queue.ts

@@ -188,6 +188,19 @@ export const generationWorker = new Worker(
 
       startHeartbeat();
 
+      const tokenCounter = (token: string) => {
+        cancelPoll.check();
+        countToken(token);
+        if (approxTokens % 20 === 0) {
+          job.updateProgress(job.progress ?? 5).catch(() => {});
+          db
+            .update(generationJob)
+            .set({ progressMessage: `Generating... (~${approxTokens} tokens)` })
+            .where(eq(generationJob.id, jobId))
+            .catch(() => {});
+        }
+      };
+
       let result;
       try {
         result =
@@ -203,21 +216,9 @@ export const generationWorker = new Worker(
                 const status = step?.status === "error" ? "error" : step?.status === "done" ? "done" : "running";
                 await updateProgress(stepProgress, msg);
                 await pushLog(step?.step ?? "unknown", msg, status, step?.output);
-              })
+              }, tokenCounter)
             : await generateQuestionsQuick(input, {
-                onToken: (token) => {
-                  cancelPoll.check();
-                  countToken(token);
-                  // Update progress message with token count every ~500 chars
-                  if (approxTokens % 20 === 0) {
-                    job.updateProgress(job.progress ?? 5).catch(() => {});
-                    db
-                      .update(generationJob)
-                      .set({ progressMessage: `Generating... (~${approxTokens} tokens)` })
-                      .where(eq(generationJob.id, jobId))
-                      .catch(() => {});
-                  }
-                },
+                onToken: tokenCounter,
               });
       } catch (quickErr: any) {
         const quickErrorMessage = quickErr?.message ?? String(quickErr);
@@ -241,6 +242,7 @@ export const generationWorker = new Worker(
               p.steps[p.currentStep]?.message ?? p.steps[p.currentStep]?.step ?? "Processing...";
             await updateProgress(stepProgress, msg);
           },
+          tokenCounter,
         );
       }
 
@@ -435,6 +437,7 @@ export async function enqueueGeneration(
       questionCount: input.questionCount,
       status: "pending",
       progress: 0,
+      inputJson: input as any,
     })
     .returning();
 

packages/api/src/routers/ai.ts

@@ -109,6 +109,35 @@ export const aiRouter = router({
     };
   }),
 
+  retryJob: protectedProcedure
+    .input(z.object({ jobId: z.string().uuid() }))
+    .mutation(async ({ ctx, input }) => {
+      const [job] = await db
+        .select()
+        .from(generationJob)
+        .where(eq(generationJob.id, input.jobId))
+        .limit(1);
+
+      if (!job) throw new Error("Job tidak ditemukan");
+      if (job.userId !== ctx.session.user.id) throw new Error("Tidak diizinkan");
+      if (job.status !== "failed" && job.status !== "cancelled") {
+        throw new Error("Hanya job yang gagal atau dibatalkan yang bisa di-retry");
+      }
+
+      if (!job.inputJson || typeof job.inputJson !== "object") {
+        throw new Error("Data input job tidak tersedia untuk retry");
+      }
+
+      const jobInput = job.inputJson as any;
+      // Ensure the parsed input has the apiKeyConfig shape the pipeline expects
+      if (!jobInput.apiKeyConfig?.baseUrl || !jobInput.apiKeyConfig?.apiKey || !jobInput.apiKeyConfig?.model) {
+        throw new Error("Konfigurasi API key tidak valid untuk retry");
+      }
+
+      const newJobId = await enqueueGeneration(ctx.session.user.id, jobInput);
+      return { jobId: newJobId };
+    }),
+
   saveQuestions: protectedProcedure
     .input(
       z.object({

packages/db/src/schema/app.ts

@@ -513,6 +513,7 @@ export const generationJob = pgTable(
     progressMessage: text("progress_message"),
     logs: jsonb("logs"), // Array of {step, message, timestamp, status}
     resultJson: jsonb("result_json"), // GenerationResult
+    inputJson: jsonb("input_json"), // GenerationInput (stored for retry)
     errorMessage: text("error_message"),
     tokensUsed: integer("tokens_used"),
     durationMs: integer("duration_ms"),