Varied question openers, readable rationales, plain practice score
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s

- 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 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-16 12:05:46 -07:00
parent 10be5c39da
commit 517278be71
15 changed files with 382 additions and 24 deletions

156
server/ai/openers.ts Normal file
View file

@ -0,0 +1,156 @@
/**
* 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 a quarter of the questions (at least 4), and which of them to reword. */
export function repeatedOpeners(questions: Pick<DraftQuestion, 'stem' | 'type'>[], 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<string, number[]>();
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<DraftQuestion, 'stem' | 'type'>, stem: string, repeated: Set<string>): 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<DraftQuestion, 'stem' | 'type'>[]): 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.`;
}