@intellectif/lk-core 0.16.0 → 0.17.0

package/dist/index.d.cts

@@ -1,12 +1,129 @@
+import { v as AiSupportedActivityType, g as AiActivityInput, k as AiFeature, Z as LearnerResponse, Y as ItemOutcome, j as AiExplanationRequest, o as AiGrade, p as AiHintRequest, ad as ScoringDetail, q as AiItemFacts, w as AiTextResult, u as AiRefusal, a as ActivityData, ai as ValidationError, f as ActivityType, b as ActivityDataMap, C as CriterionScore, Q as GradeRecord, a5 as NativeControlHint, d as ActivityMedia, af as ScoringResult, z as DeferredScoringPartial, E as DictationData, G as DictationLearnerResponse, J as FillInTheBlanksData, K as FillInTheBlanksLearnerResponse, N as GapSelectData, P as GapSelectLearnerResponse, a1 as MultipleChoiceData, a2 as MultipleChoiceLearnerResponse, a6 as ReadAloudData, a9 as ReadAloudLearnerResponse, ak as WrittenResponseData, al as WrittenResponseLearnerResponse } from './activity-BmjBjXVJ.cjs';
+export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiDictationFacts, l as AiFillInTheBlanksFacts, m as AiGapFact, n as AiGapSelectFacts, r as AiMultipleChoiceFacts, s as AiOptionFact, t as AiProvenance, x as AiVerdict, y as AiWordFact, B as BlankConfig, D as DeferredReason, F as DictationEquivalence, H as DictationSlowMedia, I as DictationTolerance, L as GapSelectBank, M as GapSelectChoice, O as GapSelectGap, R as Grader, S as GraderKind, T as GraderUsage, U as GradingState, V as InlineCorrection, W as InteractionEvent, X as InteractionKind, _ as LearnerResponseMap, $ as MediaPlaybackPolicy, a0 as MediaTrack, a3 as MultipleChoiceOption, a4 as MultipleChoiceOptionMedia, a7 as ReadAloudDimension, a8 as ReadAloudDimensionWeight, aa as ReadAloudSlowMedia, ab as RecordingBounds, ac as RecordingRef, ae as ScoringOutcome, ag as TextMatchPolicy, ah as TextMatchResult, aj as ValidationResult, am as WrittenResponseRubric, an as WrittenResponseRubricCriterion, ao as XAPIActor, ap as XAPIConfig, aq as XAPIContext, ar as XAPIContextActivities, as as XAPIError, at as XAPIObject, au as XAPIResult, av as XAPIScore, aw as XAPIStatement, ax as XAPIVerbObject, ay as levenshteinDistance, az as matchText } from './activity-BmjBjXVJ.cjs';
 import { ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.cjs';
 export { AssessmentSectionInput, Band, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, GradeReadAloudOptions, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, roundGrade, score, validateSpeechAssessment } from './scoring.cjs';
-import { x as ItemOutcome, A as ActivityData, L as LearnerResponse, _ as ValidationError, e as ActivityType, a as ActivityDataMap, C as CriterionScore, q as GradeRecord, N as NativeControlHint, c as ActivityMedia, X as ScoringResult, f as DeferredScoringPartial, g as DictationData, i as DictationLearnerResponse, F as FillInTheBlanksData, l as FillInTheBlanksLearnerResponse, n as GapSelectData, p as GapSelectLearnerResponse, E as MultipleChoiceData, H as MultipleChoiceLearnerResponse, R as ReadAloudData, Q as ReadAloudLearnerResponse, a0 as WrittenResponseData, a1 as WrittenResponseLearnerResponse } from './activity-DcxtpX7Z.cjs';
-export { b as ActivityFeedback, d as ActivityResult, B as BlankConfig, D as DeferredReason, h as DictationEquivalence, j as DictationSlowMedia, k as DictationTolerance, G as GapSelectBank, m as GapSelectChoice, o as GapSelectGap, r as Grader, s as GraderKind, t as GraderUsage, u as GradingState, I as InlineCorrection, v as InteractionEvent, w as InteractionKind, y as LearnerResponseMap, M as MediaPlaybackPolicy, z as MediaTrack, J as MultipleChoiceOption, K as MultipleChoiceOptionMedia, O as ReadAloudDimension, P as ReadAloudDimensionWeight, S as ReadAloudSlowMedia, T as RecordingBounds, U as RecordingRef, V as ScoringDetail, W as ScoringOutcome, Y as TextMatchPolicy, Z as TextMatchResult, $ as ValidationResult, a2 as WrittenResponseRubric, a3 as WrittenResponseRubricCriterion, a4 as XAPIActor, a5 as XAPIConfig, a6 as XAPIContext, a7 as XAPIContextActivities, a8 as XAPIError, a9 as XAPIObject, aa as XAPIResult, ab as XAPIScore, ac as XAPIStatement, ad as XAPIVerbObject, ae as levenshteinDistance, af as matchText } from './activity-DcxtpX7Z.cjs';
-import { a4 as SequenceSlot, a3 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-BWpwZRQw.cjs';
-export { B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, A as RedactedFillInTheBlanksDataSchema, C as RedactedGapSelectBank, E as RedactedGapSelectBankSchema, H as RedactedGapSelectChoice, J as RedactedGapSelectChoiceSchema, K as RedactedGapSelectData, L as RedactedGapSelectDataSchema, O as RedactedGapSelectGap, P as RedactedGapSelectGapSchema, Q as RedactedItemGroupSchema, S as RedactedMediaSchema, T as RedactedMultipleChoiceData, U as RedactedMultipleChoiceDataSchema, V as RedactedMultipleChoiceOption, W as RedactedMultipleChoiceOptionMedia, X as RedactedMultipleChoiceOptionMediaSchema, Y as RedactedMultipleChoiceOptionSchema, Z as RedactedReadAloudData, _ as RedactedReadAloudDataSchema, $ as RedactedStimulus, a0 as RedactedStimulusSchema, a1 as RedactedWrittenResponseData, a2 as RedactedWrittenResponseDataSchema, a5 as SequenceSlotGroup, a6 as Stimulus, a7 as StimulusKind, a8 as StimulusSchema, a9 as TextMatchPolicySchema, aa as TimelineChapter, ab as TimelineChapterSchema, ac as TimelineCue, ad as TimelineCueSchema, ae as WrittenResponseDataSchema, af as WrittenResponseRubricCriterionSchema, ag as WrittenResponseRubricSchema, ah as dictationJsonSchema, ai as fillInTheBlanksJsonSchema, aj as gapSelectJsonSchema, ak as itemGroupJsonSchema, al as jsonSchemaFor, am as multipleChoiceJsonSchema, an as readAloudJsonSchema, ao as stimulusJsonSchema, ap as validateActivity, aq as validateItemGroup, ar as writtenResponseJsonSchema } from './index-BWpwZRQw.cjs';
+import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-CvfeD_cU.cjs';
+export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-CvfeD_cU.cjs';
 import { z } from 'zod/v4';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.cjs';
 
+/**
+ * The activity types the SDK builds facts for, and which of them take hints.
+ * A dictation takes none: its answer is the whole sentence, and it has
+ * word-by-word hints of its own.
+ */
+declare const AI_EXPLANATION_TYPES: readonly AiSupportedActivityType[];
+declare const AI_HINT_TYPES: readonly AiSupportedActivityType[];
+/** The longest AI text shown, in code points. Longer is refused, not cut. */
+declare const AI_TEXT_MAX_LENGTH = 2000;
+/**
+ * Whether the SDK supports `feature` for this activity type. A type it builds
+ * no facts for — a written response, a read-aloud, a consumer's own — has
+ * neither.
+ */
+declare function aiSupports(activityType: string, feature: AiFeature): boolean;
+/**
+ * Whether the item's author allows `feature`. Only an explicit `false`
+ * switches it off: an author can refuse a feature, never force one on.
+ */
+declare function aiAllowedByContent(data: AiActivityInput, feature: AiFeature): boolean;
+/** A grade as an explanation must speak to it: all marks, some, or none. */
+declare function aiGradeOf(result: {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+}): AiGrade;
+/**
+ * The facts a model is given about one item and one answer. `details` are the
+ * SDK's per-part verdicts — from its own scorer, or from a server's outcome in
+ * review — and every `correct` is `null` without them. A redacted item yields
+ * facts without a key, which is what the learner's side holds; a port that
+ * needs the key loads the item on its server.
+ *
+ * `null` for a type the SDK builds no facts for.
+ */
+declare function buildAiFacts(data: AiActivityInput, response: LearnerResponse | null, details: readonly ScoringDetail[] | null): AiItemFacts | null;
+/**
+ * The request for an explanation of `response`, or `null` when there is none
+ * to give: an unsupported type, an author who switched explanations off, or
+ * nothing graded to explain.
+ *
+ * A scored `outcome` — the grade of record a review shows — wins over grading
+ * locally, so the explanation speaks to the grade on the screen.
+ */
+declare function aiExplanationRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    outcome?: ItemOutcome;
+    learnerLocale?: string;
+}): AiExplanationRequest | null;
+/**
+ * The request for the next hint on an unsubmitted answer, or `null` when
+ * there is none to give: an unsupported type, an author who switched hints
+ * off, or a redacted item — hints are for practice, where the item is whole.
+ *
+ * The facts carry the key, and which parts the learner has right so far, so a
+ * model can hint where it helps. The learner never sees them; a hint that
+ * contains an answer is refused by {@link checkAiHint}.
+ */
+declare function aiHintRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    previousHints: readonly string[];
+    learnerLocale?: string;
+}): AiHintRequest | null;
+/**
+ * Reads what a port returned. Anything but an object with a string `text` is
+ * `malformed`; text that is empty once cleaned, or longer than
+ * {@link AI_TEXT_MAX_LENGTH}, is refused rather than shown or cut.
+ */
+declare function readAiTextResult(raw: unknown): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Checks an explanation a port returned for `request`. On top of
+ * {@link readAiTextResult}: an explanation that states a verdict other than
+ * the SDK's grade is refused (`contradicts-grade`) — it explains an answer
+ * the learner did not get.
+ */
+declare function checkAiExplanation(raw: unknown, request: AiExplanationRequest): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Checks a hint a port returned for `request`. On top of
+ * {@link readAiTextResult}: a hint that contains an answer is refused
+ * (`reveals-answer`) — see {@link hintRevealsAnswer}.
+ */
+declare function checkAiHint(raw: unknown, request: AiHintRequest): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Whether a hint gives away an answer, judged against the facts it was asked
+ * for. It is a floor, not a proof: it finds an answer written out, not one
+ * spelled letter by letter or described.
+ *
+ * - **Multiple choice:** the text of any correct option, as whole words.
+ * - **Fill-in-the-blanks and gap select:** any accepted answer, as whole words.
+ *   An answer of one short word ("is", "the") counts only where the hint
+ *   writes it beside a neighbour it has in the passage — "name is", "is
+ *   Rossi" — so a hint may still use the word on its own.
+ *
+ * Case, accents and punctuation are ignored on both sides.
+ */
+declare function hintRevealsAnswer(facts: AiItemFacts, hint: string): boolean;
+
 /**
  * The frozen record of what one attempt was served.
  *
@@ -1332,4 +1449,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, assertRedacted, assertRedactedItemGroup, canonicalJson, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };
+export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };

package/dist/index.d.ts

@@ -1,12 +1,129 @@
+import { v as AiSupportedActivityType, g as AiActivityInput, k as AiFeature, Z as LearnerResponse, Y as ItemOutcome, j as AiExplanationRequest, o as AiGrade, p as AiHintRequest, ad as ScoringDetail, q as AiItemFacts, w as AiTextResult, u as AiRefusal, a as ActivityData, ai as ValidationError, f as ActivityType, b as ActivityDataMap, C as CriterionScore, Q as GradeRecord, a5 as NativeControlHint, d as ActivityMedia, af as ScoringResult, z as DeferredScoringPartial, E as DictationData, G as DictationLearnerResponse, J as FillInTheBlanksData, K as FillInTheBlanksLearnerResponse, N as GapSelectData, P as GapSelectLearnerResponse, a1 as MultipleChoiceData, a2 as MultipleChoiceLearnerResponse, a6 as ReadAloudData, a9 as ReadAloudLearnerResponse, ak as WrittenResponseData, al as WrittenResponseLearnerResponse } from './activity-BmjBjXVJ.js';
+export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiDictationFacts, l as AiFillInTheBlanksFacts, m as AiGapFact, n as AiGapSelectFacts, r as AiMultipleChoiceFacts, s as AiOptionFact, t as AiProvenance, x as AiVerdict, y as AiWordFact, B as BlankConfig, D as DeferredReason, F as DictationEquivalence, H as DictationSlowMedia, I as DictationTolerance, L as GapSelectBank, M as GapSelectChoice, O as GapSelectGap, R as Grader, S as GraderKind, T as GraderUsage, U as GradingState, V as InlineCorrection, W as InteractionEvent, X as InteractionKind, _ as LearnerResponseMap, $ as MediaPlaybackPolicy, a0 as MediaTrack, a3 as MultipleChoiceOption, a4 as MultipleChoiceOptionMedia, a7 as ReadAloudDimension, a8 as ReadAloudDimensionWeight, aa as ReadAloudSlowMedia, ab as RecordingBounds, ac as RecordingRef, ae as ScoringOutcome, ag as TextMatchPolicy, ah as TextMatchResult, aj as ValidationResult, am as WrittenResponseRubric, an as WrittenResponseRubricCriterion, ao as XAPIActor, ap as XAPIConfig, aq as XAPIContext, ar as XAPIContextActivities, as as XAPIError, at as XAPIObject, au as XAPIResult, av as XAPIScore, aw as XAPIStatement, ax as XAPIVerbObject, ay as levenshteinDistance, az as matchText } from './activity-BmjBjXVJ.js';
 import { ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.js';
 export { AssessmentSectionInput, Band, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, GradeReadAloudOptions, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, roundGrade, score, validateSpeechAssessment } from './scoring.js';
-import { x as ItemOutcome, A as ActivityData, L as LearnerResponse, _ as ValidationError, e as ActivityType, a as ActivityDataMap, C as CriterionScore, q as GradeRecord, N as NativeControlHint, c as ActivityMedia, X as ScoringResult, f as DeferredScoringPartial, g as DictationData, i as DictationLearnerResponse, F as FillInTheBlanksData, l as FillInTheBlanksLearnerResponse, n as GapSelectData, p as GapSelectLearnerResponse, E as MultipleChoiceData, H as MultipleChoiceLearnerResponse, R as ReadAloudData, Q as ReadAloudLearnerResponse, a0 as WrittenResponseData, a1 as WrittenResponseLearnerResponse } from './activity-DcxtpX7Z.js';
-export { b as ActivityFeedback, d as ActivityResult, B as BlankConfig, D as DeferredReason, h as DictationEquivalence, j as DictationSlowMedia, k as DictationTolerance, G as GapSelectBank, m as GapSelectChoice, o as GapSelectGap, r as Grader, s as GraderKind, t as GraderUsage, u as GradingState, I as InlineCorrection, v as InteractionEvent, w as InteractionKind, y as LearnerResponseMap, M as MediaPlaybackPolicy, z as MediaTrack, J as MultipleChoiceOption, K as MultipleChoiceOptionMedia, O as ReadAloudDimension, P as ReadAloudDimensionWeight, S as ReadAloudSlowMedia, T as RecordingBounds, U as RecordingRef, V as ScoringDetail, W as ScoringOutcome, Y as TextMatchPolicy, Z as TextMatchResult, $ as ValidationResult, a2 as WrittenResponseRubric, a3 as WrittenResponseRubricCriterion, a4 as XAPIActor, a5 as XAPIConfig, a6 as XAPIContext, a7 as XAPIContextActivities, a8 as XAPIError, a9 as XAPIObject, aa as XAPIResult, ab as XAPIScore, ac as XAPIStatement, ad as XAPIVerbObject, ae as levenshteinDistance, af as matchText } from './activity-DcxtpX7Z.js';
-import { a4 as SequenceSlot, a3 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-DRJqwO2y.js';
-export { B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, A as RedactedFillInTheBlanksDataSchema, C as RedactedGapSelectBank, E as RedactedGapSelectBankSchema, H as RedactedGapSelectChoice, J as RedactedGapSelectChoiceSchema, K as RedactedGapSelectData, L as RedactedGapSelectDataSchema, O as RedactedGapSelectGap, P as RedactedGapSelectGapSchema, Q as RedactedItemGroupSchema, S as RedactedMediaSchema, T as RedactedMultipleChoiceData, U as RedactedMultipleChoiceDataSchema, V as RedactedMultipleChoiceOption, W as RedactedMultipleChoiceOptionMedia, X as RedactedMultipleChoiceOptionMediaSchema, Y as RedactedMultipleChoiceOptionSchema, Z as RedactedReadAloudData, _ as RedactedReadAloudDataSchema, $ as RedactedStimulus, a0 as RedactedStimulusSchema, a1 as RedactedWrittenResponseData, a2 as RedactedWrittenResponseDataSchema, a5 as SequenceSlotGroup, a6 as Stimulus, a7 as StimulusKind, a8 as StimulusSchema, a9 as TextMatchPolicySchema, aa as TimelineChapter, ab as TimelineChapterSchema, ac as TimelineCue, ad as TimelineCueSchema, ae as WrittenResponseDataSchema, af as WrittenResponseRubricCriterionSchema, ag as WrittenResponseRubricSchema, ah as dictationJsonSchema, ai as fillInTheBlanksJsonSchema, aj as gapSelectJsonSchema, ak as itemGroupJsonSchema, al as jsonSchemaFor, am as multipleChoiceJsonSchema, an as readAloudJsonSchema, ao as stimulusJsonSchema, ap as validateActivity, aq as validateItemGroup, ar as writtenResponseJsonSchema } from './index-DRJqwO2y.js';
+import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-G_KusUcK.js';
+export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-G_KusUcK.js';
 import { z } from 'zod/v4';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.js';
 
+/**
+ * The activity types the SDK builds facts for, and which of them take hints.
+ * A dictation takes none: its answer is the whole sentence, and it has
+ * word-by-word hints of its own.
+ */
+declare const AI_EXPLANATION_TYPES: readonly AiSupportedActivityType[];
+declare const AI_HINT_TYPES: readonly AiSupportedActivityType[];
+/** The longest AI text shown, in code points. Longer is refused, not cut. */
+declare const AI_TEXT_MAX_LENGTH = 2000;
+/**
+ * Whether the SDK supports `feature` for this activity type. A type it builds
+ * no facts for — a written response, a read-aloud, a consumer's own — has
+ * neither.
+ */
+declare function aiSupports(activityType: string, feature: AiFeature): boolean;
+/**
+ * Whether the item's author allows `feature`. Only an explicit `false`
+ * switches it off: an author can refuse a feature, never force one on.
+ */
+declare function aiAllowedByContent(data: AiActivityInput, feature: AiFeature): boolean;
+/** A grade as an explanation must speak to it: all marks, some, or none. */
+declare function aiGradeOf(result: {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+}): AiGrade;
+/**
+ * The facts a model is given about one item and one answer. `details` are the
+ * SDK's per-part verdicts — from its own scorer, or from a server's outcome in
+ * review — and every `correct` is `null` without them. A redacted item yields
+ * facts without a key, which is what the learner's side holds; a port that
+ * needs the key loads the item on its server.
+ *
+ * `null` for a type the SDK builds no facts for.
+ */
+declare function buildAiFacts(data: AiActivityInput, response: LearnerResponse | null, details: readonly ScoringDetail[] | null): AiItemFacts | null;
+/**
+ * The request for an explanation of `response`, or `null` when there is none
+ * to give: an unsupported type, an author who switched explanations off, or
+ * nothing graded to explain.
+ *
+ * A scored `outcome` — the grade of record a review shows — wins over grading
+ * locally, so the explanation speaks to the grade on the screen.
+ */
+declare function aiExplanationRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    outcome?: ItemOutcome;
+    learnerLocale?: string;
+}): AiExplanationRequest | null;
+/**
+ * The request for the next hint on an unsubmitted answer, or `null` when
+ * there is none to give: an unsupported type, an author who switched hints
+ * off, or a redacted item — hints are for practice, where the item is whole.
+ *
+ * The facts carry the key, and which parts the learner has right so far, so a
+ * model can hint where it helps. The learner never sees them; a hint that
+ * contains an answer is refused by {@link checkAiHint}.
+ */
+declare function aiHintRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    previousHints: readonly string[];
+    learnerLocale?: string;
+}): AiHintRequest | null;
+/**
+ * Reads what a port returned. Anything but an object with a string `text` is
+ * `malformed`; text that is empty once cleaned, or longer than
+ * {@link AI_TEXT_MAX_LENGTH}, is refused rather than shown or cut.
+ */
+declare function readAiTextResult(raw: unknown): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Checks an explanation a port returned for `request`. On top of
+ * {@link readAiTextResult}: an explanation that states a verdict other than
+ * the SDK's grade is refused (`contradicts-grade`) — it explains an answer
+ * the learner did not get.
+ */
+declare function checkAiExplanation(raw: unknown, request: AiExplanationRequest): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Checks a hint a port returned for `request`. On top of
+ * {@link readAiTextResult}: a hint that contains an answer is refused
+ * (`reveals-answer`) — see {@link hintRevealsAnswer}.
+ */
+declare function checkAiHint(raw: unknown, request: AiHintRequest): {
+    ok: true;
+    result: AiTextResult;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * Whether a hint gives away an answer, judged against the facts it was asked
+ * for. It is a floor, not a proof: it finds an answer written out, not one
+ * spelled letter by letter or described.
+ *
+ * - **Multiple choice:** the text of any correct option, as whole words.
+ * - **Fill-in-the-blanks and gap select:** any accepted answer, as whole words.
+ *   An answer of one short word ("is", "the") counts only where the hint
+ *   writes it beside a neighbour it has in the passage — "name is", "is
+ *   Rossi" — so a hint may still use the word on its own.
+ *
+ * Case, accents and punctuation are ignored on both sides.
+ */
+declare function hintRevealsAnswer(facts: AiItemFacts, hint: string): boolean;
+
 /**
  * The frozen record of what one attempt was served.
  *
@@ -1332,4 +1449,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, assertRedacted, assertRedactedItemGroup, canonicalJson, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };
+export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };