@intellectif/lk-core 1.4.0 → 1.5.0

package/dist/{ai-writing-G6tnCGzw.cjs → ai-writing-Cen7-3qs.cjs}

@@ -1,6 +1,6 @@
-const require_registry = require("./registry-DVi0LR_i.cjs");
-const require_scoring = require("./scoring-B2_HEhMT.cjs");
-const require_item_group = require("./item-group-DroFXgLb.cjs");
+const require_registry = require("./registry-Ce00A_OW.cjs");
+const require_scoring = require("./scoring-lKQVYsxy.cjs");
+const require_item_group = require("./item-group-DEB7nLID.cjs");
 //#region src/ai-material.ts
 /**
 * What a model is told about the group a question sits in: the material the
@@ -2289,65 +2289,19 @@ function interactiveVideoFromDrafts(input) {
 	};
 }
 //#endregion
-//#region src/ai-writing.ts
+//#region src/ai-written.ts
+/**
+* What the AI features about a written response share: reading a model's text
+* fields, and finding each correction's quote in the learner's text.
+*
+* Internal. `ai-writing.ts` (feedback on a draft) and `ai-grading.ts` (a
+* grade) are their public faces, and hold every correction to the same
+* anchoring.
+*/
 /** The most corrections one piece of writing feedback may carry. More is refused, not cut. */
 const AI_WRITING_MAX_CORRECTIONS = 20;
 /** The longest quote, correction, explanation or criterion comment, in code points. */
 const AI_WRITING_MAX_FIELD_LENGTH = 500;
