@intellectif/lk-core 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @intellectif/lk-core
 
+## 0.17.0
+
+### Minor Changes
+
+- 15a3435: The contract for AI help a learner reads — an explanation of a graded answer, and hints before one —
+  between an activity and a model the host runs. The SDK never calls a model and holds no key or prompt;
+  it builds what the model is given and checks what comes back.
+
+  - **Facts:** `buildAiFacts(data, response, details)` describes an item as the learner saw it, their
+    answer, and the SDK's own verdict part by part. It covers multiple choice (every option), fill in the
+    blanks and gap select (each blank or gap in passage order, the passage written with `[1]`, `[2]`…),
+    and dictation (the word-by-word alignment). On a redacted item the key is absent, except where a
+    server's outcome supplies it.
+  - **Requests:**
+    - `aiExplanationRequest({ data, response, outcome?, learnerLocale? })` carries the facts and the
+      `grade`, with its `category` (`correct`, `partly-correct` or `incorrect`). A scored `outcome` wins
+      over grading locally, so an explanation speaks to the grade of record.
+    - `aiHintRequest({ data, response, previousHints, learnerLocale? })` carries the key and the answer
+      so far, marked part by part. It gives none for a dictation, which has hints of its own, or for a
+      redacted item.
+  - **Checks:**
+    - `readAiTextResult` refuses anything but plain text of up to 2,000 characters (`malformed`,
+      `empty`, `too-long`), with control characters removed.
+    - `checkAiExplanation` also refuses an explanation stating a verdict other than the SDK's
+      (`contradicts-grade`).
+    - `checkAiHint` also refuses a hint that contains an answer (`reveals-answer`).
+  - **The guard:** `hintRevealsAnswer(facts, text)` finds an answer written out, ignoring case,
+    accents and punctuation. An answer of one short word counts only where the hint writes it beside a
+    neighbour it has in the passage, so a hint can still say "the verb is…".
+  - **Permissions:** `aiSupports(type, feature)`, `aiAllowedByContent(data, feature)`, `aiGradeOf`, and
+    the types `AiItemFacts`, `AiExplanationRequest`, `AiHintRequest`, `AiTextResult`, `AiProvenance`,
+    `ActivityAiPermissions` and more. Two new interaction kinds: `ai-hint-shown` and
+    `ai-explanation-shown`.
+
+  **The author's switch, and one tightened rule.** Every built-in type now defines an optional
+  `ai: { hints?: boolean, explanations?: boolean }`: `false` switches that help off for the item,
+  wherever it is delivered, and an author can only switch help off. `redact()` keeps both flags, as
+  public, and drops any other key inside `ai`; the strict redacted schemas accept them.
+
+  A field named `ai` was until now an unknown key the loose schemas kept, whatever it held. A sidecar
+  such as `ai: 'generated'`, or a flag that is not a boolean, now fails `validateActivity`: check stored
+  content before upgrading.
+
+  See `docs/ai.md`.
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/{activity-DcxtpX7Z.d.cts → activity-BmjBjXVJ.d.cts}

@@ -63,6 +63,197 @@ declare function levenshteinDistance(a: string, b: string, max: number): number;
  */
 declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
 
