@intellectif/lk-core 1.7.0 → 1.9.0

package/dist/{scoring-CtkCFyFT.cjs → scoring-Db1CZeAn.cjs}

@@ -1,4 +1,4 @@
-const require_registry = require("./registry-hzrkTeIT.cjs");
+const require_registry = require("./registry-C9O9txy5.cjs");
 let zod_v4 = require("zod/v4");
 zod_v4 = require_registry.__toESM(zod_v4, 1);
 // src/scoring/grade-numbers.ts
@@ -1407,6 +1407,10 @@ const SpeechAssessmentSchema = zod_v4.strictObject({
 		overall: Score.optional()
 	}),
 	recognizedText: require_registry.maxUnits(zod_v4.string(), 8e3).optional(),
+	transcript: zod_v4.strictObject({
+		text: require_registry.maxUnits(zod_v4.string().min(1), 8e3),
+		source: AssessorSchema
+	}).optional(),
 	miscue: zod_v4.enum(["assessor", "none"]),
 	phonemeAlphabet: zod_v4.enum(["ipa", "sapi"]).optional(),
 	words: zod_v4.array(WordSchema).max(require_registry.SPEECH_ASSESSMENT_MAX_WORDS),
@@ -1697,25 +1701,8 @@ function placeInsertions(assessment, entries) {
 		});
 	});
 }
-// src/scoring/speech/grade.ts
-/**
-* The read-aloud grade: the arithmetic over a pronunciation assessment's
-* dimension scores, and the checks that decide whether that evidence may be
-* graded at all.
-*
-* The SDK calls no assessor and holds no key. It is given the application's
-* assessment and the server's own measurement of the recording, and it refuses
-* evidence it cannot tie to this item, this text and this recording — a refusal
-* is never a zero, because a learner who was not heard has not failed.
-*/
-/**
-* Float slack when comparing two measurements of the same recording: voiced
-* time is summed window by window, so it can land a hair above the duration it
-* was measured from without either number being wrong.
-*/
-const MEASUREMENT_TOLERANCE = 1e-6;
 /** What every assessor score is out of, and what a criterion declares. */
