/** * Variety in how quiz stems open. Models tend to start nearly every NCLEX item the same way * ("A 72-year-old client…"), which reads as monotonous and cues the student. After writing, the * openers are counted; when one dominates, the excess stems are reworded (stem only: options, * answer and rationale stay) before the quiz is checked. */ import type { DraftQuestion } from '../../shared/content.ts'; import type { AppContext } from '../http.ts'; import { generateStructured, outputBudget, resolveModel } from './service.ts'; import { AIError } from './types.ts'; /** The first two words of a stem, lowercased, with ages and other numbers folded ("a #-year-old"). */ export function stemOpener(stem: string): string { return stem .replace(/[*_`>#[\]()]/g, ' ') .toLowerCase() .replace(/\b\d+(?:\.\d+)?\s*-?\s*(?:years?|months?|weeks?|days?)\s*-?\s*old\b/g, '#-year-old') .replace(/\d+(?:\.\d+)?/g, '#') .split(/\s+/) .filter(Boolean) .slice(0, 2) .join(' '); } /** * Openers used by more than 30% of the questions (at least 4), and which of them to reword. A real * course exam's most common opener ("A 4-year-old…") covered about a quarter of its items. */ export function repeatedOpeners(questions: Pick[], share = 0.3): { opener: string; example: string; total: number; reword: number[] }[] { if (questions.length < 8) return []; const allow = Math.max(3, Math.floor(questions.length * share)); const groups = new Map(); questions.forEach((q, i) => { const o = stemOpener(q.stem); if (o) groups.set(o, [...(groups.get(o) ?? []), i]); }); return [...groups] .filter(([, list]) => list.length > allow) .map(([opener, list]) => { // Keep every k-th one as it is so the remaining uses are spread out; calculations keep theirs. const keepEvery = list.length / allow; const kept = new Set(Array.from({ length: allow }, (_, k) => list[Math.floor(k * keepEvery)])); const first = questions[list[0]!]!.stem.replace(/[*_`]/g, '').trim(); return { opener, example: first.split(/\s+/).slice(0, 3).join(' '), total: list.length, reword: list.filter((i) => !kept.has(i) && questions[i]!.type !== 'numeric'), }; }) .filter((g) => g.reword.length > 0); } /** Numbers in a text (ages, vital signs, doses, lab values), which a reworded stem must keep. */ function numbersIn(text: string): string[] { return (text.match(/\d+(?:[.,]\d+)?/g) ?? []).map((n) => n.replace(',', '.')); } /** * A reworded stem is accepted only when it keeps every number of the original, keeps the * "Select all that apply." ending of a multi item, and no longer opens the repeated way. */ export function acceptRewording(original: Pick, stem: string, repeated: Set): string | null { let next = stem.trim(); if (next.length < 20 || next.length > original.stem.length * 2 + 200) return null; if (repeated.has(stemOpener(next))) return null; const have = numbersIn(next); for (const n of numbersIn(original.stem)) { const at = have.indexOf(n); if (at < 0) return null; have.splice(at, 1); } if (original.type === 'multi' && !/select all that apply\.?\s*$/i.test(next)) next = `${next.replace(/\s+$/, '')} Select all that apply.`; return next; } const OPENER_SYSTEM = `You edit NCLEX-style questions for variety. Too many stems in this quiz open the same way. Reword only the opening of each listed stem so the quiz reads like a real nursing exam. Real exam items open in plain, natural ways, for example: - with the nurse: "The nurse is caring for a client who…", "The nurse is teaching a client who…", "The nurse assesses a client…", "The nurse receives report on…" - with a family member, when the original involves one: "The parent of a client with…", "A family member asks…" - with a time or event: "Two days after a stroke, a client…", "Immediately after a seizure, the client…", "During discharge teaching, a client…" - with the question itself when the situation is short: "Which finding in a client receiving phenytoin requires immediate follow-up?" Keep each stem the way a person writing an exam would say it, in the active voice with a person as the subject. Never invert the sentence to put a symptom, order or test result first ("Two days of vomiting have left a client weak", "An order is received for…", "Assessment of a client reveals…", "Expressive aphasia affects a client…", "Clear fluid is noted in…"). Do not add a setting or details that are not in the original. Openings with the client's age are fine elsewhere in the quiz; these stems just need a different opening from the repeated one. Keep everything the question tests: the same client facts, every number exactly (age, vital signs, lab values, doses), the same question asked, and an ending of "Select all that apply." where there is one. Include the age only where it is in the original, but it need not come first. Use "client", never "patient". Make the listed stems open differently from one another too. Call submit_stems once with every listed question.`; /** * Rewords the stems of over-repeated openers. Returns the questions with the accepted rewordings * and how many were changed. Never throws except on cancel: the quiz is fine without it. */ export async function varyOpeners( app: AppContext, questions: DraftQuestion[], opts: { modelId?: string | null; signal?: AbortSignal }, ): Promise<{ questions: DraftQuestion[]; reworded: number; asked: number }> { const groups = repeatedOpeners(questions); const targets = groups.flatMap((g) => g.reword); if (targets.length === 0) return { questions, reworded: 0, asked: 0 }; const repeated = new Set(groups.map((g) => g.opener)); try { const result = await generateStructured(app, { task: 'write', purpose: 'varying question openers', modelId: opts.modelId, system: OPENER_SYSTEM, messages: [ { role: 'user', content: [ { type: 'text', text: `${groups.map((g) => `"${g.example}…" opens ${g.total} of the ${questions.length} stems.`).join(' ')}\n\nReword the opening of these stems:\n\n${targets .map((i) => `Q${i + 1}: ${questions[i]!.stem}\n(Correct answer: ${questions[i]!.options.filter((o) => o.correct).map((o) => o.text).join('; ')})`) .join('\n\n')}`, }, ], }, ], toolName: 'submit_stems', toolDescription: 'Submit the reworded stems.', schema: { type: 'object', properties: { stems: { type: 'array', items: { type: 'object', properties: { question: { type: 'integer', description: 'The question number (Qn).' }, stem: { type: 'string' } }, required: ['question', 'stem'] }, }, }, required: ['stems'], }, maxOutputTokens: outputBudget(resolveModel(app, 'write', opts.modelId), 1_000 + targets.length * 250), signal: opts.signal, }); const list = (result.data as { stems?: unknown }).stems; const wanted = new Set(targets); const next = [...questions]; let reworded = 0; for (const raw of Array.isArray(list) ? list : []) { const r = raw as { question?: unknown; stem?: unknown }; const i = typeof r.question === 'number' ? r.question - 1 : -1; if (!wanted.has(i) || typeof r.stem !== 'string') continue; const stem = acceptRewording(questions[i]!, r.stem, repeated); if (!stem) continue; wanted.delete(i); next[i] = { ...questions[i]!, stem }; reworded += 1; } return { questions: next, reworded, asked: targets.length }; } catch (err) { if (opts.signal?.aborted || (err instanceof AIError && err.code === 'aborted')) throw err; app.log('warn', 'Varying question openers failed', err instanceof Error ? err.message : err); return { questions, reworded: 0, asked: targets.length }; } } /** A line for the writing prompt naming the openers already overused, so new questions avoid them. */ export function openerAdvice(questions: Pick[]): string { const groups = repeatedOpeners(questions, 0.2); if (groups.length === 0) return ''; return `Many questions so far open with ${groups.map((g) => `"${g.example}…"`).join(' or ')}: open yours in other ways.`; }