+/**
+ * The contract between an activity and a model the HOST runs, for help a
+ * learner reads: an explanation of a graded answer, and hints before one.
+ *
+ * The SDK never calls a model and holds no key, prompt or provider. It builds
+ * the facts a model is given — from the item, the learner's answer and the
+ * SDK's own scorer — and checks what comes back. The model explains a verdict
+ * the SDK reached; it never reaches one.
+ */
+/**
+ * What an author allows AI to do for one item. Absent, or a feature left out,
+ * leaves the choice to the deployment. `false` switches a feature off for this
+ * item wherever it is delivered; an author can only switch a feature off,
+ * never force one on.
+ *
+ * Switch hints off where any hint would give the answer away — a
+ * one-word vocabulary item, say.
+ */
+interface ActivityAiPermissions {
+    /** An explanation of the learner's graded answer. */
+    explanations?: boolean;
+    /** Hints before the learner submits. */
+    hints?: boolean;
+}
+/**
+ * An activity as a renderer holds it: full data or a `redact()` projection.
+ * Structural rather than the data union, so a renderer's own view of an item —
+ * whose answer-key fields may be absent — is accepted as it is. The AI
+ * functions read every field defensively.
+ */
+interface AiActivityInput {
+    readonly type: string;
+    readonly id: string;
+    readonly title: string;
+    readonly locale?: unknown;
+    readonly redacted?: unknown;
+    readonly ai?: unknown;
+}
+/** The two kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint';
+/** The activity types the SDK builds facts for. */
+type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
+/**
+ * A whole answer's grade, from the SDK's scorer. `category` is the verdict an
+ * explanation must agree with: all marks, some, or none.
+ */
+interface AiGrade {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+    category: AiVerdict;
+}
+/** The three verdicts an explanation can speak to. */
+type AiVerdict = 'correct' | 'partly-correct' | 'incorrect';
+interface AiFactsBase {
+    activityId: string;
+    title: string;
+    /** The language the item is written in, when the author gave one. */
+    locale?: string;
+}
+/** One option of a multiple-choice question, and what the learner did with it. */
+interface AiOptionFact {
+    id: string;
+    text: string;
+    chosen: boolean;
+    /** Whether this option is part of the answer; `null` when the key is not available. */
+    correct: boolean | null;
+    /** The author's feedback on this option. */
+    feedback?: string;
+}
+interface AiMultipleChoiceFacts extends AiFactsBase {
+    activityType: 'multiple-choice';
+    question: string;
+    mode: 'single' | 'multi';
+    options: AiOptionFact[];
+}
+/** One blank, in the order it appears in the passage. */
+interface AiBlankFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** What the learner typed, or `''`. */
+    typed: string;
+    /** The answers that count; `null` when the key is not available. */
+    accepted: string[] | null;
+    /** The SDK's verdict on this blank; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's hint for this blank. */
+    hint?: string;
+    /** The author's feedback for this blank. */
+    feedback?: string;
+}
+interface AiFillInTheBlanksFacts extends AiFactsBase {
+    activityType: 'fill-in-the-blanks';
+    /** The passage, each blank written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    blanks: AiBlankFact[];
+}
+/** One gap, in the order it appears in the passage. */
+interface AiGapFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** The words offered at this gap. */
+    choices: string[];
+    /** The word the learner chose, or `null`. */
+    chosen: string | null;
+    /** The right word; `null` when the key is not available. */
+    answer: string | null;
+    /** The SDK's verdict on this gap; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's feedback for this gap. */
+    feedback?: string;
+}
+interface AiGapSelectFacts extends AiFactsBase {
+    activityType: 'gap-select';
+    /** The passage, each gap written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    gaps: AiGapFact[];
+}
+/** One word of a dictation, as the SDK's alignment paired it. */
+interface AiWordFact {
+    /** The word the recording says; `''` for an extra word the learner added. */
+    expected: string;
+    /** The word the learner typed; `''` for a word they left out. */
+    typed: string;
+    status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+interface AiDictationFacts extends AiFactsBase {
+    activityType: 'dictation';
+    /** What the recording says; `null` when the key is not available. */
+    transcript: string | null;
+    /** What the learner typed. */
+    typed: string;
+    /** The alignment word by word; `null` when the key is not available. */
+    words: AiWordFact[] | null;
+}
+/**
+ * What a model is told about one item and one answer: the question as the
+ * learner saw it, what they answered, and — part by part — the SDK's verdict.
+ */
+type AiItemFacts = AiMultipleChoiceFacts | AiFillInTheBlanksFacts | AiGapSelectFacts | AiDictationFacts;
+/**
+ * Asks for an explanation of a graded answer. Sent after the SDK has graded
+ * it, so `grade` is always present, and an explanation that contradicts
+ * `grade.category` is refused.
+ */
+interface AiExplanationRequest {
+    feature: 'explanation';
+    facts: AiItemFacts;
+    grade: AiGrade;
+    /** The language to answer in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/**
+ * Asks for the next hint before the learner submits. `facts` carries the key
+ * so a model can hint toward the answer; the SDK refuses any hint that
+ * contains it.
+ */
+interface AiHintRequest {
+    feature: 'hint';
+    facts: AiItemFacts;
+    /** 1-based: the hint being asked for. */
+    hintNumber: number;
+    /** The hints already shown for this item, oldest first. */
+    previousHints: string[];
+    learnerLocale?: string;
+}
+/** What produced an AI text, for the record a host keeps. */
+interface AiProvenance {
+    /** The model's identifier, e.g. a name and version. */
+    model?: string;
+    /** A hash or id of the prompt revision. */
+    promptHash?: string;
+    /** ISO 8601. */
+    generatedAt?: string;
+}
+/**
+ * What a host's port returns. Plain text: the SDK renders it as text, never
+ * as HTML. An explanation may state the verdict it assumed; one that
+ * disagrees with the SDK's is refused.
+ */
+interface AiTextResult {
+    text: string;
+    /** For an explanation: the verdict the model explained. */
+    verdict?: AiVerdict;
+    provenance?: AiProvenance;
+}
+/** Why a result was not shown. */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
+
 /**
  * The return trip for deferred grading.
  *
@@ -590,6 +781,8 @@ interface MultipleChoiceData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** Configuration for a single fill-in-the-blank slot. */
 interface BlankConfig {
@@ -724,6 +917,8 @@ interface GapSelectData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 interface FillInTheBlanksData {
     schemaVersion: '1.0';
@@ -756,6 +951,8 @@ interface FillInTheBlanksData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A single criterion within a written-response grading rubric. */
 interface WrittenResponseRubricCriterion {
@@ -818,6 +1015,8 @@ interface WrittenResponseData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * A second, slower recording of a dictation — a separate file (a text-to-speech
@@ -920,6 +1119,8 @@ interface DictationData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A dimension of speech a pronunciation assessor scores, on a 0–100 scale. */
 type ReadAloudDimension = 'accuracy' | 'fluency' | 'completeness' | 'prosody';
@@ -1010,6 +1211,8 @@ interface ReadAloudData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
@@ -1320,7 +1523,15 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * primary line's language, or `null` with captions off; `payload.secondary` is
  * the second line's, or `null` with none showing. Fires when either changes.
  */
- | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed' | (string & {});
+ | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed'
+/**
+ * An AI hint was shown to the learner (`hintNumber`, and the port's
+ * `provenance` when it sent one). Only a hint the SDK accepted: a refused one
+ * is never shown and never reported here.
+ */
+ | 'ai-hint-shown'
+/** An AI explanation of the graded answer was shown (`provenance` when sent). */
+ | 'ai-explanation-shown' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1333,4 +1544,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type ValidationResult as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type MultipleChoiceData as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceLearnerResponse as H, type InlineCorrection as I, type MultipleChoiceOption as J, type MultipleChoiceOptionMedia as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type ReadAloudDimension as O, type ReadAloudDimensionWeight as P, type ReadAloudLearnerResponse as Q, type ReadAloudData as R, type ReadAloudSlowMedia as S, type RecordingBounds as T, type RecordingRef as U, type ScoringDetail as V, type ScoringOutcome as W, type ScoringResult as X, type TextMatchPolicy as Y, type TextMatchResult as Z, type ValidationError as _, type ActivityDataMap as a, type WrittenResponseData as a0, type WrittenResponseLearnerResponse as a1, type WrittenResponseRubric as a2, type WrittenResponseRubricCriterion as a3, type XAPIActor as a4, type XAPIConfig as a5, type XAPIContext as a6, type XAPIContextActivities as a7, type XAPIError as a8, type XAPIObject as a9, type XAPIResult as aa, type XAPIScore as ab, type XAPIStatement as ac, type XAPIVerbObject as ad, levenshteinDistance as ae, matchText as af, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DeferredScoringPartial as f, type DictationData as g, type DictationEquivalence as h, type DictationLearnerResponse as i, type DictationSlowMedia as j, type DictationTolerance as k, type FillInTheBlanksLearnerResponse as l, type GapSelectChoice as m, type GapSelectData as n, type GapSelectGap as o, type GapSelectLearnerResponse as p, type GradeRecord as q, type Grader as r, type GraderKind as s, type GraderUsage as t, type GradingState as u, type InteractionEvent as v, type InteractionKind as w, type ItemOutcome as x, type LearnerResponseMap as y, type MediaTrack as z };
+export { type MediaPlaybackPolicy as $, type ActivityAiPermissions as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type DictationData as E, type DictationEquivalence as F, type DictationLearnerResponse as G, type DictationSlowMedia as H, type DictationTolerance as I, type FillInTheBlanksData as J, type FillInTheBlanksLearnerResponse as K, type GapSelectBank as L, type GapSelectChoice as M, type GapSelectData as N, type GapSelectGap as O, type GapSelectLearnerResponse as P, type GradeRecord as Q, type Grader as R, type GraderKind as S, type GraderUsage as T, type GradingState as U, type InlineCorrection as V, type InteractionEvent as W, type InteractionKind as X, type ItemOutcome as Y, type LearnerResponse as Z, type LearnerResponseMap as _, type ActivityData as a, type MediaTrack as a0, type MultipleChoiceData as a1, type MultipleChoiceLearnerResponse as a2, type MultipleChoiceOption as a3, type MultipleChoiceOptionMedia as a4, type NativeControlHint as a5, type ReadAloudData as a6, type ReadAloudDimension as a7, type ReadAloudDimensionWeight as a8, type ReadAloudLearnerResponse as a9, type ReadAloudSlowMedia as aa, type RecordingBounds as ab, type RecordingRef as ac, type ScoringDetail as ad, type ScoringOutcome as ae, type ScoringResult as af, type TextMatchPolicy as ag, type TextMatchResult as ah, type ValidationError as ai, type ValidationResult as aj, type WrittenResponseData as ak, type WrittenResponseLearnerResponse as al, type WrittenResponseRubric as am, type WrittenResponseRubricCriterion as an, type XAPIActor as ao, type XAPIConfig as ap, type XAPIContext as aq, type XAPIContextActivities as ar, type XAPIError as as, type XAPIObject as at, type XAPIResult as au, type XAPIScore as av, type XAPIStatement as aw, type XAPIVerbObject as ax, levenshteinDistance as ay, matchText as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiDictationFacts as i, type AiExplanationRequest as j, type AiFeature as k, type AiFillInTheBlanksFacts as l, type AiGapFact as m, type AiGapSelectFacts as n, type AiGrade as o, type AiHintRequest as p, type AiItemFacts as q, type AiMultipleChoiceFacts as r, type AiOptionFact as s, type AiProvenance as t, type AiRefusal as u, type AiSupportedActivityType as v, type AiTextResult as w, type AiVerdict as x, type AiWordFact as y, type DeferredScoringPartial as z };

package/dist/{activity-DcxtpX7Z.d.ts → activity-BmjBjXVJ.d.ts}

@@ -63,6 +63,197 @@ declare function levenshteinDistance(a: string, b: string, max: number): number;
  */
 declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
 
+/**
+ * The contract between an activity and a model the HOST runs, for help a
+ * learner reads: an explanation of a graded answer, and hints before one.
+ *
+ * The SDK never calls a model and holds no key, prompt or provider. It builds
+ * the facts a model is given — from the item, the learner's answer and the
+ * SDK's own scorer — and checks what comes back. The model explains a verdict
+ * the SDK reached; it never reaches one.
+ */
+/**
+ * What an author allows AI to do for one item. Absent, or a feature left out,
+ * leaves the choice to the deployment. `false` switches a feature off for this
+ * item wherever it is delivered; an author can only switch a feature off,
+ * never force one on.
+ *
+ * Switch hints off where any hint would give the answer away — a
+ * one-word vocabulary item, say.
+ */
+interface ActivityAiPermissions {
+    /** An explanation of the learner's graded answer. */
+    explanations?: boolean;
+    /** Hints before the learner submits. */
+    hints?: boolean;
+}
+/**
+ * An activity as a renderer holds it: full data or a `redact()` projection.
+ * Structural rather than the data union, so a renderer's own view of an item —
+ * whose answer-key fields may be absent — is accepted as it is. The AI
+ * functions read every field defensively.
+ */
+interface AiActivityInput {
+    readonly type: string;
+    readonly id: string;
+    readonly title: string;
+    readonly locale?: unknown;
+    readonly redacted?: unknown;
+    readonly ai?: unknown;
+}
+/** The two kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint';
+/** The activity types the SDK builds facts for. */
+type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
+/**
+ * A whole answer's grade, from the SDK's scorer. `category` is the verdict an
+ * explanation must agree with: all marks, some, or none.
+ */
+interface AiGrade {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+    category: AiVerdict;
+}
+/** The three verdicts an explanation can speak to. */
+type AiVerdict = 'correct' | 'partly-correct' | 'incorrect';
+interface AiFactsBase {
+    activityId: string;
+    title: string;
+    /** The language the item is written in, when the author gave one. */
+    locale?: string;
+}
+/** One option of a multiple-choice question, and what the learner did with it. */
+interface AiOptionFact {
+    id: string;
+    text: string;
+    chosen: boolean;
+    /** Whether this option is part of the answer; `null` when the key is not available. */
+    correct: boolean | null;
+    /** The author's feedback on this option. */
+    feedback?: string;
+}
+interface AiMultipleChoiceFacts extends AiFactsBase {
+    activityType: 'multiple-choice';
+    question: string;
+    mode: 'single' | 'multi';
+    options: AiOptionFact[];
+}
+/** One blank, in the order it appears in the passage. */
+interface AiBlankFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** What the learner typed, or `''`. */
+    typed: string;
+    /** The answers that count; `null` when the key is not available. */
+    accepted: string[] | null;
+    /** The SDK's verdict on this blank; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's hint for this blank. */
+    hint?: string;
+    /** The author's feedback for this blank. */
+    feedback?: string;
+}
+interface AiFillInTheBlanksFacts extends AiFactsBase {
+    activityType: 'fill-in-the-blanks';
+    /** The passage, each blank written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    blanks: AiBlankFact[];
+}
+/** One gap, in the order it appears in the passage. */
+interface AiGapFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** The words offered at this gap. */
+    choices: string[];
+    /** The word the learner chose, or `null`. */
+    chosen: string | null;
+    /** The right word; `null` when the key is not available. */
+    answer: string | null;
+    /** The SDK's verdict on this gap; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's feedback for this gap. */
+    feedback?: string;
+}
+interface AiGapSelectFacts extends AiFactsBase {
+    activityType: 'gap-select';
+    /** The passage, each gap written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    gaps: AiGapFact[];
+}
+/** One word of a dictation, as the SDK's alignment paired it. */
+interface AiWordFact {
+    /** The word the recording says; `''` for an extra word the learner added. */
+    expected: string;
+    /** The word the learner typed; `''` for a word they left out. */
+    typed: string;
+    status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+interface AiDictationFacts extends AiFactsBase {
+    activityType: 'dictation';
+    /** What the recording says; `null` when the key is not available. */
+    transcript: string | null;
+    /** What the learner typed. */
+    typed: string;
+    /** The alignment word by word; `null` when the key is not available. */
+    words: AiWordFact[] | null;
+}
+/**
+ * What a model is told about one item and one answer: the question as the
+ * learner saw it, what they answered, and — part by part — the SDK's verdict.
+ */
+type AiItemFacts = AiMultipleChoiceFacts | AiFillInTheBlanksFacts | AiGapSelectFacts | AiDictationFacts;
+/**
+ * Asks for an explanation of a graded answer. Sent after the SDK has graded
+ * it, so `grade` is always present, and an explanation that contradicts
+ * `grade.category` is refused.
+ */
+interface AiExplanationRequest {
+    feature: 'explanation';
+    facts: AiItemFacts;
+    grade: AiGrade;
+    /** The language to answer in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/**
+ * Asks for the next hint before the learner submits. `facts` carries the key
+ * so a model can hint toward the answer; the SDK refuses any hint that
+ * contains it.
+ */
+interface AiHintRequest {
+    feature: 'hint';
+    facts: AiItemFacts;
+    /** 1-based: the hint being asked for. */
+    hintNumber: number;
+    /** The hints already shown for this item, oldest first. */
+    previousHints: string[];
+    learnerLocale?: string;
+}
+/** What produced an AI text, for the record a host keeps. */
+interface AiProvenance {
+    /** The model's identifier, e.g. a name and version. */
+    model?: string;
+    /** A hash or id of the prompt revision. */
+    promptHash?: string;
+    /** ISO 8601. */
+    generatedAt?: string;
+}
+/**
+ * What a host's port returns. Plain text: the SDK renders it as text, never
+ * as HTML. An explanation may state the verdict it assumed; one that
+ * disagrees with the SDK's is refused.
+ */
+interface AiTextResult {
+    text: string;
+    /** For an explanation: the verdict the model explained. */
+    verdict?: AiVerdict;
+    provenance?: AiProvenance;
+}
+/** Why a result was not shown. */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
+
 /**
  * The return trip for deferred grading.
  *
@@ -590,6 +781,8 @@ interface MultipleChoiceData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** Configuration for a single fill-in-the-blank slot. */
 interface BlankConfig {
@@ -724,6 +917,8 @@ interface GapSelectData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 interface FillInTheBlanksData {
     schemaVersion: '1.0';
@@ -756,6 +951,8 @@ interface FillInTheBlanksData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A single criterion within a written-response grading rubric. */
 interface WrittenResponseRubricCriterion {
@@ -818,6 +1015,8 @@ interface WrittenResponseData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * A second, slower recording of a dictation — a separate file (a text-to-speech
@@ -920,6 +1119,8 @@ interface DictationData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A dimension of speech a pronunciation assessor scores, on a 0–100 scale. */
 type ReadAloudDimension = 'accuracy' | 'fluency' | 'completeness' | 'prosody';
@@ -1010,6 +1211,8 @@ interface ReadAloudData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
@@ -1320,7 +1523,15 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * primary line's language, or `null` with captions off; `payload.secondary` is
  * the second line's, or `null` with none showing. Fires when either changes.
  */
- | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed' | (string & {});
+ | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed'
+/**
+ * An AI hint was shown to the learner (`hintNumber`, and the port's
+ * `provenance` when it sent one). Only a hint the SDK accepted: a refused one
+ * is never shown and never reported here.
+ */
+ | 'ai-hint-shown'
+/** An AI explanation of the graded answer was shown (`provenance` when sent). */
+ | 'ai-explanation-shown' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1333,4 +1544,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type ValidationResult as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type MultipleChoiceData as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceLearnerResponse as H, type InlineCorrection as I, type MultipleChoiceOption as J, type MultipleChoiceOptionMedia as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type ReadAloudDimension as O, type ReadAloudDimensionWeight as P, type ReadAloudLearnerResponse as Q, type ReadAloudData as R, type ReadAloudSlowMedia as S, type RecordingBounds as T, type RecordingRef as U, type ScoringDetail as V, type ScoringOutcome as W, type ScoringResult as X, type TextMatchPolicy as Y, type TextMatchResult as Z, type ValidationError as _, type ActivityDataMap as a, type WrittenResponseData as a0, type WrittenResponseLearnerResponse as a1, type WrittenResponseRubric as a2, type WrittenResponseRubricCriterion as a3, type XAPIActor as a4, type XAPIConfig as a5, type XAPIContext as a6, type XAPIContextActivities as a7, type XAPIError as a8, type XAPIObject as a9, type XAPIResult as aa, type XAPIScore as ab, type XAPIStatement as ac, type XAPIVerbObject as ad, levenshteinDistance as ae, matchText as af, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DeferredScoringPartial as f, type DictationData as g, type DictationEquivalence as h, type DictationLearnerResponse as i, type DictationSlowMedia as j, type DictationTolerance as k, type FillInTheBlanksLearnerResponse as l, type GapSelectChoice as m, type GapSelectData as n, type GapSelectGap as o, type GapSelectLearnerResponse as p, type GradeRecord as q, type Grader as r, type GraderKind as s, type GraderUsage as t, type GradingState as u, type InteractionEvent as v, type InteractionKind as w, type ItemOutcome as x, type LearnerResponseMap as y, type MediaTrack as z };
+export { type MediaPlaybackPolicy as $, type ActivityAiPermissions as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type DictationData as E, type DictationEquivalence as F, type DictationLearnerResponse as G, type DictationSlowMedia as H, type DictationTolerance as I, type FillInTheBlanksData as J, type FillInTheBlanksLearnerResponse as K, type GapSelectBank as L, type GapSelectChoice as M, type GapSelectData as N, type GapSelectGap as O, type GapSelectLearnerResponse as P, type GradeRecord as Q, type Grader as R, type GraderKind as S, type GraderUsage as T, type GradingState as U, type InlineCorrection as V, type InteractionEvent as W, type InteractionKind as X, type ItemOutcome as Y, type LearnerResponse as Z, type LearnerResponseMap as _, type ActivityData as a, type MediaTrack as a0, type MultipleChoiceData as a1, type MultipleChoiceLearnerResponse as a2, type MultipleChoiceOption as a3, type MultipleChoiceOptionMedia as a4, type NativeControlHint as a5, type ReadAloudData as a6, type ReadAloudDimension as a7, type ReadAloudDimensionWeight as a8, type ReadAloudLearnerResponse as a9, type ReadAloudSlowMedia as aa, type RecordingBounds as ab, type RecordingRef as ac, type ScoringDetail as ad, type ScoringOutcome as ae, type ScoringResult as af, type TextMatchPolicy as ag, type TextMatchResult as ah, type ValidationError as ai, type ValidationResult as aj, type WrittenResponseData as ak, type WrittenResponseLearnerResponse as al, type WrittenResponseRubric as am, type WrittenResponseRubricCriterion as an, type XAPIActor as ao, type XAPIConfig as ap, type XAPIContext as aq, type XAPIContextActivities as ar, type XAPIError as as, type XAPIObject as at, type XAPIResult as au, type XAPIScore as av, type XAPIStatement as aw, type XAPIVerbObject as ax, levenshteinDistance as ay, matchText as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiDictationFacts as i, type AiExplanationRequest as j, type AiFeature as k, type AiFillInTheBlanksFacts as l, type AiGapFact as m, type AiGapSelectFacts as n, type AiGrade as o, type AiHintRequest as p, type AiItemFacts as q, type AiMultipleChoiceFacts as r, type AiOptionFact as s, type AiProvenance as t, type AiRefusal as u, type AiSupportedActivityType as v, type AiTextResult as w, type AiVerdict as x, type AiWordFact as y, type DeferredScoringPartial as z };