@intellectif/lk-core 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @intellectif/lk-core
 
+## 1.9.0
+
+### Minor Changes
+
+- [#141](https://github.com/intellectif/learning-kit/pull/141) [`d5b3a3c`](https://github.com/intellectif/learning-kit/commit/d5b3a3c60278555160734af845eb062d918cd083) Thanks [@diego28e](https://github.com/diego28e)! - **`speaking-response`: a learner answers a prompt out loud, graded on a rubric by a judge on the transcript and by the speech engine's measures**
+
+  **Action required:** none. Everything is new; read-aloud grades, written-response grades and stored content are unchanged.
+
+  - **The type `speaking-response`**, built in and deferred like `written-response`: a prompt (plain and rich), optional instructions and media (a picture to describe, a recording to answer), a canonical locale with a region, recording bounds, and a rubric whose criteria may name a `measure` — `pronunciation`, `fluency` or `prosody`. A criterion with a measure is scored from the engine; one without, by a judge. The response is a recording, `{ type: 'speaking-response', recording }`, with `recording: null` for a blank. Schema, strict redacted schema, field policy (the rubric is public, `measure` included), JSON Schema, xAPI definition, `createDraft` and seventeen `sr_*` draft checks.
+  - **Evidence:** `SpeechAssessment.transcript?: { text, source }` — the transcriber's verbatim text of an unscripted take, and who wrote it — which the engine measured the take against and the judge reads. `gradeReadAloud` keeps refusing unscripted evidence (`task_mismatch`).
+  - **`gradeSpeakingResponse(data, response, { assessment, judgement }, options)`:** each criterion scored once, by the judge (an `AiGradingJudgement` from `checkAiGrading`, or a person's marks in that shape) or from the engine's scores out of 100, unless `judgeMeasures` gives the judge those too; the total by `gradeFromRubric`. A blank is 0. Evidence it cannot tie to the item and the take is refused with `read-aloud`'s codes, plus `judgement_mismatch` for a judgement that does not score each of the judge's criteria exactly once on its 0..1 scale. A judged grade carries the judge's feedback, corrections and identity, and `routeGrade` and `calibrationReport` take the speaking item as their scope.
+  - **`aiSpeakingGradingRequest`** builds a judge's request (`feature: 'speaking-grading'`): the task, the transcript verbatim, only the criteria the judge scores, and the measured criteria with the engine's scores as context. It builds none for evidence the grade would refuse. `checkAiGrading` accepts it beside a written response's request; `aiGradingRequest` and its facts are unchanged.
+  - **Vectors:** 58 grade vectors — every refusal, every policy and measurement bound, judge and engine, judged measures, rounding — and the type's validation seed; no existing expectation changed. A mutation sweep of the grade leaves 5 of 121 mutants alive, none of which changes a grade: refusal wording, error wording, a missing measurement thrown as a `TypeError` either way, and an inherited `redacted` marker JSON cannot carry (a unit test pins it).
+  - **Why a minor:** additive. `SpeechUnscorableCode` gains `judgement_mismatch`, and `BUILT_IN_ACTIVITY_TYPES` gains the type: a TypeScript `switch` or `Record` that is exhaustive over either needs one more entry.
+
+  Guide: https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md#spoken-answers-19
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/ai-check.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_ai_writing = require("./ai-writing-Bh2Y53cY.cjs");
-const require_scoring = require("./scoring-D9tFvPEG.cjs");
+const require_ai_writing = require("./ai-writing-DbpZpGRk.cjs");
+const require_scoring = require("./scoring-Db1CZeAn.cjs");
 // src/ai-check/cases.ts
 /**
 * The items the cases are built from. Small, ordinary language-course content

package/dist/ai-check.d.cts

@@ -1,4 +1,4 @@
-import { $ as AiTextResult, E as AiExplanationRequest, L as AiGradingJudgement, R as AiGradingRequest, S as AiDrafts, V as AiHintRequest, Y as AiRefusal, a as AiCoachingRequest, dt as AiVariantsRequest, i as AiCoaching, l as AiCritique, m as AiCritiqueRequest, ut as AiVariants, vt as AiWritingFeedback, w as AiDraftsRequest, yt as AiWritingFeedbackRequest } from "./ai-Cnm0qE8v.cjs";
+import { Ct as AiWritingFeedback, E as AiExplanationRequest, L as AiGradingJudgement, R as AiGradingRequest, S as AiDrafts, V as AiHintRequest, Y as AiRefusal, a as AiCoachingRequest, gt as AiVariantsRequest, ht as AiVariants, i as AiCoaching, it as AiTextResult, l as AiCritique, m as AiCritiqueRequest, w as AiDraftsRequest, wt as AiWritingFeedbackRequest } from "./ai-zhc9yhRj.cjs";
 /**
  * One call to make against a host's port, and what a learner was looking at
  * when the SDK would have made it.

package/dist/ai-check.d.ts

@@ -1,4 +1,4 @@
-import { $ as AiTextResult, E as AiExplanationRequest, L as AiGradingJudgement, R as AiGradingRequest, S as AiDrafts, V as AiHintRequest, Y as AiRefusal, a as AiCoachingRequest, dt as AiVariantsRequest, i as AiCoaching, l as AiCritique, m as AiCritiqueRequest, ut as AiVariants, vt as AiWritingFeedback, w as AiDraftsRequest, yt as AiWritingFeedbackRequest } from "./ai-Cnm0qE8v.js";
+import { Ct as AiWritingFeedback, E as AiExplanationRequest, L as AiGradingJudgement, R as AiGradingRequest, S as AiDrafts, V as AiHintRequest, Y as AiRefusal, a as AiCoachingRequest, gt as AiVariantsRequest, ht as AiVariants, i as AiCoaching, it as AiTextResult, l as AiCritique, m as AiCritiqueRequest, w as AiDraftsRequest, wt as AiWritingFeedbackRequest } from "./ai-zhc9yhRj.js";
 /**
  * One call to make against a host's port, and what a learner was looking at
  * when the SDK would have made it.

package/dist/ai-check.js

@@ -1,5 +1,5 @@
-import { E as checkAiCritique, T as aiCritiqueRequest, X as aiCoachingRequest, Z as checkAiCoaching, b as checkAiDrafts, c as aiVariantsRequest, ct as checkAiHint, f as aiGradingRequest, it as aiHintRequest, l as checkAiVariants, n as checkAiWritingFeedback, nt as aiExplanationRequest, p as checkAiGrading, st as checkAiExplanation, t as aiWritingFeedbackRequest, y as aiDraftsRequest } from "./ai-writing-DeIV-GfN.js";
-import { o as gradeReadAloud } from "./scoring-DIBmo_cy.js";
+import { D as checkAiCritique, E as aiCritiqueRequest, Q as checkAiCoaching, Z as aiCoachingRequest, at as aiHintRequest, b as aiDraftsRequest, c as aiVariantsRequest, ct as checkAiExplanation, f as aiGradingRequest, l as checkAiVariants, lt as checkAiHint, m as checkAiGrading, n as checkAiWritingFeedback, rt as aiExplanationRequest, t as aiWritingFeedbackRequest, x as checkAiDrafts } from "./ai-writing-DQjI9EFN.js";
+import { s as gradeReadAloud } from "./scoring-BGKdff2i.js";
 // src/ai-check/cases.ts
 /**
 * The items the cases are built from. Small, ordinary language-course content

package/dist/{ai-writing-DeIV-GfN.js → ai-writing-DQjI9EFN.js}

@@ -1,6 +1,6 @@
-import { A as normaliseFinding, B as checkMedia, Ct as revealsAnswer, F as levelDistribution, G as isUnset, H as covers, I as levelKey, J as pathKey, K as isUnwritten, L as readRubricLevels, O as keyPositionFinding, P as LEVEL_PROBABILITY_TOLERANCE, Q as groupCaptionsField, R as countWords, St as placeholderOrder, Tt as PLACEHOLDER_RE, U as isMissingId, V as coveredPathsOf, W as isRecord$8, Y as refusesEmpty, Z as GROUP_CAPTIONS_REVEAL_DICTATION, a as readSchema, bt as numberedPassage, it as alignDictation, j as policyFor, k as finding, mt as withValidationScope, nt as UnknownActivityTypeError, q as issue, t as getActivityTypeDescriptor, vt as containsWords, xt as passageWithoutPlaceholders, yt as fold, z as DRAFT_ISSUE_SEVERITY } from "./registry-tkacvJUI.js";
-import { F as isGradeInRange, S as canonicalJson, _ as gradeFromRubric, c as validateSpeechAssessment, h as seededShuffle, r as score, s as alignReadAloud } from "./scoring-DIBmo_cy.js";
-import { a as INTERACTIVE_VIDEO_ITEM_TYPES, i as validateItemGroup, t as ItemGroupSchema, u as isInteractiveVideoItemType } from "./item-group-BceUoxoM.js";
+import { $ as GROUP_CAPTIONS_REVEAL_DICTATION, A as keyPositionFinding, B as countWords, Ct as passageWithoutPlaceholders, Dt as PLACEHOLDER_RE, G as isMissingId, H as checkMedia, I as LEVEL_PROBABILITY_TOLERANCE, J as isUnwritten, K as isRecord$8, L as levelDistribution, M as normaliseFinding, N as policyFor, R as levelKey, St as numberedPassage, Tt as revealsAnswer, U as coveredPathsOf, V as DRAFT_ISSUE_SEVERITY, W as covers, X as pathKey, Y as issue, Z as refusesEmpty, a as readSchema, bt as containsWords, et as groupCaptionsField, gt as withValidationScope, it as UnknownActivityTypeError, j as finding, ot as alignDictation, q as isUnset, t as getActivityTypeDescriptor, v as SPEAKING_MEASURES, wt as placeholderOrder, xt as fold, z as readRubricLevels } from "./registry-Bw9grsCN.js";
+import { C as canonicalJson, I as isGradeInRange, c as alignReadAloud, g as seededShuffle, l as validateSpeechAssessment, r as score, v as gradeFromRubric } from "./scoring-BGKdff2i.js";
+import { a as INTERACTIVE_VIDEO_ITEM_TYPES, i as validateItemGroup, t as ItemGroupSchema, u as isInteractiveVideoItemType } from "./item-group-CKZk3txt.js";
 // src/ai-material.ts
 /**
 * What a model is told about the group a question sits in: the material the
@@ -3508,6 +3508,131 @@ function aiGradingRequest(input) {
 		}
 	};
 }
+const MEASURES = SPEAKING_MEASURES;
+/**
+* The request for a model's grade of a spoken answer (1.9), or why there is
+* none to make.
+*
+* Built as a written response's is, on the server and from the whole item, with
+* the take's evidence: the model reads `assessment.transcript` — the
+* transcriber's verbatim text, the same text the engine measured the take
+* against — and scores the criteria a judge scores: those that name no
+* `measure`, or every criterion when `judgeMeasures` is set. The measured
+* criteria go with it as context, with the engine's scores, so feedback can
+* speak of them; the model does not score them.
+*
+* The evidence is checked as `gradeSpeakingResponse` checks it — valid,
+* unscripted, for this item's locale and this response's recording — so a model
+* is never paid to judge a take the grade would refuse. Read the reply with
+* `checkAiGrading`, and grade with `gradeSpeakingResponse` under the same
+* `judgeMeasures`.
+*/
+function aiSpeakingGradingRequest(input) {
+	const { data, response, learnerLocale } = input;
+	if (data.type !== "speaking-response") return {
+		ok: false,
+		problem: "not-speaking-response"
+	};
+	if (data.redacted === true) return {
+		ok: false,
+		problem: "redacted"
+	};
+	const item = data;
+	const rubric = rubricFacts(item.rubric);
+	if (!rubric.ok) return rubric;
+	const authored = item.rubric.criteria;
+	const judged = [];
+	const measured = [];
+	for (const [index, fact] of rubric.criteria.entries()) {
+		const measure = authored[index].measure;
+		if (measure !== void 0 && !MEASURES.includes(measure)) return {
+			ok: false,
+			problem: "no-rubric",
+			path: [
+				"rubric",
+				"criteria",
+				index,
+				"measure"
+			]
+		};
+		if (measure === void 0 || input.judgeMeasures === true) judged.push({
+			...fact,
+			...measure !== void 0 ? { measure } : {}
+		});
+		else measured.push({
+			name: fact.name,
+			measure,
+			weight: fact.weight
+		});
+	}
+	if (judged.length === 0) return {
+		ok: false,
+		problem: "nothing-to-judge"
+	};
+	const recording = response?.type === "speaking-response" ? response.recording : null;
+	if (recording === null || recording === void 0) return {
+		ok: false,
+		problem: "empty-response"
+	};
+	const checked = input.assessment === null || input.assessment === void 0 ? void 0 : validateSpeechAssessment(input.assessment);
+	if (checked === void 0 || !checked.success) return {
+		ok: false,
+		problem: "invalid-assessment"
+	};
+	const evidence = checked.data;
+	if (evidence.status === "no_speech") return {
+		ok: false,
+		problem: "empty-response"
+	};
+	if (evidence.task !== "unscripted" || evidence.locale !== item.locale || evidence.recordingKey !== recording.key) return {
+		ok: false,
+		problem: "evidence-mismatch"
+	};
+	if (evidence.transcript === void 0) return {
+		ok: false,
+		problem: "no-transcript"
+	};
+	const text = evidence.transcript.text;
+	const scores = evidence.scores;
+	const scoreOf = {
+		pronunciation: scores.accuracy,
+		fluency: scores.fluency,
+		prosody: scores.prosody
+	};
+	const media = isRecord$1(item.media) && typeof item.media.type === "string" ? item.media : void 0;
+	const material = materialFacts(input.group);
+	return {
+		ok: true,
+		request: {
+			feature: "speaking-grading",
+			facts: {
+				activityType: "speaking-response",
+				activityId: data.id,
+				title: data.title,
+				locale: item.locale,
+				...typeof item.instructions === "string" ? { instructions: item.instructions } : {},
+				prompt: typeof item.prompt === "string" ? item.prompt : "",
+				...media !== void 0 ? { media: {
+					type: media.type,
+					...typeof media.alt === "string" ? { alt: media.alt } : {}
+				} } : {},
+				text,
+				wordCount: countWords(text),
+				rubric: judged,
+				measured: measured.map((fact) => {
+					const score = scoreOf[fact.measure];
+					return score !== void 0 ? {
+						...fact,
+						score
+					} : fact;
+				}),
+				...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$1(rubric) ? rubric.criteria : void 0;
@@ -5427,6 +5552,6 @@ function checkAiWritingFeedback(raw, request) {
 		}
 	};
 }
-export { AI_HINT_TYPES as $, createInteractiveVideoDraft as A, sharedAnswers as B, AI_CRITIQUE_MAX_FIELD_LENGTH as C, createDraft as D, checkAiCritique as E, AI_VARIANT_LENGTH_BANDS as F, listMediaRefs as G, structureMisses as H, AI_VARIANT_NEAR_COPY_THRESHOLD as I, AI_COACHING_MAX_TIP_LENGTH as J, mapMediaRefs as K, keysOf as L, critiqueDrafts as M, critiqueItemGroupDraft as N, critiqueDraft as O, validateItemGroupDraft as P, AI_EXPLANATION_TYPES as Q, lengthMisses as R, interactiveVideoFromDrafts as S, aiCritiqueRequest as T, textSimilarity as U, shownScore as V, textsOf as W, aiCoachingRequest as X, AI_COACHING_MAX_WORDS as Y, checkAiCoaching as Z, AI_DRAFTS_MAX_REPAIRS as _, AI_VARIANTS_MAX_REPAIRS as a, aiSupports as at, checkAiDrafts as b, aiVariantsRequest as c, checkAiHint as ct, AI_GRADING_PROBABILITY_TOLERANCE as d, AI_MATERIAL_MAX_LENGTH as dt, AI_TEXT_MAX_LENGTH as et, aiGradingRequest as f, AI_DRAFTS_MAX_COUNT as g, AI_WRITING_MAX_FIELD_LENGTH as h, AI_VARIANTS_MAX_MATERIAL_LENGTH as i, aiHintRequest as it, createItemGroupDraft as j, validateDraft as k, checkAiVariants as l, hintRevealsAnswer as lt, AI_WRITING_MAX_CORRECTIONS as m, checkAiWritingFeedback as n, aiExplanationRequest as nt, AI_VARIANT_CODE_SEVERITY as o, buildAiFacts as ot, checkAiGrading as p, transcriptOf as q, AI_VARIANTS_MAX_EXEMPLARS as r, aiGradeOf as rt, aiVariantsRepairRequest as s, checkAiExplanation as st, aiWritingFeedbackRequest as t, aiAllowedByContent as tt, generateVariants as u, readAiTextResult as ut, aiDraftsRepairRequest as v, AI_CRITIQUE_MAX_FINDINGS as w, generateDrafts as x, aiDraftsRequest as y, optionSet as z };
+export { AI_EXPLANATION_TYPES as $, validateDraft as A, optionSet as B, interactiveVideoFromDrafts as C, checkAiCritique as D, aiCritiqueRequest as E, validateItemGroupDraft as F, textsOf as G, shownScore as H, AI_VARIANT_LENGTH_BANDS as I, transcriptOf as J, listMediaRefs as K, AI_VARIANT_NEAR_COPY_THRESHOLD as L, createItemGroupDraft as M, critiqueDrafts as N, createDraft as O, critiqueItemGroupDraft as P, checkAiCoaching as Q, keysOf as R, generateDrafts as S, AI_CRITIQUE_MAX_FINDINGS as T, structureMisses as U, sharedAnswers as V, textSimilarity as W, AI_COACHING_MAX_WORDS as X, AI_COACHING_MAX_TIP_LENGTH as Y, aiCoachingRequest as Z, AI_DRAFTS_MAX_COUNT as _, AI_VARIANTS_MAX_REPAIRS as a, aiHintRequest as at, aiDraftsRequest as b, aiVariantsRequest as c, checkAiExplanation as ct, AI_GRADING_PROBABILITY_TOLERANCE as d, readAiTextResult as dt, AI_HINT_TYPES as et, aiGradingRequest as f, AI_MATERIAL_MAX_LENGTH as ft, AI_WRITING_MAX_FIELD_LENGTH as g, AI_WRITING_MAX_CORRECTIONS as h, AI_VARIANTS_MAX_MATERIAL_LENGTH as i, aiGradeOf as it, createInteractiveVideoDraft as j, critiqueDraft as k, checkAiVariants as l, checkAiHint as lt, checkAiGrading as m, checkAiWritingFeedback as n, aiAllowedByContent as nt, AI_VARIANT_CODE_SEVERITY as o, aiSupports as ot, aiSpeakingGradingRequest as p, mapMediaRefs as q, AI_VARIANTS_MAX_EXEMPLARS as r, aiExplanationRequest as rt, aiVariantsRepairRequest as s, buildAiFacts as st, aiWritingFeedbackRequest as t, AI_TEXT_MAX_LENGTH as tt, generateVariants as u, hintRevealsAnswer as ut, AI_DRAFTS_MAX_REPAIRS as v, AI_CRITIQUE_MAX_FIELD_LENGTH as w, checkAiDrafts as x, aiDraftsRepairRequest as y, lengthMisses as z };
 
-//# sourceMappingURL=ai-writing-DeIV-GfN.js.map
+//# sourceMappingURL=ai-writing-DQjI9EFN.js.map