Study/server/ai/generate.ts
Elijah 7125dec3e0
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Restore a full backup from Settings
Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:33:42 -07:00

1492 lines
82 KiB
TypeScript

/**
* Content generation: quizzes, flashcards and study guides from documents, pasted text,
* existing decks/quizzes, weak areas, or a plain topic.
*
* Every job writes into a draft row. Nothing reaches the library until the user has
* reviewed the draft and saved it. Long jobs are split into batches, each with its own
* slice of source material, so output limits and context windows are never a problem.
*/
import { z } from 'zod';
import {
validateDraftCard,
validateDraftQuestion,
type ContentDraft,
type DeckDraft,
type DraftCard,
type DraftQuestion,
type NoteDraft,
type QuizDraft,
} from '../../shared/content.ts';
import { draftsFromValue } from '../../shared/importer.ts';
import type { DB } from '../db.ts';
import { badRequest, notFound, type AppContext } from '../http.ts';
import { missedQuestionIds } from '../services/attempts.ts';
import {
createDeck,
createNote,
createQuiz,
draftCardToInput,
draftQuestionToInput,
getClass,
getDeck,
getQuiz,
insertCards,
insertQuestions,
listCards,
listQuestions,
updateQuestion,
} from '../services/content.ts';
import { chunkById, formatExcerpts, searchChunks, selectContext, sourceLabel, type ChunkHit } from '../services/documents.ts';
import { hybridSearch } from '../services/semantic.ts';
import { weakTopics } from '../services/stats.ts';
import { getSetting, setSetting } from '../settings.ts';
import { newId, now, parseJson } from '../util.ts';
import { generateStructured, outputBudget, resolveModel, runChat, runChatWithMcp } from './service.ts';
import { openerAdvice, repeatedOpeners, varyOpeners } from './openers.ts';
import { applyQuizFixes, proofreadQuiz, verifyQuizDraft, type QuizCheck } from './verify.ts';
/** Most quiz checks per generation: the first, then re-checks after fixes and replacements. */
const VERIFY_ROUNDS = 3;
/** Writing batches run at the same time, this many per wave. */
const WRITE_WAVE = 4;
import { AIError } from './types.ts';
/* ------------------------------ drafts ------------------------------ */
interface DraftRow {
id: string;
kind: 'quiz' | 'deck' | 'note';
class_id: string | null;
folder_id: string | null;
title: string;
payload: string;
meta: string;
status: 'generating' | 'ready' | 'failed' | 'saved' | 'discarded';
progress: number;
progress_label: string;
error: string;
saved_kind: string | null;
saved_id: string | null;
conversation_id: string | null;
/** Made by a visitor of this share link (saved to the library automatically when done). */
share_id: string | null;
created_at: number;
updated_at: number;
}
export interface DraftMeta {
origin?: 'generate' | 'assistant' | 'convert' | 'improve' | 'import' | 'share';
model?: string;
request?: Record<string, unknown>;
sources?: { documentId: string; title: string }[];
/** For "improve" drafts: the stored question each draft question replaces (same order). */
replaceQuestionIds?: string[];
/** Suggested target when the draft is meant to extend an existing item. */
targetKind?: 'quiz' | 'deck';
targetId?: string;
notes?: string[];
}
function emptyPayload(kind: DraftRow['kind'], title = ''): ContentDraft {
if (kind === 'quiz') return { kind: 'quiz', title, description: '', questions: [] };
if (kind === 'deck') return { kind: 'deck', title, description: '', cards: [] };
return { kind: 'note', title, content: '' };
}
export function mapDraft(row: DraftRow) {
const payload = parseJson<ContentDraft>(row.payload, emptyPayload(row.kind, row.title));
return {
id: row.id,
kind: row.kind,
classId: row.class_id,
folderId: row.folder_id,
title: row.title,
payload,
meta: parseJson<DraftMeta>(row.meta, {}),
status: row.status,
progress: row.progress,
progressLabel: row.progress_label,
error: row.error,
savedKind: row.saved_kind,
savedId: row.saved_id,
conversationId: row.conversation_id,
shareId: row.share_id ?? null,
itemCount: payload.kind === 'quiz' ? payload.questions.length : payload.kind === 'deck' ? payload.cards.length : payload.content.length,
createdAt: row.created_at,
updatedAt: row.updated_at,
};
}
export type DraftDto = ReturnType<typeof mapDraft>;
export function getDraft(db: DB, id: string): DraftDto {
const row = db.get<DraftRow>('SELECT * FROM drafts WHERE id = ?', id);
if (!row) throw notFound('Draft');
return mapDraft(row);
}
export function createDraft(
db: DB,
input: {
kind: DraftRow['kind'];
classId?: string | null;
folderId?: string | null;
title: string;
payload?: ContentDraft;
meta?: DraftMeta;
status?: DraftRow['status'];
conversationId?: string | null;
shareId?: string | null;
},
): string {
const id = newId();
const at = now();
db.run(
`INSERT INTO drafts (id, kind, class_id, folder_id, title, payload, meta, status, conversation_id, share_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
id,
input.kind,
input.classId ?? null,
input.folderId ?? null,
input.title.slice(0, 200),
JSON.stringify(input.payload ?? emptyPayload(input.kind, input.title)),
JSON.stringify(input.meta ?? {}),
input.status ?? 'ready',
input.conversationId ?? null,
input.shareId ?? null,
at,
at,
);
return id;
}
export function listDrafts(db: DB) {
return db
.all<DraftRow>(`SELECT * FROM drafts WHERE status IN ('generating', 'ready', 'failed') ORDER BY updated_at DESC LIMIT 50`)
.map(mapDraft)
.map(({ payload: _payload, ...rest }) => rest);
}
export function updateDraftPayload(db: DB, id: string, payload: ContentDraft, extra: { classId?: string | null; folderId?: string | null } = {}): DraftDto {
const draft = getDraft(db, id);
if (draft.status === 'generating') throw badRequest('This draft is still being generated');
if (payload.kind !== draft.kind) throw badRequest('Draft type cannot change');
db.run(
'UPDATE drafts SET payload = ?, title = ?, class_id = ?, folder_id = ?, updated_at = ? WHERE id = ?',
JSON.stringify(payload),
(payload.title ?? '').slice(0, 200),
extra.classId === undefined ? draft.classId : extra.classId,
extra.folderId === undefined ? draft.folderId : extra.folderId,
now(),
id,
);
return getDraft(db, id);
}
export const draftSaveSchema = z.object({
classId: z.string().optional(),
folderId: z.string().nullish(),
/** new: create an item. append: add to an existing quiz/deck. replace: apply improved questions in place. */
mode: z.enum(['new', 'append', 'replace']).default('new'),
targetId: z.string().optional(),
});
/** Turns a reviewed draft into real content. Invalid items are rejected, never silently dropped. */
export function saveDraft(app: AppContext, id: string, input: z.input<typeof draftSaveSchema>): { kind: string; id: string; count: number } {
const { db } = app;
const opts = draftSaveSchema.parse(input);
const draft = getDraft(db, id);
if (draft.status === 'generating') throw badRequest('This draft is still being generated');
if (draft.status === 'saved' && draft.savedId) return { kind: draft.savedKind ?? draft.kind, id: draft.savedId, count: 0 };
const payload = draft.payload;
const classId = opts.classId ?? draft.classId;
let result: { kind: string; id: string; count: number };
if (payload.kind === 'quiz') {
const bad = payload.questions.flatMap((q, i) => validateDraftQuestion(q, i)).filter((x) => x.level === 'error');
if (bad.length > 0) throw badRequest(`Question ${(bad[0].index ?? 0) + 1}: ${bad[0].message}`, bad);
if (payload.questions.length === 0) throw badRequest('There are no questions to save');
const inputs = payload.questions.map(draftQuestionToInput);
if (opts.mode === 'replace') {
const ids = draft.meta.replaceQuestionIds ?? [];
const quizId = opts.targetId ?? draft.meta.targetId;
if (!quizId) throw badRequest('No quiz to update');
getQuiz(db, quizId);
db.tx(() => {
inputs.forEach((q, i) => {
const target = ids[i];
if (target && db.get('SELECT id FROM questions WHERE id = ? AND quiz_id = ?', target, quizId)) updateQuestion(db, target, q);
else insertQuestions(db, quizId, [q]);
});
});
result = { kind: 'quiz', id: quizId, count: inputs.length };
} else if (opts.mode === 'append') {
const quizId = opts.targetId ?? draft.meta.targetId;
if (!quizId) throw badRequest('Choose a quiz to add these questions to');
getQuiz(db, quizId);
insertQuestions(db, quizId, inputs);
result = { kind: 'quiz', id: quizId, count: inputs.length };
} else {
if (!classId) throw badRequest('Choose a class to save this quiz in');
const quiz = createQuiz(db, { classId, folderId: opts.folderId ?? draft.folderId, title: payload.title.trim() || 'Untitled quiz', description: payload.description, questions: inputs });
result = { kind: 'quiz', id: quiz.id, count: inputs.length };
}
} else if (payload.kind === 'deck') {
const bad = payload.cards.flatMap((c, i) => validateDraftCard(c, i)).filter((x) => x.level === 'error');
if (bad.length > 0) throw badRequest(`Card ${(bad[0].index ?? 0) + 1}: ${bad[0].message}`, bad);
if (payload.cards.length === 0) throw badRequest('There are no cards to save');
const inputs = payload.cards.map(draftCardToInput);
if (opts.mode === 'append') {
const deckId = opts.targetId ?? draft.meta.targetId;
if (!deckId) throw badRequest('Choose a deck to add these cards to');
getDeck(db, deckId);
insertCards(db, deckId, inputs);
result = { kind: 'deck', id: deckId, count: inputs.length };
} else {
if (!classId) throw badRequest('Choose a class to save this deck in');
const deck = createDeck(db, { classId, folderId: opts.folderId ?? draft.folderId, title: payload.title.trim() || 'Untitled deck', description: payload.description, cards: inputs });
result = { kind: 'deck', id: deck.id, count: inputs.length };
}
} else {
if (!payload.content.trim()) throw badRequest('The note is empty');
if (!classId) throw badRequest('Choose a class to save this note in');
const note = createNote(db, {
classId,
folderId: opts.folderId ?? draft.folderId,
title: payload.title.trim() || 'Untitled note',
content: payload.content,
kind: 'guide',
source: { model: draft.meta.model, sources: draft.meta.sources },
});
result = { kind: 'note', id: note.id, count: 1 };
}
db.run(`UPDATE drafts SET status = 'saved', saved_kind = ?, saved_id = ?, updated_at = ? WHERE id = ?`, result.kind, result.id, now(), id);
return result;
}
export function discardDraft(db: DB, id: string): void {
cancelGeneration(id);
const { changes } = db.run(`UPDATE drafts SET status = 'discarded', updated_at = ? WHERE id = ?`, now(), id);
if (!changes) throw notFound('Draft');
}
/** Removes finished drafts after a while and marks jobs interrupted by a restart as failed. */
export function tidyDrafts(db: DB): void {
db.run(`UPDATE drafts SET status = 'failed', error = 'Generation was interrupted by a restart. Start it again.' WHERE status = 'generating'`);
db.run(`DELETE FROM drafts WHERE status IN ('saved', 'discarded') AND updated_at < ?`, now() - 14 * 86_400_000);
db.run(`DELETE FROM drafts WHERE status IN ('ready', 'failed') AND updated_at < ?`, now() - 60 * 86_400_000);
}
/* ------------------------------ request ------------------------------ */
export const generateRequestSchema = z.object({
kind: z.enum(['quiz', 'deck', 'note']),
classId: z.string().nullish(),
folderId: z.string().nullish(),
title: z.string().trim().max(200).optional(),
source: z
.object({
documentIds: z.array(z.string()).max(50).optional(),
/** Use every processed document in the class, or in the exam (folder) when folderId is set. */
allClassDocuments: z.boolean().optional(),
text: z.string().max(400_000).optional(),
quizId: z.string().optional(),
deckId: z.string().optional(),
noteId: z.string().optional(),
/** Build from the questions the user keeps missing. */
weakAreas: z.boolean().optional(),
})
.default({}),
/** Topic or focus, e.g. "pediatric respiratory disorders". */
focus: z.string().trim().max(600).optional(),
instructions: z.string().trim().max(4000).optional(),
count: z.number().int().min(1).max(200).optional(),
/** Kept for old presets and API callers; every quiz is written NCLEX style. */
style: z.enum(['nclex', 'standard', 'recall']).optional(),
/** practice: a short set (default 15). exam: a full practice exam (default 50, at most 5 calculations). */
format: z.enum(['practice', 'exam']).optional(),
difficulty: z.enum(['easy', 'medium', 'hard', 'mixed']).optional(),
/** Share of select-all-that-apply questions, 0..1. */
sataShare: z.number().min(0).max(1).optional(),
/**
* Quizzes: exactly this many medication math (dosage calculation) questions, written at the
* chosen difficulty even when the material has no calculations. Absent: calculations only
* when the material involves them.
*/
mathQuestions: z.number().int().min(0).max(25).optional(),
cardStyle: z.enum(['concise', 'detailed', 'medication', 'definition']).optional(),
noteStyle: z.enum(['study_guide', 'summary', 'outline', 'cheat_sheet']).optional(),
modelId: z.string().nullish(),
/** Quizzes: check the finished draft with the model and the Python sandbox (default on). */
verify: z.boolean().optional(),
});
export type GenerateRequest = z.infer<typeof generateRequestSchema>;
/* ------------------------------ prompts ------------------------------ */
/** How a rationale is laid out, so it reads at a glance instead of as one block of text. */
const RATIONALE_FORMAT =
'Format the rationale in Markdown for quick reading: one bold sentence with the key point, then 2 to 4 short bullet points (one idea each, such as the principle or framework, the physiology or drug action, the safety point). No long paragraphs, and do not repeat the choices\' "why" text, which is shown beside each choice.';
const QUESTION_SCHEMA = {
type: 'object',
properties: {
questions: {
type: 'array',
items: {
type: 'object',
properties: {
type: {
type: 'string',
enum: ['single', 'multi', 'numeric'],
description: 'single = one correct answer; multi = select all that apply; numeric = a calculation the student answers by typing the number',
},
stem: { type: 'string', description: 'The question. Markdown allowed.' },
options: {
type: 'array',
description: 'Answer choices. For numeric questions: exactly one option, the correct answer with its unit (e.g. "12.5 mL"), correct = true, and "why" showing the calculation.',
items: {
type: 'object',
properties: {
text: { type: 'string' },
correct: { type: 'boolean' },
why: { type: 'string', description: 'One sentence on why this choice is right or wrong.' },
},
required: ['text', 'correct', 'why'],
},
},
rationale: { type: 'string', description: `Teaching explanation of the correct answer. ${RATIONALE_FORMAT}` },
topic: {
type: 'string',
description: 'Broad topic: the main condition, drug class or body system in 1-3 words (e.g. "Stroke", "Heart failure", "Anticoagulants"). Never a subtype or aspect such as "Hemorrhagic stroke" or "Heparin client teaching". Reuse the same label for every question on that subject.',
},
difficulty: { type: 'string', enum: ['easy', 'medium', 'hard'] },
source: { type: 'string', description: 'Id of the excerpt this question is based on, e.g. "c42". Empty if none.' },
},
required: ['type', 'stem', 'options', 'rationale', 'topic', 'difficulty'],
},
},
},
required: ['questions'],
};
const CARD_SCHEMA = {
type: 'object',
properties: {
cards: {
type: 'array',
items: {
type: 'object',
properties: {
front: { type: 'string', description: 'Prompt side: one specific question about one fact.' },
back: { type: 'string', description: 'Only the answer: a word, number or short phrase. No explanation.' },
tags: { type: 'array', items: { type: 'string' }, description: '1-2 short topic tags.' },
},
required: ['front', 'back'],
},
},
},
required: ['cards'],
};
/** What the medication math questions look like at each difficulty, when the user asks for them. */
const MATH_LEVELS: Record<string, string> = {
easy: 'single-step problems: tablets or capsules per dose, mL of an oral liquid, and simple unit conversions (g, mg, mcg; L, mL; lb to kg)',
medium: 'weight-based doses (mg/kg), mL to draw up from a vial, and IV pump rates in mL/h',
hard: 'multi-step problems: gravity drip rates in gtt/min with a drop factor, mcg/kg/min titrations, heparin units/h from a protocol, and reconstituted medications',
mixed: 'a spread from single-step dose and conversion problems to weight-based doses, IV pump rates (mL/h) and drip rates (gtt/min)',
};
const NUMERIC_RULE = `- Only write calculation items when the source material itself involves calculations (or the request asks for medication math), and never more than the number allowed in the request. Calculation items (dosages, weight-based doses, IV and drip rates, conversions, intake and output) use type "numeric": the student types the number instead of choosing. Give exactly one option, the correct answer with its unit (for example "12.5 mL"), marked correct, with "why" showing the working. State the unit and the rounding rule in the stem ("Round to the nearest tenth."). Only the number is checked, so the student may leave out the unit.`;
const NCLEX_RULES = `Write NCLEX-style (Next Generation NCLEX) items:
- Test clinical judgment at the application and analysis level: recognise cues, analyse, prioritise, choose and evaluate actions. Avoid pure recall.
- Give a brief, realistic client scenario containing only relevant data (age, diagnosis, key findings, vital signs or lab values with units).
- Vary how stems open, as a real exam does: with the client ("A 68-year-old client…", "A client with…"), the nurse's situation ("The nurse is caring for…", "After receiving report…"), the setting or role ("In the emergency department…", "The charge nurse…", "During discharge teaching…"), a finding, order or report ("A client with heart failure reports…", "The health care provider prescribes…"), or the question itself. Mix these so no single opening dominates the quiz.
- Ask one clear question. Use priority wording where it fits (first, best, most important, requires immediate follow-up) and build it on a real framework: ABCs, Maslow, the nursing process, acute before chronic, unstable before stable, safety, least invasive first.
- Cover the client-needs areas where the material allows: safe and effective care, pharmacology, physiological adaptation, reduction of risk, health promotion, psychosocial integrity, delegation and assignment.
- Every distractor must be plausible to a student with partial knowledge and wrong for a specific reason. Keep choices parallel in grammar and similar in length. Never use "all of the above" or "none of the above". Do not give the answer away through wording or length.
- Multiple-choice items have exactly 4 choices with exactly one best answer. Select-all-that-apply items have 5 or 6 choices with 2 to 5 correct, and the stem ends with "Select all that apply."
- Use generic drug names. Use current, standard practice.
- The rationale teaches: state why the correct answer is correct, name the principle behind it, and give each choice its own "why".
- ${RATIONALE_FORMAT}
${NUMERIC_RULE}`;
const CARD_RULES: Record<string, string> = {
concise:
`Atomic cards: each card tests exactly one fact, so it can be learned in one look. The front asks one specific question (never "describe" or "explain"). The back is only the answer: a word, a number with its unit, or a short phrase, ideally under 10 words and never more than one short sentence. No explanations, reasons, lists or paragraphs on the back. Split anything with several parts (a drug's class, action and side effects; the signs of a condition) into separate cards.`,
detailed: 'Each card covers one concept. The back is at most 3 short bullet points (a few words each), no paragraphs.',
medication:
'Make medication cards. Front: the generic drug name (with a common brand name in parentheses when well known). Back: a Markdown list with **Class**, **Action**, **Uses**, **Adverse effects** (the most important ones), **Nursing considerations** and **Client teaching**. Only include what the material supports.',
definition: 'Make term and definition cards. Front: the term. Back: a precise definition in one or two sentences, plus an example when useful.',
};
const NOTE_RULES: Record<string, string> = {
study_guide:
'Write a study guide in Markdown: a one-paragraph overview, then sections with headings. Under each heading give the key concepts as tight bullet points, important values and medications in tables where that helps, common pitfalls, and finish with a "Check yourself" list of 5-10 self-test questions (answers at the very end).',
summary: 'Write a faithful summary in Markdown: a short overview paragraph, then the main points grouped under headings. Keep it compact and do not add outside information.',
outline: 'Write a hierarchical outline in Markdown using nested bullet points. Capture the structure and every key point of the material without full sentences where a phrase will do.',
cheat_sheet: 'Write a one-page cheat sheet in Markdown: dense, scannable, organised under short headings, using tables for values, drug classes and comparisons, and bold for must-know facts.',
};
const BASE_ROLE = 'You are an expert educator writing study material for a nursing student. Accuracy is critical: this material is used to prepare for licensing exams.';
/* ------------------------------ editable instructions ------------------------------ */
/**
* The instructions the built-in generator (Generate and the assistant) sends to the model.
* Every entry can be replaced in Settings → Templates; an absent value means the built-in
* wording. These are separate from the instructions for outside chatbots
* (`LLM_INSTRUCTIONS`), which also have to describe the import JSON format.
*/
export const GENERATION_INSTRUCTIONS = {
base: { group: 'All content', label: 'Role', text: BASE_ROLE },
'quiz.nclex': { group: 'Quiz questions', label: 'NCLEX style', text: NCLEX_RULES },
'deck.concise': { group: 'Flashcards', label: 'Concise', text: CARD_RULES.concise },
'deck.detailed': { group: 'Flashcards', label: 'Detailed', text: CARD_RULES.detailed },
'deck.medication': { group: 'Flashcards', label: 'Medication', text: CARD_RULES.medication },
'deck.definition': { group: 'Flashcards', label: 'Term and definition', text: CARD_RULES.definition },
'note.study_guide': { group: 'Study guides', label: 'Study guide', text: NOTE_RULES.study_guide },
'note.summary': { group: 'Study guides', label: 'Summary', text: NOTE_RULES.summary },
'note.outline': { group: 'Study guides', label: 'Outline', text: NOTE_RULES.outline },
'note.cheat_sheet': { group: 'Study guides', label: 'Cheat sheet', text: NOTE_RULES.cheat_sheet },
} as const;
export type InstructionKey = keyof typeof GENERATION_INSTRUCTIONS;
const INSTRUCTIONS_SETTING = 'ai.instructions';
export function instructionOverrides(db: DB): Partial<Record<InstructionKey, string>> {
return getSetting<Partial<Record<InstructionKey, string>>>(db, INSTRUCTIONS_SETTING, {});
}
export function instruction(db: DB, key: InstructionKey): string {
const own = instructionOverrides(db)[key];
return own?.trim() ? own : GENERATION_INSTRUCTIONS[key].text;
}
export function listInstructions(db: DB) {
const own = instructionOverrides(db);
return (Object.keys(GENERATION_INSTRUCTIONS) as InstructionKey[]).map((key) => ({
key,
group: GENERATION_INSTRUCTIONS[key].group,
label: GENERATION_INSTRUCTIONS[key].label,
text: own[key]?.trim() ? own[key]! : GENERATION_INSTRUCTIONS[key].text,
builtin: GENERATION_INSTRUCTIONS[key].text,
customized: Boolean(own[key]?.trim()),
}));
}
export const instructionPatchSchema = z.object({
key: z.enum(Object.keys(GENERATION_INSTRUCTIONS) as [InstructionKey, ...InstructionKey[]]),
/** null restores the built-in wording. */
text: z.string().trim().min(10).max(20_000).nullable(),
});
export function saveInstruction(db: DB, input: z.input<typeof instructionPatchSchema>): void {
const { key, text } = instructionPatchSchema.parse(input);
const next = { ...instructionOverrides(db) };
if (text === null || text === GENERATION_INSTRUCTIONS[key].text) delete next[key];
else next[key] = text;
setSetting(db, INSTRUCTIONS_SETTING, next);
}
function baseSystem(db: DB, req: GenerateRequest, hasSources: boolean): string {
const lines = [
instruction(db, 'base'),
hasSources
? 'Base everything on the provided source material. Do not introduce facts that contradict it. You may rely on standard, well-established knowledge only to write plausible distractors and clear explanations.'
: 'No source material was provided, so rely on current, well-established knowledge. If something is uncertain or varies by institution, prefer the most widely taught standard.',
'Write in clear, natural English. Use Markdown inside text fields where it aids clarity (bold key terms, short lists, tables). Do not wrap output in code fences.',
];
if (req.instructions) lines.push(`Additional instructions from the student (follow them unless they conflict with accuracy):\n${req.instructions}`);
return lines.join('\n\n');
}
/* ------------------------------ source gathering ------------------------------ */
interface Sources {
/** Batches of excerpts (documents). */
groups: ChunkHit[][];
/** Free text used as-is (pasted notes, an existing deck or quiz, missed questions). */
inline: string;
docs: { documentId: string; title: string }[];
refs: Map<string, string>;
totalTokens: number;
}
async function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: number, groups: number): Promise<Sources> {
const { db } = app;
const src = req.source;
const out: Sources = { groups: [], inline: '', docs: [], refs: new Map(), totalTokens: 0 };
const inline: string[] = [];
let documentIds = src.documentIds ?? [];
if (src.allClassDocuments && req.folderId) {
// An exam's material only: generating for Exam 2 never draws on Exam 1's slides.
documentIds = db.all<{ id: string }>(`SELECT id FROM documents WHERE folder_id = ? AND status = 'ready' AND chunk_count > 0 ORDER BY sort_order, created_at`, req.folderId).map((d) => d.id);
if (documentIds.length === 0) throw badRequest('This exam has no processed documents yet. Upload its slides or notes first, or choose documents yourself.');
} else if (src.allClassDocuments && req.classId) {
documentIds = db.all<{ id: string }>(`SELECT id FROM documents WHERE class_id = ? AND status = 'ready' AND chunk_count > 0 ORDER BY sort_order, created_at`, req.classId).map((d) => d.id);
}
if (documentIds.length > 0) {
const rows = db.all<{ id: string; title: string; status: string; chunk_count: number }>(
`SELECT id, title, status, chunk_count FROM documents WHERE id IN (${documentIds.map(() => '?').join(',')})`,
...documentIds,
);
const usable = rows.filter((r) => r.status === 'ready' && r.chunk_count > 0);
if (usable.length === 0) {
throw badRequest(rows.some((r) => r.status !== 'ready') ? 'Those documents are still being processed. Try again in a moment.' : 'Those documents have no readable text yet.');
}
out.docs = usable.map((r) => ({ documentId: r.id, title: r.title }));
const scope = { documentIds: usable.map((r) => r.id) };
const ranked = req.focus?.trim() ? await hybridSearch(app, req.focus, scope, 400) : undefined;
out.groups = selectContext(db, scope, { focus: req.focus, budgetTokens, groups, ranked });
}
if (src.text?.trim()) inline.push(`Notes provided by the student:\n${src.text.trim()}`);
if (src.noteId) {
const note = db.get<{ title: string; content: string }>('SELECT title, content FROM notes WHERE id = ?', src.noteId);
if (note) inline.push(`Note "${note.title}":\n${note.content}`);
}
if (src.deckId) {
const deck = getDeck(db, src.deckId);
const cards = listCards(db, deck.id);
if (cards.length === 0) throw badRequest('That deck has no cards');
inline.push(`Flashcards from the deck "${deck.title}":\n${cards.map((c, i) => `${i + 1}. ${c.front}\n -> ${c.back}`).join('\n')}`);
}
if (src.quizId) {
const quiz = getQuiz(db, src.quizId);
const questions = listQuestions(db, quiz.id);
if (questions.length === 0) throw badRequest('That quiz has no questions');
inline.push(
`Questions from the quiz "${quiz.title}":\n${questions
.map((q, i) => `${i + 1}. ${q.stem}\n Correct: ${q.options.filter((o) => o.correct).map((o) => o.text).join('; ')}\n Rationale: ${q.rationale}`)
.join('\n')}`,
);
}
if (src.weakAreas) {
const scope = { classId: req.classId ?? undefined, folderId: req.folderId ?? undefined };
const ids = missedQuestionIds(db, scope, 40);
const topics = weakTopics(db, scope, 10);
if (ids.length === 0 && topics.length === 0) throw badRequest('There is not enough quiz history yet to find weak areas. Take a few quizzes first.');
const missed = ids
.map((id) => db.get<{ stem: string; topic: string; rationale: string }>('SELECT stem, topic, rationale FROM questions WHERE id = ?', id))
.filter((q): q is { stem: string; topic: string; rationale: string } => Boolean(q));
inline.push(
[
'The student keeps missing these concepts. Write NEW items that test the same underlying knowledge from different angles. Do not repeat or lightly reword the original questions.',
topics.length ? `Weakest topics: ${topics.map((t) => `${t.topic} (${Math.round(t.accuracy * 100)}% correct)`).join(', ')}` : '',
missed.length ? `Questions answered incorrectly:\n${missed.map((q, i) => `${i + 1}. [${q.topic || 'General'}] ${q.stem}\n Key point: ${q.rationale.slice(0, 400)}`).join('\n')}` : '',
]
.filter(Boolean)
.join('\n\n'),
);
// Pull supporting passages from the class documents for those topics.
if (req.classId && out.groups.length === 0) {
const query = [...topics.map((t) => t.topic), ...missed.slice(0, 10).map((q) => q.topic)].filter(Boolean).join(' ');
const examDocs = req.folderId ? db.all<{ id: string }>(`SELECT id FROM documents WHERE folder_id = ? AND status = 'ready'`, req.folderId).map((d) => d.id) : [];
const hits = query ? await hybridSearch(app, query, examDocs.length ? { documentIds: examDocs } : { classId: req.classId }, 24) : [];
if (hits.length > 0) {
const perGroup = Math.max(1, Math.ceil(hits.length / groups));
for (let i = 0; i < hits.length; i += perGroup) out.groups.push(hits.slice(i, i + perGroup));
}
}
}
out.inline = inline.join('\n\n');
for (const g of out.groups) for (const c of g) out.refs.set(`c${c.id}`, sourceLabel(c));
out.totalTokens = out.groups.reduce((n, g) => n + g.reduce((m, c) => m + c.tokens, 0), 0) + Math.ceil(out.inline.length / 4);
return out;
}
function sourceBlock(sources: Sources, groupIndex: number): string {
const parts: string[] = [];
const group = sources.groups.length > 0 ? sources.groups[groupIndex % sources.groups.length] : [];
if (group.length > 0) parts.push(`SOURCE EXCERPTS (each starts with its id in brackets):\n\n${formatExcerpts(group)}`);
if (sources.inline) parts.push(sources.inline);
return parts.join('\n\n======\n\n');
}
/* ------------------------------ job control ------------------------------ */
const running = new Map<string, AbortController>();
export function cancelGeneration(draftId: string): void {
running.get(draftId)?.abort();
running.delete(draftId);
}
/** Stops every running generation (before a full backup replaces the database). */
export function cancelAllGenerations(): number {
const n = running.size;
for (const c of running.values()) c.abort();
running.clear();
return n;
}
/** Listeners for a running job's progress labels (the assistant shows them on its tool step). */
const progressListeners = new Map<string, (label: string) => void>();
function setProgress(db: DB, id: string, progress: number, label: string, payload?: ContentDraft): void {
if (label) progressListeners.get(id)?.(label);
if (payload) {
db.run('UPDATE drafts SET progress = ?, progress_label = ?, payload = ?, updated_at = ? WHERE id = ?', progress, label, JSON.stringify(payload), now(), id);
} else {
db.run('UPDATE drafts SET progress = ?, progress_label = ?, updated_at = ? WHERE id = ?', progress, label, now(), id);
}
}
function defaultTitle(app: AppContext, req: GenerateRequest, sources: Sources): string {
if (req.title) return req.title;
const subject =
req.focus?.replace(/\s+/g, ' ').slice(0, 80) ||
(sources.docs.length === 1 ? sources.docs[0].title : '') ||
(req.source.deckId ? getDeck(app.db, req.source.deckId).title : '') ||
(req.source.quizId ? getQuiz(app.db, req.source.quizId).title : '') ||
(req.source.weakAreas ? 'Weak areas' : '') ||
(req.classId ? getClass(app.db, req.classId).name : 'Untitled');
const suffix = req.kind === 'quiz' ? (req.source.weakAreas ? 'practice' : req.format === 'exam' ? 'NCLEX practice exam' : 'NCLEX practice') : req.kind === 'deck' ? 'flashcards' : NOTE_TITLES[req.noteStyle ?? 'study_guide'];
const cap = subject.charAt(0).toUpperCase() + subject.slice(1);
return `${cap} · ${suffix}`.slice(0, 200);
}
/* ------------------------------ quiz helpers ------------------------------ */
const CALCULATION_RE =
/\b(dosage calculation|dose calculation|calculat\w*|mg\/kg|mcg\/kg|units?\/kg|mg\/m2|ml\/h(?:r|our)?|ml per hour|gtt\/min|gtts?|drops? per minute|drop factor|drip rate|flow rate|infusion rate|units?\/ml|mg\/ml|mcg\/ml|round(?:ed)? to the nearest|body surface area|desired over have|dimensional analysis|intake and output|i ?& ?o)\b/i;
const TOPIC_SCHEMA = {
type: 'object',
properties: {
topics: {
type: 'array',
items: { type: 'object', properties: { label: { type: 'string' }, topic: { type: 'string', description: 'Broad topic, 1-2 words' } }, required: ['label', 'topic'] },
},
},
required: ['topics'],
};
/**
* Maps the topic labels of a new quiz onto a few broad topics ("Heparin client teaching" ->
* "Heparin") with one quick model call, reusing the class's existing broad topics. Any failure
* keeps the labels as they are.
*/
async function broadenTopics(app: AppContext, modelId: string | null | undefined, labels: string[], known: string[], signal: AbortSignal): Promise<Map<string, string>> {
const out = new Map<string, string>();
const broadKnown = [...new Set(known.filter((t) => t.trim() && t.trim().split(/\s+/).length <= 2))].slice(0, 40);
if (labels.length === 0 || labels.every((l) => broadKnown.includes(l))) return out;
try {
const result = await generateStructured(app, {
task: 'generate',
purpose: 'topic grouping',
modelId,
reasoningEffort: 'low',
maxOutputTokens: 2_000,
signal,
system: 'You organise nursing exam questions into topics.',
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: `Map each topic label below to a broad exam topic of 1-2 words, the way a test blueprint or textbook chapter names it: a condition, a drug or drug class, or a body system (for example "Stroke", "Heparin", "Anticoagulants", "Heart failure", "Fluid balance"). Leave the nursing activity (teaching, monitoring, plan of care, adverse effects, priorities) out of the topic. Labels about the same condition or drug must get the same topic.${broadKnown.length ? `\nReuse one of the class's existing topics when it fits: ${broadKnown.join(', ')}.` : ''}\n\nLabels:\n${labels.map((l) => `- ${l}`).join('\n')}`,
},
],
},
],
toolName: 'submit_topics',
toolDescription: 'Submit the broad topic for every label.',
schema: TOPIC_SCHEMA,
});
const rows = (result.data as { topics?: { label?: unknown; topic?: unknown }[] })?.topics ?? [];
for (const row of Array.isArray(rows) ? rows : []) {
const label = typeof row?.label === 'string' ? row.label.trim() : '';
const topic = typeof row?.topic === 'string' ? row.topic.replace(/\s+/g, ' ').trim() : '';
if (label && topic && topic.length <= 40 && topic.split(' ').length <= 4 && labels.includes(label)) out.set(label, topic);
}
} catch (err) {
if (err instanceof AIError && err.code === 'aborted') throw err;
}
return out;
}
/** Places the matching items at even intervals among the others, keeping each group's order. */
export function spreadEvenly<T>(list: T[], pick: (item: T) => boolean): T[] {
const chosen = list.filter(pick);
const rest = list.filter((x) => !pick(x));
if (chosen.length === 0 || rest.length === 0) return list;
const out: T[] = [];
const step = (rest.length + chosen.length) / chosen.length;
let next = Math.floor(step / 2);
let c = 0;
for (let i = 0, r = 0; i < list.length; i += 1) {
if (c < chosen.length && i >= next) {
out.push(chosen[c++]);
next = Math.floor(step / 2 + c * step);
} else if (r < rest.length) out.push(rest[r++]);
else out.push(chosen[c++]);
}
return out;
}
/** True when the material involves calculations, so calculation questions are fair game. */
export function mentionsCalculations(text: string): boolean {
return CALCULATION_RE.test(text);
}
function sourcesText(sources: { groups: { text: string }[][]; inline: string }): string {
return [sources.inline, ...sources.groups.flat().map((c) => c.text)].join('\n');
}
/** Random answer order, so the keyed answer is not always first. "All/none of the above" stay last. */
function shuffleOptions<T extends { text: string }>(options: T[]): T[] {
const pinned = options.filter((o) => /^(all|none|both|neither)\b.*\b(above|these)\b/i.test(o.text.trim()));
const free = options.filter((o) => !pinned.includes(o));
for (let i = free.length - 1; i > 0; i -= 1) {
const j = Math.floor(Math.random() * (i + 1));
[free[i], free[j]] = [free[j], free[i]];
}
return [...free, ...pinned];
}
/**
* Folds narrow topic labels into broad ones: case and spacing differences merge, and a label
* that contains another label as whole words ("Hemorrhagic stroke" and "Stroke") takes the
* broader one. Existing class topics win ties so results line up with earlier quizzes.
*/
export function consolidateTopics<T extends { topic: string }>(questions: T[], known: string[] = []): T[] {
const norm = (t: string) => t.toLowerCase().replace(/\s+/g, ' ').trim();
const canonical = new Map<string, string>();
for (const t of [...known, ...questions.map((q) => q.topic)]) if (t.trim() && !canonical.has(norm(t))) canonical.set(norm(t), t.trim());
const labels = [...canonical.keys()].sort((a, b) => a.length - b.length);
const target = (t: string): string => {
const n = norm(t);
if (!n) return t;
const broader = labels.find((l) => l !== n && l.length >= 4 && new RegExp(`(^|\\s)${l.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|\\s)`).test(n));
return canonical.get(broader ?? n) ?? t;
};
return questions.map((q) => ({ ...q, topic: target(q.topic) }));
}
const NOTE_TITLES: Record<string, string> = { study_guide: 'study guide', summary: 'summary', outline: 'outline', cheat_sheet: 'cheat sheet' };
/**
* Starts a generation job in the background and returns the draft id immediately.
* The caller polls the draft (or awaits `done`) for progress.
*/
export function startGeneration(
app: AppContext,
input: z.input<typeof generateRequestSchema>,
opts: {
conversationId?: string | null;
origin?: DraftMeta['origin'];
onProgress?: (label: string) => void;
shareId?: string;
/** Save the finished draft to the library straight away (share-link visitors' sets). */
autoSave?: { description: string };
} = {},
): { draftId: string; done: Promise<DraftDto> } {
const req = generateRequestSchema.parse(input);
if (req.classId) getClass(app.db, req.classId);
if (req.folderId) {
const folder = app.db.get<{ class_id: string }>('SELECT class_id FROM folders WHERE id = ?', req.folderId);
if (!folder || (req.classId && folder.class_id !== req.classId)) throw badRequest('That exam is not part of this class.');
}
// Fail fast (before creating a draft) when no model is configured.
const resolved = resolveModel(app, 'write', req.modelId);
const draftId = createDraft(app.db, {
kind: req.kind,
classId: req.classId ?? null,
folderId: req.folderId ?? null,
title: req.title ?? '',
status: 'generating',
conversationId: opts.conversationId ?? null,
shareId: opts.shareId ?? null,
meta: { origin: opts.origin ?? 'generate', model: resolved.model.label, request: { ...req, source: { ...req.source, text: req.source.text ? `${req.source.text.slice(0, 200)}…` : undefined } } },
});
const controller = new AbortController();
running.set(draftId, controller);
if (opts.onProgress) progressListeners.set(draftId, opts.onProgress);
const done = runWithRestart(app, draftId, req, controller.signal)
.catch((err) => {
const message = err instanceof AIError ? err.message : err instanceof Error && 'status' in err ? err.message : 'Generation failed unexpectedly.';
if (!(err instanceof AIError) && !(err instanceof Error && 'status' in err)) app.log('error', 'Generation failed', err);
try {
const current = app.db.get<{ status: string }>('SELECT status FROM drafts WHERE id = ?', draftId);
if (current?.status === 'generating') {
app.db.run(`UPDATE drafts SET status = 'failed', error = ?, updated_at = ? WHERE id = ?`, controller.signal.aborted ? 'Generation was cancelled.' : message, now(), draftId);
}
} catch {
/* the database was closed during shutdown; tidyDrafts marks the job failed on the next start */
}
})
.then(() => {
running.delete(draftId);
progressListeners.delete(draftId);
if (opts.autoSave) autoSaveDraft(app, draftId, opts.autoSave.description);
return getDraft(app.db, draftId);
});
return { draftId, done };
}
/**
* Saves a finished draft into its class (and exam) as if the owner had approved it. When saving
* fails, the draft stays in the owner's drafts to review.
*/
function autoSaveDraft(app: AppContext, draftId: string, description: string): void {
try {
const draft = getDraft(app.db, draftId);
if (draft.status !== 'ready' || (draft.payload.kind !== 'quiz' && draft.payload.kind !== 'deck')) return;
if (!draft.payload.description) updateDraftPayload(app.db, draftId, { ...draft.payload, description });
saveDraft(app, draftId, {});
} catch (err) {
app.log('warn', 'A share-link set could not be saved automatically; it is waiting in Drafts', err);
}
}
/** Failures worth starting the whole job over for: bad output and passing provider trouble. */
const RESTARTABLE = new Set(['invalid_response', 'server', 'timeout', 'network', 'rate_limit']);
/**
* Runs a generation job, and when it fails on bad model output (or a passing provider error)
* starts it over once with the same request. A second failure fails the draft.
*/
async function runWithRestart(app: AppContext, draftId: string, req: GenerateRequest, signal: AbortSignal): Promise<void> {
try {
await runGeneration(app, draftId, req, signal);
} catch (err) {
if (signal.aborted || !(err instanceof AIError) || !RESTARTABLE.has(err.code)) throw err;
app.log('warn', 'Generation failed; starting it over once', err.message);
const kind = req.kind;
app.db.run(
`UPDATE drafts SET payload = ?, progress = 0.02, progress_label = 'Starting over', updated_at = ? WHERE id = ? AND status = 'generating'`,
JSON.stringify(emptyPayload(kind, req.title ?? '')),
now(),
draftId,
);
progressListeners.get(draftId)?.('Starting over');
await runGeneration(app, draftId, req, signal);
}
}
async function runGeneration(app: AppContext, draftId: string, req: GenerateRequest, signal: AbortSignal): Promise<void> {
const { db } = app;
const resolved = resolveModel(app, 'write', req.modelId);
const window = resolved.model.contextWindow ?? 32_000;
const budgetTokens = Math.max(2_500, Math.min(Math.floor(window * 0.4), 28_000));
setProgress(db, draftId, 0.03, 'Reading your material');
if (req.kind === 'note') {
await generateNote(app, draftId, req, signal, budgetTokens, window);
return;
}
const isQuiz = req.kind === 'quiz';
const perBatch = isQuiz ? 8 : 25;
const defaultCount = isQuiz ? 15 : 30;
let count = req.count ?? (isQuiz && req.format === 'exam' ? 50 : defaultCount);
if ((req.source.deckId || req.source.quizId) && !req.count) {
// Conversions default to one item per source item.
count = req.source.deckId ? listCards(db, req.source.deckId).length : listQuestions(db, req.source.quizId!).length;
count = Math.min(Math.max(count, 1), 100);
}
const batches = Math.ceil(count / perBatch);
const sources = await gatherSources(app, req, budgetTokens, batches);
const hasSources = sources.groups.length > 0 || Boolean(sources.inline);
if (!hasSources && !req.focus && !req.instructions) throw badRequest('Choose source material or describe a topic to generate from.');
const title = defaultTitle(app, req, sources);
const draft: QuizDraft | DeckDraft = isQuiz ? { kind: 'quiz', title, description: '', questions: [] } : { kind: 'deck', title, description: '', cards: [] };
const items = (): (DraftQuestion | DraftCard)[] => (draft.kind === 'quiz' ? draft.questions : draft.cards);
const key = (x: DraftQuestion | DraftCard) => ('stem' in x ? x.stem : x.front).toLowerCase().replace(/\W+/g, ' ').trim().slice(0, 120);
const seen = new Set<string>();
const notes: string[] = [];
// Every quiz is NCLEX style (the student's exams are); older presets asking for another style get it too.
const style = 'nclex' as const;
const rules = isQuiz ? instruction(db, 'quiz.nclex') : instruction(db, `deck.${req.cardStyle ?? 'concise'}`);
const system = `${baseSystem(db, req, hasSources)}\n\n${rules}`;
const sata = req.sataShare ?? 0.3;
const difficulty = req.difficulty ?? 'mixed';
// Calculation questions: only when the material involves calculations, and at most 5 per
// 50-question exam (10% of a practice set).
const mathAllowed = isQuiz && mentionsCalculations([sourcesText(sources), req.focus ?? '', req.instructions ?? ''].join('\n'));
// Medication math on request: exactly that many, written in their own batches after the rest.
const forcedMath = isQuiz && req.mathQuestions !== undefined ? Math.min(req.mathQuestions, count) : null;
const regularCount = forcedMath === null ? count : count - forcedMath;
const numericCap =
forcedMath !== null ? forcedMath : !mathAllowed ? 0 : req.format === 'exam' ? Math.min(5, Math.max(1, Math.round(count / 10))) : Math.max(1, Math.round(count / 10));
const numericCount = () => (draft.kind === 'quiz' ? draft.questions.filter((q) => q.type === 'numeric').length : 0);
// Broad topic labels, shared with the class's existing quizzes so results group sensibly.
const knownTopics = isQuiz && req.classId ? db.all<{ topic: string }>(`SELECT DISTINCT q.topic FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE z.class_id = ? AND q.topic != '' LIMIT 60`, req.classId).map((r) => r.topic) : [];
const runBatch = async (index: number, want: number, math = false, parallel = false, angles: string[] = []): Promise<number> => {
const written = items().map((x) => `- ${('stem' in x ? x.stem : x.front).replace(/\s+/g, ' ').slice(0, 140)}`);
const sataCount = Math.round(want * sata);
// With requested math, the regular batches write none; the math batches write only those.
const numericLeft = forcedMath !== null && !math ? 0 : Math.max(0, numericCap - numericCount());
const topicsSoFar = [...new Set([...knownTopics, ...(draft.kind === 'quiz' ? draft.questions.map((q) => q.topic) : [])].filter(Boolean))];
const ask = math
? [
`Write ${want} medication math (dosage calculation) questions, all of type "numeric": the student types the number.`,
`Difficulty ${difficulty}: ${MATH_LEVELS[difficulty] ?? MATH_LEVELS.mixed}.`,
'These do not need to come from the course material: write standard nursing med math with realistic orders, labels and client weights, using generic drug names (drugs from the material are welcome where they fit).',
'Each stem gives the order and what is on hand, and states the unit and the rounding rule ("Round to the nearest tenth."). Exactly one option: the correct answer with its unit, marked correct, with "why" showing the working step by step (dimensional analysis or desired over have). The rationale explains the method and one safety check.',
'Set the topic to "Dosage calculation". Vary the problem types.',
]
: isQuiz
? [
`Write ${want} NCLEX-style questions${req.focus ? ` about: ${req.focus}` : ''}.`,
sata <= 0 ? 'Use only multiple-choice (single) questions, apart from calculations.' : sata >= 1 ? 'Use only select-all-that-apply (multi) questions, apart from calculations.' : `Exactly ${sataCount} of them must be select-all-that-apply (type "multi"); the rest multiple choice (single).`,
numericLeft === 0
? `Do not write any calculation (numeric) questions in this batch.${forcedMath ? ' Calculation questions are written separately.' : ''}`
: `The material involves calculations: you may include up to ${numericLeft} calculation question${numericLeft === 1 ? '' : 's'} (type "numeric", the student types the number). Do not exceed that.`,
`Topic labels must be broad (the main condition, drug class or body system, 1-3 words), not subtypes or aspects.${topicsSoFar.length ? ` Reuse these existing topics wherever they fit: ${topicsSoFar.slice(0, 40).join(', ')}.` : ''}`,
difficulty === 'mixed' ? 'Mix difficulty: mostly medium, with a few easy and a few hard.' : `Difficulty: ${difficulty}.`,
'Vary how the stems open (the client and their age, the nurse\'s situation, the setting, a finding or order, or the question itself) so no single opening dominates.',
draft.kind === 'quiz' ? openerAdvice(draft.questions) : '',
sources.groups.length > 0 ? 'Spread the questions across the excerpts instead of clustering on one. Set "source" to the id of the excerpt each question is based on.' : '',
req.source.deckId ? 'Turn the flashcards into questions: use each card\'s answer as the correct choice and write distractors that a student could confuse with it.' : '',
]
: [
`Write ${want} flashcards${req.focus ? ` about: ${req.focus}` : ''}.`,
sources.groups.length > 0 ? 'Cover the most testable facts across all of the excerpts.' : '',
req.source.quizId ? 'Turn the quiz questions into flashcards: the front asks for the key fact, the back states only that fact.' : '',
'Do not write hints.',
];
if (written.length > 0) ask.push(`Already written (do not repeat or closely paraphrase these):\n${written.slice(-80).join('\n')}`);
if (angles.length > 0 && !math) ask.push(`Write exactly one question for each of these planned angles, in this order (other angles are covered by other questions, so stay on each one):\n${angles.map((a, k) => `${k + 1}. ${a}`).join('\n')}`);
else if (parallel && !math) ask.push('Other questions are being written from other excerpts at the same time: base every item on your own excerpts so the sets do not overlap.');
// Med math is standard material: the excerpts would only cost tokens.
const user = [math ? '' : sourceBlock(sources, index), ask.filter(Boolean).join('\n')].filter(Boolean).join('\n\n======\n\n');
const result = await generateStructured(app, {
task: 'write',
purpose: isQuiz ? 'quiz generation' : 'flashcard generation',
modelId: req.modelId,
system,
messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
toolName: isQuiz ? 'submit_questions' : 'submit_flashcards',
toolDescription: isQuiz ? 'Submit the finished questions.' : 'Submit the finished flashcards.',
schema: isQuiz ? QUESTION_SCHEMA : CARD_SCHEMA,
maxOutputTokens: outputBudget(resolved, 16_000),
signal,
mcpArea: 'generate',
});
const parsed = draftsFromValue(result.data).items.find((x) => x.kind === req.kind) as QuizDraft | DeckDraft | undefined;
const incoming: (DraftQuestion | DraftCard)[] = parsed ? (parsed.kind === 'quiz' ? parsed.questions : parsed.cards) : [];
let added = 0;
for (const item of incoming) {
const k = key(item);
if (!k || seen.has(k)) continue;
const problems = ('stem' in item ? validateDraftQuestion(item, 0) : validateDraftCard(item, 0)).filter((p) => p.level === 'error');
if (problems.length > 0) continue; // malformed items are dropped here and replaced by a top-up batch
if ('stem' in item) {
const ref = (item.source ?? '').replace(/[[\]\s]/g, '');
item.source = sources.refs.get(ref) ?? undefined;
}
if ('stem' in item && item.type === 'numeric' && (numericLeft === 0 || numericCount() >= numericCap)) continue; // over the calculation allowance; a top-up replaces it
if (math && (!('stem' in item) || item.type !== 'numeric')) continue; // a math batch keeps only calculations
if ('stem' in item && item.type !== 'numeric') item.options = shuffleOptions(item.options);
seen.add(k);
(items() as (DraftQuestion | DraftCard)[]).push(item);
added += 1;
if (math ? numericCount() >= numericCap : items().length - numericCount() >= regularCount && forcedMath !== null) break;
if (items().length >= count) break;
}
if (result.truncated) notes.push('One batch hit the model output limit, so it produced fewer items than requested.');
return added;
};
// Regular items written so far (with requested math, calculations are counted separately).
const regularDone = () => (forcedMath === null ? items().length : items().length - numericCount());
/**
* Plans `n` distinct angles (client situation + what is tested) before writing, so batches that
* run at the same time, and replacements, cover different ground instead of repeating each
* other. Empty when planning fails (batches then fall back to their own excerpts).
*/
const planAngles = async (n: number, avoid: string[]): Promise<string[]> => {
if (!isQuiz || n <= 0) return [];
try {
const result = await generateStructured(app, {
task: 'plan',
purpose: 'planning questions',
modelId: req.modelId,
system: `${baseSystem(db, req, hasSources)}\n\nYou plan NCLEX-style quizzes. List distinct angles, one per question: each names the client situation and the single decision or fact it tests, in one line (for example "Continuous IV heparin, aPTT 3x control with gum bleeding: first action"). No two angles may test the same decision, fact or teaching point, even in a different scenario. Vary the framing too: the setting (unit, clinic, home, emergency department), the nurse's role (bedside, charge nurse, delegating, teaching) and what prompts the question (a finding, a report, an order, a call light). Spread them over the client-needs areas the material supports (pharmacology, safety, prioritisation, delegation, teaching, lab values, complications, psychosocial). When the material is short, vary the situations and the area tested rather than repeating its points.`,
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: [
hasSources ? `MATERIAL:\n${sourcesText(sources).slice(0, 60_000)}` : '',
`Write ${n} angles${req.focus ? ` about: ${req.focus}` : ''}. Difficulty: ${difficulty}. Calculation questions are planned separately; do not include any.`,
avoid.length ? `Already in the quiz (plan different angles from all of these):\n${avoid.map((x) => `- ${x.replace(/\s+/g, ' ').slice(0, 140)}`).join('\n')}` : '',
]
.filter(Boolean)
.join('\n\n'),
},
],
},
],
toolName: 'plan_questions',
toolDescription: 'Submit the planned angles.',
schema: { type: 'object', properties: { angles: { type: 'array', items: { type: 'string' } } }, required: ['angles'] },
maxOutputTokens: outputBudget(resolveModel(app, 'plan', req.modelId), 8_000),
signal,
});
const list = (result.data as { angles?: unknown }).angles;
return Array.isArray(list) ? list.filter((a): a is string => typeof a === 'string' && a.trim() !== '').map((a) => a.trim().slice(0, 300)).slice(0, n) : [];
} catch (err) {
if (signal.aborted) throw err;
app.log('warn', 'Planning quiz angles failed; writing without a plan', err instanceof Error ? err.message : err);
return [];
}
};
/** Runs batches for `wants` at once; the planned angles are shared out in order. */
const runWave = (wants: number[], indexFrom: number, angles: string[]) => {
let at = 0;
return Promise.allSettled(
wants.map((want, k) => {
const mine = angles.slice(at, at + want);
at += want;
return runBatch(indexFrom + k, want, false, wants.length > 1, mine.length === want ? mine : []);
}),
);
};
// Requested medication math needs no excerpts, so it is written alongside the first wave.
const writeMath = async () => {
if (!forcedMath || draft.kind !== 'quiz') return;
for (let attempt = 0; attempt < Math.ceil(forcedMath / perBatch) + 2 && numericCount() < forcedMath; attempt += 1) {
if (signal.aborted) throw new AIError('aborted', 'Generation was cancelled.');
const want = Math.min(perBatch, forcedMath - numericCount());
try {
if ((await runBatch(batches + 10 + attempt, want, true)) === 0 && attempt > 0) break;
} catch (err) {
if (err instanceof AIError && err.code === 'aborted') throw err;
notes.push(`A med math batch failed: ${err instanceof Error ? err.message : 'unknown error'}`);
}
}
};
const mathJob = writeMath();
// Batches run in waves of WRITE_WAVE at a time. Each batch has its own excerpts, and each wave
// is told what the earlier waves wrote, so the parallel writing does not repeat itself.
const plan: number[] = [];
for (let left = regularCount; left > 0; left -= perBatch) plan.push(Math.min(perBatch, left));
if (plan.length > 1) setProgress(db, draftId, 0.04, 'Planning the questions', draft);
const angles = plan.length > 1 ? await planAngles(regularCount, []) : [];
let angleAt = 0;
let failures = 0;
let firstError: unknown = null;
for (let w = 0; w < plan.length && regularDone() < regularCount; w += WRITE_WAVE) {
if (signal.aborted) throw new AIError('aborted', 'Generation was cancelled.');
const wave = plan.slice(w, w + WRITE_WAVE);
const from = regularDone() + 1;
const to = Math.min(regularCount, regularDone() + wave.reduce((n, x) => n + x, 0));
setProgress(db, draftId, 0.05 + (0.85 * items().length) / count, `Writing ${isQuiz ? 'questions' : 'cards'} ${from}-${to} of ${count}`, draft);
const results = await runWave(wave, w, angles.slice(angleAt));
angleAt += wave.reduce((n, x) => n + x, 0);
for (const r of results) {
if (r.status === 'fulfilled') continue;
const err = r.reason;
if (err instanceof AIError && err.code === 'aborted') throw err;
// One bad batch should not sink a long job that already has good content.
failures += 1;
firstError ??= err;
if (err instanceof AIError && !['invalid_response', 'server', 'rate_limit', 'timeout', 'network'].includes(err.code)) throw err;
notes.push(`A batch failed and was skipped: ${err instanceof Error ? err.message : 'unknown error'}`);
}
if ((regularDone() === 0 && failures > 0) || failures > Math.max(2, Math.floor(plan.length / 2))) throw firstError;
}
await mathJob;
// Top up when validation or de-duplication left the draft short.
for (let extra = 0; extra < 2 && regularDone() < regularCount && items().length > 0; extra += 1) {
if (signal.aborted) break;
const want = Math.min(perBatch, regularCount - regularDone());
setProgress(db, draftId, 0.92, `Writing the last ${want} ${isQuiz ? 'questions' : 'cards'}`, draft);
try {
if ((await runBatch(batches + extra, want)) === 0) break;
} catch {
break;
}
}
if (forcedMath && draft.kind === 'quiz') {
draft.questions = spreadEvenly(draft.questions, (q) => q.type === 'numeric');
if (numericCount() < forcedMath) notes.push(`Wrote ${numericCount()} of the ${forcedMath} med math questions requested.`);
}
if (items().length === 0) throw new AIError('invalid_response', 'The model did not produce any usable items. Try again, or choose a different model for content generation.');
if (items().length < count) notes.push(`Generated ${items().length} of the ${count} requested.`);
if (draft.kind === 'quiz') {
setProgress(db, draftId, 0.95, 'Grouping topics', draft);
const mapping = await broadenTopics(app, req.modelId, [...new Set(draft.questions.map((q) => q.topic).filter(Boolean))], knownTopics, signal);
draft.questions = consolidateTopics(
draft.questions.map((q) => ({ ...q, topic: mapping.get(q.topic) ?? q.topic })),
knownTopics.filter((t) => t.trim().split(/\s+/).length <= 2),
);
// When most stems open the same way ("A 72-year-old client…"), reword the openings of the
// excess ones (stem only) before the check reads them.
if (repeatedOpeners(draft.questions).length) setProgress(db, draftId, 0.95, 'Varying how questions open', draft);
const varied = await varyOpeners(app, draft.questions, { modelId: req.modelId, signal });
draft.questions = varied.questions;
if (varied.asked > 0) notes.push(`Reworded how ${varied.reworded} question${varied.reworded === 1 ? '' : 's'} open${varied.reworded === 1 ? 's' : ''}, so fewer start the same way.`);
}
// Check counts, the type mix, answer keys and calculations with Python, and keep fixing until
// the quiz passes: fixes are applied, removed questions are replaced with new ones, and the
// whole quiz is checked again (at most VERIFY_ROUNDS checks).
if (draft.kind === 'quiz' && req.verify !== false) {
const quiz = draft;
const history: string[] = [];
let last: QuizCheck | null = null;
let rounds = 0;
let secondReview: Awaited<ReturnType<typeof proofreadQuiz>> | null = null;
for (let round = 1; round <= VERIFY_ROUNDS; round += 1) {
rounds = round;
if (signal.aborted) throw new AIError('aborted', 'Generation was cancelled.');
setProgress(db, draftId, 0.96, round === 1 ? 'Checking the questions with Python' : `Checking the questions again (round ${round})`, quiz);
// The Python check and a second, independent read of the whole quiz (for badly written
// questions) run at the same time on the same questions.
const snapshot = quiz.questions;
const [check, second] = await Promise.all([
verifyQuizDraft(app, quiz, { count, style, sataShare: sata, difficulty, numericCap, numericRequested: forcedMath !== null }, { modelId: req.modelId, signal, onStep: (label) => setProgress(db, draftId, 0.97, round === 1 ? label : `${label} · round ${round}`) }),
proofreadQuiz(app, quiz, { modelId: req.modelId, signal }),
]);
last = check;
quiz.questions = check.draft.questions;
if (check.incomplete) break;
history.push(...check.applied.map((a) => (round > 1 ? `Round ${round}: ${a}` : a)));
// The second review's fixes, moved onto the checked questions. A question the check already
// rewrote or removed is left to the next round.
const moved = second.fixes.flatMap((f) => {
const stem = snapshot[f.question - 1]?.stem;
const at = stem === undefined ? -1 : quiz.questions.findIndex((q) => q.stem === stem);
return at >= 0 ? [{ ...f, question: at + 1 }] : [];
});
const reviewed = applyQuizFixes(quiz.questions, moved);
quiz.questions = reviewed.questions;
secondReview = { ...second, applied: reviewed.applied, refused: reviewed.refused };
history.push(...reviewed.applied.map((a) => `${round > 1 ? `Round ${round}: ` : ''}Second review: ${a}`));
if (reviewed.refused.length) history.push(...reviewed.refused.map((r) => `Second review: ${r}`));
// Replace what the check removed (duplicates, unfixable items) with new questions.
const missing = count - quiz.questions.length;
if (missing > 0) {
setProgress(db, draftId, 0.96, `Replacing ${missing} question${missing === 1 ? '' : 's'}`, quiz);
// Planned replacements, written in parallel, then single batches for anything still missing.
const mathShort = forcedMath ? Math.max(0, forcedMath - numericCount()) : 0;
const regularShort = missing - mathShort;
if (regularShort > perBatch) {
const fresh = await planAngles(regularShort, quiz.questions.map((q) => q.stem));
const wants: number[] = [];
for (let left = regularShort; left > 0; left -= perBatch) wants.push(Math.min(perBatch, left));
await Promise.all([runWave(wants, batches + 40 + round * 10, fresh), mathShort > 0 ? runBatch(batches + 39 + round * 10, mathShort, true).catch(() => 0) : Promise.resolve(0)]);
}
for (let attempt = 0; attempt < 3 && quiz.questions.length < count; attempt += 1) {
const wantMath = forcedMath ? Math.min(forcedMath - numericCount(), count - quiz.questions.length) : 0;
try {
if (wantMath > 0) await runBatch(batches + 30 + round * 3 + attempt, wantMath, true);
else await runBatch(batches + 30 + round * 3 + attempt, Math.min(perBatch, count - quiz.questions.length));
} catch (err) {
if (err instanceof AIError && err.code === 'aborted') throw err;
}
}
if (forcedMath) quiz.questions = spreadEvenly(quiz.questions, (q) => q.type === 'numeric');
history.push(`Round ${round}: ${missing} removed question${missing === 1 ? ' was' : 's were'} replaced with new ones${round === VERIFY_ROUNDS ? ' (after the last check)' : ''}.`);
}
// Done when nothing is left to fix and nothing new (rewritten or replacement questions) needs checking.
const done = missing <= 0 && check.rewritten === 0 && reviewed.applied.length === 0 && check.failed.length === 0 && check.refused.length === 0;
if (done || round === VERIFY_ROUNDS) break;
}
if (last) {
const summary = last.notes[0] ?? '';
notes.push(
...(last.incomplete ? last.notes : [
rounds > 1 ? summary.replace(/^Checked with Python/, `Checked with Python in ${rounds} rounds, last round`) : summary, ...last.failed.map((f) => `Check failed: ${f}`), ...(secondReview ? [secondReview.incomplete ? 'The second review could not finish.' : secondReview.flagged === 0 ? 'Second review: no problems found.' : `Second review: ${secondReview.flagged} question${secondReview.flagged === 1 ? '' : 's'} fixed in the last round.`] : []), ...history, ...last.refused]),
);
}
}
// A short name and description of what this particular set covers.
if (!req.title) {
setProgress(db, draftId, 0.99, 'Naming the set', draft);
const named = await nameSet(app, draft, { classId: req.classId ?? null, modelId: req.modelId, signal, difficulty, math: numericCount() > 0 });
if (named) {
draft.title = named.title;
draft.description = named.description;
}
}
db.run(
`UPDATE drafts SET status = 'ready', title = ?, payload = ?, meta = ?, progress = 1, progress_label = '', error = '', updated_at = ? WHERE id = ?`,
draft.title,
JSON.stringify(draft),
JSON.stringify({ ...getDraft(db, draftId).meta, model: resolved.model.label, sources: sources.docs, notes: [...new Set(notes)] } satisfies DraftMeta),
now(),
draftId,
);
}
const NAME_SCHEMA = {
type: 'object',
properties: {
title: { type: 'string', description: 'Short, specific name for this set: 2-6 words naming what it covers.' },
description: { type: 'string', description: 'One sentence (at most 25 words) saying what the set covers.' },
},
required: ['title', 'description'],
};
/**
* Asks the model for a short, distinctive title and a one-line description of a finished quiz
* or flashcard set, different from the class's other titles. Null when naming fails (the
* generic title stays).
*/
export async function nameSet(
app: AppContext,
draft: QuizDraft | DeckDraft,
opts: { classId: string | null; modelId?: string | null; signal?: AbortSignal; difficulty?: string; math?: boolean },
): Promise<{ title: string; description: string } | null> {
const isQuiz = draft.kind === 'quiz';
const taken = opts.classId
? app.db.all<{ title: string }>(`SELECT title FROM ${isQuiz ? 'quizzes' : 'decks'} WHERE class_id = ? ORDER BY created_at DESC LIMIT 80`, opts.classId).map((r) => r.title)
: [];
const lines = isQuiz
? (() => {
const counts = new Map<string, number>();
for (const q of draft.questions) counts.set(q.topic || 'General', (counts.get(q.topic || 'General') ?? 0) + 1);
const topics = [...counts].sort((a, b) => b[1] - a[1]).map(([t, n]) => `${t} (${n})`).join(', ');
return [`A quiz of ${draft.questions.length} questions. Topics: ${topics}.`, ...draft.questions.slice(0, 40).map((q) => `- ${q.stem.replace(/\s+/g, ' ').slice(0, 110)}`)];
})()
: [`A flashcard set of ${draft.cards.length} cards.`, ...draft.cards.slice(0, 60).map((c) => `- ${c.front.replace(/\s+/g, ' ').slice(0, 90)}`)];
try {
const result = await generateStructured(app, {
task: 'generate',
purpose: 'naming a set',
modelId: opts.modelId,
system: `You name study sets for a nursing student. The title is 2-6 words in title case and names the actual subject matter (for example "Heart Failure and Diuretics" or "Stroke Priorities"). Never use generic words such as Quiz, Flashcards, Practice, NCLEX, Exam, Review or Set, and no dates or numbers of items.${
opts.math ? ' The set includes medication math, so the title may mention it.' : ''
} The description is one plain sentence on what it covers.`,
messages: [{ role: 'user', content: [{ type: 'text', text: `${lines.join('\n')}${taken.length ? `\n\nTitles already used in this class (yours must differ from all of them):\n${taken.map((t) => `- ${t}`).join('\n')}` : ''}` }] }],
toolName: 'name_set',
toolDescription: 'Submit the title and description.',
schema: NAME_SCHEMA,
maxOutputTokens: 400,
signal: opts.signal,
});
const value = result.data as { title?: unknown; description?: unknown };
let title = typeof value.title === 'string' ? value.title.replace(/\s+/g, ' ').replace(/^["'“]+|["'”.]+$/g, '').trim().slice(0, 80) : '';
const description = typeof value.description === 'string' ? value.description.replace(/\s+/g, ' ').trim().slice(0, 300) : '';
if (!title) return null;
const lower = new Set(taken.map((t) => t.toLowerCase()));
if (lower.has(title.toLowerCase())) {
let n = 2;
while (lower.has(`${title} ${n}`.toLowerCase())) n += 1;
title = `${title} ${n}`;
}
return { title, description };
} catch (err) {
if (opts.signal?.aborted) throw err;
app.log('warn', 'Naming a generated set failed; keeping the default title', err instanceof Error ? err.message : err);
return null;
}
}
async function generateNote(app: AppContext, draftId: string, req: GenerateRequest, signal: AbortSignal, budgetTokens: number, window: number): Promise<void> {
const { db } = app;
const resolved = resolveModel(app, 'write', req.modelId);
const style = req.noteStyle ?? 'study_guide';
// A guide reads the material in as few passes as possible; allow a bigger slice per pass than item generation.
const perPass = Math.max(budgetTokens, Math.min(Math.floor(window * 0.55), 90_000));
const sources = await gatherSources(app, req, perPass, 12);
const hasSources = sources.groups.length > 0 || Boolean(sources.inline);
if (!hasSources && !req.focus) throw badRequest('Choose source material or describe a topic to write about.');
const title = defaultTitle(app, req, sources);
const system = `${baseSystem(db, req, hasSources)}\n\n${instruction(db, `note.${style}`)}\n\n${
sources.groups.length > 0 ? 'Cite the excerpts you draw on by putting their id in brackets at the end of the relevant line or paragraph, e.g. [c42]. Use only ids that appear in the source.' : ''
}\nStart directly with the content (no preamble, no title line).`;
// Merge excerpt groups into as few passes as fit.
const passes: ChunkHit[][] = [];
let current: ChunkHit[] = [];
let size = 0;
for (const g of sources.groups) {
const t = g.reduce((n, c) => n + c.tokens, 0);
if (current.length > 0 && size + t > perPass) {
passes.push(current);
current = [];
size = 0;
}
current.push(...g);
size += t;
}
if (current.length > 0) passes.push(current);
const ask = `${req.focus ? `Focus on: ${req.focus}\n` : ''}Write the ${NOTE_TITLES[style]} now.`;
let content = '';
if (passes.length <= 1) {
setProgress(db, draftId, 0.2, 'Writing');
const body = [passes[0]?.length ? `SOURCE EXCERPTS:\n\n${formatExcerpts(passes[0])}` : '', sources.inline, ask].filter(Boolean).join('\n\n======\n\n');
const res = await runChatWithMcp(app, { task: 'write', purpose: 'study guide', modelId: req.modelId, system, messages: [{ role: 'user', content: [{ type: 'text', text: body }] }], maxOutputTokens: outputBudget(resolved, 16_000), signal }, 'generate');
content = res.text;
} else {
// Long material: condense each part, then write the final piece from the condensed notes.
const partials: string[] = [];
for (let i = 0; i < passes.length; i += 1) {
if (signal.aborted) throw new AIError('aborted', 'Generation was cancelled.');
setProgress(db, draftId, 0.05 + (0.7 * i) / passes.length, `Reading part ${i + 1} of ${passes.length}`);
const res = await runChat(app, {
task: 'write',
purpose: 'study guide',
modelId: req.modelId,
system: `${baseSystem(db, req, true)}\n\nCondense this part of the material into detailed notes: every key concept, value, medication, cause, sign, intervention and warning, as Markdown bullet points under short headings. Keep the bracketed excerpt ids (e.g. [c42]) next to the points they support. Do not add outside information.`,
messages: [{ role: 'user', content: [{ type: 'text', text: `${req.focus ? `Focus on: ${req.focus}\n\n` : ''}SOURCE EXCERPTS (part ${i + 1} of ${passes.length}):\n\n${formatExcerpts(passes[i])}` }] }],
maxOutputTokens: 6_000,
signal,
});
partials.push(res.text.trim());
}
setProgress(db, draftId, 0.8, 'Writing');
const res = await runChatWithMcp(
app,
{
task: 'write',
purpose: 'study guide',
modelId: req.modelId,
system,
messages: [{ role: 'user', content: [{ type: 'text', text: `CONDENSED NOTES FROM THE FULL MATERIAL:\n\n${partials.join('\n\n---\n\n')}\n\n======\n\n${sources.inline ? `${sources.inline}\n\n======\n\n` : ''}${ask}` }] }],
maxOutputTokens: outputBudget(resolved, 16_000),
signal,
},
'generate',
);
content = res.text;
}
content = content.trim().replace(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```$/i, '$1');
if (!content) throw new AIError('invalid_response', 'The model returned an empty document. Try again.');
// Turn [c42] markers into readable citations and append a source list.
const used = new Map<string, string>();
content = content.replace(/\[(c\d+(?:\s*,\s*c\d+)*)\]/g, (_m, list: string) => {
const labels = list
.split(',')
.map((r) => r.trim())
.map((r) => {
const label = sources.refs.get(r) ?? (() => {
const hit = chunkById(db, Number(r.slice(1)));
return hit ? sourceLabel(hit) : null;
})();
if (label) used.set(label, label);
return label;
})
.filter(Boolean);
return labels.length ? ` *(${[...new Set(labels)].join('; ')})*` : '';
});
const payload: NoteDraft = { kind: 'note', title, content };
db.run(
`UPDATE drafts SET status = 'ready', title = ?, payload = ?, meta = ?, progress = 1, progress_label = '', error = '', updated_at = ? WHERE id = ?`,
title,
JSON.stringify(payload),
JSON.stringify({ ...getDraft(db, draftId).meta, model: resolved.model.label, sources: sources.docs } satisfies DraftMeta),
now(),
draftId,
);
}
/* ------------------------------ improve existing questions ------------------------------ */
export const improveRequestSchema = z.object({
quizId: z.string(),
questionIds: z.array(z.string()).max(60).optional(),
instructions: z.string().trim().max(2000).optional(),
modelId: z.string().nullish(),
});
/** Rewrites existing questions (clearer stems, better distractors, fuller rationales) into a draft the user can apply. */
export function startImprove(app: AppContext, input: z.input<typeof improveRequestSchema>, opts: { conversationId?: string | null; onProgress?: (label: string) => void } = {}): { draftId: string; done: Promise<DraftDto> } {
const req = improveRequestSchema.parse(input);
const quiz = getQuiz(app.db, req.quizId);
let questions = listQuestions(app.db, quiz.id);
if (req.questionIds?.length) questions = questions.filter((q) => req.questionIds!.includes(q.id));
if (questions.length === 0) throw badRequest('No questions to improve');
questions = questions.slice(0, 60);
const resolved = resolveModel(app, 'write', req.modelId);
const draftId = createDraft(app.db, {
kind: 'quiz',
classId: quiz.class_id,
title: quiz.title,
status: 'generating',
conversationId: opts.conversationId ?? null,
meta: { origin: 'improve', model: resolved.model.label, targetKind: 'quiz', targetId: quiz.id, replaceQuestionIds: [] },
});
const controller = new AbortController();
running.set(draftId, controller);
if (opts.onProgress) progressListeners.set(draftId, opts.onProgress);
const done = (async () => {
const out: DraftQuestion[] = [];
const ids: string[] = [];
const system = `You are an expert nursing educator and item writer reviewing existing exam questions.
Improve each question while keeping what it tests and its correct answer(s) unless the keyed answer is factually wrong (if so, fix it and say so at the start of the rationale).
- Make the stem clear, complete and free of clues; fix grammar. Vary how the stems open so they do not all start the same way.
- Replace weak or implausible distractors; keep choices parallel and similar in length; remove "all/none of the above".
- Write a teaching rationale, and give every choice a one-sentence "why". ${RATIONALE_FORMAT}
- Keep the same question type unless it is clearly wrong for the content. Set a short topic label and a difficulty.
Return the questions in the same order, one output question per input question.${req.instructions ? `\n\nAdditional instructions: ${req.instructions}` : ''}`;
for (let i = 0; i < questions.length; i += 8) {
if (controller.signal.aborted) throw new AIError('aborted', 'Cancelled.');
const batch = questions.slice(i, i + 8);
setProgress(app.db, draftId, 0.05 + (0.9 * i) / questions.length, `Reviewing questions ${i + 1}-${i + batch.length} of ${questions.length}`);
const body = batch
.map(
(q, n) =>
`Question ${n + 1} (${q.type})\nStem: ${q.stem}\nChoices:\n${q.options.map((o) => `- [${o.correct ? 'x' : ' '}] ${o.text}`).join('\n')}\nRationale: ${q.rationale || '(none)'}\nTopic: ${q.topic || '(none)'}`,
)
.join('\n\n');
const result = await generateStructured(app, {
task: 'write',
purpose: 'improve questions',
modelId: req.modelId,
system,
messages: [{ role: 'user', content: [{ type: 'text', text: body }] }],
toolName: 'submit_questions',
toolDescription: 'Submit the improved questions in the original order.',
schema: QUESTION_SCHEMA,
maxOutputTokens: outputBudget(resolved, 16_000),
signal: controller.signal,
mcpArea: 'generate',
});
const parsed = draftsFromValue(result.data).items.find((x) => x.kind === 'quiz') as QuizDraft | undefined;
const improved = parsed?.questions ?? [];
batch.forEach((orig, n) => {
const next = improved[n];
if (!next || validateDraftQuestion(next, 0).some((p) => p.level === 'error')) return;
next.source = undefined;
out.push(next);
ids.push(orig.id);
});
}
if (out.length === 0) throw new AIError('invalid_response', 'The model did not return usable revisions. Try again or use a different model.');
const payload: QuizDraft = { kind: 'quiz', title: quiz.title, description: quiz.description, questions: out };
app.db.run(
`UPDATE drafts SET status = 'ready', payload = ?, meta = ?, progress = 1, progress_label = '', updated_at = ? WHERE id = ?`,
JSON.stringify(payload),
JSON.stringify({ origin: 'improve', model: resolved.model.label, targetKind: 'quiz', targetId: quiz.id, replaceQuestionIds: ids } satisfies DraftMeta),
now(),
draftId,
);
})()
.catch((err) => {
const message = err instanceof AIError || (err instanceof Error && 'status' in err) ? (err as Error).message : 'Improving the questions failed unexpectedly.';
try {
app.db.run(`UPDATE drafts SET status = 'failed', error = ?, updated_at = ? WHERE id = ? AND status = 'generating'`, message, now(), draftId);
} catch {
/* database closed during shutdown */
}
})
.then(() => {
running.delete(draftId);
progressListeners.delete(draftId);
return getDraft(app.db, draftId);
});
return { draftId, done };
}