-const ASSESSMENT_SCALE = 100;
+const ASSESSMENT_SCALE$1 = 100;
 /** A value named in an error message, without serialising the object it came from. */
 function describeValue$1(value) {
 	return typeof value === "number" ? String(value) : `of type ${typeof value}`;
@@ -1732,10 +1719,10 @@ function describeValue$1(value) {
 * recording-key binding. Every field is read once, and what is returned is what
 * was checked.
 */
-function readResponseRecording(value) {
+function readResponseRecording(value, expected = "read-aloud") {
 	if (typeof value !== "object" || value === null) return;
 	const { type, recording } = value;
-	if (type !== "read-aloud") return;
+	if (type !== expected) return;
 	if (recording === null) return { recording: null };
 	if (typeof recording !== "object") return;
 	const { key, mimeType } = recording;
@@ -1766,7 +1753,7 @@ function spokenWordCount(assessment) {
 */
 function scoreOf(entry) {
 	if (entry.state === "omitted") return { score: 0 };
-	return entry.accuracy !== void 0 ? { score: entry.accuracy / ASSESSMENT_SCALE } : {};
+	return entry.accuracy !== void 0 ? { score: entry.accuracy / ASSESSMENT_SCALE$1 } : {};
 }
 /**
 * Grades a read-aloud take from a {@link SpeechAssessment} the application
@@ -1837,7 +1824,7 @@ function gradeReadAloud(data, response, assessment, options) {
 	const measured = options.measured;
 	if (measured === null || measured === void 0) throw new TypeError("gradeReadAloud needs `options.measured`, the server's own measurement of the recording (inspectWav), for a response that carries a recording. A duration the client reported is not evidence.");
 	const { durationMs, voicedMs } = measured;
-	if (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0 || typeof voicedMs !== "number" || !Number.isFinite(voicedMs) || voicedMs < 0 || voicedMs > durationMs + MEASUREMENT_TOLERANCE) throw new RangeError(`Invalid recording measurement (durationMs ${describeValue$1(durationMs)}, voicedMs ${describeValue$1(voicedMs)}): expected finite millisecond counts, 0 or above, with voicedMs inside durationMs.`);
+	if (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0 || typeof voicedMs !== "number" || !Number.isFinite(voicedMs) || voicedMs < 0 || voicedMs > durationMs + 1e-6) throw new RangeError(`Invalid recording measurement (durationMs ${describeValue$1(durationMs)}, voicedMs ${describeValue$1(voicedMs)}): expected finite millisecond counts, 0 or above, with voicedMs inside durationMs.`);
 	const unscorable = (code, reason) => ({
 		unscorable: true,
 		code,
@@ -1861,7 +1848,7 @@ function gradeReadAloud(data, response, assessment, options) {
 	const graded = gradeFromRubric(weighed.map((dimension) => ({
 		name: dimension.name,
 		score: evidence.scores[dimension.name],
-		maxScore: ASSESSMENT_SCALE,
+		maxScore: ASSESSMENT_SCALE$1,
 		weight: dimension.weight
 	})), item, rounding !== void 0 ? { rounding } : {});
 	if ("unscorable" in graded) return unscorable("invalid_assessment", `No weighted total could be computed from the assessment's scores: ${graded.reason}`);
@@ -1888,6 +1875,207 @@ function gradeReadAloud(data, response, assessment, options) {
 function referenceWordsOf(data) {
 	return require_registry.dictationReferenceWords({ transcript: data.referenceText })[0];
 }
+// src/scoring/speech/grade-speaking.ts
+/**
+* The spoken-answer grade: a rubric scored partly by a judge, from the
+* transcript of what the learner said, and partly from an engine's measures of
+* how they said it.
+*
+* As for a read-aloud, the SDK calls no engine and no model. It is given the
+* application's unscripted assessment of the take, a judgement of the criteria
+* a judge scores, and the server's own measurement of the recording, and it
+* refuses evidence it cannot tie to this item and this recording — a refusal is
+* never a zero.
+*/
+/** What every assessor score is out of. */
+const ASSESSMENT_SCALE = 100;
+/** The assessment score each measure is read from. */
+const MEASURE_SCORE = {
+	pronunciation: "accuracy",
+	fluency: "fluency",
+	prosody: "prosody"
+};
+/**
+* How many words were spoken, for the speech-rate check: the transcript's when
+* the evidence carries one — it is the text the judge grades — and otherwise
+* what the engine recognised.
+*/
+function wordsSpoken(evidence) {
+	return evidence.transcript !== void 0 ? require_registry.countWords(evidence.transcript.text) : spokenWordCount(evidence);
+}
+/**
+* The judged criteria, each read once and matched to the criterion of the
+* rubric it judges — or why the judgement cannot be graded with this item.
+*/
+function matchJudgement(judgement, byJudge) {
+	const listed = judgement.criteria;
+	if (!Array.isArray(listed)) return "The judgement carries no list of criteria.";
+	const wanted = new Map(byJudge.map((criterion) => [require_registry.levelKey(criterion.name), criterion]));
+	const judged = /* @__PURE__ */ new Set();
+	const criteria = [];
+	for (const one of listed) {
+		const { name, score, level, probabilities, comment } = one ?? {};
+		const key = typeof name === "string" ? require_registry.levelKey(name) : void 0;
+		const criterion = key === void 0 ? void 0 : wanted.get(key);
+		if (key === void 0 || criterion === void 0 || judged.has(key)) return `The judgement names criterion ${typeof name === "string" ? `"${name}"` : describeValue$1(name)}, which is not one the judge scores on this item once.`;
+		if (typeof score !== "number" || !(score >= 0 && score <= 1)) return `The judgement scores "${criterion.name}" ${describeValue$1(score)}, off its 0..1 scale.`;
+		judged.add(key);
+		criteria.push({
+			name: criterion.name,
+			score,
+			weight: criterion.weight,
+			...level !== void 0 ? { band: level } : {},
+			...probabilities !== void 0 ? { levelProbabilities: [...probabilities] } : {},
+			...comment !== void 0 ? { comment } : {}
+		});
+	}
+	const left = byJudge.find((criterion) => !judged.has(require_registry.levelKey(criterion.name)));
+	if (left !== void 0) return `The judgement leaves out criterion "${left.name}". A total over fewer criteria would grade a different task.`;
+	return criteria;
+}
+/**
+* Grades a spoken answer to a `speaking-response` item (1.9).
+*
+* Each criterion of the rubric is scored once:
+*
+* - **by the judge** when it names no `measure` — what was said, how it was
+*   organised, the range and accuracy of the language — from
+*   `evidence.judgement`: a model's reply as `checkAiGrading` read it, or a
+*   person's marks in the same shape, each from 0 to 1;
+* - **from the engine** when it names one: `pronunciation` is the assessment's
+*   accuracy, `fluency` its fluency, `prosody` its prosody, each out of 100. With
+*   `options.judgeMeasures` the judge scores those too, and the engine's scores
+*   are not read.
+*
+* The weighted total is `gradeFromRubric`'s, over the item's weights and pass
+* line. Evidence is refused rather than scored, as a read-aloud's is: an
+* assessment that is not `unscripted`, not for the item's locale or not for
+* this recording; one from a model, unless `allowAiAssessor`; a take with no
+* speech, too little voiced time, or more words in its transcript than the
+* voiced time holds; a weighted measure the assessment has no score for
+* (`missing_dimension`); and a judgement that does not score each criterion the
+* judge scores exactly once, on its 0..1 scale (`judgement_mismatch`). A
+* judgement is matched whenever one is given, so marks meant for another item,
+* or for measures the judge was not asked to score, are refused.
+*
+* A blank (`response.recording === null`) is a grade of 0: the learner
+* submitted and said nothing. The evidence and the measurement are not read.
+*
+* With a judge, the grade is the judge's, as `gradeFromJudgement` makes one:
+* its feedback (or the authored feedback, when it gave none), its corrections
+* and rationale, `requiresHumanReview`, and `grader: { kind: 'ai', model,
+* promptHash }` — so `routeGrade` routes a spoken answer as it routes a written
+* one. Without one, the feedback is the authored feedback and the grader is the
+* engine that measured.
+*
+* @throws RangeError when `options.plausibility` or `options.rounding` cannot be
+* applied, or `options.measured` is not a pair of finite, non-negative
+* millisecond counts with `voicedMs` inside `durationMs`.
+* @throws TypeError when `response` is not a speaking-response response, or a
+* recording is graded without an assessment, a measurement, or — when the
+* judge scores a criterion — a judgement.
+* @throws ActivitySchemaError when `data` is not valid speaking-response data.
+* @throws RedactedScoringError when `data` is a `redact()` projection.
+*/
+function gradeSpeakingResponse(data, response, evidence, options) {
+	const maxWordsPerSecond = options?.plausibility?.maxWordsPerSecond;
+	if (typeof maxWordsPerSecond !== "number" || !Number.isFinite(maxWordsPerSecond) || maxWordsPerSecond <= 0) throw new RangeError(`Invalid plausibility policy (maxWordsPerSecond ${describeValue$1(maxWordsPerSecond)}): expected a finite number above 0.`);
+	const minVoicedMs = options?.plausibility?.minVoicedMs;
+	if (typeof minVoicedMs !== "number" || !Number.isFinite(minVoicedMs) || minVoicedMs < 0) throw new RangeError(`Invalid plausibility policy (minVoicedMs ${describeValue$1(minVoicedMs)}): expected a finite number of milliseconds, 0 or above.`);
+	const rounding = roundingPolicyOf(options?.rounding);
+	const parsed = require_registry.SpeakingResponseDataSchema.safeParse(data);
+	if (!parsed.success) throw new require_registry.ActivitySchemaError("speaking-response", parsed.error.issues.map((issue) => ({
+		path: issue.path.map(String),
+		message: issue.message,
+		code: issue.code
+	})));
+	if (isRedacted(data) || isRedacted(parsed.data)) throw new require_registry.RedactedScoringError("speaking-response");
+	const item = parsed.data;
+	const checkedResponse = readResponseRecording(response, "speaking-response");
+	if (checkedResponse === void 0) throw new TypeError("gradeSpeakingResponse needs a speaking-response response: { type: \"speaking-response\", recording: null } for a blank, or a recording with a non-empty `key` and a `mimeType`.");
+	const recording = checkedResponse.recording;
+	if (recording === null) {
+		const passed = computePassThreshold(item, 0, rounding);
+		return {
+			score: 0,
+			maxScore: 1,
+			passed,
+			feedback: selectFeedback(item, passed),
+			criteria: []
+		};
+	}
+	const judgeMeasures = options.judgeMeasures === true;
+	const byJudge = item.rubric.criteria.filter((criterion) => judgeMeasures || criterion.measure === void 0);
+	const byEngine = item.rubric.criteria.filter((criterion) => !judgeMeasures && criterion.measure !== void 0);
+	const assessment = evidence?.assessment;
+	if (assessment === null || assessment === void 0) throw new TypeError("gradeSpeakingResponse needs the engine's unscripted assessment of a response that carries a recording. Pass one, or grade the blank (recording: null).");
+	const judgement = evidence.judgement ?? void 0;
+	if (judgement === void 0 && byJudge.length > 0) throw new TypeError(`gradeSpeakingResponse needs a judgement of the criteria a judge scores on this item: ${byJudge.map((criterion) => `"${criterion.name}"`).join(", ")}.`);
+	const measured = options.measured;
+	if (measured === null || measured === void 0) throw new TypeError("gradeSpeakingResponse needs `options.measured`, the server's own measurement of the recording (inspectWav), for a response that carries a recording. A duration the client reported is not evidence.");
+	const { durationMs, voicedMs } = measured;
+	if (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0 || typeof voicedMs !== "number" || !Number.isFinite(voicedMs) || voicedMs < 0 || voicedMs > durationMs + 1e-6) throw new RangeError(`Invalid recording measurement (durationMs ${describeValue$1(durationMs)}, voicedMs ${describeValue$1(voicedMs)}): expected finite millisecond counts, 0 or above, with voicedMs inside durationMs.`);
+	const unscorable = (code, reason) => ({
+		unscorable: true,
+		code,
+		reason
+	});
+	const checked = validateSpeechAssessment(assessment);
+	if (!checked.success) return unscorable("invalid_assessment", `The speech assessment is not well formed (${describeValidationError(checked.errors[0])}).`);
+	const engine = checked.data;
+	if (engine.task !== "unscripted") return unscorable("task_mismatch", `The assessment was made for a "${engine.task}" task; a spoken answer is assessed unscripted, against what the learner said.`);
+	if (engine.locale !== item.locale) return unscorable("locale_mismatch", `The assessment was made for locale "${engine.locale}", and the item is answered in "${item.locale}". Pronunciation is assessed against one locale's speech.`);
+	if (engine.recordingKey !== recording.key) return unscorable("recording_mismatch", engine.recordingKey === void 0 ? `The assessment names no recording, and this response submitted "${recording.key}". Unscripted evidence must carry the key of the recording it measured.` : `The assessment was made for recording "${engine.recordingKey}", and this response submitted "${recording.key}".`);
+	if (engine.assessor.kind === "ai" && options.allowAiAssessor !== true) return unscorable("assessor_not_accepted", "The assessment was produced by a generative model. Pass `allowAiAssessor: true` to accept that as measurement evidence.");
+	if (engine.status === "no_speech") return unscorable("no_speech", "The assessor heard no speech in this recording.");
+	if (voicedMs < minVoicedMs) return unscorable("insufficient_voiced_time", `The recording holds ${voicedMs} ms of voiced time, and the policy asks for at least ${minVoicedMs} ms.`);
+	const words = wordsSpoken(engine);
+	if (words > 0 && (voicedMs === 0 || words / (voicedMs / 1e3) > maxWordsPerSecond)) return unscorable("implausible_speech_rate", `The assessment claims ${words} word(s) in ${voicedMs} ms of voiced time, above the ${maxWordsPerSecond} word(s) per second the policy allows.`);
+	const missing = byEngine.find((criterion) => criterion.weight > 0 && engine.scores[MEASURE_SCORE[criterion.measure]] === void 0);
+	if (missing !== void 0) {
+		const score = MEASURE_SCORE[missing.measure];
+		return unscorable("missing_dimension", `The item scores "${missing.name}" from ${missing.measure}, and the assessment carries no ${score} score. An absent score is not a 0.`);
+	}
+	const criteria = [];
+	for (const criterion of byEngine) {
+		const score = engine.scores[MEASURE_SCORE[criterion.measure]];
+		if (score !== void 0) criteria.push({
+			name: criterion.name,
+			score,
+			maxScore: ASSESSMENT_SCALE,
+			weight: criterion.weight
+		});
+	}
+	if (judgement !== void 0) {
+		const judged = matchJudgement(judgement, byJudge);
+		if (typeof judged === "string") return unscorable("judgement_mismatch", judged);
+		criteria.push(...judged);
+	}
+	const order = new Map(item.rubric.criteria.map((criterion, index) => [require_registry.levelKey(criterion.name), index]));
+	criteria.sort((a, b) => order.get(require_registry.levelKey(a.name)) - order.get(require_registry.levelKey(b.name)));
+	const graded = gradeFromRubric(criteria, item, rounding !== void 0 ? { rounding } : {});
+	if ("unscorable" in graded) return unscorable("invalid_assessment", `No weighted total could be computed from the evidence: ${graded.reason}`);
+	if (byJudge.length === 0 || judgement === void 0) return {
+		...graded,
+		feedback: selectFeedback(item, graded.passed),
+		grader: { ...engine.assessor }
+	};
+	const { provenance, usage } = judgement;
+	return {
+		...graded,
+		feedback: judgement.feedback ?? selectFeedback(item, graded.passed),
+		...judgement.corrections.length > 0 ? { corrections: [...judgement.corrections] } : {},
+		...judgement.rationale !== void 0 ? { rationale: judgement.rationale } : {},
+		requiresHumanReview: judgement.requiresHumanReview,
+		grader: {
+			kind: "ai",
+			...provenance?.model !== void 0 ? { model: provenance.model } : {},
+			...provenance?.promptHash !== void 0 ? { promptHash: provenance.promptHash } : {}
+		},
+		...usage !== void 0 ? { usage } : {},
+		...provenance?.generatedAt !== void 0 ? { gradedAt: provenance.generatedAt } : {}
+	};
+}
 // src/scoring/speech/wav.ts
 /** `RIFF` + the file size + `WAVE`, before the first chunk. */
 const HEADER_BYTES = 12;
@@ -2336,6 +2524,12 @@ Object.defineProperty(exports, "gradeReadAloud", {
 		return gradeReadAloud;
 	}
 });
+Object.defineProperty(exports, "gradeSpeakingResponse", {
+	enumerable: true,
+	get: function() {
+		return gradeSpeakingResponse;
+	}
+});
 Object.defineProperty(exports, "graderConfiguration", {
 	enumerable: true,
 	get: function() {
@@ -2445,4 +2639,4 @@ Object.defineProperty(exports, "validateSpeechAssessment", {
 	}
 });
 
-//# sourceMappingURL=scoring-CtkCFyFT.cjs.map
+//# sourceMappingURL=scoring-Db1CZeAn.cjs.map