@intellectif/lk-core 1.4.0 → 1.5.0

package/dist/{ai-writing-CPpH9Qxq.js → ai-writing-D8PdhJJz.js}

@@ -1,6 +1,6 @@
-import { B as issue, D as keyPositionFinding, F as covers, G as groupCaptionsField, H as refusesEmpty, I as isMissingId, L as isRecord$5, M as DRAFT_ISSUE_SEVERITY, N as checkMedia, O as normaliseFinding, P as coveredPathsOf, R as isUnset, V as pathKey, W as GROUP_CAPTIONS_REVEAL_DICTATION, Y as UnknownActivityTypeError, Z as alignDictation, a as readSchema, dt as containsWords, ft as fold, ht as revealsAnswer, j as countWords, mt as placeholderOrder, pt as numberedPassage, st as withValidationScope, t as getActivityTypeDescriptor, z as isUnwritten } from "./registry-Dsx9mNsS.js";
-import { c as validateSpeechAssessment, d as gradeFromRubric, r as score, s as alignReadAloud, w as isGradeInRange } from "./scoring-BZqUkuDF.js";
-import { a as INTERACTIVE_VIDEO_ITEM_TYPES, i as validateItemGroup, t as ItemGroupSchema, u as isInteractiveVideoItemType } from "./item-group-DXiR8nOr.js";
+import { B as covers, F as readRubricLevels, G as issue, H as isRecord$5, I as countWords, K as pathKey, L as DRAFT_ISSUE_SEVERITY, M as LEVEL_PROBABILITY_TOLERANCE, N as levelDistribution, O as keyPositionFinding, P as levelKey, R as checkMedia, U as isUnset, V as isMissingId, W as isUnwritten, X as groupCaptionsField, Y as GROUP_CAPTIONS_REVEAL_DICTATION, _t as fold, a as readSchema, bt as revealsAnswer, et as UnknownActivityTypeError, ft as withValidationScope, gt as containsWords, k as normaliseFinding, nt as alignDictation, q as refusesEmpty, t as getActivityTypeDescriptor, vt as numberedPassage, yt as placeholderOrder, z as coveredPathsOf } from "./registry-DaZRpqjW.js";
+import { F as isGradeInRange, _ as gradeFromRubric, c as validateSpeechAssessment, r as score, s as alignReadAloud } from "./scoring-BKNNTz-s.js";
+import { a as INTERACTIVE_VIDEO_ITEM_TYPES, i as validateItemGroup, t as ItemGroupSchema, u as isInteractiveVideoItemType } from "./item-group-DdSUCUjM.js";
 //#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 = 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 = 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 = 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(levelKey(name))) return {
+			ok: false,
+			problem: "duplicate-criteria",
+			path: [
+				"rubric",
+				"criteria",
+				index,
+				"name"
+			]
+		};
+		names.add(levelKey(name));
+		const levels = 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) => [levelKey(criterion.name), index]));
+	return (name) => folded.get(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) => levelKey(one.label) === 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 = 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 = 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;
@@ -2596,6 +2929,6 @@ function checkAiWritingFeedback(raw, request) {
 	};
 }
 //#endregion
-export { AI_TEXT_MAX_LENGTH as A, readAiTextResult as B, validateItemGroupDraft as C, checkAiCoaching as D, aiCoachingRequest as E, aiSupports as F, buildAiFacts as I, checkAiExplanation as L, aiExplanationRequest as M, aiGradeOf as N, AI_EXPLANATION_TYPES as O, aiHintRequest as P, checkAiHint as R, critiqueItemGroupDraft as S, AI_COACHING_MAX_WORDS as T, AI_MATERIAL_MAX_LENGTH as V, critiqueDraft as _, AI_DRAFTS_MAX_COUNT as a, createItemGroupDraft as b, aiDraftsRequest as c, interactiveVideoFromDrafts as d, AI_CRITIQUE_MAX_FIELD_LENGTH as f, createDraft as g, checkAiCritique as h, checkAiWritingFeedback as i, aiAllowedByContent as j, AI_HINT_TYPES as k, checkAiDrafts as l, aiCritiqueRequest as m, AI_WRITING_MAX_FIELD_LENGTH as n, AI_DRAFTS_MAX_REPAIRS as o, AI_CRITIQUE_MAX_FINDINGS as p, aiWritingFeedbackRequest as r, aiDraftsRepairRequest as s, AI_WRITING_MAX_CORRECTIONS as t, generateDrafts as u, validateDraft as v, AI_COACHING_MAX_TIP_LENGTH as w, critiqueDrafts as x, createInteractiveVideoDraft as y, hintRevealsAnswer as z };
+export { checkAiCoaching as A, checkAiExplanation as B, createItemGroupDraft as C, AI_COACHING_MAX_TIP_LENGTH as D, validateItemGroupDraft as E, aiExplanationRequest as F, hintRevealsAnswer as H, aiGradeOf as I, aiHintRequest as L, AI_HINT_TYPES as M, AI_TEXT_MAX_LENGTH as N, AI_COACHING_MAX_WORDS as O, aiAllowedByContent as P, aiSupports as R, createInteractiveVideoDraft as S, critiqueItemGroupDraft as T, readAiTextResult as U, checkAiHint as V, AI_MATERIAL_MAX_LENGTH as W, aiCritiqueRequest as _, checkAiGrading as a, critiqueDraft as b, AI_DRAFTS_MAX_COUNT as c, aiDraftsRequest as d, checkAiDrafts as f, AI_CRITIQUE_MAX_FINDINGS as g, AI_CRITIQUE_MAX_FIELD_LENGTH as h, aiGradingRequest as i, AI_EXPLANATION_TYPES as j, aiCoachingRequest as k, AI_DRAFTS_MAX_REPAIRS as l, interactiveVideoFromDrafts as m, checkAiWritingFeedback as n, AI_WRITING_MAX_CORRECTIONS as o, generateDrafts as p, AI_GRADING_PROBABILITY_TOLERANCE as r, AI_WRITING_MAX_FIELD_LENGTH as s, aiWritingFeedbackRequest as t, aiDraftsRepairRequest as u, checkAiCritique as v, critiqueDrafts as w, validateDraft as x, createDraft as y, buildAiFacts as z };
 
-//# sourceMappingURL=ai-writing-CPpH9Qxq.js.map
+//# sourceMappingURL=ai-writing-D8PdhJJz.js.map