@intellectif/lk-core 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @intellectif/lk-core
 
+## 1.1.0
+
+### Minor Changes
+
+- [#86](https://github.com/intellectif/learning-kit/pull/86) [`2215060`](https://github.com/intellectif/learning-kit/commit/22150600b0d8f5f058214a0551566b58e154276d) Thanks [@diego28e](https://github.com/diego28e)! - **Coaching on a reading aloud**: "Coach me on this reading" under a read-aloud's marks, where a model may coach only the words the speech engine marked.
+
+  **Action required:** none unless your code switches over `AiFeature`, `AiRefusal` or `InteractionKind` without a `default` branch (new members `'pronunciation-coaching'`, `'contradicts-marks'` and `'ai-coaching-shown'`), reads `AiCheckCase.request` without narrowing on `feature`, or implements a complete `LkStrings` (six new keys). Nothing changes until you pass a `pronunciationCoaching` port. Install lk-core 1.1.0 with lk-react 23.1.0: lk-react calls the new lk-core functions, and its peer range moves to `^1.1.0`. See https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **lk-core:** `aiCoachingRequest` builds what a model is given: the text, the engine's marks word by word — with each word's sounds and what each was heard as, when the marks come from the assessment — its dimension scores, and the grade. `checkAiCoaching` checks the reply before a learner sees it. Every word it coaches must be one the engine marked mispronounced or omitted, and every sound one the engine reported for that word; anything else refuses the whole reply as `contradicts-marks`. The words come back in reading order, each as the marks show it, and no number in the reply is read. An assessment the grader would not read (no speech, unscripted, another text or locale) gives no coaching.
+  - **lk-react:** a `pronunciationCoaching` port on `LearnerAi`. `<ReadAloud>` offers coaching under its marks in `practice` once a take is graded and in `review` wherever marks are shown, from a kept assessment or a stored grade; never in `exam`. `<PronunciationFeedback>` offers it too, given the item's `id` and `title` in `data`, and takes `ai`, `renderMode`, `delivery` and `onInteraction` for it. It follows the author's and the paper's `ai.explanations` and needs `feedback`, not `solutions`. One coaching per take. `useAiCoaching` gives marks you draw yourself the same rules.
+  - **Records:** `ai-coaching-shown` (how many words were coached, provenance and usage; never the text), and `ai-help-refused` with `feature: 'pronunciation-coaching'`.
+  - **ai-check:** a `pronunciationCoaching` port runs four reading cases: a mispronounced "th" and a word left out, a clean reading, the same slips from a stored grade without sounds, and coaching asked for in Spanish.
+  - Six new strings: `aiCoaching`, `aiCoachingLoading`, `aiCoachingHeading`, `aiCoachingUnavailable`, `aiCoachingWords`, `aiCoachingSound`.
+  - **Stability:** the promise now says what a minor may add to a type the SDK hands you — a union member, a `LkStrings` key, an optional property — and that a `default` branch keeps a switch correct across minors.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -28,7 +28,7 @@ npm install @intellectif/lk-core
 - **Item groups** — `Stimulus` + `ItemGroup` (one passage or recording serving several questions), `flattenSequence()` for seeded, shuffle-atomic presentation order with stable slot identity. Slot ids are positional by default (`"3"`, `"1.0"`); author a `slotKey` on an entry and its id survives an insert, so a stored response cannot slide onto a different question.
 - **Delivery policies** — `DeliveryPolicy` says what a school lets a learner see around a question: feedback, solutions, hints and AI help. `resolveDeliveryPolicy` spells one out (an unreadable setting restricts, never allows), `validateDeliveryPolicy` checks one before it is stored, and `combineDeliveryPolicies` keeps a setting on only where every policy leaves it on.
 - **Scoring policies** — `ItemScoringPolicy` says how a paper's questions are scored when a learner can try again or ask for hints: `retries`, which try `counts`, and what a try and a hint cost. `scoreTries` does the arithmetic, `evaluate(…, { scoring })` and `evaluateTries` reach a question's outcome from its answers, and `validateItemScoringPolicy` / `resolveItemScoringPolicy` refuse a policy that cannot be applied rather than guess — every setting moves a grade. No policy changes nothing, and the arithmetic is pinned by the grade vectors.
-- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest` and `aiWritingFeedbackRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint` and `checkAiWritingFeedback` refuse an explanation that contradicts the grade, a hint that contains the answer, and writing feedback that corrects words the learner never wrote, and `checkAiWritingFeedback` computes the rubric's indicative score itself.
+- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest`, `aiWritingFeedbackRequest` and `aiCoachingRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint`, `checkAiWritingFeedback` and `checkAiCoaching` refuse an explanation that contradicts the grade, a hint that contains the answer, writing feedback that corrects words the learner never wrote, and coaching on a reading that names a word the speech engine did not mark or a sound it did not report; `checkAiWritingFeedback` computes the rubric's indicative score itself.
 - **Attempt plans** — `planAttempt(entries, { seed, shuffleEntries, points, delivery })` freezes the exact paper a learner sat, and the delivery policy it was sat under: slot order, per-slot points, a content hash of each item, and a `planHash` over the lot. `verifyAttemptPlan(plan, current)` reports the drift when that content is later edited (`changedSlotIds`, `changedStimulusSlotIds`, `changedPointsSlotIds`, `missingSlotIds`, …) — the thing you need during a remark or an appeal. `scoredItemsFromPlan(plan, outcomes)` turns collected outcomes into the `ScoredItem[]` composition wants, and defaults a slot with **no** outcome to `deferred` rather than silently shrinking the denominator.
 - **Attempt state** — `serializeAttemptState(plan, progress)` / `restoreAttemptState(plan, snapshot)` round-trip an interrupted attempt (responses, submitted slots, position) and are **bound to the plan**: restoring answers onto a paper the learner never sat throws instead of succeeding quietly. `diffResponses(before, after)` reports what moved between two snapshots, including an answer the learner *cleared*.
 - **Media playback policy** — `media.playback` on an audio recording: `maxPlays`, `seek`, `rate`, and advisory `nativeControlHints`. `resolvePlaybackPolicy()` derives the defaults once so the schema, the plan and the renderer cannot drift. Budgets are frozen into the plan by `planAttempt`, so editing `maxPlays` mid-window cannot change what a past learner was held to, and `planAttempt` refuses a paper where one recording is budgeted under two keys.

package/dist/{activity-DgpBJeBc.d.cts → activity-MBOYLBjR.d.cts}

@@ -226,8 +226,8 @@ interface GradeRecord {
 interface ActivityAiPermissions {
     /**
      * An explanation of the learner's graded answer — and, on a written
-     * response, feedback on a draft: both are a model's words about the
-     * learner's own answer.
+     * response, feedback on a draft, and on a read-aloud, coaching on the
+     * marks: each is a model's words about the learner's own answer.
      */
     explanations?: boolean;
     /** Hints before the learner submits. */
@@ -248,7 +248,7 @@ interface AiActivityInput {
     readonly ai?: unknown;
 }
 /** The kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
+type AiFeature = 'explanation' | 'hint' | 'writing-feedback' | 'pronunciation-coaching';
 /** The activity types the SDK builds facts for. */
 type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
 /**
@@ -411,9 +411,10 @@ interface AiTextResult {
 /**
  * Why a result was not shown. `misquotes-answer` is writing feedback that
  * corrects words the learner did not write: a correction whose quote is not in
- * the draft, or not where it claims to be.
+ * the draft, or not where it claims to be. `contradicts-marks` is coaching on
+ * a word the engine did not mark, or on a sound it did not report.
  */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer' | 'contradicts-marks';
 /** One criterion of a written response's rubric, as the author wrote it. */
 interface AiRubricCriterionFact {
     name: string;
@@ -519,6 +520,110 @@ interface AiWritingFeedback {
     provenance?: AiProvenance;
     usage?: GraderUsage;
 }
+/** One sound of a word, as the engine reported it. */
+interface AiSoundFact {
+    /** The sound expected, in the assessment's phoneme alphabet. */
+    symbol: string;
+    /** How close it came, 0..100, when the engine scored it. */
+    accuracy?: number;
+    /** What the engine heard instead, best first, each with its score 0..100. */
+    heardAs?: {
+        symbol: string;
+        score: number;
+    }[];
+}
+/** One word of a reading, as the engine marked it. */
+interface AiReadingWordFact {
+    /** `w<n>` for a word of the text; absent for a word the learner added. */
+    itemId?: string;
+    /** The word of the text, normalised; `''` for a word the learner added. */
+    word: string;
+    /** What was heard, normalised; `''` for an omitted word. */
+    heard: string;
+    state: 'correct' | 'mispronounced' | 'omitted' | 'inserted';
+    /** The engine's accuracy for the word, 0..100, when it has one. */
+    accuracy?: number;
+    /** The word's sounds, from the full assessment only. */
+    sounds?: AiSoundFact[];
+}
+/**
+ * What a model is told about a read-aloud: the text, the engine's marks word
+ * by word, and its scores. The marks are the engine's; a model explains them
+ * and never makes its own.
+ */
+interface AiReadingFacts {
+    activityType: 'read-aloud';
+    activityId: string;
+    title: string;
+    /** The language the text is in. */
+    locale: string;
+    referenceText: string;
+    instructions?: string;
+    /** Who made the marks: a measurement engine, a model, or a person. */
+    assessor: 'auto' | 'ai' | 'human' | 'unknown';
+    /** The alphabet `sounds` are written in, when any are. */
+    phonemeAlphabet?: 'ipa' | 'sapi';
+    /** The engine's dimension scores, each 0..100, where it measured them. */
+    scores: {
+        accuracy?: number;
+        fluency?: number;
+        completeness?: number;
+        prosody?: number;
+    };
+    words: AiReadingWordFact[];
+}
+/**
+ * Asks for coaching on a graded reading: what to work on, word by word, and
+ * how. Never in an exam.
+ */
+interface AiCoachingRequest {
+    feature: 'pronunciation-coaching';
+    facts: AiReadingFacts;
+    /** The grade of the reading, when there is one. */
+    grade?: {
+        score: number;
+        maxScore: number;
+        passed: boolean;
+    };
+    /** The language to write in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/** One word a model coaches, as it returns it. */
+interface AiCoachingWord {
+    /** The `itemId` of a word the engine marked mispronounced or omitted. */
+    itemId: string;
+    /** What to do about it, addressed to the learner. */
+    tip: string;
+    /**
+     * A sound the engine reported for this word — `expected` — and, if the
+     * model names one, what the engine heard instead.
+     */
+    sound?: {
+        expected: string;
+        heard?: string;
+    };
+}
+/** What a host's `pronunciationCoaching` port returns. */
+interface AiCoachingResult {
+    /** The coaching as a whole, addressed to the learner. Plain text, never HTML. */
+    text: string;
+    words?: AiCoachingWord[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/** Coaching, as the SDK accepted it: what a learner is shown. */
+interface AiCoaching {
+    text: string;
+    /**
+     * The words to work on, in reading order, each with the word of the text as
+     * the SDK has it — never the model's spelling of it.
+     */
+    words: (AiCoachingWord & {
+        word: string;
+    })[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1714,7 +1819,12 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * number of `corrections`, the `indicativeScore` when there was one, and the
  * port's `provenance` and `usage` when it sent them). Never the text.
  */
- | 'ai-writing-feedback-shown' | (string & {});
+ | 'ai-writing-feedback-shown'
+/**
+ * Coaching on a read-aloud was shown (the number of `words` it coached, and
+ * the port's `provenance` and `usage` when it sent them). Never the text.
+ */
+ | 'ai-coaching-shown' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1727,4 +1837,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type GradingState as $, type ActivityAiPermissions as A, type AiWordFact as B, type AiWritingCorrection as C, type AiWritingFacts as D, type AiWritingFeedback as E, type AiWritingFeedbackRequest as F, type AiWritingFeedbackResult as G, type BlankConfig as H, type CriterionScore as I, type DeferredReason as J, type DeferredScoringPartial as K, type DictationData as L, type DictationEquivalence as M, type DictationLearnerResponse as N, type DictationSlowMedia as O, type DictationTolerance as P, type FillInTheBlanksData as Q, type FillInTheBlanksLearnerResponse as R, type GapSelectBank as S, type GapSelectChoice as T, type GapSelectData as U, type GapSelectGap as V, type GapSelectLearnerResponse as W, type GradeRecord as X, type Grader as Y, type GraderKind as Z, type GraderUsage as _, type ActivityData as a, type InlineCorrection as a0, type InteractionEvent as a1, type InteractionKind as a2, type ItemOutcome as a3, type LearnerResponse as a4, type LearnerResponseMap as a5, type MediaPlaybackPolicy as a6, type MediaTrack as a7, type MultipleChoiceData as a8, type MultipleChoiceLearnerResponse as a9, type XAPIObject as aA, type XAPIResult as aB, type XAPIScore as aC, type XAPIStatement as aD, type XAPIVerbObject as aE, levenshteinDistance as aF, matchText as aG, type MultipleChoiceOption as aa, type MultipleChoiceOptionMedia as ab, type NativeControlHint as ac, type ReadAloudData as ad, type ReadAloudDimension as ae, type ReadAloudDimensionWeight as af, type ReadAloudLearnerResponse as ag, type ReadAloudSlowMedia as ah, type RecordingBounds as ai, type RecordingRef as aj, type ScoringDetail as ak, type ScoringOutcome as al, type ScoringResult as am, type TextMatchPolicy as an, type TextMatchResult as ao, type ValidationError as ap, type ValidationResult as aq, type WrittenResponseData as ar, type WrittenResponseLearnerResponse as as, type WrittenResponseRubric as at, type WrittenResponseRubricCriterion as au, type XAPIActor as av, type XAPIConfig as aw, type XAPIContext as ax, type XAPIContextActivities as ay, type XAPIError 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 AiCriterionJudgement as i, type AiDictationFacts as j, type AiExplanationRequest as k, type AiFeature as l, type AiFillInTheBlanksFacts as m, type AiGapFact as n, type AiGapSelectFacts as o, type AiGrade as p, type AiHintRequest as q, type AiItemFacts as r, type AiMultipleChoiceFacts as s, type AiOptionFact as t, type AiProvenance as u, type AiRefusal as v, type AiRubricCriterionFact as w, type AiSupportedActivityType as x, type AiTextResult as y, type AiVerdict as z };
+export { type GapSelectData as $, type ActivityAiPermissions as A, type AiReadingWordFact as B, type AiRefusal as C, type AiRubricCriterionFact as D, type AiSoundFact as E, type AiSupportedActivityType as F, type AiTextResult as G, type AiVerdict as H, type AiWordFact as I, type AiWritingCorrection as J, type AiWritingFacts as K, type AiWritingFeedback as L, type AiWritingFeedbackRequest as M, type AiWritingFeedbackResult as N, type BlankConfig as O, type CriterionScore as P, type DeferredReason as Q, type DeferredScoringPartial as R, type DictationData as S, type DictationEquivalence as T, type DictationLearnerResponse as U, type DictationSlowMedia as V, type DictationTolerance as W, type FillInTheBlanksData as X, type FillInTheBlanksLearnerResponse as Y, type GapSelectBank as Z, type GapSelectChoice as _, type ActivityData as a, type GapSelectGap as a0, type GapSelectLearnerResponse as a1, type GradeRecord as a2, type Grader as a3, type GraderKind as a4, type GraderUsage as a5, type GradingState as a6, type InlineCorrection as a7, type InteractionEvent as a8, type InteractionKind as a9, type WrittenResponseRubric as aA, type WrittenResponseRubricCriterion as aB, type XAPIActor as aC, type XAPIConfig as aD, type XAPIContext as aE, type XAPIContextActivities as aF, type XAPIError as aG, type XAPIObject as aH, type XAPIResult as aI, type XAPIScore as aJ, type XAPIStatement as aK, type XAPIVerbObject as aL, levenshteinDistance as aM, matchText as aN, type ItemOutcome as aa, type LearnerResponse as ab, type LearnerResponseMap as ac, type MediaPlaybackPolicy as ad, type MediaTrack as ae, type MultipleChoiceData as af, type MultipleChoiceLearnerResponse as ag, type MultipleChoiceOption as ah, type MultipleChoiceOptionMedia as ai, type NativeControlHint as aj, type ReadAloudData as ak, type ReadAloudDimension as al, type ReadAloudDimensionWeight as am, type ReadAloudLearnerResponse as an, type ReadAloudSlowMedia as ao, type RecordingBounds as ap, type RecordingRef as aq, type ScoringDetail as ar, type ScoringOutcome as as, type ScoringResult as at, type TextMatchPolicy as au, type TextMatchResult as av, type ValidationError as aw, type ValidationResult as ax, type WrittenResponseData as ay, type WrittenResponseLearnerResponse 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 AiCoaching as i, type AiCoachingRequest as j, type AiCoachingResult as k, type AiCoachingWord as l, type AiCriterionJudgement as m, type AiDictationFacts as n, type AiExplanationRequest as o, type AiFeature as p, type AiFillInTheBlanksFacts as q, type AiGapFact as r, type AiGapSelectFacts as s, type AiGrade as t, type AiHintRequest as u, type AiItemFacts as v, type AiMultipleChoiceFacts as w, type AiOptionFact as x, type AiProvenance as y, type AiReadingFacts as z };

package/dist/{activity-DgpBJeBc.d.ts → activity-MBOYLBjR.d.ts}

@@ -226,8 +226,8 @@ interface GradeRecord {
 interface ActivityAiPermissions {
     /**
      * An explanation of the learner's graded answer — and, on a written
-     * response, feedback on a draft: both are a model's words about the
-     * learner's own answer.
+     * response, feedback on a draft, and on a read-aloud, coaching on the
+     * marks: each is a model's words about the learner's own answer.
      */
     explanations?: boolean;
     /** Hints before the learner submits. */
@@ -248,7 +248,7 @@ interface AiActivityInput {
     readonly ai?: unknown;
 }
 /** The kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
+type AiFeature = 'explanation' | 'hint' | 'writing-feedback' | 'pronunciation-coaching';
 /** The activity types the SDK builds facts for. */
 type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
 /**
@@ -411,9 +411,10 @@ interface AiTextResult {
 /**
  * Why a result was not shown. `misquotes-answer` is writing feedback that
  * corrects words the learner did not write: a correction whose quote is not in
- * the draft, or not where it claims to be.
+ * the draft, or not where it claims to be. `contradicts-marks` is coaching on
+ * a word the engine did not mark, or on a sound it did not report.
  */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer' | 'contradicts-marks';
 /** One criterion of a written response's rubric, as the author wrote it. */
 interface AiRubricCriterionFact {
     name: string;
@@ -519,6 +520,110 @@ interface AiWritingFeedback {
     provenance?: AiProvenance;
     usage?: GraderUsage;
 }
+/** One sound of a word, as the engine reported it. */
+interface AiSoundFact {
+    /** The sound expected, in the assessment's phoneme alphabet. */
+    symbol: string;
+    /** How close it came, 0..100, when the engine scored it. */
+    accuracy?: number;
+    /** What the engine heard instead, best first, each with its score 0..100. */
+    heardAs?: {
+        symbol: string;
+        score: number;
+    }[];
+}
+/** One word of a reading, as the engine marked it. */
+interface AiReadingWordFact {
+    /** `w<n>` for a word of the text; absent for a word the learner added. */
+    itemId?: string;
+    /** The word of the text, normalised; `''` for a word the learner added. */
+    word: string;
+    /** What was heard, normalised; `''` for an omitted word. */
+    heard: string;
+    state: 'correct' | 'mispronounced' | 'omitted' | 'inserted';
+    /** The engine's accuracy for the word, 0..100, when it has one. */
+    accuracy?: number;
+    /** The word's sounds, from the full assessment only. */
+    sounds?: AiSoundFact[];
+}
+/**
+ * What a model is told about a read-aloud: the text, the engine's marks word
+ * by word, and its scores. The marks are the engine's; a model explains them
+ * and never makes its own.
+ */
+interface AiReadingFacts {
+    activityType: 'read-aloud';
+    activityId: string;
+    title: string;
+    /** The language the text is in. */
+    locale: string;
+    referenceText: string;
+    instructions?: string;
+    /** Who made the marks: a measurement engine, a model, or a person. */
+    assessor: 'auto' | 'ai' | 'human' | 'unknown';
+    /** The alphabet `sounds` are written in, when any are. */
+    phonemeAlphabet?: 'ipa' | 'sapi';
+    /** The engine's dimension scores, each 0..100, where it measured them. */
+    scores: {
+        accuracy?: number;
+        fluency?: number;
+        completeness?: number;
+        prosody?: number;
+    };
+    words: AiReadingWordFact[];
+}
+/**
+ * Asks for coaching on a graded reading: what to work on, word by word, and
+ * how. Never in an exam.
+ */
+interface AiCoachingRequest {
+    feature: 'pronunciation-coaching';
+    facts: AiReadingFacts;
+    /** The grade of the reading, when there is one. */
+    grade?: {
+        score: number;
+        maxScore: number;
+        passed: boolean;
+    };
+    /** The language to write in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/** One word a model coaches, as it returns it. */
+interface AiCoachingWord {
+    /** The `itemId` of a word the engine marked mispronounced or omitted. */
+    itemId: string;
+    /** What to do about it, addressed to the learner. */
+    tip: string;
+    /**
+     * A sound the engine reported for this word — `expected` — and, if the
+     * model names one, what the engine heard instead.
+     */
+    sound?: {
+        expected: string;
+        heard?: string;
+    };
+}
+/** What a host's `pronunciationCoaching` port returns. */
+interface AiCoachingResult {
+    /** The coaching as a whole, addressed to the learner. Plain text, never HTML. */
+    text: string;
+    words?: AiCoachingWord[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/** Coaching, as the SDK accepted it: what a learner is shown. */
+interface AiCoaching {
+    text: string;
+    /**
+     * The words to work on, in reading order, each with the word of the text as
+     * the SDK has it — never the model's spelling of it.
+     */
+    words: (AiCoachingWord & {
+        word: string;
+    })[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1714,7 +1819,12 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * number of `corrections`, the `indicativeScore` when there was one, and the
  * port's `provenance` and `usage` when it sent them). Never the text.
  */
- | 'ai-writing-feedback-shown' | (string & {});
+ | 'ai-writing-feedback-shown'
+/**
+ * Coaching on a read-aloud was shown (the number of `words` it coached, and
+ * the port's `provenance` and `usage` when it sent them). Never the text.
+ */
+ | 'ai-coaching-shown' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1727,4 +1837,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type GradingState as $, type ActivityAiPermissions as A, type AiWordFact as B, type AiWritingCorrection as C, type AiWritingFacts as D, type AiWritingFeedback as E, type AiWritingFeedbackRequest as F, type AiWritingFeedbackResult as G, type BlankConfig as H, type CriterionScore as I, type DeferredReason as J, type DeferredScoringPartial as K, type DictationData as L, type DictationEquivalence as M, type DictationLearnerResponse as N, type DictationSlowMedia as O, type DictationTolerance as P, type FillInTheBlanksData as Q, type FillInTheBlanksLearnerResponse as R, type GapSelectBank as S, type GapSelectChoice as T, type GapSelectData as U, type GapSelectGap as V, type GapSelectLearnerResponse as W, type GradeRecord as X, type Grader as Y, type GraderKind as Z, type GraderUsage as _, type ActivityData as a, type InlineCorrection as a0, type InteractionEvent as a1, type InteractionKind as a2, type ItemOutcome as a3, type LearnerResponse as a4, type LearnerResponseMap as a5, type MediaPlaybackPolicy as a6, type MediaTrack as a7, type MultipleChoiceData as a8, type MultipleChoiceLearnerResponse as a9, type XAPIObject as aA, type XAPIResult as aB, type XAPIScore as aC, type XAPIStatement as aD, type XAPIVerbObject as aE, levenshteinDistance as aF, matchText as aG, type MultipleChoiceOption as aa, type MultipleChoiceOptionMedia as ab, type NativeControlHint as ac, type ReadAloudData as ad, type ReadAloudDimension as ae, type ReadAloudDimensionWeight as af, type ReadAloudLearnerResponse as ag, type ReadAloudSlowMedia as ah, type RecordingBounds as ai, type RecordingRef as aj, type ScoringDetail as ak, type ScoringOutcome as al, type ScoringResult as am, type TextMatchPolicy as an, type TextMatchResult as ao, type ValidationError as ap, type ValidationResult as aq, type WrittenResponseData as ar, type WrittenResponseLearnerResponse as as, type WrittenResponseRubric as at, type WrittenResponseRubricCriterion as au, type XAPIActor as av, type XAPIConfig as aw, type XAPIContext as ax, type XAPIContextActivities as ay, type XAPIError 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 AiCriterionJudgement as i, type AiDictationFacts as j, type AiExplanationRequest as k, type AiFeature as l, type AiFillInTheBlanksFacts as m, type AiGapFact as n, type AiGapSelectFacts as o, type AiGrade as p, type AiHintRequest as q, type AiItemFacts as r, type AiMultipleChoiceFacts as s, type AiOptionFact as t, type AiProvenance as u, type AiRefusal as v, type AiRubricCriterionFact as w, type AiSupportedActivityType as x, type AiTextResult as y, type AiVerdict as z };
+export { type GapSelectData as $, type ActivityAiPermissions as A, type AiReadingWordFact as B, type AiRefusal as C, type AiRubricCriterionFact as D, type AiSoundFact as E, type AiSupportedActivityType as F, type AiTextResult as G, type AiVerdict as H, type AiWordFact as I, type AiWritingCorrection as J, type AiWritingFacts as K, type AiWritingFeedback as L, type AiWritingFeedbackRequest as M, type AiWritingFeedbackResult as N, type BlankConfig as O, type CriterionScore as P, type DeferredReason as Q, type DeferredScoringPartial as R, type DictationData as S, type DictationEquivalence as T, type DictationLearnerResponse as U, type DictationSlowMedia as V, type DictationTolerance as W, type FillInTheBlanksData as X, type FillInTheBlanksLearnerResponse as Y, type GapSelectBank as Z, type GapSelectChoice as _, type ActivityData as a, type GapSelectGap as a0, type GapSelectLearnerResponse as a1, type GradeRecord as a2, type Grader as a3, type GraderKind as a4, type GraderUsage as a5, type GradingState as a6, type InlineCorrection as a7, type InteractionEvent as a8, type InteractionKind as a9, type WrittenResponseRubric as aA, type WrittenResponseRubricCriterion as aB, type XAPIActor as aC, type XAPIConfig as aD, type XAPIContext as aE, type XAPIContextActivities as aF, type XAPIError as aG, type XAPIObject as aH, type XAPIResult as aI, type XAPIScore as aJ, type XAPIStatement as aK, type XAPIVerbObject as aL, levenshteinDistance as aM, matchText as aN, type ItemOutcome as aa, type LearnerResponse as ab, type LearnerResponseMap as ac, type MediaPlaybackPolicy as ad, type MediaTrack as ae, type MultipleChoiceData as af, type MultipleChoiceLearnerResponse as ag, type MultipleChoiceOption as ah, type MultipleChoiceOptionMedia as ai, type NativeControlHint as aj, type ReadAloudData as ak, type ReadAloudDimension as al, type ReadAloudDimensionWeight as am, type ReadAloudLearnerResponse as an, type ReadAloudSlowMedia as ao, type RecordingBounds as ap, type RecordingRef as aq, type ScoringDetail as ar, type ScoringOutcome as as, type ScoringResult as at, type TextMatchPolicy as au, type TextMatchResult as av, type ValidationError as aw, type ValidationResult as ax, type WrittenResponseData as ay, type WrittenResponseLearnerResponse 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 AiCoaching as i, type AiCoachingRequest as j, type AiCoachingResult as k, type AiCoachingWord as l, type AiCriterionJudgement as m, type AiDictationFacts as n, type AiExplanationRequest as o, type AiFeature as p, type AiFillInTheBlanksFacts as q, type AiGapFact as r, type AiGapSelectFacts as s, type AiGrade as t, type AiHintRequest as u, type AiItemFacts as v, type AiMultipleChoiceFacts as w, type AiOptionFact as x, type AiProvenance as y, type AiReadingFacts as z };

package/dist/ai-check.cjs

@@ -5,8 +5,12 @@
 
 
 
-var _chunkW5KB3DNTcjs = require('./chunk-W5KB3DNT.cjs');
-require('./chunk-VSH7ECQL.cjs');
+
+
+var _chunkLDFQUZIIcjs = require('./chunk-LDFQUZII.cjs');
+
+
+var _chunkVSH7ECQLcjs = require('./chunk-VSH7ECQL.cjs');
 require('./chunk-DSDXL3JO.cjs');
 
 // src/ai-check/cases.ts
@@ -87,6 +91,68 @@ var weekend = {
     ]
   }
 };
+var weather = {
+  schemaVersion: "1.0",
+  type: "read-aloud",
+  id: "ai-check-reading",
+  title: "Read the forecast aloud",
+  referenceText: "The weather is warm in the north.",
+  locale: "en-US",
+  recording: { maxSeconds: 20 },
+  scoring: {
+    dimensions: [
+      { name: "accuracy", weight: 2 },
+      { name: "fluency", weight: 1 }
+    ]
+  }
+};
+var said = (text, over = {}) => ({
+  text,
+  error: "none",
+  accuracy: 92,
+  ...over
+});
+function forecast(slips) {
+  return {
+    assessmentVersion: "1.0",
+    status: "assessed",
+    task: "scripted",
+    locale: "en-US",
+    referenceText: weather.referenceText,
+    recordingKey: "ai-check-take",
+    assessor: { kind: "auto", id: "pronunciation-engine" },
+    scale: 100,
+    scores: slips ? { accuracy: 68, fluency: 81, completeness: 86 } : { accuracy: 94, fluency: 90 },
+    miscue: "assessor",
+    phonemeAlphabet: "ipa",
+    words: [
+      said("The"),
+      slips ? said("weather", {
+        accuracy: 38,
+        error: "mispronunciation",
+        phonemes: [
+          { symbol: "w", accuracy: 90 },
+          { symbol: "\u025B", accuracy: 85 },
+          {
+            symbol: "\xF0",
+            accuracy: 12,
+            heardAs: [
+              { symbol: "d", score: 64 },
+              { symbol: "z", score: 21 },
+              { symbol: "\xF0", score: 12 }
+            ]
+          },
+          { symbol: "\u025A", accuracy: 80 }
+        ]
+      }) : said("weather"),
+      said("is"),
+      said("warm"),
+      said("in"),
+      said("the"),
+      slips ? { text: "north", error: "omission" } : said("north")
+    ]
+  };
+}
 var chose = (ids) => ({
   type: "multiple-choice",
   selectedOptionIds: ids
@@ -106,21 +172,21 @@ var drafted = (text) => ({
   wordCount: 0
 });
 function explanationCase(id, about, data, response) {
-  const request = _chunkW5KB3DNTcjs.aiExplanationRequest.call(void 0, { data, response });
+  const request = _chunkLDFQUZIIcjs.aiExplanationRequest.call(void 0, { data, response });
   if (request === null) {
     throw new Error(`ai-check: no explanation request for "${id}"`);
   }
   return { id, feature: "explanation", about, request };
 }
 function hintCase(id, about, data, response, previousHints = []) {
-  const request = _chunkW5KB3DNTcjs.aiHintRequest.call(void 0, { data, response, previousHints });
+  const request = _chunkLDFQUZIIcjs.aiHintRequest.call(void 0, { data, response, previousHints });
   if (request === null) {
     throw new Error(`ai-check: no hint request for "${id}"`);
   }
   return { id, feature: "hint", about, request };
 }
 function writingCase(id, about, text, previousFeedback = [], learnerLocale) {
-  const request = _chunkW5KB3DNTcjs.aiWritingFeedbackRequest.call(void 0, {
+  const request = _chunkLDFQUZIIcjs.aiWritingFeedbackRequest.call(void 0, {
     data: weekend,
     response: drafted(text),
     previousFeedback,
@@ -131,6 +197,31 @@ function writingCase(id, about, text, previousFeedback = [], learnerLocale) {
   }
   return { id, feature: "writing-feedback", about, request };
 }
+function coachingCase(id, about, marks, learnerLocale) {
+  const assessment = _nullishCoalesce(marks.assessment, () => ( forecast(true)));
+  const grade = _chunkVSH7ECQLcjs.gradeReadAloud.call(void 0, 
+    weather,
+    { type: "read-aloud", recording: { key: "ai-check-take", mimeType: "audio/wav" } },
+    assessment,
+    {
+      measured: { durationMs: 4e3, voicedMs: 3e3 },
+      plausibility: { maxWordsPerSecond: 6, minVoicedMs: 500 }
+    }
+  );
+  if ("unscorable" in grade) {
+    throw new Error(`ai-check: the reading for "${id}" did not grade: ${grade.reason}`);
+  }
+  const request = _chunkLDFQUZIIcjs.aiCoachingRequest.call(void 0, {
+    data: weather,
+    ...marks.fromGradeOnly === true ? {} : { assessment },
+    grade,
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  });
+  if (request === null) {
+    throw new Error(`ai-check: no coaching request for "${id}"`);
+  }
+  return { id, feature: "pronunciation-coaching", about, request };
+}
 function aiCheckCases() {
   return [
     explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
@@ -220,6 +311,23 @@ function aiCheckCases() {
       "Last weekend I visit my grandmother. She cook a big lunch and we eat together in the garden.",
       [],
       "es"
+    ),
+    coachingCase("coaching-slips", 'A reading with a mispronounced "th" and a word left out', {
+      assessment: forecast(true)
+    }),
+    coachingCase("coaching-clean", "A reading the engine marked correct throughout", {
+      assessment: forecast(false)
+    }),
+    coachingCase(
+      "coaching-from-grade",
+      "The same slips, from a stored grade: marks without sounds",
+      { fromGradeOnly: true }
+    ),
+    coachingCase(
+      "coaching-in-spanish",
+      "The same slips, with coaching asked for in Spanish",
+      { assessment: forecast(true) },
+      "es"
     )
   ];
 }
@@ -231,7 +339,8 @@ var REFUSALS = [
   "too-long",
   "contradicts-grade",
   "reveals-answer",
-  "misquotes-answer"
+  "misquotes-answer",
+  "contradicts-marks"
 ];
 function portFor(ports, one) {
   switch (one.request.feature) {
@@ -239,6 +348,8 @@ function portFor(ports, one) {
       return ports.explain;
     case "hint":
       return ports.hint;
+    case "pronunciation-coaching":
+      return ports.pronunciationCoaching;
     default:
       return ports.writingFeedback;
   }
@@ -262,8 +373,26 @@ async function runCase(ports, one) {
     };
   }
   const ms = now() - started;
+  if (one.request.feature === "pronunciation-coaching") {
+    const checked2 = _chunkLDFQUZIIcjs.checkAiCoaching.call(void 0, raw, one.request);
+    if (checked2.ok) {
+      const { text, provenance, usage } = checked2.coaching;
+      return {
+        case: one,
+        ok: true,
+        result: {
+          text,
+          ...provenance !== void 0 ? { provenance } : {},
+          ...usage !== void 0 ? { usage } : {}
+        },
+        coaching: checked2.coaching,
+        ms
+      };
+    }
+    return refused(one, raw, checked2.refusal, ms);
+  }
   if (one.request.feature === "writing-feedback") {
-    const checked2 = _chunkW5KB3DNTcjs.checkAiWritingFeedback.call(void 0, raw, one.request);
+    const checked2 = _chunkLDFQUZIIcjs.checkAiWritingFeedback.call(void 0, raw, one.request);
     if (checked2.ok) {
       const { text, provenance, usage } = checked2.feedback;
       return {
@@ -280,7 +409,7 @@ async function runCase(ports, one) {
     }
     return refused(one, raw, checked2.refusal, ms);
   }
-  const checked = one.request.feature === "explanation" ? _chunkW5KB3DNTcjs.checkAiExplanation.call(void 0, raw, one.request) : _chunkW5KB3DNTcjs.checkAiHint.call(void 0, raw, one.request);
+  const checked = one.request.feature === "explanation" ? _chunkLDFQUZIIcjs.checkAiExplanation.call(void 0, raw, one.request) : _chunkLDFQUZIIcjs.checkAiHint.call(void 0, raw, one.request);
   if (checked.ok) {
     return { case: one, ok: true, result: checked.result, ms };
   }