/** * 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, resolveModel, runChat } from './service.ts'; 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; created_at: number; updated_at: number; } export interface DraftMeta { origin?: 'generate' | 'assistant' | 'convert' | 'improve' | 'import'; model?: string; request?: Record; 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(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(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, 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; export function getDraft(db: DB, id: string): DraftDto { const row = db.get('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 }, ): string { const id = newId(); const at = now(); db.run( `INSERT INTO drafts (id, kind, class_id, folder_id, title, payload, meta, status, conversation_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, at, at, ); return id; } export function listDrafts(db: DB) { return db .all(`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): { 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. */ 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(), style: z.enum(['nclex', 'standard', 'recall']).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(), cardStyle: z.enum(['concise', 'detailed', 'medication', 'definition']).optional(), noteStyle: z.enum(['study_guide', 'summary', 'outline', 'cheat_sheet']).optional(), modelId: z.string().nullish(), }); export type GenerateRequest = z.infer; /* ------------------------------ prompts ------------------------------ */ 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. Markdown allowed.' }, topic: { type: 'string', description: 'Short topic label, reused across related questions (2-4 words).' }, 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 or term.' }, back: { type: 'string', description: 'Answer side. Markdown allowed.' }, hint: { type: 'string', description: 'Optional memory hook or mnemonic. Empty string if none.' }, tags: { type: 'array', items: { type: 'string' }, description: '1-2 short topic tags.' }, }, required: ['front', 'back'], }, }, }, required: ['cards'], }; const NUMERIC_RULE = `- 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. - Open with a brief, realistic client scenario containing only relevant data (age, diagnosis, key findings, vital signs or lab values with units). - 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". ${NUMERIC_RULE}`; const STANDARD_RULES = `Write clear exam-quality questions: - Each question tests one idea and has one defensible answer set. - Mix understanding and application; avoid trivia and trick wording. - Distractors are plausible and parallel. Never use "all of the above" or "none of the above". - Multiple-choice items have 4 choices with exactly one correct. Select-all items have 4 to 6 choices with at least 2 correct. - The rationale explains the correct answer, and each choice gets its own "why". ${NUMERIC_RULE}`; const RECALL_RULES = `Write straightforward recall questions that check key facts, definitions, normal values and classifications. - Multiple-choice items have 4 choices with exactly one correct. Select-all items have 4 to 6 choices with at least 2 correct. - Keep stems short and unambiguous. Each choice gets a brief "why". ${NUMERIC_RULE}`; const CARD_RULES: Record = { concise: 'Each card tests exactly one fact. Fronts are specific questions or terms; backs are short (a phrase or one or two lines).', detailed: 'Each card covers one concept. Backs may use a short bullet list (up to 5 bullets) for the key points.', 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 = { 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 }, 'quiz.standard': { group: 'Quiz questions', label: 'Standard exam style', text: STANDARD_RULES }, 'quiz.recall': { group: 'Quiz questions', label: 'Quick recall', text: RECALL_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> { return getSetting>>(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): 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; totalTokens: number; } async function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: number, groups: number): Promise { 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.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 ids = missedQuestionIds(db, { classId: req.classId ?? undefined }, 40); const topics = weakTopics(db, { classId: req.classId ?? undefined }, 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 hits = query ? await hybridSearch(app, query, { 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(); export function cancelGeneration(draftId: string): void { running.get(draftId)?.abort(); running.delete(draftId); } function setProgress(db: DB, id: string, progress: number, label: string, payload?: ContentDraft): void { 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.style === 'nclex' ? 'NCLEX practice' : 'quiz') : 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); } const NOTE_TITLES: Record = { 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, opts: { conversationId?: string | null; origin?: DraftMeta['origin'] } = {}): { draftId: string; done: Promise } { const req = generateRequestSchema.parse(input); if (req.classId) getClass(app.db, req.classId); // Fail fast (before creating a draft) when no model is configured. const resolved = resolveModel(app, 'generate', 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, 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); const done = runGeneration(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); return getDraft(app.db, draftId); }); return { draftId, done }; } async function runGeneration(app: AppContext, draftId: string, req: GenerateRequest, signal: AbortSignal): Promise { const { db } = app; const resolved = resolveModel(app, 'generate', 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 ?? 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(); const notes: string[] = []; const style = req.style ?? 'nclex'; const rules = isQuiz ? instruction(db, `quiz.${style}`) : instruction(db, `deck.${req.cardStyle ?? 'concise'}`); const system = `${baseSystem(db, req, hasSources)}\n\n${rules}`; const sata = req.sataShare ?? (style === 'nclex' ? 0.3 : 0.2); const difficulty = req.difficulty ?? 'mixed'; const runBatch = async (index: number, want: number): Promise => { const written = items().map((x) => `- ${('stem' in x ? x.stem : x.front).replace(/\s+/g, ' ').slice(0, 140)}`); const sataCount = Math.round(want * sata); const ask = isQuiz ? [ `Write ${want} ${style === 'nclex' ? '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.' : `About ${sataCount} of them should be select-all-that-apply (multi); the rest multiple choice (single).`, 'If the material involves calculations (dosages, IV rates, conversions), write those as numeric questions the student answers by typing the number.', difficulty === 'mixed' ? 'Mix difficulty: mostly medium, with a few easy and a few hard.' : `Difficulty: ${difficulty}.`, 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 it with the essential reasoning.' : '', ]; if (written.length > 0) ask.push(`Already written (do not repeat or closely paraphrase these):\n${written.slice(-80).join('\n')}`); const user = [sourceBlock(sources, index), ask.filter(Boolean).join('\n')].filter(Boolean).join('\n\n======\n\n'); const result = await generateStructured(app, { task: 'generate', 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: resolved.params.maxOutputTokens ?? 16_000, signal, }); 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; } seen.add(k); (items() as (DraftQuestion | DraftCard)[]).push(item); added += 1; 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; }; let failures = 0; for (let i = 0; i < batches && items().length < count; i += 1) { if (signal.aborted) throw new AIError('aborted', 'Generation was cancelled.'); const want = Math.min(perBatch, count - items().length); setProgress(db, draftId, 0.05 + (0.9 * items().length) / count, `Writing ${isQuiz ? 'questions' : 'cards'} ${items().length + 1}-${Math.min(count, items().length + want)} of ${count}`, draft); try { await runBatch(i, want); } catch (err) { // One bad batch should not sink a long job that already has good content. failures += 1; if (items().length === 0 || failures > 2 || (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'}`); } } // Top up when validation or de-duplication left the draft short. for (let extra = 0; extra < 2 && items().length < count && items().length > 0; extra += 1) { if (signal.aborted) break; const want = Math.min(perBatch, count - items().length); 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 (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.`); 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, ); } async function generateNote(app: AppContext, draftId: string, req: GenerateRequest, signal: AbortSignal, budgetTokens: number, window: number): Promise { const { db } = app; const resolved = resolveModel(app, 'generate', 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 runChat(app, { task: 'generate', purpose: 'study guide', modelId: req.modelId, system, messages: [{ role: 'user', content: [{ type: 'text', text: body }] }], maxOutputTokens: resolved.params.maxOutputTokens ?? 16_000, signal }); 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: 'generate', 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 runChat(app, { task: 'generate', 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: resolved.params.maxOutputTokens ?? 16_000, signal, }); 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(); 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, opts: { conversationId?: string | null } = {}): { draftId: string; done: Promise } { 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, 'generate', 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); 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. - 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". - 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: 'generate', 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: resolved.params.maxOutputTokens ?? 16_000, signal: controller.signal, }); 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); return getDraft(app.db, draftId); }); return { draftId, done }; }