From 517278be718a460867d93a030cbacf1b60a06d2d Mon Sep 17 00:00:00 2001 From: Elijah Date: Mon, 16 Nov 2026 12:05:46 -0700 Subject: [PATCH] Varied question openers, readable rationales, plain practice score - Stems no longer all open the same way: the writing rules, batch prompt and planner ask for varied openings (age openings stay part of the mix), and when one opener covers more than a quarter of a quiz the excess stems have only their opening reworded, keeping every number, before the check. - Rationales are asked for as Markdown (a bold key point, then short bullets); older one-paragraph rationales are laid out the same way on display. - The practice score in the quiz header is a plain "x/y correct", with no percentage or colour. - Fix a flaky assertion: the mock's answer-key fix is a no-op when the shuffle already put the answer in place. Co-Authored-By: Claude Opus 5.5 --- PROGRESS.md | 13 ++- docs/AI.md | 14 ++++ server/ai/generate.ts | 25 ++++-- server/ai/openers.ts | 156 ++++++++++++++++++++++++++++++++++++ server/ai/verify.ts | 2 +- shared/importer.ts | 4 +- shared/rationale.ts | 74 +++++++++++++++++ tests/ai.test.ts | 9 ++- tests/mockAi.ts | 3 + tests/openers.test.ts | 47 +++++++++++ tests/rationale.test.ts | 34 ++++++++ web/src/features/quiz.tsx | 16 ++-- web/src/genui/library.tsx | 3 +- web/src/pages/DraftPage.tsx | 3 +- web/src/pages/QuizPage.tsx | 3 +- 15 files changed, 382 insertions(+), 24 deletions(-) create mode 100644 server/ai/openers.ts create mode 100644 shared/rationale.ts create mode 100644 tests/openers.test.ts create mode 100644 tests/rationale.test.ts diff --git a/PROGRESS.md b/PROGRESS.md index 6771dd3..fe4c278 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -187,6 +187,17 @@ Settings → AI now has separate Planning, Writing, Python check and Second revi Content generation (each inherits until set), and shared quizzes say what Practice and Exam mean under the mode toggle. +Stems no longer all open the same way: the writing rules and planner ask for varied openings, +and when one opener ("A 72-year-old…") covers more than a quarter of a quiz, the excess stems are +reworded (opening only, every number kept) before the check. Age openings stay allowed as part +of the mix. Tests: `tests/openers.test.ts`. + +Rationales are written as Markdown (a bold key point, then 2 to 4 short bullets). Older +one-paragraph rationales are broken up on display (`shared/rationale.ts`): the first sentence is +shown in bold, the rest in short paragraphs, and a walk-through of the choices becomes a list. +The practice score in the quiz header is now a plain "x/y correct" with no percentage or colour. +Tests: `tests/rationale.test.ts`. + Tests: `tests/revision5.test.ts`. Live check on the rev1 copy with DeepSeek flash: a visitor's 10-card set was written, named ("Heparin, Furosemide, and Dosage Calculations"), saved and listed once with the New tag; cards were single facts with no hints. The rev1 copy's 401 was its @@ -195,7 +206,7 @@ stored DeepSeek connection still holding the old key; it was updated from `.env` ## Verification status Baseline: 162 tests passed, TypeScript passed and production web/server builds passed. -Added six regression tests. Full `npm run check` passes: **281 tests** (generation steps, 2026-11-16; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript +Added six regression tests. Full `npm run check` passes: **289 tests** (rationale layout, 2026-11-16; 285 after varied openers; 281 after generation steps; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript and both production builds. The Docker `test` stage runs the same 181 tests on Node 24. Tests were run with loopback access for the mock provider. The earlier agent manually exercised quiz completion/results, flashcards, streak effects, diff --git a/docs/AI.md b/docs/AI.md index 29630ad..29617ed 100644 --- a/docs/AI.md +++ b/docs/AI.md @@ -84,6 +84,20 @@ garbled or contradictory stem, missing data, two defensible answers), or `remove model files as cosmetic or informational (answer position, quotes) are not counted as failed checks; answer order is shuffled whenever a quiz is taken. +Before the check, **openers are varied** (`server/ai/openers.ts`). Models tend to open nearly +every stem the same way ("A 72-year-old client…"). The first two words of each stem are compared, +with ages and numbers folded together. When one opener covers more than a quarter of a quiz of 8 or +more, a spread-out quarter is kept. The rest have only their opening reworded (`submit_stems`); the +options, answer and rationale stay the same. A rewording is kept only when it holds every number +from the original, keeps "Select all that apply." and no longer opens the repeated way. +Calculations keep their wording. The writing rules, the batch prompt (which names openers already +overused) and the planner (setting, role, trigger) also ask for varied openings. + +**Rationales** are asked for as Markdown: one bold key sentence, then 2 to 4 short bullet points, +without repeating the per-choice "why" (`RATIONALE_FORMAT`, also in the question schema, the +review's rewrite schema, "improve questions" and the outside-chatbot instructions). The web app +lays out older one-paragraph rationales the same way when it shows them (`formatRationale`). + Then a **second review**: a fresh model call with no Python reads the whole quiz as a careful student and item writer would, and rewrites or removes questions that are badly written (a writer changing its mind mid-stem such as "A 78 kg? No — an 80 kg client", contradictions, diff --git a/server/ai/generate.ts b/server/ai/generate.ts index fcb82a3..8d9ca1d 100644 --- a/server/ai/generate.ts +++ b/server/ai/generate.ts @@ -42,6 +42,7 @@ 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. */ @@ -321,6 +322,10 @@ export type GenerateRequest = z.infer; /* ------------------------------ 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: { @@ -348,7 +353,7 @@ const QUESTION_SCHEMA = { required: ['text', 'correct', 'why'], }, }, - rationale: { type: 'string', description: 'Teaching explanation of the correct answer. Markdown allowed.' }, + 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.', @@ -394,13 +399,15 @@ const NUMERIC_RULE = `- Only write calculation items when the source material it 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). +- 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}`; @@ -928,6 +935,8 @@ async function runGeneration(app: AppContext, draftId: string, req: GenerateRequ : `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.' : '', ] @@ -995,7 +1004,7 @@ async function runGeneration(app: AppContext, draftId: string, req: GenerateRequ 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. 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.`, + 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', @@ -1109,6 +1118,12 @@ async function runGeneration(app: AppContext, draftId: string, req: GenerateRequ 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 @@ -1404,9 +1419,9 @@ export function startImprove(app: AppContext, input: z.input#[\]()]/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 a quarter of the questions (at least 4), and which of them to reword. */ +export function repeatedOpeners(questions: Pick[], share = 0.25): { 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 exam, where items open in many ways, for example: +- with the nurse's situation: "The nurse is caring for…", "While reviewing the morning laboratory results, the nurse notes…", "After receiving report, the nurse…" +- with the setting or role: "On a medical-surgical unit…", "In the emergency department…", "The charge nurse is making assignments…", "During discharge teaching…" +- with a finding, order or report: "A client with heart failure reports…", "The health care provider prescribes…", "Two hours after surgery, a client's…" +- or with the question itself when the scenario is short: "Which finding in a client receiving… requires immediate follow-up?" +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.`; +} diff --git a/server/ai/verify.ts b/server/ai/verify.ts index eda33be..657608d 100644 --- a/server/ai/verify.ts +++ b/server/ai/verify.ts @@ -119,7 +119,7 @@ const SUBMIT_REVIEW_QUESTION_TEXT = { type: { type: 'string', enum: ['single', 'multi', 'numeric'] }, stem: { type: 'string' }, options: { type: 'array', items: { type: 'object', properties: { text: { type: 'string' }, correct: { type: 'boolean' }, why: { type: 'string' } }, required: ['text', 'correct'] } }, - rationale: { type: 'string' }, + rationale: { type: 'string', description: 'Markdown: one bold key sentence, then 2 to 4 short bullet points.' }, }, required: ['type', 'stem', 'options', 'rationale'], }; diff --git a/shared/importer.ts b/shared/importer.ts index 978d377..d80117a 100644 --- a/shared/importer.ts +++ b/shared/importer.ts @@ -636,8 +636,8 @@ Rules: - "single" questions have exactly 4 options and exactly one with "correct": true. - "multi" questions have 5 or 6 options, 2 to 5 of them correct, and the stem ends with "Select all that apply." - Use "numeric" for calculations (dosages, IV rates, drip rates, conversions, intake and output). Its "options" holds only the correct answer, e.g. [{ "text": "12.5 mL", "correct": true, "why": "Show the calculation" }]. The stem states the unit and how to round, e.g. "Round to the nearest tenth." Only the number is checked, so units in the answer are optional. -- Write NCLEX-style questions that test clinical judgment: a short client scenario, one clear question, priority wording where it fits (first, best, most important), and distractors that are plausible but wrong for a specific reason. Never use "all of the above" or "none of the above". -- Every option needs a one-sentence "why". The "rationale" explains the principle behind the correct answer. +- Write NCLEX-style questions that test clinical judgment: a short client scenario (vary how stems open so they do not all start the same way), one clear question, priority wording where it fits (first, best, most important), and distractors that are plausible but wrong for a specific reason. Never use "all of the above" or "none of the above". +- Every option needs a one-sentence "why". The "rationale" explains the principle behind the correct answer, laid out for quick reading: one bold key sentence, then 2 to 4 short bullet points (use \\n between lines). - "topic" is a short label. Reuse the same label for related questions and keep the number of different topics small. - "difficulty" is "easy", "medium" or "hard". - Markdown is allowed inside strings (bold, lists, tables). Write line breaks inside strings as \\n. diff --git a/shared/rationale.ts b/shared/rationale.ts new file mode 100644 index 0000000..08710c4 --- /dev/null +++ b/shared/rationale.ts @@ -0,0 +1,74 @@ +/** + * Rationale layout. New rationales are written as Markdown (a bold key point, then short + * bullets); older ones are often one long paragraph. `formatRationale` breaks such a paragraph + * into readable pieces for display: the first sentence on its own, then short paragraphs, and + * a list when it walks through the choices ("Option A…", "Choice 2…"). Text that already has + * structure (line breaks, lists, headings) is returned unchanged. + */ + +/** Words that end with a period without ending the sentence. */ +const ABBREVIATIONS = /(?:^|\s|\()(?:e\.g|i\.e|vs|etc|approx|dr|mr|mrs|ms|st|no|fig|min|max|hr|hrs|mg|mcg|kg|ml|mL|dL|mEq|U|gtt|q|b\.i\.d|t\.i\.d|q\.i\.d|p\.r\.n|a\.m|p\.m)\.$/i; + +/** Splits plain prose into sentences, keeping decimals ("2.5 mg") and abbreviations together. */ +export function splitSentences(text: string): string[] { + const out: string[] = []; + let start = 0; + const re = /([.!?])(["'”’)*_]*)\s+(?=["“'(*_]*[A-Z0-9])/g; + let m: RegExpExecArray | null; + while ((m = re.exec(text))) { + const end = m.index + m[1].length + m[2].length; + const piece = text.slice(start, end); + if (m[1] === '.' && ABBREVIATIONS.test(text.slice(start, m.index + 1))) continue; + if (piece.trim()) out.push(piece.trim()); + start = re.lastIndex; + } + const rest = text.slice(start).trim(); + if (rest) out.push(rest); + return out; +} + +const CHOICE_START = /^(?:\*\*)?(?:option|choice|answer|distractor)\s*(?:[A-F]|[1-6])\b/i; +const FOLLOW_ON = /^(?:it|this|that|these|those|they|however|instead|also|because|but)\b/i; + +export function formatRationale(text: string): string { + const value = text.trim(); + // Already laid out, or short enough to read at a glance. + if (value.length < 260 || /\n/.test(value)) return value; + const sentences = splitSentences(value); + if (sentences.length < 3) return value; + const [lead, ...rest] = sentences; + // The key point leads in bold, as new rationales do (unless it already has emphasis). + const blocks: string[] = [/[*_]/.test(lead!) ? lead! : `**${lead}**`]; + let paragraph: string[] = []; + const flush = () => { + if (paragraph.length) blocks.push(paragraph.join(' ')); + paragraph = []; + }; + let bullets: string[] = []; + const flushBullets = () => { + if (bullets.length) blocks.push(bullets.map((b) => `- ${b}`).join('\n')); + bullets = []; + }; + // Walk-throughs of the choices become a list when there are at least two of them. + const choiceCount = rest.filter((s) => CHOICE_START.test(s)).length; + for (const sentence of rest) { + if (choiceCount >= 2 && CHOICE_START.test(sentence)) { + flush(); + bullets.push(sentence); + continue; + } + if (bullets.length) { + // A follow-on sentence about the same choice ("It…", "This…") stays in its bullet. + if (FOLLOW_ON.test(sentence) && sentence.length < 160) { + bullets[bullets.length - 1] += ` ${sentence}`; + continue; + } + flushBullets(); + } + paragraph.push(sentence); + if (paragraph.length >= 2 || paragraph.join(' ').length > 220) flush(); + } + flush(); + flushBullets(); + return blocks.join('\n\n'); +} diff --git a/tests/ai.test.ts b/tests/ai.test.ts index 4d9708b..2db1ad5 100644 --- a/tests/ai.test.ts +++ b/tests/ai.test.ts @@ -54,7 +54,7 @@ async function sse(url: string, body: unknown): Promise { const isCheck = (r: { body: any }) => (r.body?.tools ?? []).some((t: any) => t.function?.name === 'submit_review'); /** The quick call that groups topic labels after a quiz is written. */ const isGrouping = (r: { body: any }) => (r.body?.tools ?? []).some((t: any) => t.function?.name === 'submit_topics'); -const isNaming = (r: { body: any }) => ['name_set', 'submit_proofread', 'plan_questions'].includes(r.body?.tool_choice?.function?.name); +const isNaming = (r: { body: any }) => ['name_set', 'submit_proofread', 'plan_questions', 'submit_stems'].includes(r.body?.tool_choice?.function?.name); async function waitForDraft(id: string) { for (let i = 0; i < 200; i += 1) { @@ -213,7 +213,12 @@ describe('generation', () => { expect(pythonResult.ok).toBe(true); expect(pythonResult.stdout).toMatch(/^12 12 \d+ \[(?:[12], ){11}[12]\]\n$/); expect(draft.payload.questions[1].options.map((o: any) => o.correct)).toEqual([false, true, false, false]); - expect(draft.meta.notes.join(' ')).toMatch(/Checked with Python \(1 run\): 2 of 2 checks passed, 1 fix applied/); + // The mock's fix keys option 2; when the shuffle already put the answer there it changes + // nothing and is skipped, so "1 fix applied" only shows when it did something. + expect(draft.meta.notes.join(' ')).toMatch(/Checked with Python \(1 run\): 2 of 2 checks passed(?:, 1 fix applied|\.)/); + // Every mock stem opens "Mock question…": the excess ones were reworded (stem only) before the check. + expect(draft.meta.notes.join(' ')).toMatch(/Reworded how \d+ questions open/); + expect(draft.payload.questions.filter((q: any) => q.stem.startsWith('On the unit, Mock question')).length).toBeGreaterThan(4); expect(JSON.stringify(calls[0].body.messages)).toMatch(/SOURCE EXCERPTS/); // The questions are planned first; both batches then run at the same time, each with its own planned angles. expect(all.filter((r) => r.body?.tool_choice?.function?.name === 'plan_questions')).toHaveLength(1); diff --git a/tests/mockAi.ts b/tests/mockAi.ts index db974fa..5ee33e5 100644 --- a/tests/mockAi.ts +++ b/tests/mockAi.ts @@ -105,6 +105,9 @@ function toolArgs(name: string, userText: string, all: string): Record ({ front: `Mock term ${i + 1 + offset}`, back: `Mock definition ${i + 1 + offset}`, tags: ['mock'] })) }; case 'plan_questions': return { angles: Array.from({ length: count }, (_, k) => `Mock angle ${k + 1 + offset}`) }; + case 'submit_stems': + // Rewords each listed stem's opening, keeping the rest of it. + return { stems: [...userText.matchAll(/^Q(\d+): (.+)$/gm)].map((m) => ({ question: Number(m[1]), stem: `On the unit, ${m[2]}` })) }; case 'name_set': return /quiz of/i.test(userText) ? { title: 'Heart Failure and Pharmacology', description: 'Covers heart failure care and the drugs used for it.' } : { title: 'Mock Terms', description: 'Covers the mock terms.' }; case 'generate_quiz': diff --git a/tests/openers.test.ts b/tests/openers.test.ts new file mode 100644 index 0000000..9cb38d4 --- /dev/null +++ b/tests/openers.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it } from 'vitest'; +import { acceptRewording, openerAdvice, repeatedOpeners, stemOpener } from '../server/ai/openers.ts'; + +const q = (stem: string, type: 'single' | 'multi' | 'numeric' = 'single') => ({ stem, type }); + +describe('question openers', () => { + it('folds ages and numbers so "A 72-year-old" and "A 45 year old" count as one opener', () => { + expect(stemOpener('A 72-year-old client with heart failure…')).toBe('a #-year-old'); + expect(stemOpener('**A 45 year old** patient reports…')).toBe('a #-year-old'); + expect(stemOpener('The nurse is caring for…')).toBe('the nurse'); + }); + + it('flags an opener used by more than a quarter of the quiz and keeps a spread-out share of it', () => { + const stems = [ + ...Array.from({ length: 16 }, (_, i) => q(`A ${40 + i}-year-old client with condition ${i} reports pain. Which action is first?`)), + ...Array.from({ length: 4 }, (_, i) => q(`The nurse is caring for client ${i}. Which finding requires follow-up?`)), + ]; + const groups = repeatedOpeners(stems); + expect(groups).toHaveLength(1); + expect(groups[0]!.opener).toBe('a #-year-old'); + expect(groups[0]!.total).toBe(16); + // 20 questions allow 5 of one opener: 11 are reworded, the 5 kept are spread out. + expect(groups[0]!.reword).toHaveLength(11); + expect(groups[0]!.reword).not.toContain(0); + expect(openerAdvice(stems)).toMatch(/"A 40-year-old client…"/); + }); + + it('leaves varied quizzes, short quizzes and calculations alone', () => { + const varied = ['The nurse', 'A client', 'In the', 'During discharge', 'Which finding', 'The charge', 'After receiving', 'The provider'].map((o, i) => q(`${o} ${i} … what is the priority?`)); + expect(repeatedOpeners(varied)).toEqual([]); + expect(repeatedOpeners(Array.from({ length: 6 }, (_, i) => q(`A ${i}-year-old client…`)))).toEqual([]); + const math = Array.from({ length: 10 }, (_, i) => q(`The provider orders ${i + 2} mg. How many mL?`, 'numeric')); + expect(repeatedOpeners(math)).toEqual([]); + }); + + it('accepts a rewording only when it keeps every number and the select-all ending', () => { + const original = q('A 72-year-old client has a potassium of 3.1 mEq/L and a heart rate of 52. Select all that apply.', 'multi'); + const repeated = new Set(['a #-year-old']); + expect(acceptRewording(original, 'The nurse reviews the laboratory results of a 72-year-old client: potassium 3.1 mEq/L, heart rate 52.', repeated)).toBe( + 'The nurse reviews the laboratory results of a 72-year-old client: potassium 3.1 mEq/L, heart rate 52. Select all that apply.', + ); + // A number was lost or changed. + expect(acceptRewording(original, 'The nurse reviews the laboratory results of a 72-year-old client: potassium 3.4 mEq/L, heart rate 52.', repeated)).toBeNull(); + // Still opens the repeated way. + expect(acceptRewording(original, 'A 72-year-old client on the unit has a potassium of 3.1 mEq/L and a heart rate of 52.', repeated)).toBeNull(); + }); +}); diff --git a/tests/rationale.test.ts b/tests/rationale.test.ts new file mode 100644 index 0000000..5bc655b --- /dev/null +++ b/tests/rationale.test.ts @@ -0,0 +1,34 @@ +import { describe, expect, it } from 'vitest'; +import { formatRationale, splitSentences } from '../shared/rationale.ts'; + +describe('rationale layout', () => { + it('keeps decimals and abbreviations inside a sentence', () => { + expect(splitSentences('Give 2.5 mg now, e.g. with food. Recheck the level in 6 hr. Then report it.')).toEqual(['Give 2.5 mg now, e.g. with food.', 'Recheck the level in 6 hr. Then report it.']); + }); + + it('breaks a long paragraph into a lead sentence and short paragraphs', () => { + const brick = + 'Potassium of 2.9 mEq/L is hypokalemia caused by loop-diuretic potassium loss. It explains the cramps, weakness and palpitations the client reports. Hypokalemia destabilises cardiac membranes and can cause dysrhythmias. This is more dangerous in a client who also takes digoxin. The nurse notifies the provider and anticipates potassium replacement. The weight loss and urine output show the drug is working as intended.'; + const out = formatRationale(brick); + const blocks = out.split('\n\n'); + expect(blocks[0]).toBe('**Potassium of 2.9 mEq/L is hypokalemia caused by loop-diuretic potassium loss.**'); + expect(blocks.length).toBeGreaterThanOrEqual(3); + expect(out.replace(/\*\*/g, '').replace(/\s+/g, ' ')).toBe(brick); + }); + + it('turns a walk-through of the choices into a list', () => { + const brick = + 'The priority is airway, so suctioning comes first in this situation for the client. Option A is wrong because repositioning does not clear secretions. It also delays care. Option B is wrong because oxygen will not help a blocked airway. Option D can wait until the airway is clear and the client is stable. The nurse reassesses breath sounds after suctioning.'; + const out = formatRationale(brick); + expect(out).toMatch(/\n- Option A is wrong because repositioning does not clear secretions\. It also delays care\.\n/); + expect(out).toMatch(/\n- Option B is wrong/); + // A closing sentence on a new subject ends the list. + expect(out).toMatch(/stable\.\n\nThe nurse reassesses/); + }); + + it('leaves short or already structured rationales alone', () => { + expect(formatRationale('Short and clear.')).toBe('Short and clear.'); + const md = '**Furosemide is a loop diuretic.**\n\n- Check potassium before each dose and report any low value.\n- Weigh daily at the same time with the same scale and clothing.\n- Give it in the morning to prevent nocturia and falls overnight at home.'; + expect(formatRationale(md)).toBe(md); + }); +}); diff --git a/web/src/features/quiz.tsx b/web/src/features/quiz.tsx index 48bf80b..7fc6d19 100644 --- a/web/src/features/quiz.tsx +++ b/web/src/features/quiz.tsx @@ -4,6 +4,7 @@ import { isFullyCorrect, letterGrade, optionLetter, parseNumericAnswer, scoreQue import type { AnswerState, SnapshotQuestion } from '@/lib/types'; import { cx, formatDuration, formatMinutes, plural, useHotkeys, useLatest } from '@/lib/util'; import { Markdown } from '@/ui/Markdown'; +import { formatRationale } from '@shared/rationale'; import { Badge, Button, Dialog, IconButton, Input, ProgressBar, Segmented, useConfirm } from '@/ui'; import { ExplainSideContext } from './Explain'; @@ -345,14 +346,9 @@ export function QuizRunner(p: RunnerProps) {
{p.mode === 'exam' ? 'Exam' : 'Practice'}
{live && ( -
- - {fmtPoints(live.points)}/{live.n} correct · - - {live.percent}% +
+ {fmtPoints(live.points)}/{live.n} +  correct
)} {/* The clock is a timed-exam feature; untimed sessions track time quietly for the results. */} @@ -402,7 +398,7 @@ export function QuizRunner(p: RunnerProps) { {question.rationale && (
Rationale
- {question.rationale} + {formatRationale(question.rationale)}
)} {p.renderExtra?.(question, answerTexts(question, selected))} @@ -708,7 +704,7 @@ export function QuizResults(p: ResultsProps) { {r.q.rationale && (
Rationale
- {r.q.rationale} + {formatRationale(r.q.rationale)}
)} {p.renderExtra && ( diff --git a/web/src/genui/library.tsx b/web/src/genui/library.tsx index 69a0bfe..e829983 100644 --- a/web/src/genui/library.tsx +++ b/web/src/genui/library.tsx @@ -8,6 +8,7 @@ import { useState, type ReactNode } from 'react'; import { GENUI_COMPONENTS, GENUI_GROUPS, GENUI_ROOT } from '@shared/genui'; import { cx } from '@/lib/util'; import { Markdown } from '@/ui/Markdown'; +import { formatRationale } from '@shared/rationale'; import { BarChart, LineChart, PieChart, type ChartSeries } from './charts'; type Props = Record; @@ -367,7 +368,7 @@ const R: Record = { {right ? : } {right ? 'Correct' : 'Not quite'}
- {props.rationale && {text(props.rationale)}} + {props.rationale && {formatRationale(text(props.rationale))}} diff --git a/web/src/pages/DraftPage.tsx b/web/src/pages/DraftPage.tsx index 1e42411..e3438cd 100644 --- a/web/src/pages/DraftPage.tsx +++ b/web/src/pages/DraftPage.tsx @@ -10,6 +10,7 @@ import { qk, useClass, useClasses, useQuiz, useRefresh } from '@/lib/queries'; import type { Draft } from '@/lib/types'; import { cx, plural, useDocumentTitle } from '@/lib/util'; import { Markdown } from '@/ui/Markdown'; +import { formatRationale } from '@shared/rationale'; import { Badge, Button, Callout, EmptyState, ErrorState, Field, IconButton, Input, PageLoading, ProgressBar, Segmented, Select, Textarea, useConfirm } from '@/ui'; const KIND = { quiz: { label: 'Quiz', icon: , url: 'quizzes' }, deck: { label: 'Flashcards', icon: , url: 'decks' }, note: { label: 'Note', icon: , url: 'notes' } } as const; @@ -36,7 +37,7 @@ function QuestionPreview({ q }: { q: DraftQuestion }) { {q.rationale && (
Rationale
- {q.rationale} + {formatRationale(q.rationale)}
)} {q.source && ( diff --git a/web/src/pages/QuizPage.tsx b/web/src/pages/QuizPage.tsx index 7653011..cc5d21b 100644 --- a/web/src/pages/QuizPage.tsx +++ b/web/src/pages/QuizPage.tsx @@ -13,6 +13,7 @@ import { useAssistantContext } from '@/lib/assistantStore'; import { useAiStatus, useQuiz, useRefresh } from '@/lib/queries'; import { cx, downloadFile, formatDateTime, formatMinutes, gradeTone, pct, plural, timeAgo, useDocumentTitle, useLocalStorage } from '@/lib/util'; import { Markdown } from '@/ui/Markdown'; +import { formatRationale } from '@shared/rationale'; import { SortableList } from '@/ui/Sortable'; import { Badge, Button, Callout, ClassDot, Dialog, EmptyState, ErrorState, Field, IconButton, Input, Menu, MenuItem, MenuSeparator, Segmented, Skeleton, Switch, Textarea, useConfirm } from '@/ui'; @@ -254,7 +255,7 @@ function QuestionView({ q, index, stat }: { q: Question; index: number; stat?: { {open && q.rationale && (
- {q.rationale} + {formatRationale(q.rationale)}
)}