@intellectif/lk-core 1.2.0 → 1.3.0

package/dist/ai-check.js

@@ -1,662 +1,791 @@
-import {
-  aiCoachingRequest,
-  aiCritiqueRequest,
-  aiDraftsRequest,
-  aiExplanationRequest,
-  aiHintRequest,
-  aiWritingFeedbackRequest,
-  checkAiCoaching,
-  checkAiCritique,
-  checkAiDrafts,
-  checkAiExplanation,
-  checkAiHint,
-  checkAiWritingFeedback
-} from "./chunk-7KOWU4RO.js";
-import {
-  gradeReadAloud
-} from "./chunk-QX2ERL72.js";
-import "./chunk-MV2N2WNS.js";
-import "./chunk-QS7B42ZR.js";
-
-// src/ai-check/cases.ts
-var capital = {
-  schemaVersion: "1.0",
-  type: "multiple-choice",
-  id: "ai-check-mc",
-  title: "Capital cities",
-  question: "What is the capital of Spain?",
-  mode: "single",
-  scoringStrategy: "all-or-nothing",
-  options: [
-    { id: "madrid", text: "Madrid", isCorrect: true },
-    { id: "barcelona", text: "Barcelona", isCorrect: false },
-    { id: "seville", text: "Seville", isCorrect: false }
-  ]
+import { D as checkAiCoaching, E as aiCoachingRequest, L as checkAiExplanation, M as aiExplanationRequest, P as aiHintRequest, R as checkAiHint, c as aiDraftsRequest, h as checkAiCritique, i as checkAiWritingFeedback, l as checkAiDrafts, m as aiCritiqueRequest, r as aiWritingFeedbackRequest } from "./ai-writing-CCBjTOM3.js";
+import { o as gradeReadAloud } from "./scoring-BZqUkuDF.js";
+//#region src/ai-check/cases.ts
+/**
+* The items the cases are built from. Small, ordinary language-course content
+* — and deliberately awkward in the places a model slips:
+*
+* - an answer a hint can hardly avoid naming (`Madrid`);
+* - an answer of one short word (`is`), which a hint may write as an ordinary
+*   word and must not write beside its neighbour in the passage;
+* - an accented answer (`cañón`), so a hint that spells it without the accent
+*   is still caught;
+* - a passage with more than one blank, so a hint can be about the wrong one;
+* - a short essay whose mistakes a model must quote exactly as the learner
+*   wrote them — straight apostrophes a model likes to curl, a mistake made
+*   twice — so a correction of words nobody wrote is caught.
+*/
+const capital = {
+	schemaVersion: "1.0",
+	type: "multiple-choice",
+	id: "ai-check-mc",
+	title: "Capital cities",
+	question: "What is the capital of Spain?",
+	mode: "single",
+	scoringStrategy: "all-or-nothing",
+	options: [
+		{
+			id: "madrid",
+			text: "Madrid",
+			isCorrect: true
+		},
+		{
+			id: "barcelona",
+			text: "Barcelona",
+			isCorrect: false
+		},
+		{
+			id: "seville",
+			text: "Seville",
+			isCorrect: false
+		}
+	]
 };
-var introduction = {
-  schemaVersion: "1.0",
-  type: "fill-in-the-blanks",
-  id: "ai-check-fib",
-  title: "Introducing yourself",
-  passage: "My name {{be}} Rossi and I {{live}} in Madrid.",
-  blanks: [
-    { id: "be", acceptedAnswers: ["is"] },
-    { id: "live", acceptedAnswers: ["live"], hint: "Present simple, first person." }
-  ],
-  scoringStrategy: "partial"
+const introduction = {
+	schemaVersion: "1.0",
+	type: "fill-in-the-blanks",
+	id: "ai-check-fib",
+	title: "Introducing yourself",
+	passage: "My name {{be}} Rossi and I {{live}} in Madrid.",
+	blanks: [{
+		id: "be",
+		acceptedAnswers: ["is"]
+	}, {
+		id: "live",
+		acceptedAnswers: ["live"],
+		hint: "Present simple, first person."
+	}],
+	scoringStrategy: "partial"
 };
-var landscape = {
-  schemaVersion: "1.0",
-  type: "gap-select",
-  id: "ai-check-gap",
-  title: "Geography",
-  locale: "es-ES",
-  passage: "El r\xEDo pasa por un {{g1}} muy profundo, y el agua {{g2}} fr\xEDa.",
-  gaps: [
-    {
-      id: "g1",
-      choices: [
-        { id: "canon", text: "ca\xF1\xF3n" },
-        { id: "campo", text: "campo" }
-      ],
-      correctChoiceId: "canon"
-    },
-    {
-      id: "g2",
-      choices: [
-        { id: "esta", text: "est\xE1" },
-        { id: "es", text: "es" }
-      ],
-      correctChoiceId: "esta"
-    }
-  ],
-  scoringStrategy: "partial"
+const landscape = {
+	schemaVersion: "1.0",
+	type: "gap-select",
+	id: "ai-check-gap",
+	title: "Geography",
+	locale: "es-ES",
+	passage: "El río pasa por un {{g1}} muy profundo, y el agua {{g2}} fría.",
+	gaps: [{
+		id: "g1",
+		choices: [{
+			id: "canon",
+			text: "cañón"
+		}, {
+			id: "campo",
+			text: "campo"
+		}],
+		correctChoiceId: "canon"
+	}, {
+		id: "g2",
+		choices: [{
+			id: "esta",
+			text: "está"
+		}, {
+			id: "es",
+			text: "es"
+		}],
+		correctChoiceId: "esta"
+	}],
+	scoringStrategy: "partial"
 };
-var listening = {
-  schemaVersion: "1.0",
-  type: "dictation",
-  id: "ai-check-dictation",
-  title: "Listen and type",
-  transcript: "The train leaves at half past nine."
+const listening = {
+	schemaVersion: "1.0",
+	type: "dictation",
+	id: "ai-check-dictation",
+	title: "Listen and type",
+	transcript: "The train leaves at half past nine."
 };
-var weekend = {
-  schemaVersion: "1.0",
-  type: "written-response",
-  id: "ai-check-writing",
-  title: "Your weekend",
-  prompt: "Write a few sentences about what you did last weekend.",
-  minWords: 15,
-  maxWords: 120,
-  languageTarget: "en-A2",
-  rubric: {
-    criteria: [
-      { name: "Grammar", description: "Past tenses, articles, agreement", weight: 2 },
-      { name: "Vocabulary", description: "Everyday words, used correctly", weight: 1 },
-      { name: "Task", description: "Says what the learner did, in order", weight: 1 }
-    ]
-  }
+const weekend = {
+	schemaVersion: "1.0",
+	type: "written-response",
+	id: "ai-check-writing",
+	title: "Your weekend",
+	prompt: "Write a few sentences about what you did last weekend.",
+	minWords: 15,
+	maxWords: 120,
+	languageTarget: "en-A2",
+	rubric: { criteria: [
+		{
+			name: "Grammar",
+			description: "Past tenses, articles, agreement",
+			weight: 2
+		},
+		{
+			name: "Vocabulary",
+			description: "Everyday words, used correctly",
+			weight: 1
+		},
+		{
+			name: "Task",
+			description: "Says what the learner did, in order",
+			weight: 1
+		}
+	] }
 };
-var weather = {
-  schemaVersion: "1.0",
-  type: "read-aloud",
-  id: "ai-check-reading",
-  title: "Read the forecast aloud",
-  referenceText: "The weather is warm in the north.",
-  locale: "en-US",
-  recording: { maxSeconds: 20 },
-  scoring: {
-    dimensions: [
-      { name: "accuracy", weight: 2 },
-      { name: "fluency", weight: 1 }
-    ]
-  }
+const weather = {
+	schemaVersion: "1.0",
+	type: "read-aloud",
+	id: "ai-check-reading",
+	title: "Read the forecast aloud",
+	referenceText: "The weather is warm in the north.",
+	locale: "en-US",
+	recording: { maxSeconds: 20 },
+	scoring: { dimensions: [{
+		name: "accuracy",
+		weight: 2
+	}, {
+		name: "fluency",
+		weight: 1
+	}] }
 };
-var said = (text, over = {}) => ({
-  text,
-  error: "none",
-  accuracy: 92,
-  ...over
+/** A word of the forecast as an engine reports it. */
+const said = (text, over = {}) => ({
+	text,
+	error: "none",
+	accuracy: 92,
+	...over
 });
+/**
+* An engine's assessment of the forecast. With `slips`, "weather" is
+* mispronounced — its "th" heard as /d/ or /z/ — and "north" is left out: the
+* marks a model must coach, and no others.
+*/
 function forecast(slips) {
-  return {
-    assessmentVersion: "1.0",
-    status: "assessed",
-    task: "scripted",
-    locale: "en-US",
-    referenceText: weather.referenceText,
-    recordingKey: "ai-check-take",
-    assessor: { kind: "auto", id: "pronunciation-engine" },
-    scale: 100,
-    scores: slips ? { accuracy: 68, fluency: 81, completeness: 86 } : { accuracy: 94, fluency: 90 },
-    miscue: "assessor",
-    phonemeAlphabet: "ipa",
-    words: [
-      said("The"),
-      slips ? said("weather", {
-        accuracy: 38,
-        error: "mispronunciation",
-        phonemes: [
-          { symbol: "w", accuracy: 90 },
-          { symbol: "\u025B", accuracy: 85 },
-          {
-            symbol: "\xF0",
-            accuracy: 12,
-            heardAs: [
-              { symbol: "d", score: 64 },
-              { symbol: "z", score: 21 },
-              { symbol: "\xF0", score: 12 }
-            ]
-          },
-          { symbol: "\u025A", accuracy: 80 }
-        ]
-      }) : said("weather"),
-      said("is"),
-      said("warm"),
-      said("in"),
-      said("the"),
-      slips ? { text: "north", error: "omission" } : said("north")
-    ]
-  };
+	return {
+		assessmentVersion: "1.0",
+		status: "assessed",
+		task: "scripted",
+		locale: "en-US",
+		referenceText: weather.referenceText,
+		recordingKey: "ai-check-take",
+		assessor: {
+			kind: "auto",
+			id: "pronunciation-engine"
+		},
+		scale: 100,
+		scores: slips ? {
+			accuracy: 68,
+			fluency: 81,
+			completeness: 86
+		} : {
+			accuracy: 94,
+			fluency: 90
+		},
+		miscue: "assessor",
+		phonemeAlphabet: "ipa",
+		words: [
+			said("The"),
+			slips ? said("weather", {
+				accuracy: 38,
+				error: "mispronunciation",
+				phonemes: [
+					{
+						symbol: "w",
+						accuracy: 90
+					},
+					{
+						symbol: "ɛ",
+						accuracy: 85
+					},
+					{
+						symbol: "ð",
+						accuracy: 12,
+						heardAs: [
+							{
+								symbol: "d",
+								score: 64
+							},
+							{
+								symbol: "z",
+								score: 21
+							},
+							{
+								symbol: "ð",
+								score: 12
+							}
+						]
+					},
+					{
+						symbol: "ɚ",
+						accuracy: 80
+					}
+				]
+			}) : said("weather"),
+			said("is"),
+			said("warm"),
+			said("in"),
+			said("the"),
+			slips ? {
+				text: "north",
+				error: "omission"
+			} : said("north")
+		]
+	};
 }
-var chose = (ids) => ({
-  type: "multiple-choice",
-  selectedOptionIds: ids
+const chose = (ids) => ({
+	type: "multiple-choice",
+	selectedOptionIds: ids
+});
+const typed = (answers) => ({
+	type: "fill-in-the-blanks",
+	answers
 });
-var typed = (answers) => ({
-  type: "fill-in-the-blanks",
-  answers
+const picked = (choices) => ({
+	type: "gap-select",
+	selections: choices
 });
-var picked = (choices) => ({
-  type: "gap-select",
-  selections: choices
+const wrote = (text) => ({
+	type: "dictation",
+	text
 });
-var wrote = (text) => ({ type: "dictation", text });
-var drafted = (text) => ({
-  type: "written-response",
-  text,
-  wordCount: 0
+const drafted = (text) => ({
+	type: "written-response",
+	text,
+	wordCount: 0
 });
-var fruit = {
-  schemaVersion: "1.0",
-  type: "multiple-choice",
-  id: "ai-check-fruit",
-  title: "Food words",
-  question: "Which of these is a fruit?",
-  mode: "single",
-  scoringStrategy: "all-or-nothing",
-  options: [
-    { id: "f1", text: "Apple", isCorrect: true },
-    { id: "f2", text: "Carrot", isCorrect: false },
-    { id: "f3", text: "Tomato", isCorrect: false }
-  ]
+/**
+* Items an author asks a model to review. Each is valid, and each but the last
+* has a flaw a rule cannot see: a distractor that is botanically a right
+* answer, and a task far above the level it is set for.
+*/
+const fruit = {
+	schemaVersion: "1.0",
+	type: "multiple-choice",
+	id: "ai-check-fruit",
+	title: "Food words",
+	question: "Which of these is a fruit?",
+	mode: "single",
+	scoringStrategy: "all-or-nothing",
+	options: [
+		{
+			id: "f1",
+			text: "Apple",
+			isCorrect: true
+		},
+		{
+			id: "f2",
+			text: "Carrot",
+			isCorrect: false
+		},
+		{
+			id: "f3",
+			text: "Tomato",
+			isCorrect: false
+		}
+	]
 };
-var tooHard = {
-  schemaVersion: "1.0",
-  type: "written-response",
-  id: "ai-check-too-hard",
-  title: "Cities",
-  prompt: "Discuss the socioeconomic ramifications of rapid urbanisation in developing economies.",
-  minWords: 40,
-  maxWords: 80
+const tooHard = {
+	schemaVersion: "1.0",
+	type: "written-response",
+	id: "ai-check-too-hard",
+	title: "Cities",
+	prompt: "Discuss the socioeconomic ramifications of rapid urbanisation in developing economies.",
+	minWords: 40,
+	maxWords: 80
 };
-var cleanCloze = {
-  schemaVersion: "1.0",
-  type: "fill-in-the-blanks",
-  id: "ai-check-clean-cloze",
-  title: "Daily routine",
-  passage: "Every morning I {{1}} up at seven and {{2}} a shower.",
-  blanks: [
-    { id: "1", acceptedAnswers: ["get", "wake"] },
-    { id: "2", acceptedAnswers: ["take", "have"] }
-  ],
-  scoringStrategy: "partial"
+const cleanCloze = {
+	schemaVersion: "1.0",
+	type: "fill-in-the-blanks",
+	id: "ai-check-clean-cloze",
+	title: "Daily routine",
+	passage: "Every morning I {{1}} up at seven and {{2}} a shower.",
+	blanks: [{
+		id: "1",
+		acceptedAnswers: ["get", "wake"]
+	}, {
+		id: "2",
+		acceptedAnswers: ["take", "have"]
+	}],
+	scoringStrategy: "partial"
 };
 function critiqueCase(id, about, type, draft, extra = {}) {
-  const request = aiCritiqueRequest({ type, draft, ...extra });
-  if (request === null) {
-    throw new Error(`ai-check: no critique request for "${id}"`);
-  }
-  return { id, feature: "item-critique", about, request };
+	const request = aiCritiqueRequest({
+		type,
+		draft,
+		...extra
+	});
+	if (request === null) throw new Error(`ai-check: no critique request for "${id}"`);
+	return {
+		id,
+		feature: "item-critique",
+		about,
+		request
+	};
 }
-var MARKET = "Maria lives in Seville, in the south of Spain. Every Saturday she walks to the market with her grandmother. They buy oranges, fresh bread and a little cheese. On the way home they stop at a caf\xE9, where Maria drinks hot chocolate and her grandmother reads the newspaper.";
-var MARKET_CAPTIONS = [
-  { start: 0, end: 4.2, text: "Maria lives in Seville, in the south of Spain." },
-  { start: 4.2, end: 8.9, text: "Every Saturday she walks to the market with her grandmother." },
-  { start: 8.9, end: 12.6, text: "They buy oranges, fresh bread and a little cheese." },
-  { start: 12.6, end: 18.1, text: "On the way home they stop at a caf\xE9." }
+/** A short reading to draft from: plain, and with facts a question can be asked about. */
+const MARKET = "Maria lives in Seville, in the south of Spain. Every Saturday she walks to the market with her grandmother. They buy oranges, fresh bread and a little cheese. On the way home they stop at a café, where Maria drinks hot chocolate and her grandmother reads the newspaper.";
+/** The same reading as a video's captions, with times in seconds. */
+const MARKET_CAPTIONS = [
+	{
+		start: 0,
+		end: 4.2,
+		text: "Maria lives in Seville, in the south of Spain."
+	},
+	{
+		start: 4.2,
+		end: 8.9,
+		text: "Every Saturday she walks to the market with her grandmother."
+	},
+	{
+		start: 8.9,
+		end: 12.6,
+		text: "They buy oranges, fresh bread and a little cheese."
+	},
+	{
+		start: 12.6,
+		end: 18.1,
+		text: "On the way home they stop at a café."
+	}
 ];
 function draftsCase(id, about, types, source, extra = {}) {
-  const request = aiDraftsRequest({ types, source, ...extra });
-  if (request === null) {
-    throw new Error(`ai-check: no drafts request for "${id}"`);
-  }
-  return { id, feature: "draft-generation", about, request };
+	const request = aiDraftsRequest({
+		types,
+		source,
+		...extra
+	});
+	if (request === null) throw new Error(`ai-check: no drafts request for "${id}"`);
+	return {
+		id,
+		feature: "draft-generation",
+		about,
+		request
+	};
 }
-var READ_ALOUD_SETTINGS = {
-  locale: "en-US",
-  recording: { maxSeconds: 20 },
-  scoring: { dimensions: [{ name: "accuracy", weight: 1 }] }
+/**
+* What a host sets on every read-aloud it drafts: the SDK has no default for a
+* recording's length or the dimensions a reading is graded on.
+*/
+const READ_ALOUD_SETTINGS = {
+	locale: "en-US",
+	recording: { maxSeconds: 20 },
+	scoring: { dimensions: [{
+		name: "accuracy",
+		weight: 1
+	}] }
 };
+/** Builds a case, failing loudly rather than shipping a case with no request. */
 function explanationCase(id, about, data, response) {
-  const request = aiExplanationRequest({ data, response });
-  if (request === null) {
-    throw new Error(`ai-check: no explanation request for "${id}"`);
-  }
-  return { id, feature: "explanation", about, request };
+	const request = aiExplanationRequest({
+		data,
+		response
+	});
+	if (request === null) throw new Error(`ai-check: no explanation request for "${id}"`);
+	return {
+		id,
+		feature: "explanation",
+		about,
+		request
+	};
 }
 function hintCase(id, about, data, response, previousHints = []) {
-  const request = aiHintRequest({ data, response, previousHints });
-  if (request === null) {
-    throw new Error(`ai-check: no hint request for "${id}"`);
-  }
-  return { id, feature: "hint", about, request };
+	const request = aiHintRequest({
+		data,
+		response,
+		previousHints
+	});
+	if (request === null) throw new Error(`ai-check: no hint request for "${id}"`);
+	return {
+		id,
+		feature: "hint",
+		about,
+		request
+	};
 }
 function writingCase(id, about, text, previousFeedback = [], learnerLocale) {
-  const request = aiWritingFeedbackRequest({
-    data: weekend,
-    response: drafted(text),
-    previousFeedback,
-    ...learnerLocale !== void 0 ? { learnerLocale } : {}
-  });
-  if (request === null) {
-    throw new Error(`ai-check: no writing feedback request for "${id}"`);
-  }
-  return { id, feature: "writing-feedback", about, request };
+	const request = aiWritingFeedbackRequest({
+		data: weekend,
+		response: drafted(text),
+		previousFeedback,
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	});
+	if (request === null) throw new Error(`ai-check: no writing feedback request for "${id}"`);
+	return {
+		id,
+		feature: "writing-feedback",
+		about,
+		request
+	};
 }
 function coachingCase(id, about, marks, learnerLocale) {
-  const assessment = marks.assessment ?? forecast(true);
-  const grade = gradeReadAloud(
-    weather,
-    { type: "read-aloud", recording: { key: "ai-check-take", mimeType: "audio/wav" } },
-    assessment,
-    {
-      measured: { durationMs: 4e3, voicedMs: 3e3 },
-      plausibility: { maxWordsPerSecond: 6, minVoicedMs: 500 }
-    }
-  );
-  if ("unscorable" in grade) {
-    throw new Error(`ai-check: the reading for "${id}" did not grade: ${grade.reason}`);
-  }
-  const request = aiCoachingRequest({
-    data: weather,
-    ...marks.fromGradeOnly === true ? {} : { assessment },
-    grade,
-    ...learnerLocale !== void 0 ? { learnerLocale } : {}
-  });
-  if (request === null) {
-    throw new Error(`ai-check: no coaching request for "${id}"`);
-  }
-  return { id, feature: "pronunciation-coaching", about, request };
+	const assessment = marks.assessment ?? forecast(true);
+	const grade = gradeReadAloud(weather, {
+		type: "read-aloud",
+		recording: {
+			key: "ai-check-take",
+			mimeType: "audio/wav"
+		}
+	}, assessment, {
+		measured: {
+			durationMs: 4e3,
+			voicedMs: 3e3
+		},
+		plausibility: {
+			maxWordsPerSecond: 6,
+			minVoicedMs: 500
+		}
+	});
+	if ("unscorable" in grade) throw new Error(`ai-check: the reading for "${id}" did not grade: ${grade.reason}`);
+	const request = aiCoachingRequest({
+		data: weather,
+		...marks.fromGradeOnly === true ? {} : { assessment },
+		grade,
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	});
+	if (request === null) throw new Error(`ai-check: no coaching request for "${id}"`);
+	return {
+		id,
+		feature: "pronunciation-coaching",
+		about,
+		request
+	};
 }
+/**
+* The cases {@link runAiCheck} runs: every type the SDK explains, answered
+* right, wrong and — where a type can be — partly right; every type it hints
+* for, before an answer and after a wrong one; and drafts of an essay, with
+* mistakes, without, and revised.
+*
+* They are ordinary calls. What makes them a test is that the SDK knows the
+* answer to each, so it can check what your model writes about it.
+*
+* A fresh array each call, so a caller may filter, slice or add to it without
+* changing what the next caller gets.
+*/
 function aiCheckCases() {
-  return [
-    explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
-    explanationCase("mc-wrong", "Chose Barcelona", capital, chose(["barcelona"])),
-    explanationCase("mc-blank", "Chose nothing and submitted", capital, chose([])),
-    explanationCase(
-      "fib-correct",
-      "Filled both blanks correctly",
-      introduction,
-      typed({ be: "is", live: "live" })
-    ),
-    explanationCase(
-      "fib-partly",
-      "One blank right, one wrong",
-      introduction,
-      typed({ be: "is", live: "lives" })
-    ),
-    explanationCase(
-      "fib-wrong",
-      "Both blanks wrong",
-      introduction,
-      typed({ be: "are", live: "living" })
-    ),
-    explanationCase(
-      "gap-partly",
-      "One gap right, one wrong, in Spanish",
-      landscape,
-      picked({ g1: "canon", g2: "es" })
-    ),
-    explanationCase(
-      "gap-wrong",
-      "Both gaps wrong, in Spanish",
-      landscape,
-      picked({ g1: "campo", g2: "es" })
-    ),
-    explanationCase(
-      "dictation-near",
-      "Typed the sentence with two words wrong",
-      listening,
-      wrote("The train leaves at half past five")
-    ),
-    explanationCase(
-      "dictation-correct",
-      "Typed the sentence correctly",
-      listening,
-      wrote("The train leaves at half past nine.")
-    ),
-    hintCase("mc-hint-1", "Has not answered yet", capital, chose([])),
-    hintCase("mc-hint-2", "Asked again after choosing Seville", capital, chose(["seville"]), [
-      "Think about where the government sits."
-    ]),
-    hintCase("fib-hint-1", "Both blanks empty", introduction, typed({})),
-    hintCase(
-      "fib-hint-2",
-      "Asked again with one blank wrong",
-      introduction,
-      typed({ be: "are", live: "" }),
-      ["Look again at the first blank."]
-    ),
-    hintCase("gap-hint-1", "Neither gap chosen, in Spanish", landscape, picked({})),
-    hintCase(
-      "gap-hint-2",
-      "Asked again with the first gap wrong",
-      landscape,
-      picked({ g1: "campo" }),
-      ["Piensa en la forma del terreno."]
-    ),
-    writingCase(
-      "writing-mistakes",
-      "A first draft with tense, article and agreement mistakes",
-      "Last weekend I go to the market and buyed a apple. My friends was there too, so we don't go home early. Then I go to the cinema."
-    ),
-    writingCase(
-      "writing-clean",
-      "A first draft with no mistakes to correct",
-      "Last weekend I went to the market and bought an apple. My friends were there too, so we stayed until the evening. Then we went to the cinema."
-    ),
-    writingCase(
-      "writing-revised",
-      "A second draft that fixed some mistakes",
-      "Last weekend I went to the market and bought a apple. My friends was there too, so we didn't go home early.",
-      ['Check your past tenses: "go" and "buyed" should be past forms.']
-    ),
-    writingCase(
-      "writing-feedback-in-spanish",
-      "A first draft, with feedback asked for in Spanish",
-      "Last weekend I visit my grandmother. She cook a big lunch and we eat together in the garden.",
-      [],
-      "es"
-    ),
-    coachingCase("coaching-slips", 'A reading with a mispronounced "th" and a word left out', {
-      assessment: forecast(true)
-    }),
-    coachingCase("coaching-clean", "A reading the engine marked correct throughout", {
-      assessment: forecast(false)
-    }),
-    coachingCase(
-      "coaching-from-grade",
-      "The same slips, from a stored grade: marks without sounds",
-      { fromGradeOnly: true }
-    ),
-    coachingCase(
-      "coaching-in-spanish",
-      "The same slips, with coaching asked for in Spanish",
-      { assessment: forecast(true) },
-      "es"
-    ),
-    critiqueCase(
-      "critique-second-answer",
-      'A question whose distractor "Tomato" is botanically a fruit',
-      "multiple-choice",
-      fruit,
-      { level: "A1" }
-    ),
-    critiqueCase(
-      "critique-level",
-      "A writing task far above the A1 level it is set for",
-      "written-response",
-      tooHard,
-      { level: "A1" }
-    ),
-    critiqueCase(
-      "critique-clean",
-      "A cloze with nothing wrong in it",
-      "fill-in-the-blanks",
-      cleanCloze,
-      {
-        level: "A2"
-      }
-    ),
-    critiqueCase(
-      "critique-in-spanish",
-      "The fruit question, reviewed in Spanish for its author",
-      "multiple-choice",
-      fruit,
-      { level: "A1", authorLocale: "es" }
-    ),
-    draftsCase(
-      "drafts-questions",
-      "Four multiple-choice questions on a short reading",
-      ["multiple-choice"],
-      { kind: "passage", text: MARKET },
-      { count: 4, level: "A2", locale: "en" }
-    ),
-    draftsCase(
-      "drafts-cloze",
-      "A cloze on the same reading, from its transcript",
-      ["fill-in-the-blanks"],
-      { kind: "transcript", text: MARKET },
-      { count: 1, level: "A2", locale: "en", instructions: "Blank the verbs." }
-    ),
-    draftsCase(
-      "drafts-gaps",
-      "A choose-the-word item on the same reading",
-      ["gap-select"],
-      { kind: "passage", text: MARKET },
-      { count: 1, level: "A2", locale: "en" }
-    ),
-    draftsCase(
-      "drafts-writing",
-      "A writing task that follows on from the reading",
-      ["written-response"],
-      { kind: "passage", text: MARKET },
-      { count: 1, level: "A2", locale: "en" }
-    ),
-    draftsCase(
-      "drafts-video",
-      "A video quiz from timed captions: multiple choice, then dictation, then read-aloud, as many as the video is worth",
-      ["multiple-choice", "dictation", "read-aloud"],
-      { kind: "captions", cues: MARKET_CAPTIONS },
-      { level: "A2", locale: "en", settings: { "read-aloud": READ_ALOUD_SETTINGS } }
-    ),
-    draftsCase(
-      "drafts-script",
-      "The same video from its script alone, with no times, and what the author asked for",
-      ["multiple-choice", "dictation", "read-aloud"],
-      { kind: "transcript", text: MARKET },
-      {
-        level: "A2",
-        locale: "en",
-        instructions: "Focus on what Maria and her grandmother buy.",
-        settings: { "read-aloud": READ_ALOUD_SETTINGS }
-      }
-    )
-  ];
+	return [
+		explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
+		explanationCase("mc-wrong", "Chose Barcelona", capital, chose(["barcelona"])),
+		explanationCase("mc-blank", "Chose nothing and submitted", capital, chose([])),
+		explanationCase("fib-correct", "Filled both blanks correctly", introduction, typed({
+			be: "is",
+			live: "live"
+		})),
+		explanationCase("fib-partly", "One blank right, one wrong", introduction, typed({
+			be: "is",
+			live: "lives"
+		})),
+		explanationCase("fib-wrong", "Both blanks wrong", introduction, typed({
+			be: "are",
+			live: "living"
+		})),
+		explanationCase("gap-partly", "One gap right, one wrong, in Spanish", landscape, picked({
+			g1: "canon",
+			g2: "es"
+		})),
+		explanationCase("gap-wrong", "Both gaps wrong, in Spanish", landscape, picked({
+			g1: "campo",
+			g2: "es"
+		})),
+		explanationCase("dictation-near", "Typed the sentence with two words wrong", listening, wrote("The train leaves at half past five")),
+		explanationCase("dictation-correct", "Typed the sentence correctly", listening, wrote("The train leaves at half past nine.")),
+		hintCase("mc-hint-1", "Has not answered yet", capital, chose([])),
+		hintCase("mc-hint-2", "Asked again after choosing Seville", capital, chose(["seville"]), ["Think about where the government sits."]),
+		hintCase("fib-hint-1", "Both blanks empty", introduction, typed({})),
+		hintCase("fib-hint-2", "Asked again with one blank wrong", introduction, typed({
+			be: "are",
+			live: ""
+		}), ["Look again at the first blank."]),
+		hintCase("gap-hint-1", "Neither gap chosen, in Spanish", landscape, picked({})),
+		hintCase("gap-hint-2", "Asked again with the first gap wrong", landscape, picked({ g1: "campo" }), ["Piensa en la forma del terreno."]),
+		writingCase("writing-mistakes", "A first draft with tense, article and agreement mistakes", "Last weekend I go to the market and buyed a apple. My friends was there too, so we don't go home early. Then I go to the cinema."),
+		writingCase("writing-clean", "A first draft with no mistakes to correct", "Last weekend I went to the market and bought an apple. My friends were there too, so we stayed until the evening. Then we went to the cinema."),
+		writingCase("writing-revised", "A second draft that fixed some mistakes", "Last weekend I went to the market and bought a apple. My friends was there too, so we didn't go home early.", ["Check your past tenses: \"go\" and \"buyed\" should be past forms."]),
+		writingCase("writing-feedback-in-spanish", "A first draft, with feedback asked for in Spanish", "Last weekend I visit my grandmother. She cook a big lunch and we eat together in the garden.", [], "es"),
+		coachingCase("coaching-slips", "A reading with a mispronounced \"th\" and a word left out", { assessment: forecast(true) }),
+		coachingCase("coaching-clean", "A reading the engine marked correct throughout", { assessment: forecast(false) }),
+		coachingCase("coaching-from-grade", "The same slips, from a stored grade: marks without sounds", { fromGradeOnly: true }),
+		coachingCase("coaching-in-spanish", "The same slips, with coaching asked for in Spanish", { assessment: forecast(true) }, "es"),
+		critiqueCase("critique-second-answer", "A question whose distractor \"Tomato\" is botanically a fruit", "multiple-choice", fruit, { level: "A1" }),
+		critiqueCase("critique-level", "A writing task far above the A1 level it is set for", "written-response", tooHard, { level: "A1" }),
+		critiqueCase("critique-clean", "A cloze with nothing wrong in it", "fill-in-the-blanks", cleanCloze, { level: "A2" }),
+		critiqueCase("critique-in-spanish", "The fruit question, reviewed in Spanish for its author", "multiple-choice", fruit, {
+			level: "A1",
+			authorLocale: "es"
+		}),
+		draftsCase("drafts-questions", "Four multiple-choice questions on a short reading", ["multiple-choice"], {
+			kind: "passage",
+			text: MARKET
+		}, {
+			count: 4,
+			level: "A2",
+			locale: "en"
+		}),
+		draftsCase("drafts-cloze", "A cloze on the same reading, from its transcript", ["fill-in-the-blanks"], {
+			kind: "transcript",
+			text: MARKET
+		}, {
+			count: 1,
+			level: "A2",
+			locale: "en",
+			instructions: "Blank the verbs."
+		}),
+		draftsCase("drafts-gaps", "A choose-the-word item on the same reading", ["gap-select"], {
+			kind: "passage",
+			text: MARKET
+		}, {
+			count: 1,
+			level: "A2",
+			locale: "en"
+		}),
+		draftsCase("drafts-writing", "A writing task that follows on from the reading", ["written-response"], {
+			kind: "passage",
+			text: MARKET
+		}, {
+			count: 1,
+			level: "A2",
+			locale: "en"
+		}),
+		draftsCase("drafts-video", "A video quiz from timed captions: multiple choice, then dictation, then read-aloud, as many as the video is worth", [
+			"multiple-choice",
+			"dictation",
+			"read-aloud"
+		], {
+			kind: "captions",
+			cues: MARKET_CAPTIONS
+		}, {
+			level: "A2",
+			locale: "en",
+			settings: { "read-aloud": READ_ALOUD_SETTINGS }
+		}),
+		draftsCase("drafts-script", "The same video from its script alone, with no times, and what the author asked for", [
+			"multiple-choice",
+			"dictation",
+			"read-aloud"
+		], {
+			kind: "transcript",
+			text: MARKET
+		}, {
+			level: "A2",
+			locale: "en",
+			instructions: "Focus on what Maria and her grandmother buy.",
+			settings: { "read-aloud": READ_ALOUD_SETTINGS }
+		})
+	];
 }
-
-// src/ai-check/index.ts
-var REFUSALS = [
-  "malformed",
-  "empty",
-  "too-long",
-  "contradicts-grade",
-  "reveals-answer",
-  "misquotes-answer",
-  "contradicts-marks",
-  "contradicts-item"
+//#endregion
+//#region src/ai-check/index.ts
+/**
+* A test kit for the prompts behind your AI ports.
+*
+* The SDK cannot test your model, and will not try. What it can do is make the
+* calls a learner's questions would make — on items whose answers it knows —
+* and run the same checks it runs before a learner sees anything. What comes
+* back is a count of what would have been shown and what would have been
+* refused, and why.
+*
+* Run it where you change a prompt or a model, in your own CI, with your own
+* key. It is a separate entry point (`@intellectif/lk-core/ai-check`) because
+* it is for your test run, not for a learner's browser: nothing here is
+* imported by anything a page renders.
+*
+* ```ts
+* import { aiCheckCases, formatAiCheckReport, runAiCheck } from '@intellectif/lk-core/ai-check';
+*
+* const report = await runAiCheck({
+*   explain: (request) => callMyModel(EXPLAIN_PROMPT, request),
+*   hint: (request) => callMyModel(HINT_PROMPT, request),
+*   writingFeedback: (request) => callMyModel(FEEDBACK_PROMPT, request),
+*   pronunciationCoaching: (request) => callMyModel(COACHING_PROMPT, request),
+*   critique: (request) => callMyModel(CRITIQUE_PROMPT, request),
+*   drafts: (request) => callMyModel(DRAFTS_PROMPT, request),
+* });
+* console.log(formatAiCheckReport(report));
+* if (report.refused > 0 || report.errors > 0) {
+*   process.exitCode = 1;
+* }
+* ```
+*
+* A refusal is a real failure, not a warning: it is an answer a learner would
+* have asked for and not received. `reveals-answer` on a hint case is the one
+* to take most seriously — that prompt gives answers away. Next come
+* `misquotes-answer` on a writing case — that prompt corrects words the learner
+* never wrote — and `contradicts-marks` on a coaching case: that prompt coaches
+* words the engine heard as right, or sounds it never reported.
+*/
+const REFUSALS = [
+	"malformed",
+	"empty",
+	"too-long",
+	"contradicts-grade",
+	"reveals-answer",
+	"misquotes-answer",
+	"contradicts-marks",
+	"contradicts-item"
 ];
+/** The port a case is for. */
 function portFor(ports, one) {
-  switch (one.request.feature) {
-    case "explanation":
-      return ports.explain;
-    case "hint":
-      return ports.hint;
-    case "pronunciation-coaching":
-      return ports.pronunciationCoaching;
-    case "item-critique":
-      return ports.critique;
-    case "draft-generation":
-      return ports.drafts;
-    default:
-      return ports.writingFeedback;
-  }
+	switch (one.request.feature) {
+		case "explanation": return ports.explain;
+		case "hint": return ports.hint;
+		case "pronunciation-coaching": return ports.pronunciationCoaching;
+		case "item-critique": return ports.critique;
+		case "draft-generation": return ports.drafts;
+		default: return ports.writingFeedback;
+	}
 }
-var now = () => Date.now();
+/** Milliseconds, from whichever clock this runtime has. */
+const now = () => Date.now();
+/** Runs one case: calls the port, times it, and checks what came back. */
 async function runCase(ports, one) {
-  const started = now();
-  const port = portFor(ports, one);
-  if (port === void 0) {
-    throw new Error(`ai-check: no port for "${one.id}"`);
-  }
-  let raw;
-  try {
-    raw = await port(one.request);
-  } catch (error) {
-    return {
-      case: one,
-      ok: false,
-      error: error instanceof Error ? error.message : String(error),
-      ms: now() - started
-    };
-  }
-  const ms = now() - started;
-  if (one.request.feature === "draft-generation") {
-    let next = 0;
-    const checked2 = checkAiDrafts(raw, one.request, {
-      newId: () => {
-        next += 1;
-        return `ai-check-${next}`;
-      }
-    });
-    return checked2.ok ? { case: one, ok: true, drafts: checked2.drafts, ms } : refused(one, raw, checked2.refusal, ms);
-  }
-  if (one.request.feature === "item-critique") {
-    const checked2 = checkAiCritique(raw, one.request);
-    return checked2.ok ? { case: one, ok: true, critique: checked2.critique, ms } : refused(one, raw, checked2.refusal, ms);
-  }
-  if (one.request.feature === "pronunciation-coaching") {
-    const checked2 = checkAiCoaching(raw, one.request);
-    if (checked2.ok) {
-      const { text, provenance, usage } = checked2.coaching;
-      return {
-        case: one,
-        ok: true,
-        result: {
-          text,
-          ...provenance !== void 0 ? { provenance } : {},
-          ...usage !== void 0 ? { usage } : {}
-        },
-        coaching: checked2.coaching,
-        ms
-      };
-    }
-    return refused(one, raw, checked2.refusal, ms);
-  }
-  if (one.request.feature === "writing-feedback") {
-    const checked2 = checkAiWritingFeedback(raw, one.request);
-    if (checked2.ok) {
-      const { text, provenance, usage } = checked2.feedback;
-      return {
-        case: one,
-        ok: true,
-        result: {
-          text,
-          ...provenance !== void 0 ? { provenance } : {},
-          ...usage !== void 0 ? { usage } : {}
-        },
-        feedback: checked2.feedback,
-        ms
-      };
-    }
-    return refused(one, raw, checked2.refusal, ms);
-  }
-  const checked = one.request.feature === "explanation" ? checkAiExplanation(raw, one.request) : checkAiHint(raw, one.request);
-  if (checked.ok) {
-    return { case: one, ok: true, result: checked.result, ms };
-  }
-  return refused(one, raw, checked.refusal, ms);
+	const started = now();
+	const port = portFor(ports, one);
+	if (port === void 0) throw new Error(`ai-check: no port for "${one.id}"`);
+	let raw;
+	try {
+		raw = await port(one.request);
+	} catch (error) {
+		return {
+			case: one,
+			ok: false,
+			error: error instanceof Error ? error.message : String(error),
+			ms: now() - started
+		};
+	}
+	const ms = now() - started;
+	if (one.request.feature === "draft-generation") {
+		let next = 0;
+		const checked = checkAiDrafts(raw, one.request, { newId: () => {
+			next += 1;
+			return `ai-check-${next}`;
+		} });
+		return checked.ok ? {
+			case: one,
+			ok: true,
+			drafts: checked.drafts,
+			ms
+		} : refused(one, raw, checked.refusal, ms);
+	}
+	if (one.request.feature === "item-critique") {
+		const checked = checkAiCritique(raw, one.request);
+		return checked.ok ? {
+			case: one,
+			ok: true,
+			critique: checked.critique,
+			ms
+		} : refused(one, raw, checked.refusal, ms);
+	}
+	if (one.request.feature === "pronunciation-coaching") {
+		const checked = checkAiCoaching(raw, one.request);
+		if (checked.ok) {
+			const { text, provenance, usage } = checked.coaching;
+			return {
+				case: one,
+				ok: true,
+				result: {
+					text,
+					...provenance !== void 0 ? { provenance } : {},
+					...usage !== void 0 ? { usage } : {}
+				},
+				coaching: checked.coaching,
+				ms
+			};
+		}
+		return refused(one, raw, checked.refusal, ms);
+	}
+	if (one.request.feature === "writing-feedback") {
+		const checked = checkAiWritingFeedback(raw, one.request);
+		if (checked.ok) {
+			const { text, provenance, usage } = checked.feedback;
+			return {
+				case: one,
+				ok: true,
+				result: {
+					text,
+					...provenance !== void 0 ? { provenance } : {},
+					...usage !== void 0 ? { usage } : {}
+				},
+				feedback: checked.feedback,
+				ms
+			};
+		}
+		return refused(one, raw, checked.refusal, ms);
+	}
+	const checked = one.request.feature === "explanation" ? checkAiExplanation(raw, one.request) : checkAiHint(raw, one.request);
+	if (checked.ok) return {
+		case: one,
+		ok: true,
+		result: checked.result,
+		ms
+	};
+	return refused(one, raw, checked.refusal, ms);
 }
+/** A case whose answer was refused, with the text that came back when there was one to read. */
 function refused(one, raw, refusal, ms) {
-  const text = typeof raw?.text === "string" ? raw : void 0;
-  return {
-    case: one,
-    ok: false,
-    refusal,
-    ...text !== void 0 ? { result: text } : {},
-    ms
-  };
+	const text = typeof raw?.text === "string" ? raw : void 0;
+	return {
+		case: one,
+		ok: false,
+		refusal,
+		...text !== void 0 ? { result: text } : {},
+		ms
+	};
 }
+/**
+* Calls your ports on every case and reports what a learner would have seen.
+*
+* It never throws for a failing case: a port that rejects is an `error` in the
+* report, so one bad call cannot hide the rest.
+*/
 async function runAiCheck(ports, options = {}) {
-  const all = options.cases ?? aiCheckCases();
-  const asked = Math.trunc(options.concurrency ?? 1);
-  const lanes = Number.isFinite(asked) && asked >= 1 ? Math.min(asked, 16) : 1;
-  const runnable = all.filter((one) => portFor(ports, one) !== void 0);
-  const results = new Array(runnable.length);
-  let next = 0;
-  const lane = async () => {
-    while (next < runnable.length) {
-      const mine = next;
-      next += 1;
-      const one = runnable[mine];
-      if (one === void 0) {
-        return;
-      }
-      results[mine] = await runCase(ports, one);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(lanes, runnable.length) }, lane));
-  const byRefusal = Object.fromEntries(REFUSALS.map((reason) => [reason, 0]));
-  let shown = 0;
-  let refused2 = 0;
-  let errors = 0;
-  for (const result of results) {
-    if (result.ok) {
-      shown += 1;
-    } else if (result.refusal !== void 0) {
-      refused2 += 1;
-      byRefusal[result.refusal] += 1;
-    } else {
-      errors += 1;
-    }
-  }
-  return {
-    total: results.length,
-    shown,
-    refused: refused2,
-    errors,
-    skipped: all.length - runnable.length,
-    byRefusal,
-    results
-  };
+	const all = options.cases ?? aiCheckCases();
+	const asked = Math.trunc(options.concurrency ?? 1);
+	const lanes = Number.isFinite(asked) && asked >= 1 ? Math.min(asked, 16) : 1;
+	const runnable = all.filter((one) => portFor(ports, one) !== void 0);
+	const results = new Array(runnable.length);
+	let next = 0;
+	const lane = async () => {
+		while (next < runnable.length) {
+			const mine = next;
+			next += 1;
+			const one = runnable[mine];
+			if (one === void 0) return;
+			results[mine] = await runCase(ports, one);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(lanes, runnable.length) }, lane));
+	const byRefusal = Object.fromEntries(REFUSALS.map((reason) => [reason, 0]));
+	let shown = 0;
+	let refused = 0;
+	let errors = 0;
+	for (const result of results) if (result.ok) shown += 1;
+	else if (result.refusal !== void 0) {
+		refused += 1;
+		byRefusal[result.refusal] += 1;
+	} else errors += 1;
+	return {
+		total: results.length,
+		shown,
+		refused,
+		errors,
+		skipped: all.length - runnable.length,
+		byRefusal,
+		results
+	};
 }
+/**
+* The report as a few lines for a CI log: the counts, then every case that
+* failed, with what came back.
+*
+* The refused text is printed — this is your own test run, not a learner's
+* screen, and a hint that gives the answer away is only fixable if you can
+* read it.
+*/
 function formatAiCheckReport(report) {
-  const lines = [];
-  const slowest = report.results.reduce((worst, one) => Math.max(worst, one.ms), 0);
-  lines.push(
-    `ai-check: ${report.shown}/${report.total} shown, ${report.refused} refused, ${report.errors} failed${report.skipped > 0 ? `, ${report.skipped} skipped (no port)` : ""} \u2014 slowest ${slowest} ms`
-  );
-  for (const reason of REFUSALS) {
-    const count = report.byRefusal[reason];
-    if (count > 0) {
-      lines.push(`  ${reason}: ${count}`);
-    }
-  }
-  for (const result of report.results) {
-    if (result.ok) {
-      continue;
-    }
-    const why = result.refusal ?? `port failed (${result.error ?? "no message"})`;
-    lines.push(`  \u2717 ${result.case.id} [${result.case.feature}] ${result.case.about}: ${why}`);
-    if (result.result !== void 0) {
-      lines.push(`      ${result.result.text.replace(/\s+/g, " ").slice(0, 200)}`);
-    }
-  }
-  return lines.join("\n");
+	const lines = [];
+	const slowest = report.results.reduce((worst, one) => Math.max(worst, one.ms), 0);
+	lines.push(`ai-check: ${report.shown}/${report.total} shown, ${report.refused} refused, ${report.errors} failed${report.skipped > 0 ? `, ${report.skipped} skipped (no port)` : ""} — slowest ${slowest} ms`);
+	for (const reason of REFUSALS) {
+		const count = report.byRefusal[reason];
+		if (count > 0) lines.push(`  ${reason}: ${count}`);
+	}
+	for (const result of report.results) {
+		if (result.ok) continue;
+		const why = result.refusal ?? `port failed (${result.error ?? "no message"})`;
+		lines.push(`  ✗ ${result.case.id} [${result.case.feature}] ${result.case.about}: ${why}`);
+		if (result.result !== void 0) lines.push(`      ${result.result.text.replace(/\s+/g, " ").slice(0, 200)}`);
+	}
+	return lines.join("\n");
 }
-export {
-  aiCheckCases,
-  formatAiCheckReport,
-  runAiCheck
-};
+//#endregion
+export { aiCheckCases, formatAiCheckReport, runAiCheck };
+
 //# sourceMappingURL=ai-check.js.map