-/** The longest `category` or `band`: a tag, not a sentence. */
-const MAX_TAG_LENGTH = 40;
-/**
-* The request for feedback on a draft, or `null` when there is none to give:
-* not a written response, an author who switched explanations off (writing
-* feedback reads `ai.explanations`), a redacted item — feedback is for
-* practice, where the item is whole — or a draft with nothing in it.
-*
-* The facts are the task as the learner saw it, the draft verbatim with its
-* word count recomputed as the grader will count it, and the rubric the answer
-* will be graded on. `previousFeedback` is the text of the feedback already
-* shown on earlier drafts, so a model can speak to what changed. `group` is the
-* item group the task sits in: its material, the text a summary is of, goes
-* with the request as `material`.
-*/
-function aiWritingFeedbackRequest(input) {
-	const { data, response, learnerLocale } = input;
-	if (!aiSupports(data.type, "writing-feedback") || !aiAllowedByContent(data, "writing-feedback") || data.redacted === true) return null;
-	const text = response?.type === "written-response" ? response.text : "";
-	if (typeof text !== "string" || text.trim() === "") return null;
-	const item = data;
-	const wordCount = require_registry.countWords(text);
-	const minWords = typeof item.minWords === "number" ? item.minWords : 0;
-	const maxWords = typeof item.maxWords === "number" ? item.maxWords : Number.POSITIVE_INFINITY;
-	const criteria = Array.isArray(item.rubric?.criteria) ? item.rubric.criteria : null;
-	const rubric = criteria === null || criteria.length === 0 ? null : criteria.map((criterion) => ({
-		name: criterion.name,
-		...typeof criterion.description === "string" ? { description: criterion.description } : {},
-		weight: criterion.weight
-	}));
-	const previousFeedback = [...input.previousFeedback ?? []];
-	const material = materialFacts(input.group);
-	return {
-		feature: "writing-feedback",
-		facts: {
-			activityType: "written-response",
-			activityId: data.id,
-			title: data.title,
-			...typeof data.locale === "string" ? { locale: data.locale } : {},
-			prompt: typeof item.prompt === "string" ? item.prompt : "",
-			text,
-			wordCount,
-			minWords,
-			maxWords,
-			withinWordBounds: wordCount >= minWords && wordCount <= maxWords,
-			rubric,
-			...typeof item.languageTarget === "string" ? { languageTarget: item.languageTarget } : {}
-		},
-		draftNumber: previousFeedback.length + 1,
-		previousFeedback,
-		...material !== null ? { material } : {},
-		...learnerLocale !== void 0 ? { learnerLocale } : {}
-	};
-}
 /**
 * Where `quote` sits in the draft: at `claimed`, when the model named a range —
 * which must then hold the quote — or else at its first occurrence not already
@@ -2446,7 +2400,7 @@ function checkCorrections(raw, text) {
 			refusal: "malformed"
 		};
 		const explanation = textField(entry.explanation, 500);
-		const category = textField(entry.category, MAX_TAG_LENGTH);
+		const category = textField(entry.category, 40);
 		if (!explanation.ok) return explanation;
 		if (!category.ok) return category;
 		let claimed;
@@ -2478,6 +2432,385 @@ function checkCorrections(raw, text) {
 		corrections
 	};
 }
+//#endregion
+//#region src/ai-grading.ts
+/**
+* How far a model's level probabilities may sum from 1 and still be a
+* distribution: rounding in a model's output, not a different judgement.
+*/
+const AI_GRADING_PROBABILITY_TOLERANCE = require_registry.LEVEL_PROBABILITY_TOLERANCE;
+/**
+* The request for a model's grade of a submitted written response, or why there
+* is none to make.
+*
+* Grading happens on the server, from the whole item: the rubric is what a
+* model is held to, so an item without one — or one whose criteria are not each
+* a name and a weight — gives no request, nor does a `redact()` projection or
+* an empty response. A criterion's `levels`, when there are any, must be ones
+* the grading functions can read; levels they cannot read give no request
+* rather than a grade on a scale the author did not mean. `group` is the item
+* group the task sits in: its material goes with the request as `material`, as
+* on feedback on writing.
+*
+* The author's AI switch (`ai.explanations`) is not read: grading is the
+* deployment's decision, made on the server, not help a learner asks for.
+*/
+function aiGradingRequest(input) {
+	const { data, response, learnerLocale } = input;
+	if (data.type !== "written-response") return {
+		ok: false,
+		problem: "not-written-response"
+	};
+	if (data.redacted === true) return {
+		ok: false,
+		problem: "redacted"
+	};
+	const item = data;
+	const rubric = rubricFacts(item.rubric);
+	if (!rubric.ok) return rubric;
+	const text = response?.type === "written-response" ? response.text : void 0;
+	if (typeof text !== "string" || text.trim() === "") return {
+		ok: false,
+		problem: "empty-response"
+	};
+	const wordCount = require_registry.countWords(text);
+	const minWords = typeof item.minWords === "number" ? item.minWords : 0;
+	const maxWords = typeof item.maxWords === "number" ? item.maxWords : Number.POSITIVE_INFINITY;
+	const material = materialFacts(input.group);
+	return {
+		ok: true,
+		request: {
+			feature: "grading",
+			facts: {
+				activityType: "written-response",
+				activityId: data.id,
+				title: data.title,
+				...typeof data.locale === "string" ? { locale: data.locale } : {},
+				prompt: typeof item.prompt === "string" ? item.prompt : "",
+				text,
+				wordCount,
+				minWords,
+				maxWords,
+				withinWordBounds: wordCount >= minWords && wordCount <= maxWords,
+				rubric: rubric.criteria,
+				...typeof item.languageTarget === "string" ? { languageTarget: item.languageTarget } : {}
+			},
+			...material !== null ? { material } : {},
+			...learnerLocale !== void 0 ? { learnerLocale } : {}
+		}
+	};
+}
+/** The rubric as a model is given it, each criterion's levels read. */
+function rubricFacts(rubric) {
+	const listed = isRecord(rubric) ? rubric.criteria : void 0;
+	if (!Array.isArray(listed) || listed.length === 0) return {
+		ok: false,
+		problem: "no-rubric"
+	};
+	const criteria = [];
+	const names = /* @__PURE__ */ new Set();
+	for (const [index, criterion] of listed.entries()) {
+		if (!isRecord(criterion)) return {
+			ok: false,
+			problem: "no-rubric",
+			path: [
+				"rubric",
+				"criteria",
+				index
+			]
+		};
+		const { name, description, weight } = criterion;
+		if (typeof name !== "string" || name.trim() === "" || typeof weight !== "number") return {
+			ok: false,
+			problem: "no-rubric",
+			path: [
+				"rubric",
+				"criteria",
+				index
+			]
+		};
+		if (names.has(require_registry.levelKey(name))) return {
+			ok: false,
+			problem: "duplicate-criteria",
+			path: [
+				"rubric",
+				"criteria",
+				index,
+				"name"
+			]
+		};
+		names.add(require_registry.levelKey(name));
+		const levels = require_registry.readRubricLevels(criterion.levels);
+		if (!levels.ok) return {
+			ok: false,
+			problem: "unreadable-levels",
+			path: [
+				"rubric",
+				"criteria",
+				index,
+				"levels"
+			]
+		};
+		criteria.push({
+			name,
+			...typeof description === "string" ? { description } : {},
+			weight,
+			levels: levels.levels
+		});
+	}
+	return {
+		ok: true,
+		criteria
+	};
+}
+/**
+* The rubric's criteria by name, folded as level labels are: composed, trimmed,
+* spaced once, lower-cased. A model that writes "task achievement" for "Task
+* achievement" judged that criterion. The request refused a rubric with two
+* names alike once folded, so a folded name is one criterion's alone.
+*/
+function criterionIndex(rubric) {
+	const folded = new Map(rubric.map((criterion, index) => [require_registry.levelKey(criterion.name), index]));
+	return (name) => folded.get(require_registry.levelKey(name));
+}
+/** A finite number. */
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/**
+* One criterion's judgement, on that criterion's scale: a level it has, with
+* any probabilities a distribution over its levels whose likeliest is the
+* level chosen; or, without levels, a score from 0 to its `maxScore` (1 by
+* default).
+*/
+function judgeCriterion(entry, criterion) {
+	const { level, score, maxScore, probabilities } = entry;
+	const levels = criterion.levels;
+	if (levels === null) {
+		if (level !== void 0 || probabilities !== void 0) return {
+			ok: false,
+			refusal: "out-of-scale"
+		};
+		if (score === void 0) return {
+			ok: false,
+			refusal: "misses-criteria"
+		};
+		if (!isNumber(score) || maxScore !== void 0 && !isNumber(maxScore)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const max = maxScore ?? 1;
+		if (!(max > 0) || score < 0 || score - max > max * 1e-9) return {
+			ok: false,
+			refusal: "out-of-scale"
+		};
+		return {
+			ok: true,
+			judged: {
+				name: criterion.name,
+				score: Math.min(1, score / max)
+			}
+		};
+	}
+	if (score !== void 0 || maxScore !== void 0) return {
+		ok: false,
+		refusal: "out-of-scale"
+	};
+	if (level === void 0) return {
+		ok: false,
+		refusal: "misses-criteria"
+	};
+	if (typeof level !== "string") return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const chosen = levels.findIndex((one) => require_registry.levelKey(one.label) === require_registry.levelKey(level));
+	if (chosen === -1) return {
+		ok: false,
+		refusal: "out-of-scale"
+	};
+	const judged = {
+		name: criterion.name,
+		level: levels[chosen].label,
+		score: chosen / (levels.length - 1)
+	};
+	if (probabilities === void 0) return {
+		ok: true,
+		judged
+	};
+	if (!Array.isArray(probabilities)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const values = require_registry.levelDistribution(probabilities, levels.length, chosen);
+	if (values === null) return {
+		ok: false,
+		refusal: "out-of-scale"
+	};
+	return {
+		ok: true,
+		judged: {
+			...judged,
+			probabilities: values
+		}
+	};
+}
+/**
+* Checks a grade a port returned for `request`. Whole or nothing, as every AI
+* text is: a reply the SDK doubts in any part is refused, and is no grade —
+* re-ask the model or send the response to a person; never record a 0.
+*
+* - **Every criterion of the rubric, once** (`misses-criteria`). Names match as
+*   written, or folded when the folded name is one criterion's alone. Leaving
+*   one out, inventing or renaming one, judging one twice or calling one not
+*   applicable refuses the reply: a total renormalised over fewer criteria
+*   is a grade of a different task.
+* - **On each criterion's own scale** (`out-of-scale`). With levels: a `level`
+*   the criterion has, as labelled (case and spacing aside), and any
+*   `probabilities` a distribution over its levels, lowest first, whose
+*   likeliest is the level chosen. Without levels: a `score` from 0 to its
+*   `maxScore`, 1 by default.
+* - **Every correction quotes the response** (`misquotes-answer`), anchored as
+*   feedback on writing anchors it.
+* - **Text fields** — a criterion's `comment` (at most
+*   `AI_WRITING_MAX_FIELD_LENGTH` code points), `feedback` and `rationale`
+*   (at most `AI_TEXT_MAX_LENGTH`) — are plain text, cleaned; longer is
+*   `too-long`. `requiresHumanReview` is a boolean.
+*
+* The total is not computed here: `gradeFromJudgement` computes it, as
+* `gradeFromRubric` computes every grade in the SDK.
+*/
+function checkAiGrading(raw, request) {
+	if (!isRecord(raw)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const { criteria: listed, feedback, corrections, rationale, requiresHumanReview } = raw;
+	if (listed === void 0) return {
+		ok: false,
+		refusal: "misses-criteria"
+	};
+	if (!Array.isArray(listed)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const rubric = request.facts.rubric;
+	const indexOf = criterionIndex(rubric);
+	const judged = rubric.map(() => void 0);
+	for (const entry of listed) {
+		if (!isRecord(entry)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const name = entry.name;
+		const notApplicable = entry.notApplicable;
+		const written = entry.comment;
+		const scale = {
+			level: entry.level,
+			score: entry.score,
+			maxScore: entry.maxScore,
+			probabilities: entry.probabilities
+		};
+		if (typeof name !== "string" || notApplicable !== void 0 && typeof notApplicable !== "boolean") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const index = indexOf(name);
+		if (index === void 0 || judged[index] !== void 0 || notApplicable === true) return {
+			ok: false,
+			refusal: "misses-criteria"
+		};
+		const criterion = rubric[index];
+		const scaled = judgeCriterion(scale, criterion);
+		if (!scaled.ok) return scaled;
+		const comment = textField(written, 500);
+		if (!comment.ok) return comment;
+		judged[index] = {
+			...scaled.judged,
+			...comment.value !== void 0 ? { comment: comment.value } : {}
+		};
+	}
+	if (judged.some((one) => one === void 0)) return {
+		ok: false,
+		refusal: "misses-criteria"
+	};
+	const anchored = checkCorrections(corrections, request.facts.text);
+	if (!anchored.ok) return anchored;
+	const said = textField(feedback, AI_TEXT_MAX_LENGTH);
+	if (!said.ok) return said;
+	const why = textField(rationale, AI_TEXT_MAX_LENGTH);
+	if (!why.ok) return why;
+	if (requiresHumanReview !== void 0 && typeof requiresHumanReview !== "boolean") return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const provenance = provenanceOf(raw.provenance);
+	const usage = usageOf(raw.usage);
+	return {
+		ok: true,
+		judgement: {
+			criteria: judged,
+			feedback: said.value ?? null,
+			corrections: anchored.corrections,
+			...why.value !== void 0 ? { rationale: why.value } : {},
+			requiresHumanReview: requiresHumanReview === true,
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+//#endregion
+//#region src/ai-writing.ts
+/**
+* The request for feedback on a draft, or `null` when there is none to give:
+* not a written response, an author who switched explanations off (writing
+* feedback reads `ai.explanations`), a redacted item — feedback is for
+* practice, where the item is whole — or a draft with nothing in it.
+*
+* The facts are the task as the learner saw it, the draft verbatim with its
+* word count recomputed as the grader will count it, and the rubric the answer
+* will be graded on. `previousFeedback` is the text of the feedback already
+* shown on earlier drafts, so a model can speak to what changed. `group` is the
+* item group the task sits in: its material, the text a summary is of, goes
+* with the request as `material`.
+*/
+function aiWritingFeedbackRequest(input) {
+	const { data, response, learnerLocale } = input;
+	if (!aiSupports(data.type, "writing-feedback") || !aiAllowedByContent(data, "writing-feedback") || data.redacted === true) return null;
+	const text = response?.type === "written-response" ? response.text : "";
+	if (typeof text !== "string" || text.trim() === "") return null;
+	const item = data;
+	const wordCount = require_registry.countWords(text);
+	const minWords = typeof item.minWords === "number" ? item.minWords : 0;
+	const maxWords = typeof item.maxWords === "number" ? item.maxWords : Number.POSITIVE_INFINITY;
+	const criteria = Array.isArray(item.rubric?.criteria) ? item.rubric.criteria : null;
+	const rubric = criteria === null || criteria.length === 0 ? null : criteria.map((criterion) => ({
+		name: criterion.name,
+		...typeof criterion.description === "string" ? { description: criterion.description } : {},
+		weight: criterion.weight
+	}));
+	const previousFeedback = [...input.previousFeedback ?? []];
+	const material = materialFacts(input.group);
+	return {
+		feature: "writing-feedback",
+		facts: {
+			activityType: "written-response",
+			activityId: data.id,
+			title: data.title,
+			...typeof data.locale === "string" ? { locale: data.locale } : {},
+			prompt: typeof item.prompt === "string" ? item.prompt : "",
+			text,
+			wordCount,
+			minWords,
+			maxWords,
+			withinWordBounds: wordCount >= minWords && wordCount <= maxWords,
+			rubric,
+			...typeof item.languageTarget === "string" ? { languageTarget: item.languageTarget } : {}
+		},
+		draftNumber: previousFeedback.length + 1,
+		previousFeedback,
+		...material !== null ? { material } : {},
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	};
+}
 /** A criterion score a grade could be computed from: finite, 0 or more, and not above its maximum. */
 function isJudgedScore(score, maxScore) {
 	if (score === void 0) return maxScore === void 0 || typeof maxScore === "number" && maxScore > 0;
@@ -2524,7 +2857,7 @@ function checkCriteria(raw, rubric) {
 			ok: false,
 			refusal: "malformed"
 		};
-		const band = textField(entry.band, MAX_TAG_LENGTH);
+		const band = textField(entry.band, 40);
 		const comment = textField(entry.comment, 500);
 		if (!band.ok) return band;
 		if (!comment.ok) return comment;
@@ -2638,6 +2971,12 @@ Object.defineProperty(exports, "AI_EXPLANATION_TYPES", {
 		return AI_EXPLANATION_TYPES;
 	}
 });
+Object.defineProperty(exports, "AI_GRADING_PROBABILITY_TOLERANCE", {
+	enumerable: true,
+	get: function() {
+		return AI_GRADING_PROBABILITY_TOLERANCE;
+	}
+});
 Object.defineProperty(exports, "AI_HINT_TYPES", {
 	enumerable: true,
 	get: function() {
@@ -2710,6 +3049,12 @@ Object.defineProperty(exports, "aiGradeOf", {
 		return aiGradeOf;
 	}
 });
+Object.defineProperty(exports, "aiGradingRequest", {
+	enumerable: true,
+	get: function() {
+		return aiGradingRequest;
+	}
+});
 Object.defineProperty(exports, "aiHintRequest", {
 	enumerable: true,
 	get: function() {
@@ -2758,6 +3103,12 @@ Object.defineProperty(exports, "checkAiExplanation", {
 		return checkAiExplanation;
 	}
 });
+Object.defineProperty(exports, "checkAiGrading", {
+	enumerable: true,
+	get: function() {
+		return checkAiGrading;
+	}
+});
 Object.defineProperty(exports, "checkAiHint", {
 	enumerable: true,
 	get: function() {
@@ -2843,4 +3194,4 @@ Object.defineProperty(exports, "validateItemGroupDraft", {
 	}
 });
 
-//# sourceMappingURL=ai-writing-G6tnCGzw.cjs.map
+//# sourceMappingURL=ai-writing-Cen7-3qs.cjs.map