@intellectif/lk-core 0.16.0 → 0.18.0

package/dist/index.js

@@ -11,19 +11,20 @@ import {
   gte,
   hasGrade,
   inspectWav,
+  isGradeInRange,
   outcomeFromGrade,
   outcomeFromUnscorable,
   roundGrade,
   score,
   validateSpeechAssessment
-} from "./chunk-S63IOKFP.js";
+} from "./chunk-MMEQKFFQ.js";
 import {
   XAPIVerb,
   XAPI_VERB_DISPLAY,
   validateXAPIStatement,
   xAPIBuilder,
   xapiDefinitionFor
-} from "./chunk-OXF7VT7S.js";
+} from "./chunk-X5DAXBJI.js";
 import {
   INTERACTIVE_VIDEO_ITEM_TYPES,
   ItemGroupSchema,
@@ -49,9 +50,10 @@ import {
   validateActivity,
   validateItemGroup,
   writtenResponseJsonSchema
-} from "./chunk-GOZGBVJP.js";
+} from "./chunk-Z7QQZ53L.js";
 import {
   ActivitySchemaError,
+  AiPermissionsSchema,
   BlankConfigSchema,
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
   DICTATION_MAX_EQUIVALENCES,
@@ -80,6 +82,7 @@ import {
   MultipleChoiceOptionMediaSchema,
   MultipleChoiceOptionSchema,
   NativeControlHintSchema,
+  PLACEHOLDER_RE,
   READ_ALOUD_MAX_DIMENSION_WEIGHT,
   READ_ALOUD_MAX_REFERENCE_LENGTH,
   READ_ALOUD_MAX_SECONDS,
@@ -134,7 +137,410 @@ import {
   registeredActivityTypes,
   withValidationScope,
   writtenResponseType
-} from "./chunk-IRUD73IQ.js";
+} from "./chunk-D3GP5MET.js";
+
+// src/ai.ts
+var AI_EXPLANATION_TYPES = [
+  "multiple-choice",
+  "fill-in-the-blanks",
+  "gap-select",
+  "dictation"
+];
+var AI_HINT_TYPES = [
+  "multiple-choice",
+  "fill-in-the-blanks",
+  "gap-select"
+];
+var AI_TEXT_MAX_LENGTH = 2e3;
+function aiSupports(activityType, feature) {
+  const types = feature === "hint" ? AI_HINT_TYPES : AI_EXPLANATION_TYPES;
+  return types.includes(activityType);
+}
+function aiAllowedByContent(data, feature) {
+  const permissions = data.ai;
+  if (typeof permissions !== "object" || permissions === null) {
+    return true;
+  }
+  const key = feature === "hint" ? "hints" : "explanations";
+  return permissions[key] !== false;
+}
+function aiGradeOf(result) {
+  const ratio = result.maxScore > 0 ? result.score / result.maxScore : 0;
+  let category = "partly-correct";
+  if (ratio >= 1 - 1e-9) {
+    category = "correct";
+  } else if (ratio <= 1e-9) {
+    category = "incorrect";
+  }
+  return { score: result.score, maxScore: result.maxScore, passed: result.passed, category };
+}
+function placeholderOrder(passage) {
+  return [...passage.matchAll(PLACEHOLDER_RE)].map((match) => match[1]);
+}
+function numberedPassage(passage) {
+  let position = 0;
+  return passage.replace(PLACEHOLDER_RE, () => {
+    position += 1;
+    return `[${position}]`;
+  });
+}
+function isAnswerOption(detail, chosen) {
+  switch (detail.outcome) {
+    case "correct":
+    case "incorrect-omission":
+      return true;
+    case "incorrect":
+    case "correct-omission":
+      return false;
+    default:
+      return chosen ? detail.correct : !detail.correct;
+  }
+}
+var firstString = (value) => Array.isArray(value) ? value[0] : value;
+var listOf = (value) => value === void 0 ? null : Array.isArray(value) ? [...value] : [value];
+function emptyResponse(type) {
+  switch (type) {
+    case "multiple-choice":
+      return { type: "multiple-choice", selectedOptionIds: [] };
+    case "fill-in-the-blanks":
+      return { type: "fill-in-the-blanks", answers: {} };
+    case "gap-select":
+      return { type: "gap-select", selections: {} };
+    case "dictation":
+      return { type: "dictation", text: "" };
+    default:
+      return null;
+  }
+}
+var base = (data) => ({
+  activityId: data.id,
+  title: data.title,
+  ...typeof data.locale === "string" ? { locale: data.locale } : {}
+});
+function buildAiFacts(data, response, details) {
+  const byId = new Map((details ?? []).map((detail) => [detail.itemId, detail]));
+  const full = data.redacted !== true;
+  switch (data.type) {
+    case "multiple-choice": {
+      const item = data;
+      const chosen = new Set(
+        response?.type === "multiple-choice" ? response.selectedOptionIds : []
+      );
+      return {
+        ...base(data),
+        activityType: "multiple-choice",
+        question: item.question,
+        mode: item.mode,
+        options: item.options.map((option) => {
+          const detail = byId.get(option.id);
+          const wasChosen = chosen.has(option.id);
+          let correct = null;
+          if (full && typeof option.isCorrect === "boolean") {
+            correct = option.isCorrect;
+          } else if (detail !== void 0) {
+            correct = isAnswerOption(detail, wasChosen);
+          }
+          return {
+            id: option.id,
+            text: option.text,
+            chosen: wasChosen,
+            correct,
+            ...typeof option.feedback === "string" ? { feedback: option.feedback } : {}
+          };
+        })
+      };
+    }
+    case "fill-in-the-blanks": {
+      const item = data;
+      const answers = response?.type === "fill-in-the-blanks" ? response.answers : {};
+      const blanks = new Map(item.blanks.map((blank) => [blank.id, blank]));
+      return {
+        ...base(data),
+        activityType: "fill-in-the-blanks",
+        passage: numberedPassage(item.passage),
+        blanks: placeholderOrder(item.passage).map((id, index) => {
+          const blank = blanks.get(id);
+          const detail = byId.get(id);
+          const accepted = full && Array.isArray(blank?.acceptedAnswers) ? [...blank.acceptedAnswers] : listOf(detail?.correctResponse);
+          return {
+            id,
+            position: index + 1,
+            typed: typeof answers[id] === "string" ? answers[id] : "",
+            accepted,
+            correct: detail === void 0 ? null : detail.correct,
+            ...typeof blank?.hint === "string" ? { hint: blank.hint } : {},
+            ...typeof blank?.feedback === "string" ? { feedback: blank.feedback } : {}
+          };
+        })
+      };
+    }
+    case "gap-select": {
+      const item = data;
+      const selections = response?.type === "gap-select" ? response.selections : {};
+      const gaps = new Map(item.gaps.map((gap) => [gap.id, gap]));
+      const banks = new Map((item.banks ?? []).map((bank) => [bank.id, bank]));
+      return {
+        ...base(data),
+        activityType: "gap-select",
+        passage: numberedPassage(item.passage),
+        gaps: placeholderOrder(item.passage).map((id, index) => {
+          const gap = gaps.get(id);
+          const choices = gap?.choices ?? (gap?.bankId === void 0 ? [] : banks.get(gap.bankId)?.choices ?? []);
+          const textOf = (choiceId) => choiceId === void 0 ? null : choices.find((choice) => choice.id === choiceId)?.text ?? null;
+          const detail = byId.get(id);
+          const answerId = full && typeof gap?.correctChoiceId === "string" ? gap.correctChoiceId : firstString(detail?.correctResponse);
+          return {
+            id,
+            position: index + 1,
+            choices: choices.map((choice) => choice.text),
+            chosen: textOf(selections[id]),
+            answer: textOf(answerId),
+            correct: detail === void 0 ? null : detail.correct,
+            ...typeof gap?.feedback === "string" ? { feedback: gap.feedback } : {}
+          };
+        })
+      };
+    }
+    case "dictation": {
+      const item = data;
+      const typed = response?.type === "dictation" ? response.text : "";
+      const hasKey = full && typeof item.transcript === "string";
+      let words = null;
+      if (hasKey) {
+        words = alignDictation(item, typed).words.map((word) => ({
+          expected: word.reference,
+          typed: word.attempt,
+          status: word.status
+        }));
+      } else if (details !== null && details.length > 0) {
+        words = details.map((detail) => {
+          const expected = firstString(detail.correctResponse) ?? "";
+          const attempt = firstString(detail.learnerResponse) ?? "";
+          let status = "incorrect";
+          if (detail.correct) {
+            status = "correct";
+          } else if (attempt === "") {
+            status = "missing";
+          } else if (expected === "") {
+            status = "extra";
+          }
+          return { expected, typed: attempt, status };
+        });
+      }
+      return {
+        ...base(data),
+        activityType: "dictation",
+        transcript: hasKey ? item.transcript : null,
+        typed,
+        words
+      };
+    }
+    default:
+      return null;
+  }
+}
+function gradeLocally(data, response) {
+  if (data.redacted === true) {
+    return null;
+  }
+  try {
+    const result = score(data.type, data, response);
+    return { details: result.details, grade: aiGradeOf(result) };
+  } catch {
+    return null;
+  }
+}
+function aiExplanationRequest(input) {
+  const { data, response, outcome, learnerLocale } = input;
+  if (!aiSupports(data.type, "explanation") || !aiAllowedByContent(data, "explanation")) {
+    return null;
+  }
+  let details = null;
+  let grade = null;
+  if (outcome?.status === "scored") {
+    const { score: recorded, maxScore, passed } = outcome;
+    if (!isGradeInRange(recorded, maxScore)) {
+      return null;
+    }
+    details = outcome.details;
+    grade = aiGradeOf({ score: recorded, maxScore, passed });
+  } else if (response !== null) {
+    const local = gradeLocally(data, response);
+    if (local !== null) {
+      details = local.details;
+      grade = local.grade;
+    }
+  }
+  if (grade === null) {
+    return null;
+  }
+  const facts = buildAiFacts(data, response, details);
+  if (facts === null) {
+    return null;
+  }
+  return {
+    feature: "explanation",
+    facts,
+    grade,
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  };
+}
+function aiHintRequest(input) {
+  const { data, previousHints, learnerLocale } = input;
+  if (!aiSupports(data.type, "hint") || !aiAllowedByContent(data, "hint") || data.redacted === true) {
+    return null;
+  }
+  const response = input.response ?? emptyResponse(data.type);
+  const local = response === null ? null : gradeLocally(data, response);
+  const facts = buildAiFacts(data, response, local?.details ?? null);
+  if (facts === null) {
+    return null;
+  }
+  return {
+    feature: "hint",
+    facts,
+    hintNumber: previousHints.length + 1,
+    previousHints: [...previousHints],
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  };
+}
+var VERDICTS = ["correct", "partly-correct", "incorrect"];
+function provenanceOf(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const kept = {};
+  for (const key of ["model", "promptHash", "generatedAt"]) {
+    const value = raw[key];
+    if (typeof value === "string" && value.length > 0 && value.length <= 200) {
+      kept[key] = value;
+    }
+  }
+  return Object.keys(kept).length > 0 ? kept : void 0;
+}
+function cleanText(text) {
+  return text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u2028\u2029]/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function readAiTextResult(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, refusal: "malformed" };
+  }
+  const record = raw;
+  if (typeof record.text !== "string") {
+    return { ok: false, refusal: "malformed" };
+  }
+  if (record.verdict !== void 0 && !VERDICTS.includes(record.verdict)) {
+    return { ok: false, refusal: "malformed" };
+  }
+  const text = cleanText(record.text);
+  if (text === "") {
+    return { ok: false, refusal: "empty" };
+  }
+  if ([...text].length > AI_TEXT_MAX_LENGTH) {
+    return { ok: false, refusal: "too-long" };
+  }
+  const provenance = provenanceOf(record.provenance);
+  return {
+    ok: true,
+    result: {
+      text,
+      ...record.verdict !== void 0 ? { verdict: record.verdict } : {},
+      ...provenance !== void 0 ? { provenance } : {}
+    }
+  };
+}
+function checkAiExplanation(raw, request) {
+  const read = readAiTextResult(raw);
+  if (!read.ok) {
+    return read;
+  }
+  if (read.result.verdict !== void 0 && read.result.verdict !== request.grade.category) {
+    return { ok: false, refusal: "contradicts-grade" };
+  }
+  return read;
+}
+function checkAiHint(raw, request) {
+  const read = readAiTextResult(raw);
+  if (!read.ok) {
+    return read;
+  }
+  if (hintRevealsAnswer(request.facts, read.result.text)) {
+    return { ok: false, refusal: "reveals-answer" };
+  }
+  return read;
+}
+function fold(text) {
+  const folded = text.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+  return folded === "" ? [] : folded.split(" ");
+}
+function containsWords(haystack, needle) {
+  if (needle.length === 0 || needle.length > haystack.length) {
+    return false;
+  }
+  for (let start = 0; start + needle.length <= haystack.length; start += 1) {
+    let match = true;
+    for (let offset = 0; offset < needle.length; offset += 1) {
+      if (haystack[start + offset] !== needle[offset]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      return true;
+    }
+  }
+  return false;
+}
+var isShort = (words) => words.length === 1 && [...words[0]].length < 4;
+function neighbours(passage, position) {
+  const marker = `[${position}]`;
+  const at = passage.indexOf(marker);
+  if (at === -1) {
+    return {};
+  }
+  const strip = (text) => text.replace(/\[\d+\]/g, " ");
+  const left = fold(strip(passage.slice(0, at)));
+  const right = fold(strip(passage.slice(at + marker.length)));
+  const before = left[left.length - 1];
+  const after = right[0];
+  return {
+    ...before !== void 0 ? { before } : {},
+    ...after !== void 0 ? { after } : {}
+  };
+}
+function hintRevealsAnswer(facts, hint) {
+  const words = fold(hint);
+  const reveals = (answer, passage, position) => {
+    const needle = fold(answer);
+    if (needle.length === 0) {
+      return false;
+    }
+    if (!isShort(needle) || passage === void 0 || position === void 0) {
+      return containsWords(words, needle);
+    }
+    const { before, after } = neighbours(passage, position);
+    if (before === void 0 && after === void 0) {
+      return containsWords(words, needle);
+    }
+    return before !== void 0 && containsWords(words, [before, ...needle]) || after !== void 0 && containsWords(words, [...needle, after]);
+  };
+  switch (facts.activityType) {
+    case "multiple-choice":
+      return facts.options.some((option) => option.correct === true && reveals(option.text));
+    case "fill-in-the-blanks":
+      return facts.blanks.some(
+        (blank) => (blank.accepted ?? []).some((answer) => reveals(answer, facts.passage, blank.position))
+      );
+    case "gap-select":
+      return facts.gaps.some(
+        (gap) => gap.answer !== null && reveals(gap.answer, facts.passage, gap.position)
+      );
+    case "dictation":
+      return false;
+    default:
+      return false;
+  }
+}
 
 // src/content-hash.ts
 function canonicalJson(value, seen = /* @__PURE__ */ new Set()) {
@@ -1219,11 +1625,11 @@ function normalise(found) {
 }
 
 // src/redact.ts
-function mergePolicy(base, overrides) {
+function mergePolicy(base2, overrides) {
   if (overrides === void 0) {
-    return base;
+    return base2;
   }
-  const merged = { ...base };
+  const merged = { ...base2 };
   for (const [key, override] of Object.entries(overrides)) {
     const current = merged[key];
     merged[key] = typeof override === "object" && typeof current === "object" ? { ...current, ...override } : override;
@@ -1487,7 +1893,11 @@ function composeTimelineScore(entryKey, items, policy) {
   return composeAssessmentScore([{ id: entryKey, weight: 1, items: own }], policy);
 }
 export {
+  AI_EXPLANATION_TYPES,
+  AI_HINT_TYPES,
+  AI_TEXT_MAX_LENGTH,
   ActivitySchemaError,
+  AiPermissionsSchema,
   BlankConfigSchema,
   DEFAULT_PASS_THRESHOLD,
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
@@ -1555,11 +1965,19 @@ export {
   WrittenResponseRubricSchema,
   XAPIVerb,
   XAPI_VERB_DISPLAY,
+  aiAllowedByContent,
+  aiExplanationRequest,
+  aiGradeOf,
+  aiHintRequest,
+  aiSupports,
   alignDictation,
   alignReadAloud,
   assertRedacted,
   assertRedactedItemGroup,
+  buildAiFacts,
   canonicalJson,
+  checkAiExplanation,
+  checkAiHint,
   classifyBand,
   composeAssessmentScore,
   composeTimelineScore,
@@ -1589,6 +2007,7 @@ export {
   gte,
   hasGrade,
   hashSeed,
+  hintRevealsAnswer,
   inspectWav,
   isInteractiveVideoItemType,
   isItemGroup,
@@ -1602,6 +2021,7 @@ export {
   outcomeFromUnscorable,
   planAttempt,
   planMediaBudgets,
+  readAiTextResult,
   readAloudJsonSchema,
   readAloudType,
   readMediaProgress,